- 5 bước từ clone source code đến wiki hoàn chỉnh: lập dự án, LLM đọc source sinh trang đầu, lint toàn lượt, thêm tầng white-label cho người không phải kỹ sư, rồi duy trì định kỳ.
- x-algorithm-wiki (34 trang / 6,800 dòng) chứng minh quy trình hoạt động.
- Chi phí toàn bộ lifecycle: $5-30 - rẻ hơn một giờ làm việc của kỹ sư.
TL;DR
- 5 bước xây wiki cho bất kỳ dự án open source: lập dự án & khóa source, LLM tạo trang đầu, lint & kiểm chứng, thêm tầng điều hướng cho người không phải kỹ sư, duy trì liên tục.
- Case study: x-algorithm-wiki (xAI Twitter algorithm) - 34 trang / 6,800+ dòng được xây trong một lần ingest.
- Chi phí: $0.3-1.5 cho một lần ingest 50k dòng source; toàn bộ lifecycle một wiki trung bình $5-30.
- Ba lỗi thường gặp: đặt tên không nhất quán, chỉ đọc index trước khi sửa, không lint định kỳ.
Tổng quan quy trình
Bài này dùng x-algorithm-wiki làm case study - wiki về thuật toán For You của xAI/X, với bản online công khai. 34 trang / 6,800 dòng. Bất kỳ dự án open source nào cũng đi theo đúng năm bước này.
Bước 1 - Lập dự án và khóa source code
Clone source code về local, rồi lock tại một commit hoặc tag cụ thể. Đây là bước mà nhiều người bỏ qua vì thấy không cần thiết - nhưng nếu source code thay đổi trong khi đang ingest, wiki sẽ tham chiếu đến code không còn tồn tại.
git clone https://github.com/xai-org/x-algorithm /tmp/x-algorithm
cd /tmp/x-algorithm && git checkout 0bfc279
mkdir ~/code/x-algorithm-wiki && cd $_
git init && mkdir -p concepts entities changelog
cp ~/code/lanshu-wiki-skill/schema/wiki-code-repo-SCHEMA.md ./SCHEMA.md
echo "# Wiki Index" > index.md && echo "# Wiki Log" > log.mdSau khi copy template, mở SCHEMA.md và điền hai trường đánh dấu: Domain description (mô tả dự án, commit hash, các subsystem cần cover) và Tag taxonomy (hệ thống tag riêng cho dự án - ví dụ recsys, candidate-pipeline, ranking).
Bước 2 - Để LLM đọc source và sinh trang đầu
Mở Claude Code, một prompt là đủ:
Đọc
SCHEMA.md, theo quy tắc của nó, build architecture wiki cho[đường dẫn source code]. Bắt đầu từ 5 module quan trọng nhất:[liệt kê 5 thư mục/subsystem cốt lõi]. Quy tắc cứng: mỗi kết luận phải kèm anchorfile:dòng, không cover được thì không viết.
Với x-algorithm-wiki, 5 module được chọn là: home-mixer, candidate-pipeline, phoenix, thunder, grox. Một lần chạy tạo ra 10-20 trang concept + entity, tổng cộng 2,000-5,000 dòng. Đây là nơi kỷ luật "kết luận phải có anchor" được thiết lập - tất cả trang về sau đều kế thừa chuẩn này.
Bước 3 - Lint toàn lượt và kiểm chứng anchor
Sau mỗi batch, chạy /wiki lint để quét các lỗi tự động. Nhưng lint không phải tất cả - bước bắt buộc tiếp theo là chọn ngẫu nhiên 2-3 trang, đọc toàn văn, đối chiếu với source code gốc.
Đây là bước duy nhất phát hiện được lỗi ẩn: LLM nhầm chi tiết của module A với module B, hoặc trích dẫn con số từ tài liệu nội bộ cũ thay vì code hiện tại. Lint tự động không bắt được loại lỗi này.
Với x-algorithm-wiki, kiểm tra 29 trang / 482 anchor phát hiện 3 sai lệch: kích thước mini model, số lượng scorer, cấu hình isolation mask. Tất cả được ghi vào changelog - không sửa thầm lặng. Audit trail là một phần giá trị của wiki, không phải điều cần che giấu.
Bước 4 - Thêm tầng điều hướng cho người không phải kỹ sư
Sau bước 3, wiki phục vụ tốt cho kỹ sư. Nhưng khi chia sẻ cho product manager hay designer, phản hồi thường là: "Tôi không hiểu gì cả." Source code term, function name, và anchor kiểu src/main.go:247 không có nghĩa gì với người không đọc code.
Giải pháp: thêm thư mục guide/ với mô hình "trang kỹ thuật + trang bạch thoại theo cặp":
| Trang kỹ thuật (concepts/) | Trang bạch thoại (guide/) |
|---|---|
| system-architecture.md | how-it-works.md (giải thích bằng phép so sánh, không có code) |
| candidate-selection.md | how-posts-are-picked.md (dùng ẩn dụ tuyển sinh) |
| Các trang kỹ thuật khác | glossary.md / faq.md / operating-myths.md |
Trang bạch thoại vẫn phải tuân theo quy tắc truy ngược: cuối mỗi trang có bảng "Nguồn" trỏ đến trang kỹ thuật tương ứng và anchor source code. Không có anchor = trang bạch thoại trở thành "AI tự do phát biểu".
Sau bước này, cùng một wiki phục vụ hai đối tượng hoàn toàn khác nhau.
Bước 5 - Duy trì liên tục
Sau 4 bước trên, wiki có xương sống hoàn chỉnh. Việc còn lại là hai thói quen dài hạn:
- Lint định kỳ: khi dự án update, anchor trỏ vào dòng code cũ bị mất hiệu lực. Chạy lint sau mỗi release lớn để phát hiện và sửa.
- Feedback loop từ người đọc: câu hỏi hay từ đồng nghiệp → bổ sung vào
faq.md; topic mới → mở trang mới. Wiki trưởng thành theo câu hỏi thực tế, không theo kế hoạch ban đầu.
Bẫy hay gặp
Tổng hợp từ kinh nghiệm xây 7 wiki của 岚叔:
- Đặt tên không nhất quán - lỗi số 1: Hermes-Wiki từng có 8 tên khác nhau cho cùng một khái niệm kanban, 6 tên cho ralph-loop - mỗi daily-sync một người đặt tên theo cách của họ. Quy tắc: trước khi tạo trang mới, grep
index.mdtìm trang gần nghĩa. - Chỉ đọc index trước khi sửa - lỗi số 2: Đọc tóm tắt một dòng trong index rồi cập nhật trang sẽ mất thông tin. Schema bắt buộc đọc toàn văn trang trước khi chỉnh sửa.
- Không lint tag định kỳ: Sau một năm, 30 tag có thể có 10 tag gần nghĩa trùng nhau. Lint mỗi tháng một lần để hợp nhất.
- Xóa thầm lặng thay vì ghi changelog: Sửa lỗi mà không ghi lại là mất audit trail - lần sau phát hiện sai lệch tương tự sẽ không biết liệu đã xử lý hay chưa.
Khi nào không nên dùng LLM Wiki
Để cân bằng, 岚叔 cũng chia sẻ ranh giới của paradigm:
- Giới hạn quy mô ~2,000 trang:
index.mdphải fit vào context window một lần đọc. Vượt ~1,000 trang thì nên xét chia sub-wiki theo lĩnh vực; vượt ~2,000 trang thì paradigm này bắt đầu vỡ. - Cộng tác đông người còn thô: Nhiều người ingest cùng source tạo nhiều trang duplicate, cần
/wiki mergedọn sau. Schema cần được thống nhất trước khi nhiều người dùng chung. - Chi phí token không nhỏ: Ingest 50k dòng source tiêu tốn 100k-500k input token (khoảng $0.3-1.5 với Claude Sonnet). Toàn bộ lifecycle một wiki trung bình là $5-30 - rẻ hơn một giờ kỹ sư, nhưng không phải miễn phí.
Bắt đầu ngay trong 3 lệnh
Cách nhanh nhất để hiểu paradigm này là tự build một wiki. Bắt đầu bằng kho kiến thức cá nhân:
# 1. Cài skill
git clone https://github.com/cclank/lanshu-wiki-skill.git ~/code/lanshu-wiki-skill
mkdir -p ~/.claude/skills/wiki
ln -sf ~/code/lanshu-wiki-skill/SKILL.md ~/.claude/skills/wiki/SKILL.md
# 2. Khởi tạo personal wiki
mkdir -p ~/wiki/{raw,sources,entities,concepts,syntheses}
cp ~/code/lanshu-wiki-skill/schema/wiki-personal-CLAUDE.md ~/wiki/CLAUDE.md
cd ~/wiki && echo "# Wiki Index" > index.md && echo "# Wiki Log" > log.mdSau đó mở Claude Code và nói bằng tiếng tự nhiên: "thêm bài này vào wiki" hoặc "build wiki cho repo này theo SCHEMA" - skill sẽ tự điều hướng đúng thao tác.
Muốn xem thử hiệu quả trước khi tự build: truy cập lanshu-wiki-web, nhập link bất kỳ GitHub wiki repo để render thành trang web với D3 knowledge graph, Cmd+K full-text search và [[wikilink]] navigation.
Kết
LLM Wiki là paradigm đơn giản nhưng giải quyết bài toán cốt lõi: ai duy trì kiến thức khi quy mô tăng lên? Câu trả lời là LLM - miễn là bạn thiết kế đúng ba lớp, áp dụng đúng ba thao tác, và tôn trọng kỷ luật truy ngược anchor.
Không cần infrastructure phức tạp. Không cần vector database. Chỉ cần markdown, một schema tốt, và thói quen ingest có kỷ luật.