Mỗi khi mở phiên làm việc mới cùng trợ lý lập trình, câu hỏi đầu tiên mô hình đối mặt luôn giống nhau: dự án này làm gì, mã nguồn bố trí ra sao, và ranh giới nào không được vượt qua. Nếu thiếu tài liệu dẫn đường, mô hình buộc phải đoán mò hoặc tự đọc qua từng thư mục để tìm manh mối. Cả hai cách đều dẫn tới cùng một kết cục: chi phí ngữ cảnh đội lên, thời gian xử lý kéo dài, và sai lệch xuất hiện ngay từ thao tác đầu tiên.
Vì sao một kho mã nguồn cần tài liệu riêng cho agent
Khi một phiên bắt đầu, mô hình hoàn toàn không có sẵn ngữ cảnh dự án: không biết quy ước tổ chức mã, chưa từng thấy các thư viện đang dùng, và mù mờ trước những thỏa thuận ngầm tích lũy qua thời gian.
Người làm việc khi đó thường rơi vào hai lựa chọn quen thuộc. Một là không đưa tài liệu gì và ra lệnh ngắn để mô hình tự xoay xở. Mô hình sẽ đoán mò, áp dụng thói quen chung chung, và viết ra những đoạn mã xung đột với dự án. Hai là để mô hình tự lục lọi tệp tin. Nhưng như tôi từng phân tích về việc đừng để agent đọc cả repo, việc quét rộng nạp hàng chục tệp không liên quan vào bộ nhớ phiên, biến mỗi tệp thành gánh nặng ngữ cảnh phải đọc lại ở mọi lượt tiếp theo. Cả hai cách đều khiến bạn trả giá bằng thời gian gỡ lỗi, sự mệt mỏi rà soát, và chi phí bào mòn vô ích.
Bộ khung repo là lựa chọn thứ ba: trả lời sẵn những câu hỏi cốt lõi một lần duy nhất trong các tệp tin cố định. Kho mã nguồn tự giới thiệu bản thân qua tài liệu tinh gọn. Mô hình chỉ đọc đúng thứ cần biết trước khi chạm vào mã, và biết chính xác tìm ở đâu khi cần tra cứu sâu hơn.
Chín file, mỗi file trả lời một câu hỏi
Bộ khung gồm chín tệp tin Markdown rỗng, chia làm ba nhóm với chu kỳ nạp tách biệt:
`
README.md
CLAUDE.md
AGENTS.md
task-pack-template.md
docs/CODEMAP.md
docs/ARCHITECTURE.md
docs/CHANGELOG.md
.claude/session_log/README.md
.claude/session_log/YYYY-MM.md
`
Nhóm đầu tiên là tài liệu nạp ở đầu mọi phiên, nơi từng ký tự được mô hình đọc lại ở mỗi lượt:
Tệp CLAUDE.md đóng vai trò là file hướng dẫn dự án, lưu giữ quy tắc bắt buộc mô hình phải biết trước khi chạm vào mã nguồn. Vì nạp liên tục ở mọi phiên, tệp này đòi hỏi kỷ luật ngân sách nghiêm ngặt, chỉ giữ thỏa thuận cốt lõi và kiên quyết đẩy giải thích dài dòng ra ngoài.
Tệp AGENTS.md là bảng phân công vai trò: mô hình nào làm việc gì, công cụ nào phụ trách tác vụ nào, và quyền hạn can thiệp vào kho mã nguồn của từng bên tới đâu.
Nhóm thứ hai là tài liệu đọc theo nhu cầu, chỉ mở khi công việc cần tra cứu chi tiết:
Tệp docs/CODEMAP.md là bảng tra cứu hai cột với nguyên tắc muốn đổi phần nào thì sửa tệp nào. Thay vì nạp cả cây thư mục để tìm một hàm, tệp này trả về đúng địa chỉ để mô hình mở thẳng tệp cần sửa.
Tệp docs/ARCHITECTURE.md mô tả hệ thống từ cây thư mục, danh sách đường dẫn tới các thỏa thuận giao tiếp dữ liệu.
Tệp docs/CHANGELOG.md ghi lại lịch sử những gì đã bàn giao theo thứ tự mới nhất lên đầu, tuyệt đối không đóng vai trò mô tả trạng thái hiện tại.
Nhóm thứ ba là những tệp tin làm việc trực tiếp:
Bộ đôi .claude/session_log/README.md và .claude/session_log/YYYY-MM.md là nhật ký phiên, mỗi tháng một tệp và mỗi phiên đúng bốn dòng: việc đã làm, quyết định đã chốt, tệp đã sửa, và việc tiếp theo.
Tệp task-pack-template.md định hình khuôn mẫu cho một gói giao việc, xác định rõ người thực thi, điều kiện chặn, tệp cần đọc, kết quả bàn giao, cách nghiệm thu và điều cấm kỵ.
Tệp README.md ở thư mục gốc giải thích tổng quan bộ khung và thứ tự điền từng tệp cho người mới bắt đầu.
Thứ tự điền: bắt đầu từ file agent đọc trước nhất
Sai lầm phổ biến là cố điền kín mọi tệp ngay ngày đầu, vừa gây quá tải vừa dễ tạo ra những quy ước chưa qua thực tế.
Thứ tự điền mà tài liệu hướng dẫn đề xuất bắt đầu từ tệp có tác động lớn nhất: CLAUDE.md. Đây là tệp nạp ở đầu mọi phiên, định hình ranh giới an toàn của mô hình ngay từ câu lệnh đầu tiên. Thiếu quy ước nền tảng này, việc giao việc phía sau rất dễ đi sai hướng.
Sau khi tệp quy tắc có chỉ dẫn cơ bản, bước tiếp theo là lập docs/CODEMAP.md. Bảng tra cứu này phát huy tác dụng khi bạn chọn ra những luồng việc quen thuộc, chặn đứng nguy cơ mô hình quét bừa bãi kho mã nguồn ở những phiên sau.
Khi bản đồ đã có địa chỉ dẫn đường, bạn mới điền AGENTS.md. Phân vai cho mô hình chỉ có ý nghĩa khi dự án đã có quy tắc làm việc và phạm vi tệp tin rõ ràng: việc nào giao cho mô hình nhỏ, việc nào cần mô hình lớn, và ranh giới nào không được vượt qua.
Các tài liệu còn lại được điền dần theo nhịp lớn lên của dự án. Từng bước đều tựa vào bước trước: có quy tắc chung rồi mới có bản đồ dẫn đường, có bản đồ rồi mới phân vai giao việc, và có phối hợp nhịp nhàng rồi mới hoàn thiện bức tranh kiến trúc.
Phiên đầu tiên sau khi giải nén
Giải nén vào thư mục gốc dự án, bạn sẽ thấy các tệp xuất hiện đúng cấu trúc nhưng để trống nội dung. Ví dụ mẫu bên trong mượn ngữ cảnh từ ứng dụng ghi chú giả định, giúp dễ hình dung cách điền mà không cần dọn rác trước khi dùng.
Phiên đầu tiên không cần viết nhiều tài liệu. Hãy mở tệp CLAUDE.md trước tiên và tự hỏi: điều gì một người mới bắt buộc phải biết trước khi chạm vào mã nguồn — lệnh kiểm tra lỗi trước khi lưu, quy định không sửa tệp cấu hình môi trường, hay phong cách đặt tên hàm. Hãy viết những điều đó xuống thật ngắn gọn.
Kế đó, mở docs/CODEMAP.md và chỉ điền đúng ba dòng cho ba khu vực bạn hay làm nhất: giao diện, xử lý dữ liệu và định nghĩa kiểu. Ba dòng là đủ để mô hình hiểu cách tra cứu địa chỉ thay vì đoán mò.
Cuối cùng, ghi bốn dòng vào nhật ký phiên trước khi đóng máy. Phiên đầu này chỉ mất ít phút và tài liệu còn rất ngắn. Nhưng đó là khởi đầu lành mạnh: tài liệu sinh ra từ việc thật và dày dặn dần theo từng tính năng.
📥 Tải miễn phí
Bộ Khung Repo Cho AI Agent
Bộ khung này cố ý không dạy bạn điền thế nào
Bộ khung miễn phí này cung cấp cấu trúc thư mục và trả lời một kho mã nguồn cần những mục nào để trợ lý làm việc hiệu quả. Nhưng nó cố ý không dạy cách điền từng mục sao cho chuẩn xác, hay những lỗi ngầm phát sinh khi điền sai quy cách. Cấu trúc tệp tin chỉ là điều kiện cần; nội dung bên trong mới quyết định phiên làm việc thành hay bại.
Nếu cần chỉ dẫn sâu hơn để điền đúng nội dung và kiểm soát chi phí bài bản, đó là phần việc của bộ Token Efficient Vibe Coding Kit. Bộ tài liệu trả phí này gồm mười tài liệu — chín bản hướng dẫn Markdown cùng một bảng tính theo dõi chi tiết — và có sẵn chín tệp khung rỗng này bên trong thư mục riêng để người mua không cần tải lẻ. Nội dung bao quát khung định tuyến phối hợp các mô hình, kỷ luật ngân sách ngữ cảnh cho tệp quy tắc, nguyên tắc một sự thật một người sở hữu giúp tài liệu không đá nhau, kỹ thuật soạn gói giao việc, năm gói giao việc mẫu kèm hai ca thất bại thực tế, bảng chọn mô hình, mười một bài học trả giá từ dự án thật, và một bảng theo dõi lượng token kèm hướng dẫn sử dụng.
Điều tôi nhận ra
Nhìn lại quá trình xây dựng tài liệu cho các trợ lý lập trình, bài học lớn nhất là sự ngăn nắp của tài liệu phản ánh sự mạch lạc trong tư duy của người làm chủ. Khi chưa thể diễn đạt quy ước bằng vài dòng rõ ràng, mô hình không thể đoán đúng mong muốn của bạn. Chín tệp tin này tạo ra một trật tự làm việc: mô hình biết chỗ dừng chân, người làm chủ biết chỗ kiểm tra, và phiên làm việc giữ được sự tập trung từ đầu tới cuối.
Cấu trúc chín tệp tin này đúc kết từ quá trình làm việc của riêng tôi trên một nền tảng công nghệ cụ thể. Dự án khác với những ngôn ngữ và công cụ khác sẽ cần những đề mục riêng biệt, bởi bộ khung này trao tay cấu trúc định hình chứ không thể thay thế câu trả lời của chính bạn.
