Thư mục Docs của bạn sắp toang

Thư mục /docs của bạn sắp “toang”

Có thể ban đầu bạn chỉ có một file nhỏ như CLAUDE.md hoặc AGENTS.md, được bạn chăm chút viết dần theo thời gian. Sau đó bạn thêm một vài tài liệu cốt lõi (điều vốn là best practice), như ARCHITECTURE.md.

Trước khi kịp nhận ra, bạn đã viết những bản đặc tả rất lớn và bắt đầu tạo ra các tính năng hoàn chỉnh. Nhiều bản spec chia sẻ rất nhiều context giống nhau. Không muốn bỏ lỡ cơ hội tối ưu hóa, bạn tách phần boilerplate ra và chuyển thành các file Markdown riêng.

Và thế là thư mục /docs ra đời.

Không phải từ một kế hoạch chiến lược nào cả, mà đơn giản là phản ứng tự nhiên trước nhu cầu có thêm context.

Khi /docs ngày càng đầy lên, bạn có thể:

• tạo thêm sub-directory
• tạo bảng mục lục context
• tổ chức lại cấu trúc tài liệu

Nếu bạn đã làm đến mức này thì bạn không hề đơn độc — đây chính xác là cách OpenAI sử dụng nội bộ.

Cách chúng ta nghĩ về context và cách quản lý nó đã thay đổi rất nhiều chỉ trong vài tháng ngắn ngủi.

Mỗi bước tiến đều hợp lý và tự nhiên. Nhưng bạn cần nhận ra rằng thư mục /docs chỉ là một giải pháp tạm thời.

Khi bạn thêm ngày càng nhiều tài liệu trong khi code liên tục thay đổi, các sự không nhất quán nhỏ bắt đầu tích tụ.

Theo thời gian:

• context mà LLM cần để sinh code bắt đầu suy giảm chất lượng
• và không có cách dễ dàng nào để quan sát (observability) vấn đề

Nếu bạn đang có một thư mục /docs Markdown ngày càng lớn, hãy cân nhắc các vấn đề sau:

• Khả năng khám phá (Discoverability) Làm sao LLM biết rằng nó cần đọc một tài liệu cụ thể? Liệu tài liệu đó có được tham chiếu đúng thời điểm khi lập kế hoạch và sinh code không?

• Quyền sở hữu và chuyên môn (Ownership & domain expertise) Nếu tài liệu context nằm trong codebase, ai sẽ viết và duy trì chúng? Ở công ty tầm trung, bạn có thể không muốn engineer viết tài liệu về DevOps hay design pattern. Nhưng nếu có thay đổi code ảnh hưởng đến timeout hay theme frontend thì xử lý thế nào?

• Doc rot (tài liệu mục nát) Ngay cả tài liệu được bảo trì tốt cũng sẽ dần xuống cấp theo thời gian: lỗi nhỏ, lặp lại, và sự không nhất quán giữa các tài liệu. LLM có thể giúp, nhưng nếu để LLM duy trì tính nhất quán một cách mù quáng thì tài liệu sẽ mất đi ý nghĩa ban đầu.

  “Vibe documenting” có thể không làm server crash, nhưng chúng ta không có observability khi tài liệu sai. Nếu context sai, chất lượng code sinh ra sẽ giảm mà không có dấu hiệu rõ ràng nào để phát hiện.

• Velocity mismatch Context thay đổi với tốc độ khác nhau. Context của codebase có thể thay đổi mỗi commit, trong khi tài liệu kiến trúc cấp cao có thể vài tháng mới thay đổi. Nếu có 200 tài liệu, chúng ta quản lý tốc độ cập nhật khác nhau thế nào?

• Thiếu cấu trúc phân cấp Không có cấu trúc nội tại nào liên kết các tài liệu context lại với nhau. Có thể chúng được sắp xếp trong thư mục hoặc liên kết với nhau, nhưng LLM không có cách rõ ràng để điều hướng.

• Cấu trúc tài liệu tùy biến Mỗi người viết tài liệu theo cách riêng. Tài liệu của bạn có thể rất gọn gàng, nhưng không rõ cấu trúc đó có phù hợp với cách LLM đọc và hiểu thông tin hay không.

Đây đều là những vấn đề rất phức tạp.

Các công ty lớn có thể có giải pháp nội bộ cho một số vấn đề này, nhưng chúng không hề đơn giản.

LLM sẽ không cứu chúng ta

Rất dễ rơi vào trạng thái thụ động và nghĩ rằng model tiếp theo sẽ giải quyết vấn đề context cho chúng ta.

Các công ty AI chắc chắn đang cố làm điều đó.

Nhưng context chỉ liên quan gián tiếp đến việc sinh code.

LLM có thể:

• giỏi hơn trong việc suy luận context từ code
• hoặc sử dụng context hiệu quả hơn

nhưng việc tạo ra và quản lý context là một bài toán hoàn toàn khác.

Context là bản thiết kế (blueprint) mô tả sản phẩm của chúng ta tồn tại trong thế giới như thế nào (hoặc nên tồn tại như thế nào).

Đó không phải thứ model có thể tự tạo ra.

Context mà chúng ta cung cấp cho LLM mô tả:

• ý định (intent)
• cách sử dụng
• các ràng buộc thực tế

“Context” là sự kết hợp của nhiều khái niệm dẫn đến code, chứ không phải thứ có thể trích xuất từ code.

Điều này dẫn đến một câu hỏi:

Nếu context quan trọng đến vậy, tại sao chúng ta lại quản lý nó bằng một giải pháp từ năm 1985?

Các bước để có hệ thống context tốt hơn

Chúng ta đang loay hoay tiến dần đến việc quản lý context tốt hơn.

Nhưng phần lớn những gì chúng ta làm chỉ đủ để giúp LLM vượt qua rào cản context tiếp theo.

Giờ đây chúng ta đã đến một điểm mà context yếu kém chính là rào cản lớn nhất cho tiến bộ.

Điều này rất rõ khi so sánh:

• dự án greenfield (dự án mới hoàn toàn)
• với dự án đã tồn tại lâu

Các dự án lâu năm có nhiều context thực tế phức tạp hơn rất nhiều.

Nếu chúng ta ưu tiên viết và quản lý context như một mục tiêu chính, hiệu quả của LLM sẽ tăng lên đáng kể.

Viết tài liệu thực ra là phần dễ.

Những thách thức thực sự là:

• đưa context vào đúng nơi
• quản lý context một cách đáng tin cậy

Hầu hết chúng ta đang ở khoảng Stage 5 trong quá trình tiến hóa context — khá tốt rồi.

Nhưng để đến Stage 8, chúng ta phải thay đổi cách nghĩ về context:

Context phải thuộc về tổ chức

Chúng ta dùng tài liệu context để sinh code và lưu trong codebase, nhưng thực ra chúng không phải là một phần của codebase.

Phần lớn context mà engineer đưa cho LLM đến từ:

• chi tiết dự án
• các quyết định được đưa ra bởi những người không phải engineer

Thay vì truyền tay và chắt lọc context một cách ngẫu nhiên, chuyên gia domain nên trực tiếp quản lý context của họ.

Đây là rào cản lớn của Stage 7 — và nó là một thay đổi tổ chức hơn là thay đổi kỹ thuật.

Context phải có thể điều hướng

Context cần có kiến trúc riêng và các mối quan hệ nội bộ, để:

• LLM
• và con người

có thể khám phá context như một mạng lưới thông tin liên kết, thay vì các tài liệu rời rạc.

Context phải có khả năng kết hợp

Context cần có cấu trúc phân cấp để làm rõ mối quan hệ giữa các phần.

Chúng ta xây dựng quy trình từ các khái niệm, và context cũng nên hoạt động tương tự:

• context khái niệm
• context quy trình
• context triển khai

Điều này giúp LLM điều hướng context một cách xác định (deterministic).

Context phải nhận thức được code (code-aware)

“Doc rot” là vấn đề lớn vì không có tín hiệu rõ ràng khi tài liệu lỗi thời.

Context liên quan đến codebase đặc biệt dễ lỗi thời vì mỗi commit có thể thay đổi context.

Giải pháp là:

liên kết trực tiếp context về codebase với chính code đó.

Điều này tạo ra vòng phản hồi giúp code và context luôn đồng bộ.

Context-Driven Development (CDD)

Việc tập trung vào context thay vì code có thể nghe giống một thứ “nice-to-have” làm chậm tiến độ.

Nhưng thực tế nó tạo ra một số kết quả rất thú vị.

Tài liệu code-aware tạo ra mối quan hệ hai chiều, biến context thành:

một lớp trừu tượng thực sự nằm phía trên code.

Điều này có tác động lớn đến cách chúng ta:

• hiểu sản phẩm
• điều hướng code
• sửa đổi hệ thống

Khi tài liệu được liên kết trực tiếp với code:

• LLM có thể phát hiện sự không nhất quán giữa tài liệu và code
• và thậm chí tự động cập nhật tài liệu hoặc code

Việc chỉnh sửa tài liệu context để sinh code có thể nghe giống vibe coding.

Nhưng thực ra nó gần như đối lập hoàn toàn.

Khi bạn vibe code, bạn:

• mô tả thứ bạn muốn xây
• xem output / thử ứng dụng
• lặp lại

Bạn tiến sản phẩm từng bước dựa trên hiểu biết cá nhân của bạn về trạng thái hiện tại của sản phẩm.

Nếu bạn mất dấu code đang hoạt động thế nào, bạn có thể hỏi LLM để giải thích.

Nhưng cách này cuối cùng sẽ phá vỡ mô hình tinh thần của bạn, vì bạn đang xây hệ thống mà không có nguồn sự thật rõ ràng.

Với CDD, context được liên kết chặt chẽ với codebase.

Mọi chi tiết hoặc abstraction đều có thể được xem trong:

• tài liệu
• hoặc code

Tài liệu context không chỉ là bản tóm tắt hành vi.

Chúng là công cụ chức năng kết nối:

• ý định
• với cách triển khai.

Context docs trở thành nguồn sự thật cho các quyết định và yếu tố bên ngoài ảnh hưởng đến thiết kế sản phẩm.

Bằng cách liên kết context với code, chúng ta luôn giữ được cái nhìn rõ ràng về cấu trúc codebase và có thể nhảy thẳng vào code để chỉnh sửa hoặc kiểm tra bất cứ lúc nào.

Cuối cùng, sự hiểu biết của con người vẫn là ưu tiên hàng đầu.