Mở đầu
Trong nhiều năm, quy trình phát triển phần mềm truyền thống (Waterfall) luôn bắt đầu bằng việc viết tài liệu thật chi tiết:
- Project Overview
- Product Requirements Document (PRD)
- System Architecture Document (SAD)
- Technical Design Document (TDD)
- Detailed Design Document (DDD)
Sau đó mới bắt đầu lập trình.
Cách làm này vẫn phù hợp với một số dự án lớn có quy trình kiểm soát nghiêm ngặt. Tuy nhiên, khi bước vào kỷ nguyên AI-assisted Development với Claude Code, ChatGPT, Cursor, GitHub Copilot Agent hay Gemini CLI, mô hình này bộc lộ một nhược điểm rất lớn:
Tài liệu luôn cũ nhanh hơn code.
Khi AI đọc một tài liệu thiết kế đã lỗi thời, AI sẽ triển khai theo tài liệu thay vì theo trạng thái thực tế của hệ thống. Điều này khiến AI tạo ra code sai, kiến trúc lệch hướng và làm giảm đáng kể hiệu quả của AI Agent.
Đó là lý do nhiều nhóm phát triển hiện đại đang chuyển sang một tư duy mới:
Docs-as-Index, Code-as-Truth
Đây là mô hình mình đang áp dụng tại CocoSoft cho các dự án AI-first.
Vấn đề của bộ tài liệu truyền thống
Một dự án thường có cấu trúc như sau:
Project Overview.docx
PRD.docx
SAD.docx
TDD.docx
DDD.docx
Coding Standards.docx
Git Workflow.docx
Deployment Guide.docx
Nhìn qua thì rất đầy đủ.
Nhưng sau vài tháng phát triển sẽ xảy ra những vấn đề quen thuộc:
- thêm tính năng nhưng quên sửa PRD
- đổi database nhưng SAD chưa cập nhật
- refactor kiến trúc nhưng TDD vẫn giữ thiết kế cũ
- DDD khác hoàn toàn giao diện hiện tại
- AI đọc tài liệu cũ rồi sinh code sai
Cuối cùng xuất hiện hai “phiên bản sự thật”:
Version 1
Tài liệu
Version 2
Source Code
Và gần như 100% đội ngũ sẽ tin vào code hơn tài liệu.
Code mới là nguồn sự thật duy nhất (Single Source of Truth)
Trong phát triển hiện đại, đặc biệt là AI-assisted Development, nên xem:
Source Code là nguồn dữ liệu chính xác nhất.
Tài liệu không nên cố mô tả toàn bộ chi tiết của hệ thống.
Thay vào đó, tài liệu chỉ nên trả lời những câu hỏi mà code không thể tự trả lời.
Ví dụ:
- Tại sao chọn PostgreSQL?
- Vì sao không dùng Firebase?
- Mục tiêu của sản phẩm là gì?
- Người dùng mục tiêu là ai?
- Kiến trúc được chia thành những service nào?
- Quyết định kỹ thuật nào đã được thống nhất?
Những thông tin này AI không thể suy luận hoàn toàn từ source code.
Đó chính là giá trị của tài liệu.
Docs-as-Index là gì?
Thay vì biến tài liệu thành bản sao của code, hãy xem tài liệu như bản đồ (Index) của dự án.
Tài liệu chỉ đóng vai trò:
- giới thiệu
- định hướng
- giải thích
- dẫn đường
Còn mọi logic triển khai đều nằm trong source code.
Có thể hình dung như sau:
Documentation
│
▼
Architecture
│
▼
Source Code
│
▼
Runtime
AI sẽ đọc tài liệu để hiểu bối cảnh, sau đó đọc code để hiểu chi tiết.
Bộ tài liệu tối giản cho AI-first Development
Thay vì duy trì 7–10 tài liệu khác nhau, chỉ cần khoảng 4–5 tài liệu thực sự có giá trị.
1. product.md
Đây là tài liệu mô tả sản phẩm.
Bao gồm:
- sản phẩm giải quyết vấn đề gì
- đối tượng người dùng
- mục tiêu
- MVP
- roadmap
- danh sách tính năng
Không cần mô tả UI từng màn hình.
Không cần mô tả API.
Không cần mô tả database.
Chỉ cập nhật khi sản phẩm có milestone lớn.
2. architecture.md
Đây là tài liệu quan trọng nhất.
Bao gồm:
- Tech Stack
- System Architecture
- Database
- Authentication
- Storage
- Queue
- Cache
- Service Boundary
- Quyết định kiến trúc
Điểm quan trọng nhất là:
Không chỉ ghi làm gì.
Mà phải ghi:
Vì sao lại chọn cách đó.
Ví dụ:
Database:
PostgreSQL
Reason:
- ACID
- dễ mở rộng
- nhiều ORM hỗ trợ
- phù hợp dữ liệu quan hệ
Phần “Reason” chính là thứ AI rất cần.
3. deployment.md
Đây là tài liệu ít thay đổi nhất.
Bao gồm:
- môi trường
- server
- Docker
- CI/CD
- backup
- domain
- SSL
- monitoring
Đây là tài liệu rất đáng duy trì.
4. AGENTS.md (hoặc CLAUDE.md)
Đây là file cực kỳ quan trọng khi làm việc với Claude Code.
Claude sẽ tự đọc file này mỗi phiên làm việc.
Trong file chỉ nên chứa:
- coding convention
- project structure
- workflow
- cách đặt tên
- quy tắc commit
- quy tắc tạo migration
- quy tắc test
- quy trình review
Không nên viết dài.
Mọi quy tắc có thể tự động hóa thì nên để tooling xử lý.
Ví dụ:
- ESLint
- Prettier
- Husky
- Commitlint
Tooling luôn đáng tin hơn tài liệu.
5. ADR (Architecture Decision Record)
Đây là phần rất nhiều dự án bỏ qua.
Ví dụ:
docs/decisions/
0001-use-supabase.md
0002-use-monorepo.md
0003-nextjs-app-router.md
Mỗi file chỉ khoảng 1 trang.
Ví dụ:
Decision
Use Supabase
Status
Accepted
Reason
Realtime
Auth
Storage
Fast MVP
Date
2026-07-17
Điểm quan trọng:
ADR gần như không sửa.
Nó là lịch sử quyết định.
Nhờ đó người mới hoặc AI sẽ không phải tranh luận lại những vấn đề đã được thống nhất.
Vì sao nên bỏ Detailed Design Document (DDD)?
Đây là tài liệu lỗi thời nhanh nhất.
Ví dụ:
DDD viết:
Button nằm góc phải.
Hai tuần sau designer đổi sang góc trái.
Một tháng sau UI đổi hoàn toàn.
DDD trở thành tài liệu sai.
Trong khi AI lại đọc đúng tài liệu sai đó.
Đó là nguyên nhân của rất nhiều lỗi khi AI hỗ trợ lập trình.
Thay DDD bằng Plan Mode
Thay vì viết DDD trước khi lập trình.
Mỗi feature nên có một kế hoạch ngắn.
Ví dụ:
plan-user-auth.md
plan-payment.md
plan-chat.md
File chỉ gồm:
- Goal
- Scope
- Steps
- Risk
- Acceptance Criteria
Sau khi feature hoàn thành:
- có thể xóa
- hoặc lưu lại để tham khảo
Đây gọi là ephemeral documentation.
Tài liệu chỉ tồn tại trong quá trình phát triển.
Không cần bảo trì suốt đời.
Quy trình phát triển tối ưu với AI
Một workflow hiệu quả có thể như sau:
Ý tưởng
↓
product.md
↓
architecture.md
↓
Plan Mode
↓
AI sinh code
↓
Review
↓
Commit
↓
ADR (nếu có quyết định mới)
Quy trình này giúp AI luôn làm việc với thông tin mới nhất và giảm thiểu rủi ro từ tài liệu lỗi thời.
Chuẩn hóa thành Claude Code Skill
Nếu mỗi lần tạo dự án mới đều phải tạo lại cấu trúc thư mục, tài liệu và quy trình, bạn đang lặp lại cùng một công việc.
Thay vào đó, hãy đóng gói toàn bộ workflow thành một Claude Code Skill.
Ví dụ:
~/.claude/skills/new-project/
Skill này có thể tự động:
- tạo cấu trúc thư mục
- sinh product.md
- sinh architecture.md
- tạo AGENTS.md
- tạo deployment.md
- tạo thư mục ADR
- tạo template Plan Mode
Khi bắt đầu dự án mới, chỉ cần gọi một lệnh là toàn bộ nền tảng tài liệu đã sẵn sàng.
Điều này giúp chuẩn hóa quy trình giữa các dự án và đảm bảo AI luôn làm việc theo cùng một tiêu chuẩn.
Kết luận
Trong thời đại AI Agent, mục tiêu của tài liệu không còn là mô tả mọi chi tiết của hệ thống.
Thay vào đó:
- Code là nguồn sự thật duy nhất (Code-as-Truth).
- Tài liệu là bản đồ định hướng (Docs-as-Index).
- Thiết kế chi tiết nên được tạo theo từng feature và có thể chỉ tồn tại tạm thời (Ephemeral Documentation).
- Những quyết định kiến trúc quan trọng nên được lưu dưới dạng ADR thay vì chỉnh sửa liên tục một tài liệu lớn.
Bằng cách giảm số lượng tài liệu nhưng tăng chất lượng của từng tài liệu, cả con người và AI đều có thể hiểu dự án nhanh hơn, triển khai chính xác hơn và giảm đáng kể chi phí bảo trì tài liệu theo thời gian.
Đó cũng là một trong những nền tảng quan trọng để xây dựng quy trình phát triển phần mềm theo hướng AI-First Engineering.
