Claude Code Workflow — Framework tổ chức dự án phân tầng
Claude Code Workflow — Framework tổ chức dự án Claude Code với cấu trúc thư mục phân tầng 3 Layer, giúp AI hiểu và vận hành dự án hiệu quả hơn.
Claude Code mạnh nhưng không có cấu trúc tổ chức rõ ràng, nó sẽ: Quên context giữa các session, không biết khi nào nên dùng skill nào, và thiếu hệ thống lưu trữ progress một cách có hệ thống.
Claude Code Workflow là framework tổ chức thư mục phân tầng với 3 Layer, biến Claude từ "AI aide" thành "AI team member" hiểu rõ dự án, tự động lưu tiến trình, và biết chính xác cần làm gì trong mọi tình huống.
Cấu trúc thư mục tổng quan
claude-code-workflow/
├── CLAUDE.md # Entry point – Claude đọc đầu tiên
├── README.md
├── rules/ # Layer 0: Always loaded
│ ├── behaviors.md # Core behavior rules
│ ├── skill-triggers.md # Khi nào tự invoke skill nào
│ └── memory-flush.md # Auto-save triggers
├── docs/ # Layer 1: On-demand reference
│ ├── agents.md # Multi-model collaboration
│ ├── behaviors-extended.md # Extended rules
│ ├── behaviors-reference.md # Detailed operation guides
│ ├── content-safety.md # AI hallucination prevention
│ ├── scaffolding-checkpoint.md # "Có thực sự cần self-host?" checklist
│ └── task-routing.md # Model tier routing + cost
├── memory/ # Layer 2: Working state
│ ├── today.md # Daily session log
│ ├── projects.md # Cross-project status
│ ├── goals.md # Week/month/quarter goals
│ └── active-tasks.json # Cross-session task registry
├── skills/ # Reusable skill definitions
│ ├── session-end/SKILL.md
│ ├── verification-before-completion/SKILL.md
│ ├── systematic-debugging/SKILL.md
│ ├── planning-with-files/SKILL.md
│ └── experience-evolution/SKILL.md
├── agents/ # Custom agent definitions
│ ├── pr-reviewer.md
│ ├── security-reviewer.md
│ └── performance-analyzer.md
└── commands/ # Custom slash commands
├── debug.md
├── deploy.md
├── exploration.md
└── review.mdPhần 1: Kiến trúc 3 Layer
Bí quyết của workflow này là 3 Layer tách biệt, mỗi layer có mục đích và cơ chế load riêng.
Layer 0 — Rules (Always Loaded)
Đây là các quy tắc luôn luôn được Claude load khi bắt đầu session mới. Không cần invoke, không cần ask — Claude tự động đọc.
Nội dung chính:
behaviors.md: Các hành vi cốt lõi — cách debug, commit convention, routing task đến agent/skill phù hợp. Đây là "DNA behavior" của Claude trong dự án.
skill-triggers.md: Định nghĩa khi nào Claude nên tự động invoke skill nào. Ví dụ: khi gặp lỗi → trigger
systematic-debugging, khi end session → triggersession-end.memory-flush.md: Các trigger tự động lưu progress — không bao giờ mất dữ liệu giữa session. Ví dụ: mỗi 10 lần edit file → flush memory, trước khi compact → save state.
Layer 1 — Docs (On-demand Reference)
Các tài liệu tham khảo chỉ load khi Claude cần. Claude tự quyết định khi nào cần đọc dựa trên context hiện tại.
Nội dung chính:
agents.md: Framework cho multi-model collaboration — khi nào dùng Claude Opus, khi nào dùng Sonnet, và cách các agent phối hợp.
behaviors-extended.md: Rules mở rộng — knowledge base, associations, domain-specific rules cho dự án.
behaviors-reference.md: Hướng dẫn vận hành chi tiết — step-by-step cho từng loại task.
content-safety.md: Hệ thống ngăn AI hallucination — verify before claim, reference sources.
scaffolding-checkpoint.md: Checklist "Có thực sự cần self-host?" — prevents over-engineering.
task-routing.md: Model tier routing + cost comparison — chọn đúng model cho đúng task.
Layer 1 không nên quá lớn. Nếu document vượt quá 200 dòng, hãy tách thành nhiều file nhỏ hơn hoặc summarizes lại. Claude hoạt động tốt nhất với context ngắn và tập trung.
Layer 2 — Memory (Working State)
Đây là working memory templates — nơi Claude lưu và đọc trạng thái làm việc thực tế. Khác với Layer 0 và 1 (static), Layer 2 thay đổi liên tục trong quá trình làm việc.
Nội dung chính:
today.md: Daily session log — ghi lại những gì đã làm trong ngày. Khi bắt đầu session mới, Claude đọc file này để "nhớ lại" context.
projects.md: Cross-project status overview — tổng quan trạng thái các dự án đang làm.
goals.md: Week/month/quarter goals — mục tiêu ngắn hạn và dài hạn.
active-tasks.json: Cross-session task registry — registry các task đang chờ, đã hoàn thành, và ưu tiên.
Load: Luôn luôn, tự động
Thay đổi: Rất ít (stable rules)
Mục đích: Định hình behavior
Ví dụ: Debug flow, commit convention, routing rules
Load: Khi Claude cần tham khảo
Thay đổi: Thỉnh thoảng cập nhật
Mục đích: Kiến thức chuyên sâu
Ví dụ: Agent framework, safety rules, cost optimization
Load: Mỗi session start
Thay đổi: Liên tục trong quá trình làm việc
Mục đích: Lưu trạng thái thực tế
Ví dụ: Daily log, project status, active tasks
Phần 2: Skills
Skills là các workflow tái sử dụng được define trong thư mục skills/. Mỗi skill giải quyết một loại task cụ thể và được Claude invoke khi phù hợp.
session-end — Auto Wrap-up
Vấn đề: Claude thường kết thúc session mà không save progress, không commit, không record lại đã làm gì.
Giải pháp: Skill session-end tự động thực hiện 3 bước khi end session:
Save progress — Ghi lại vào
memory/today.mdnhững gì đã làmCommit — Stage và commit các thay đổi với conventional commit message
Record — Cập nhật
memory/active-tasks.jsonvàmemory/projects.md
verification-before-completion — "Run the Test. Read the Output. THEN Claim."
Vấn đề: Claude có xu hướng claim "đã xong" mà chưa thực sự verify.
Giải pháp: Skill này enforce một nguyên tắc cứng: Run the test → Read the output → THEN claim done.
Nguyên tắc: Không bao giờ nói "done" nếu chưa chạy test và đọc output
Áp dụng: Cho mọi task có test suite — bug fix, feature, refactor
Lợi ích: Loại bỏ hoàn toàn "false positive" — Claude nói xong nhưng thực tế chưa xong
systematic-debugging — 5-Phase Debugging
Vấn đề: Claude thường nhảy thẳng vào fix mà chưa hiểu root cause.
Giải pháp: Skill enforce 5 phase debugging có kỷ luật:
Kiểm tra memory/ và today.md — đã gặp bug này chưa? Có context gì từ session trước?
Đọc actual error message. Đừng guess — đọc output thật kỹ.
Trace ngược từ error đến source. Không fix symptom — fix root cause.
Minimal changes. Chỉ sửa những gì cần sửa.
Ghi lại findings vào memory/ để lần sau không cần debug lại.
planning-with-files — File-based Planning
Vấn đề: Task phức tạp cần plan chi tiết, nhưng Claude thường lose track khi plan quá dài.
Giải pháp: Skill này giúp Claude tạo file plan riêng thay vì giữ trong context.
Tác dụng: Plan nằm trong file, không chiếm context window
Khi dùng: Task có hơn 3 bước, refactor lớn, migration
Ưu điểm: Claude có thể "quên" plan trong context nhưng không bao giờ quên plan trong file
experience-evolution — Auto Accumulate Knowledge
Vấn đề: Claude học được nhiều điều về dự án trong quá trình làm việc nhưng không lưu lại.
Giải pháp: Skill tự động tích lũy project knowledge vào memory.
Knowledge domains: Architecture decisions, coding patterns, gotchas, performance tips
Storage: Ghi vào
memory/projects.mddưới các mục tương ứngGiá trị: Sau 1 tháng, Claude hiểu dự án sâu hơn bất kỳ team member mới nào
Phần 3: Agents & Commands
Custom Agents
Agents là các AI specialist được define sẵn với role và scope cụ thể. Khi cần phân tích chuyên sâu, Claude sẽ delegate cho agent phù hợp.
Custom Commands
Commands là slash commands mà bạn có thể gọi trực tiếp trong Claude Code.
/debug
Bắt đầu systematic debugging
Khi gặp bug, cần debug có kỷ luật
/deploy
Pre-deployment checklist
Trước khi deploy lên production
/exploration
CTO challenge trước khi coding
Trước khi implement feature mới
/review
Chuẩn bị code review
Sau khi hoàn thành feature/fix
Phần 4: Cách áp dụng
Bước 1: Tạo cấu trúc thư mục
Bước 2: Tạo CLAUDE.md entry point
CLAUDE.md là file Claude đọc đầu tiên khi vào repo. Nó phải reference đến Layer 0 rules:
Bước 3: Tích hợp vào dự án hiện có
Không cần thiết phải tạo đầy đủ tất cả các file ngay. Bắt đầu với Layer 0 (rules/) và 1-2 skills quan trọng nhất (session-end, verification-before-completion). Mở rộng dần khi cần.
Tạo
CLAUDE.mdvới project overviewTạo
rules/behaviors.mdvới core rulesTạo
memory/today.mdtemplateTạo skill
session-endcơ bản
Thêm
rules/skill-triggers.mdThêm
rules/memory-flush.mdThêm
verification-before-completionskillThêm
systematic-debuggingskill
Thêm Layer 1 docs khi cần
Tạo custom agents
Tạo custom commands
Thêm
planning-with-filesvàexperience-evolution
Workflow sử dụng hàng ngày
Bắt đầu session: Claude tự động đọc
CLAUDE.md→ Layer 0 rules →memory/today.mdLàm việc: Claude tự động invoke skills theo
skill-triggers.md, delegate cho agents khi cầnKết thúc session: Skill
session-endtự động save progress, commit, và recordSession tiếp theo: Claude đọc
memory/today.mdđể "nhớ lại" context từ session trước
Kết luận
Claude Code Workflow không phải là framework phức tạp — nó chỉ tổ chức lại những gì Claude cần biết thành cấu trúc rõ ràng:
Layer 0 đảm bảo Claude luôn luôn hành xử đúng
Layer 1 đảm bảo Claude biết tìm ở đâu khi cần kiến thức chuyên sâu
Layer 2 đảm bảo Claude không bao giờ mất progress
Skills đảm bảo Claude làm đúng quy trình cho từng loại task
Agents & Commands đảm bảo Claude biết delegate đúng việc
Khi nào nên dùng workflow này?
Dự án có nhiều session kéo dài (không chỉ 1 lần ask rồi xong)
Team muốn Claude hiểu rõ coding conventions và architecture
Cần audit trail — Claude đã làm gì, khi nào, kết quả ra sao
Muốn ngăn Claude "hallucinate" và claim done mà chưa verify
Mẹo: Bắt đầu nhỏ. Tạo CLAUDE.md + rules/behaviors.md + memory/today.md + 1 skill session-end là đủ để thấy hiệu quả ngay lập tức.
Tài liệu tham khảo:
Cập nhật lần cuối