CLAUDE.md cũ chỉ có 1 dòng — giờ là hướng dẫn đầy đủ cho AI agent
File CLAUDE.md của project VietConnect chỉ chứa `@AGENTS.md` — một delegation đến file khác với 2 quy tắc đơn giản. Sau khi đọc toàn bộ 10 docs trong `docs/`, chúng tôi viết lại thành một AI agent guide tự chứa: session ritual, task router, 5 critical gotchas, feature status quick ref, security checklist, và open questions. Mục tiêu: AI agent mở file này thay vì phải đọc 5 docs khác nhau.
ProjectVietConnectFileCLAUDE.mdThay đổi1 dòng → ~200 dòngDate2026-06-13
ReasoningLập luận
6-layer thinking chainChuỗi tư duy 6 tầng
L1
Raw requestYêu cầu gốc
"review kĩ và tạo 1 file claude.md hưu ích, hiệu quả cho project"
L2
Reframe — what was really neededDiễn giải lại — nhu cầu thật
Yêu cầu thực sự: tạo một file mà AI agent đọc vào đầu mỗi session và có đủ context để làm việc đúng — biết stack, biết gotchas, biết feature nào LIVE vs STUB, biết docs nào cần đọc cho task nào — mà không phải mở thêm 5 file khác. Không phải viết lại cả codebase vào 1 file, mà là viết entry point + quick ref + router.
L3
ConstraintsRàng buộc
Constraints phát hiện được:
- CLAUDE.md cũ = 1 dòng @AGENTS.md (AGENTS.md chỉ có 2 quy tắc: đọc Next.js docs, đọc docs/INDEX.md)
- Project có docs/ rất phong phú (10 files) — đây là canonical, không nên duplicate vào CLAUDE.md
- Next.js version là 16.2.1 (không phải 13/14/15 như training data của AI) — đây là critical gotcha
- Tailwind v4 không có tailwind.config — AI thường tự tạo file này
- Brand color có 4 nguồn mâu thuẫn nhau — cần cảnh báo rõ
- Project pre-revenue (Stripe placeholder price IDs) — context quan trọng
- database.ts hand-maintained (không phải Supabase-generated) — thường bị bỏ qua
L4
Options weighedCác lựa chọn cân nhắc
Options được xem xét:
1. **Giữ @AGENTS.md delegation + mở rộng AGENTS.md** — cost: vẫn cần 2 file hops, AGENTS.md không phải nơi AI agent tìm đầu tiên
2. **CLAUDE.md tự chứa + full architecture inline** — cost: duplicate hết docs/architecture.md, drift risk khi code thay đổi
3. **CLAUDE.md = task router + critical gotchas + quick ref** *(chosen)* — cost: vẫn cần mở docs cho depth, nhưng 80% tasks có đủ
4. **CLAUDE.md chỉ có rules** — cost: quá mỏng, AI vẫn phải đọc nhiều docs
L5
Principle invokedNguyên tắc áp dụng
"Single source of truth: docs/ là canonical, CLAUDE.md là entry point và quick ref — route đến docs, đừng duplicate."
L6
Pick + recognition signalLựa chọn + dấu hiệu nhận biết
**Pick:** CLAUDE.md self-contained với TL;DR → session ritual → task router → 5 critical gotchas → stack → dir map → feature status → priorities → commands → conventions → security checklist → WP gate → open questions.
**Rejected:** @AGENTS.md delegation (quá mỏng), inline full architecture (duplicate + drift risk).
**Recognition signal:** Khi một project có docs/ phong phú, CLAUDE.md nên là smart router + gotcha list, không phải encyclopedia.
DecisionsQuyết định
Layered decision cardsCác quyết định theo tầng
Self-contained vs delegation (@AGENTS.md)
L1File cũ chỉ có `@AGENTS.md` — delegate hoàn toàn
L2AGENTS.md có 2 rules quan trọng nhưng AI agent khi đọc CLAUDE.md muốn có context ngay, không phải nhảy sang file khác
L3AGENTS.md có 2 rules thực sự cần giữ — phải port vào CLAUDE.md
L4Giữ delegation / Self-contained / Hybrid (@AGENTS.md + thêm vào)
L5Ít hop = ít friction: AI agent đọc 1 file, hiểu đủ để bắt đầu
L6Self-contained. 2 rules của AGENTS.md được port vào phần gotchas. AGENTS.md không bị xóa nhưng CLAUDE.md không còn delegate sang nó.
Bao nhiêu detail là đủ?
L1Viết feature status vào CLAUDE.md hay chỉ link đến product.md?
L2AI agent cần biết ngay Stripe có hoạt động không, i18n có thật không — không phải mở thêm file. Nhưng nếu copy hết product.md thì CLAUDE.md sẽ drift khỏi source of truth.
L3product.md là 60 dòng feature table. Nếu copy hết, khi code thay đổi phải update 2 chỗ.
L4Copy toàn bộ feature table / Chỉ link pointer / Quick ref bucket (LIVE/PARTIAL/STUB) + link cho full
L5Quick ref giảm context switching mà không tạo duplicate drift risk
L6Quick ref bullets theo status bucket + link đến product.md cho full inventory.
Có đưa brand tokens inline không?
L1Brand color mismatch 4-way — cảnh báo trong CLAUDE.md hay chỉ link đến brand.md?
L2Đây là gotcha thực sự: AI agent viết code Tailwind hay dùng teal-600 vì đó là màu teal mặc định. Nếu không cảnh báo rõ, lỗi sẽ tiếp tục.
L3brand.md có full explanation nhưng AI agent viết code không nhất thiết mở brand.md.
L4Chỉ link brand.md / Copy full 4-way mismatch table / Inline token table + warning + link cho context
L5Gotcha cần inline — nếu bỏ vào đây thì AI agent mới thấy; nếu chỉ link thì bị bỏ qua
L6Inline token table (--vc-*) + bold warning đừng dùng teal-600/red-600 + link brand.md cho full context.
FilesTệp
Artifact mapBản đồ tệp tạo ra
| PathĐường dẫn | WhatLà gì | Who reads itAi dùng |
|---|---|---|
CLAUDE.md | AI agent guide tự chứa: session ritual, task router, 5 critical gotchas, stack, dir map, feature status, priorities, commands, security checklist, open questions | Đọc đầu mỗi session bởi AI agent (Claude Code, Cursor, v.v.) |
docs/INDEX.md | Knowledge base index — vẫn là canonical, CLAUDE.md route đến đây | Không thay đổi |
AGENTS.md | Vẫn còn (không bị xóa) nhưng CLAUDE.md không còn delegate sang nó | Có thể archive sau |
Self-testTự kiểm tra
Check your understanding
Tại sao CLAUDE.md không copy toàn bộ nội dung từ docs/architecture.md vào?
Tại sao brand tokens (--vc-blue, --vc-wine, v.v.) được đưa inline vào CLAUDE.md thay vì chỉ link đến docs/brand.md?
Trong project này, src/types/database.ts khác với file types thông thường của Supabase như thế nào, và tại sao điều này quan trọng?
Mastery checklist — tick what you can explain unpromptedBảng tự đánh giá — tích những gì bạn tự giải thích được