Day 05 - CLAUDE.md chuẩn cho project

1. Mục tiêu bài học

Sau khoảng 2 tiếng, học viên có thể:

• Giải thích được vì sao Claude Code có thể "quên" convention, command, kiến trúc, hoặc quyết định đã thống nhất giữa các session.
• Xem CLAUDE.md như onboarding document cho AI: ngắn, chính xác, dễ cập nhật, và được dùng lại trong session mới.
• Biết đặt project instructions ở CLAUDE.md hoặc .claude/CLAUDE.md theo tài liệu Claude Code hiện hành.
• Biết dùng /init nếu CLI version đang dùng hỗ trợ, hoặc tạo thủ công CLAUDE.md bằng prompt có kiểm soát, sau đó review như một artifact của team.
• Viết CLAUDE.md cho project taskflow-ai gồm stack, architecture, commands, coding conventions, testing rules, security rules, và workflow an toàn.
• Kiểm tra session mới có load đúng project context hay không, không chỉ tin rằng file đã tồn tại là đủ.

2. Bối cảnh thực tế

Trong công việc thật, vấn đề thường không phải Claude Code không biết viết code. Vấn đề là Claude không luôn có cùng mental model với team ở mọi session. Hôm nay bạn giải thích taskflow-ai dùng Fastify, route nằm trong apps/api, test chạy bằng Vitest, không dùng Jest. Ngày mai mở session mới, nếu không có project memory rõ ràng, Claude có thể lại đề xuất npm test, tạo thư mục src/controllers, hoặc thêm convention không tồn tại.

Claude Code có context window lớn nhưng context không phải trí nhớ vĩnh viễn. Một session mới cần được nạp lại chỉ dẫn quan trọng. Session dài có thể bị nhiễu bởi prompt cũ, diff cũ, log lỗi, hoặc các hướng đi đã bị loại. CLAUDE.md giải quyết phần này bằng cách đóng vai onboarding document cho AI: khi mở repo, Claude biết các rule cốt lõi trước khi lập plan hoặc sửa code.

Trong taskflow-ai, một CLAUDE.md tốt giúp Claude trả lời nhanh các câu hỏi như:

• Backend nằm ở đâu, frontend nằm ở đâu.
• Lệnh nào dùng để chạy dev server, typecheck, unit test, e2e test.
• Validation nên đặt ở service, route schema, hay component.
• Không được chạy command nào nếu chưa có xác nhận thủ công.
• Khi implement feature, phải plan trước, sửa nhỏ, chạy test, và không tự commit.

Không nên dùng CLAUDE.md để:

• Lưu secret, token, connection string, production credential, hoặc dữ liệu khách hàng.
• Nhét toàn bộ architecture document dài nhiều trang vào context mặc định.
• Ghi task tạm thời như "hôm nay sửa bug X" rồi quên xóa.
• Thay thế README, ADR, test, code review, hoặc security policy chính thức của team.
• Ép Claude làm theo rule chưa được team thống nhất.

3. Kiến thức nền

Claude Code hỗ trợ project memory thông qua file instruction. Theo tài liệu hiện hành, project instructions có thể nằm ở ./CLAUDE.md hoặc ./.claude/CLAUDE.md. Hai vị trí này đều phù hợp cho nội dung chia sẻ trong team và có thể commit vào source control. Nếu có cấu hình local hoặc plugin riêng cho từng developer, nên dùng file local trong .claude và đưa pattern local vào .gitignore.

Điểm cần phân biệt:

• CLAUDE.md: chỉ dẫn ngắn cho Claude về project. Đây là cheat sheet cho AI.
• README.md: tài liệu cho người mới, setup rộng hơn, có thể dài hơn và public hơn.
• .claude/settings.json: cấu hình hành vi Claude Code như permission mode mặc định hoặc tool permission. Đây không phải nơi viết architecture dài.
• Prompt trong session: chỉ dẫn cho task hiện tại. Không nên nhét rule lâu dài vào prompt lặp lại mỗi ngày.

Một CLAUDE.md chuẩn cho taskflow-ai nên trả lời 6 nhóm câu hỏi:

1. Stack: project dùng Node.js, TypeScript, backend Fastify hoặc NestJS, React + Vite, PostgreSQL, Redis, Vitest/Jest, Playwright, Docker Compose.
2. Architecture: thư mục chính, module boundary, flow request, nơi đặt validation, nơi đặt test.
3. Commands: lệnh dev, build, lint, typecheck, unit test, e2e test, migration, seed; ghi rõ chạy ở root hay package nào.
4. Coding conventions: style TypeScript, error handling, naming, dependency injection, component boundary, không tạo abstraction nếu chưa cần.
5. Testing rules: test nào bắt buộc trước khi đổi behavior, khi nào cần integration/e2e, không sửa test để hợp thức hóa bug.
6. Security rules: không đọc hoặc in .env, không dùng production data, không chạy destructive command, không tự commit, không tự push.

/init là điểm bắt đầu tốt nếu có trong CLI version đang dùng. Khi chạy trong repo, Claude Code có thể đọc cấu trúc project và viết CLAUDE.md với build commands, architecture, và conventions. Nhưng bản sinh tự động chỉ là draft. Developer vẫn phải review vì Claude có thể suy luận sai command, bỏ sót package, hoặc viết rule quá chung. Nếu slash command hoặc hành vi memory thay đổi, kiểm tra official docs hoặc chạy /help trong Claude Code thay vì dựa vào ghi nhớ cũ.

Lưu ý thêm: một số phiên bản Claude Code có khái niệm auto memory ngoài CLAUDE.md. Không nên viết bài học như thể auto memory luôn hoạt động giống nhau ở mọi môi trường. Với course này, coi CLAUDE.md hoặc .claude/CLAUDE.md là project instructions do team kiểm soát; mọi tính năng auto memory nên được xác nhận theo official docs và CLI version trước khi đưa vào workflow team.

Nguyên tắc thiết kế: CLAUDE.md nên ngắn như cheat sheet, không phải tài liệu tổng hợp. Tài liệu Claude Code khuyến nghị instruction cụ thể, có cấu trúc, và target dưới 200 dòng cho mỗi file. Nếu dài hơn hoặc phải cuộn quá nhiều, hãy chuyển phần mô tả sâu sang docs/architecture.md, docs/testing.md, hoặc ADR, rồi trong CLAUDE.md chỉ link tới tài liệu đó.

Ví dụ skeleton phù hợp cho taskflow-ai:

# CLAUDE.md

## Project
- `taskflow-ai` is a task management app for engineering teams.
- Use TypeScript across backend and frontend.

## Structure
- `apps/api`: backend API.
- `apps/web`: React + Vite frontend.
- `packages/shared`: shared types and validation helpers.
- `docker-compose.yml`: local PostgreSQL and Redis.

## Commands
- Root install: `pnpm install`
- API dev: `pnpm --filter api dev`
- Web dev: `pnpm --filter web dev`
- Typecheck: `pnpm typecheck`
- Unit tests: `pnpm test`
- E2E tests: `pnpm e2e`

## Workflow Rules
- Start risky tasks by asking for a written plan before editing.
- Read relevant files before editing.
- Keep changes small and explain diff after editing.
- Do not run destructive Git, Docker, or database commands without explicit confirmation.
- Do not commit or push unless the user asks.

Hãy xem skeleton trên là ví dụ, không phải chân lý. CLAUDE.md phải phản ánh repo thật. Nếu taskflow-ai dùng npm thay vì pnpm, hoặc dùng NestJS thay vì Fastify, file phải nói đúng điều đó.

4. Step-by-step thực hành

Mục tiêu thực hành: tạo CLAUDE.md cho taskflow-ai, review nội dung như senior developer, rồi mở session mới để kiểm tra Claude Code có load đúng context không.

Bước 1: Kiểm tra repo trước khi để Claude đọc

Chạy trong thư mục gốc taskflow-ai:

git status --short

Lệnh này cho biết working tree đang sạch hay có thay đổi chưa commit. Output kỳ vọng là rỗng hoặc chỉ gồm file bạn hiểu rõ. Rủi ro: nếu repo đang có thay đổi của bạn hoặc đồng đội, Claude có thể đọc và mô tả state tạm thời như convention chính thức.

Kiểm tra nhanh cấu trúc:

ls

Lệnh này liệt kê file và thư mục ở root. Output kỳ vọng có các file như package.json, apps, packages, docker-compose.yml, hoặc cấu trúc tương đương. Rủi ro thấp, đây là lệnh read-only.

Nếu dùng PowerShell:

Get-ChildItem

Lệnh này tương đương ls trên Windows PowerShell. Output kỳ vọng là danh sách entry ở root taskflow-ai.

Bước 2: Tạo draft bằng /init hoặc prompt thủ công

Mở Claude Code tại root taskflow-ai:

cd /path/to/taskflow-ai
claude

Lệnh này chuyển vào project rồi mở session Claude Code trong repo hiện tại. Output kỳ vọng là giao diện Claude sẵn sàng nhận prompt. Có thể dùng /help để xem slash commands được CLI version hiện tại hỗ trợ. Rủi ro: nếu mở nhầm thư mục cha hoặc thư mục con, CLAUDE.md có thể được tạo sai vị trí.

Trong Claude Code, chạy slash command:

/init

/init yêu cầu Claude đọc repo và tạo hoặc cập nhật CLAUDE.md, nếu slash command này có trong CLI version đang dùng. Output kỳ vọng là file instruction được tạo với commands, architecture, và conventions Claude suy luận từ repo. Rủi ro: bản draft có thể sai command hoặc quá dài; chưa được xem là approved.

Nếu muốn kiểm soát kỹ hơn, hoặc nếu /init không có trong CLI version hiện tại, dùng prompt tạo thủ công:

Hãy tạo CLAUDE.md cho taskflow-ai như một onboarding document cho AI.

Ràng buộc:
- Chỉ ghi thông tin có bằng chứng từ file trong repo.
- Nếu không chắc command nào đúng, ghi "verify before use" thay vì bịa.
- Giữ ngắn, target dưới 200 dòng, ưu tiên chỉ chứa rule Claude cần trong mọi session.
- Không đưa secret, endpoint production, hoặc dữ liệu nhạy cảm.
- Sau khi tạo, liệt kê file đã đọc và điểm nào còn cần tôi xác nhận.

Bước 3: Review draft như review code

Chạy trong root taskflow-ai:

git diff -- CLAUDE.md

Lệnh này chỉ xem diff của CLAUDE.md. Output kỳ vọng là một file Markdown ngắn, có section rõ ràng, không chứa secret, không chứa rule mơ hồ. Rủi ro: nếu chỉ đọc bản render trong editor mà không xem diff, bạn có thể bỏ sót đoạn Claude thêm quá rộng hoặc sai command.

Checklist review:

• Stack có đúng repo thật không.
• Commands có đúng package manager và thư mục chạy không.
• Architecture mô tả theo module hiện có, không bịa folder chưa tồn tại.
• Coding conventions có actionable rule, không chỉ "write clean code".
• Testing rules nêu đúng test runner và test scope.
• Security rules chặn secret, production data, destructive command, auto commit/push.
• File đủ ngắn để session mới không tốn context quá nhiều.

Bước 4: Chỉnh CLAUDE.md thành cheat sheet

Prompt chỉnh sửa gợi ý:

Review CLAUDE.md hiện tại như senior maintainer.

Mục tiêu:
- Giữ lại rule quan trọng cho Claude Code khi làm việc trong taskflow-ai.
- Xóa phần chung chung hoặc suy đoán không có bằng chứng.
- Chuẩn hóa thành các section: Project, Structure, Commands, Coding Conventions, Testing, Security, Workflow.
- Mỗi command phải ghi thư mục chạy và output kỳ vọng ngắn.
- Không sửa file nào ngoài `CLAUDE.md` hoặc `.claude/CLAUDE.md` nếu team đã chọn convention đó.

Sau khi Claude chỉnh, xem lại:

git diff --stat

Lệnh này cho biết tổng số file và dòng thay đổi. Output kỳ vọng: chỉ CLAUDE.md thay đổi. Rủi ro: nếu thấy file khác, dừng lại và review vì Day 05 chỉ cần sửa project instruction.

Nếu team chọn lưu project instructions ở .claude/CLAUDE.md, thay các lệnh diff tương ứng bằng path đó, ví dụ git diff -- .claude/CLAUDE.md.

Bước 5: Kiểm tra session mới có load context

Thoát session hiện tại, mở session mới ở root taskflow-ai:

cd /path/to/taskflow-ai
claude

Lệnh này mở Claude Code tại đúng project directory. Output kỳ vọng là Claude sẵn sàng chat; dùng /help nếu cần xác nhận commands hiện có. Rủi ro: nếu bạn mở sai directory, Claude sẽ không load đúng CLAUDE.md.

Không dùng claude --continue để kiểm tra một context mới sạch, vì lệnh này tiếp tục session gần nhất trong thư mục hiện tại và có thể mang theo hội thoại cũ. Dùng claude --resume hoặc /resume khi mục tiêu là chọn lại một session cũ cụ thể.

Không cần bật claude --permission-mode acceptEdits cho bước kiểm tra context. Theo docs hiện hành, acceptEdits cho phép Claude tạo/sửa file và auto-approve một số command filesystem phổ biến trong working directory. .claude/settings.json có thể đặt permissions.defaultMode là auto, nhưng chỉ nên làm sau khi team thống nhất guardrails và đã kiểm tra official docs/CLI version đang dùng.

Gửi prompt kiểm tra:

Không sửa file.
Hãy cho biết bạn đang hiểu gì về project taskflow-ai từ project instructions.

Trả lời ngắn:
- Stack chính.
- 5 command quan trọng và thư mục chạy.
- 5 rule workflow/security bắt buộc.
- Nếu không thấy CLAUDE.md hoặc không chắc, nói rõ thay vì đoán.

Kết quả tốt: Claude nhắc đúng stack, đúng command, đúng rule security/workflow từ CLAUDE.md. Kết quả chưa đạt: Claude trả lời chung chung, sai package manager, không biết command, hoặc không nói được rule security. Khi đó kiểm tra lại vị trí file, độ dài file, và session có mở đúng root không.

Bước 6: Rollback nếu draft sai

Nếu CLAUDE.md đã được Git track và bạn muốn bỏ toàn bộ thay đổi trong file đó:

git restore -- CLAUDE.md

Lệnh này đưa CLAUDE.md về trạng thái trong commit hiện tại. Output thường không có gì nếu thành công. Rủi ro: mất toàn bộ thay đổi chưa commit trong file, kể cả phần bạn tự sửa. Chỉ dùng khi bạn chắc thay đổi trong file này là của mình hoặc đã được đồng đội xác nhận.

Nếu CLAUDE.md là file mới chưa track và bạn chắc chắn muốn xóa:

rm CLAUDE.md

Lệnh này xóa file ở thư mục hiện tại. Chỉ chạy sau khi git status --short xác nhận đúng file mới do bạn tạo. Rủi ro: xóa nhầm nếu bạn đang đứng sai thư mục hoặc xóa file người khác vừa tạo.

Trên PowerShell:

Remove-Item -LiteralPath .\CLAUDE.md

Lệnh này xóa đúng file theo literal path. Rủi ro tương tự: chỉ dùng khi bạn chắc đang ở root taskflow-ai.

5. Prompt mẫu nên dùng

Prompt khám phá codebase

Bạn đang ở repo taskflow-ai. Hãy khảo sát repo để chuẩn bị viết CLAUDE.md.

Yêu cầu:
- Chỉ đọc file, chưa sửa gì.
- Nêu rõ file đã đọc.
- Xác định stack, cấu trúc thư mục, command trong package.json, test runner, Docker Compose nếu có.
- Nếu thông tin nào không có bằng chứng, đánh dấu "cần xác nhận".

Prompt lập plan

Lập plan tạo CLAUDE.md cho taskflow-ai.

Ràng buộc:
- Không implement trong bước này.
- Đề xuất section và nội dung chính cho từng section.
- Mỗi section phải có lý do tồn tại.
- Chỉ đưa rule hữu ích cho session Claude Code mới.
- Giữ file dưới 200 dòng và dễ scan như cheat sheet.

Prompt implement

Tạo hoặc cập nhật CLAUDE.md theo plan đã duyệt.

Giới hạn:
- Chỉ sửa file CLAUDE.md ở root repo.
- Không sửa README.md, package.json, source code, test, hoặc config.
- Không chạy npm install, migration, git add, git commit, git reset, git clean, hoặc lệnh xóa file.
- Sau khi sửa, tóm tắt diff và liệt kê điểm nào cần tôi xác nhận thủ công.

Prompt review

Review CLAUDE.md hiện tại như senior engineer chuẩn bị dùng trong team.

Tập trung:
- Có command nào sai hoặc thiếu thư mục chạy không.
- Có rule nào quá chung chung hoặc không actionable không.
- Có thông tin nhạy cảm, endpoint production, hoặc secret pattern không.
- Có làm tăng context/cost quá mức không.
- Có rule nào dễ khiến Claude sửa quá rộng không.
Không sửa file trong bước review này.

Prompt kiểm tra session mới

Đây là session mới trong taskflow-ai. Không đọc thêm file nếu chưa cần.

Hãy trả lời dựa trên project instructions đã load:
- Project này dùng stack gì?
- Khi sửa backend task API, workflow an toàn là gì?
- Command typecheck/test nào nên chạy và chạy ở đâu?
- Command nào không được tự chạy nếu chưa có xác nhận?
- Nếu bạn không thấy hoặc không chắc CLAUDE.md đã load, nói rõ.

6. Trade-offs

Đặt CLAUDE.md ở root dễ thấy với cả người và AI, phù hợp khi team muốn instruction là một phần chính thức của repo. Đặt ở .claude/CLAUDE.md giúp gom các artifact dành cho Claude Code vào một thư mục riêng. Cách nào cũng được, nhưng team nên chọn một convention nhất quán.

Dùng /init nhanh hơn viết từ đầu nếu CLI version hỗ trợ vì Claude có thể đọc repo và đề xuất draft. Đổi lại, draft cần review kỹ vì AI có thể suy luận nhầm package manager, test command, hoặc architecture boundary. Với repo production, /init nên là bước tạo nháp, không phải nguồn chân lý.

CLAUDE.md càng chi tiết thì Claude càng có nhiều chỉ dẫn, nhưng token/context cost tăng và nguy cơ stale cao hơn. File quá dài còn làm rule quan trọng bị chìm. File quá ngắn thì session mới vẫn phải hỏi lại nhiều. Điểm cân bằng là cheat sheet ngắn, có command chính xác và link tới tài liệu sâu.

Rule security nghiêm ngặt làm Claude chậm hơn vì phải hỏi trước khi chạy lệnh rủi ro. Đây là trade-off đáng chấp nhận trong team repo. Với sandbox workshop, bạn có thể nới lỏng một số rule, nhưng vẫn không nên đưa secret hoặc production data vào context.

Team-shared instruction giúp consistency giữa developer, nhưng có thể xung đột với thói quen cá nhân. Nội dung nào thuộc team policy thì commit vào CLAUDE.md; nội dung cá nhân hoặc local environment nên để trong local settings và không commit.

7. Best practices

• Giữ CLAUDE.md như onboarding checklist cho AI, không biến thành wiki.
• Viết command theo format: command, thư mục chạy, output kỳ vọng, rủi ro nếu có.
• Ưu tiên rule cụ thể: "không tự chạy git reset --hard" tốt hơn "hãy cẩn thận với Git".
• Không ghi secret, sample token thật, database URL thật, customer data, hoặc nội dung .env.
• Khi architecture thay đổi, cập nhật CLAUDE.md cùng PR để tránh project memory bị stale.
• Bắt Claude nêu file đã đọc trước khi sửa code production.
• Với task rủi ro, yêu cầu plan trước rồi mới edit. Nếu team muốn giảm prompt xác nhận, có thể cân nhắc claude --permission-mode acceptEdits hoặc permissions.defaultMode: "auto" trong .claude/settings.json, nhưng phải hiểu rằng chế độ này cho phép sửa file và auto-approve một số command filesystem phổ biến trong working directory.
• Không để Claude tự commit, push, chạy migration phá dữ liệu, drop table, xóa Docker volume, hoặc xóa file hàng loạt.
• Sau mỗi lần cập nhật CLAUDE.md, mở session mới để kiểm tra rule quan trọng có được load đúng không.
• Review CLAUDE.md như code: chính xác, ngắn, có owner, và có dấu hiệu khi stale.

8. Performance / cost / context

CLAUDE.md được nạp vào context của session, nên nội dung càng dài thì mỗi task càng tốn token hơn. Chi phí không chỉ là tiền; còn là độ nhiễu. Nếu file chứa lịch sử quyết định cũ, task đã xong, hoặc mô tả quá dài, Claude có thể ưu tiên sai thông tin khi lập plan.

Cách tối ưu:

• Giữ file dưới 200 dòng và tránh đoạn văn dài.
• Dùng bảng command ngắn thay vì đoạn văn dài.
• Chỉ ghi architecture boundary ổn định, không ghi chi tiết implementation dễ đổi.
• Link tới docs sâu thay vì paste toàn bộ vào CLAUDE.md.
• Tách rule global và task-specific: rule lâu dài ở CLAUDE.md, yêu cầu tạm thời ở prompt.
• Khi session dài bị nhiễu, mở session mới để kiểm tra lại CLAUDE.md thay vì tiếp tục chồng thêm prompt sửa sai.
• Nếu Claude phải đọc toàn repo ở mỗi task, CLAUDE.md đang thiếu command hoặc architecture map quan trọng.

Về performance thực thi, CLAUDE.md tốt giúp giảm số lần Claude chạy command thăm dò sai. Ví dụ biết chính xác pnpm --filter api test sẽ rẻ hơn việc Claude thử npm test, thất bại, đọc package.json, rồi thử lại.

9. Checklist cuối bài

• Tôi giải thích được vì sao Claude Code không nên được xem là có trí nhớ project vĩnh viễn.
• Tôi biết CLAUDE.md và .claude/CLAUDE.md dùng để lưu project instructions.
• Tôi đã dùng hoặc biết cách dùng /init để tạo draft CLAUDE.md.
• Tôi biết dùng claude để mở session tại project root, dùng /help để kiểm tra commands, và phân biệt --continue/--resume với session mới.
• Tôi biết review draft để loại bỏ suy đoán, command sai, rule chung chung, và thông tin nhạy cảm.
• Tôi có CLAUDE.md cho taskflow-ai gồm stack, architecture, commands, conventions, testing, security, workflow.
• Mỗi command quan trọng có thư mục chạy và output kỳ vọng.
• Security rules chặn secret, production data, destructive command, auto commit/push.
• Tôi đã mở session mới và kiểm tra Claude có load đúng instruction không.
• Tôi biết rollback CLAUDE.md bằng git restore -- CLAUDE.md hoặc xóa file mới một cách có kiểm soát.
• Tôi hiểu tác động của CLAUDE.md tới token, context, maintainability, và cost.

10. Bài tập

Bài cơ bản: chạy /init trong taskflow-ai để tạo draft CLAUDE.md nếu CLI version hỗ trợ; nếu không, dùng prompt tạo thủ công trong bài. Không accept nội dung ngay. Dùng git diff -- CLAUDE.md hoặc git diff -- .claude/CLAUDE.md để review và đánh dấu ít nhất 5 điểm cần xác nhận hoặc sửa.

Bài nâng cao: chỉnh CLAUDE.md thành cheat sheet ngắn, target dưới 200 dòng. File phải có đủ section Project, Structure, Commands, Coding Conventions, Testing, Security, Workflow. Mỗi command quan trọng phải ghi rõ chạy ở root, apps/api, apps/web, hoặc package tương ứng.

Bài áp dụng vào project cá nhân: chọn một repo bạn đang làm và viết CLAUDE.md tối giản cho repo đó. Sau đó mở session Claude Code mới, yêu cầu Claude tóm tắt project instructions đã load, rồi so sánh với file bạn viết.

Bài reflection: ghi lại 3 rule trong CLAUDE.md có tác động lớn nhất tới chất lượng code, 3 rule giúp giảm rủi ro security, và 3 rule giúp giảm token/context cost. Nếu rule nào không đo được hiệu quả, viết lại cho cụ thể hơn.

Tài liệu

Tóm tắt kiến thức

CLAUDE.md là project instructions, thường được xem như project memory do team kiểm soát cho Claude Code. Nó giúp session mới có cùng hiểu biết nền về repo: stack, architecture, commands, conventions, testing, security, và workflow. Theo tài liệu Claude Code hiện hành, project instructions có thể nằm ở CLAUDE.md hoặc .claude/CLAUDE.md.

Ý tưởng cốt lõi: CLAUDE.md không phải README thứ hai. Nó là cheat sheet cho AI, được tối ưu để Claude ra quyết định đúng hơn khi đọc code, lập plan, edit file, và đề xuất command.

Không nên đồng nhất CLAUDE.md với mọi tính năng auto memory. Nếu CLI version đang dùng có auto memory, hãy kiểm tra official docs để biết scope, giới hạn, và cách bật/tắt trước khi đưa vào workflow team. Trong Day 05, nguồn chân lý vẫn là file instruction được review và commit có chủ đích.

Nội dung nên có:

• Project summary: taskflow-ai là ứng dụng quản lý task cho team kỹ thuật.
• Stack: Node.js, TypeScript, backend Fastify hoặc NestJS, React + Vite, PostgreSQL, Redis, Vitest/Jest, Playwright, Docker Compose.
• Structure: root, backend, frontend, shared packages, test, scripts, infra.
• Commands: dev, build, lint, typecheck, unit test, integration test, e2e, Docker Compose.
• Coding conventions: module boundary, validation, error handling, naming, component boundary.
• Testing rules: test bắt buộc cho behavior change, không sửa test để hợp thức hóa bug.
• Security rules: không đọc secret, không in .env, không dùng production data, không chạy destructive command, không tự commit/push.
• Workflow: plan trước với task rủi ro, sửa nhỏ, tóm tắt diff, đề xuất verification.

Nội dung không nên có:

• Secret, token, private key, connection string thật.
• Log dài, transcript, task tạm thời, hoặc todo cá nhân.
• Toàn bộ architecture document nhiều trang.
• Rule chung chung như "write clean code" mà không có hành vi cụ thể.
• Command chưa verify nhưng viết như chắc chắn đúng.

Sơ đồ tư duy hoặc luồng xử lý

Mở repo taskflow-ai
  |
  v
Kiểm tra Git state
  |
  v
Chạy `claude` từ project root
  |
  v
`/init` nếu CLI hỗ trợ hoặc prompt khám phá repo
  |
  v
Claude tạo draft CLAUDE.md
  |
  v
Developer review như review code
  |
  +-- Sai command -> sửa hoặc đánh dấu cần xác nhận
  +-- Quá dài -> rút gọn thành cheat sheet
  +-- Có secret/rủi ro -> xóa ngay
  +-- Rule mơ hồ -> viết lại thành hành vi cụ thể
  |
  v
Commit CLAUDE.md khi đạt chuẩn team
  |
  v
Mở session mới ở root repo bằng `claude`
  |
  v
Hỏi Claude tóm tắt project instructions đã load
  |
  +-- Đúng stack/command/rule -> đạt
  +-- Trả lời chung chung/sai -> debug vị trí file, nội dung, session root

Luồng cập nhật khi repo thay đổi:

PR đổi architecture hoặc command
  -> cập nhật code/config
  -> cập nhật README nếu cần cho human
  -> cập nhật CLAUDE.md nếu ảnh hưởng Claude workflow
  -> mở session mới kiểm tra context

Bảng so sánh

Lỗi thường gặp

1. Biến CLAUDE.md thành README dài
   Hậu quả là session nào cũng phải nạp nhiều context không cần thiết, trong khi rule quan trọng bị chìm.

2. Tin tuyệt đối vào /init
/init có thể tạo draft hữu ích nhưng vẫn có thể sai command, sai folder, hoặc suy luận architecture chưa đủ bằng chứng.

3. Ghi command không có thư mục chạy
   npm test chạy ở root có thể fail nếu test thật nằm trong apps/api. Claude cần biết cwd.

4. Ghi rule chung chung
   "Use best practices" không giúp Claude ra quyết định. Hãy viết "Do not add a new abstraction unless two call sites need it".

5. Đưa secret vào project memory
   Đây là lỗi nghiêm trọng. CLAUDE.md có thể được commit và được nạp vào nhiều session. Không ghi .env, token, private key, production URL nhạy cảm.

6. Không cập nhật khi repo đổi
   Nếu chuyển từ Jest sang Vitest nhưng CLAUDE.md vẫn ghi Jest, Claude sẽ tiếp tục đề xuất test sai.

7. Không kiểm tra session mới
   File tồn tại không đảm bảo Claude đang ở đúng root repo hoặc đang load đúng instruction. Nếu dùng claude --continue, bạn có thể đang kiểm tra context cũ của session gần nhất chứ không phải một session mới sạch.

8. Trộn rule local cá nhân vào rule team
   Ví dụ path tool local, port riêng, hoặc alias shell cá nhân nên để trong local settings, không ép toàn team.

Cách debug

Khi Claude không load đúng CLAUDE.md:

1. Xác nhận đang ở root taskflow-ai:

pwd

Lệnh này in thư mục hiện tại. Output kỳ vọng kết thúc bằng taskflow-ai. Rủi ro thấp, read-only.

2. Kiểm tra file tồn tại:

ls CLAUDE.md .claude/CLAUDE.md

Lệnh này kiểm tra hai vị trí project instructions phổ biến. Output kỳ vọng có ít nhất một file tồn tại. Rủi ro thấp. Nếu shell báo file không tồn tại, kiểm tra lại vị trí file.

Trên PowerShell:

Test-Path .\CLAUDE.md
Test-Path .\.claude\CLAUDE.md

Output kỳ vọng là True cho vị trí bạn dùng.

3. Mở session mới:

cd /path/to/taskflow-ai
claude

Lệnh này mở Claude Code từ đúng project root. Output kỳ vọng là Claude sẵn sàng nhận prompt; có thể dùng /help để xem commands của CLI version hiện tại.

Không dùng claude --continue nếu mục tiêu là kiểm tra session mới sạch, vì nó resume session gần nhất trong thư mục hiện tại. Dùng claude --resume hoặc /resume khi mục tiêu là chọn session cũ để tiếp tục.

Không cần dùng claude --permission-mode acceptEdits trong bước debug context. Chế độ này cho phép tạo/sửa file và auto-approve một số command filesystem phổ biến trong working directory, nên chỉ phù hợp khi bạn thật sự muốn Claude edit sau khi guardrails đã rõ.

4. Hỏi kiểm tra context:

Không sửa file. Hãy tóm tắt project instructions đã load từ CLAUDE.md hoặc .claude/CLAUDE.md.
Nếu không thấy file instruction, nói rõ.

Nếu Claude trả lời sai, kiểm tra:

• Có mở nhầm thư mục cha hoặc package con không.
• File quá dài hoặc chứa nhiều thông tin mâu thuẫn không.
• Có cả CLAUDE.md và .claude/CLAUDE.md với rule xung đột không.
• Nội dung có ghi command cũ không.
• Session hiện tại có prompt trước đó ép Claude làm ngược rule không.

Khi command trong CLAUDE.md sai:

git diff -- CLAUDE.md

Review patch và sửa command theo package.json thật. Không để Claude đoán nếu script chưa tồn tại.

Khi file quá dài:

Rút gọn CLAUDE.md xuống dưới 200 dòng và dễ scan như cheat sheet.
Giữ lại commands, architecture boundary, testing/security/workflow rules.
Chuyển phần giải thích dài thành link tới docs, không paste nguyên văn.

Khi cần rollback:

git restore -- CLAUDE.md

Chỉ dùng nếu file đã được Git track và bạn muốn bỏ toàn bộ thay đổi chưa commit trong file đó. Rủi ro: mất phần bạn tự sửa trong cùng file. Trong repo có nhiều người cùng làm, chỉ restore file bạn chắc là do mình tạo/sửa hoặc đã được xác nhận không chứa thay đổi của người khác.

Link tài liệu nên đọc

• Claude Code Memory: https://code.claude.com/docs/en/memory
• Claude Code Best Practices: https://code.claude.com/docs/en/best-practices
• Claude Code Permissions: https://code.claude.com/docs/en/permissions
• Claude Code Settings: https://code.claude.com/docs/en/settings
• Claude Code Slash Commands: https://code.claude.com/docs/en/slash-commands
• Git ignore documentation: https://git-scm.com/docs/gitignore
• Git restore documentation: https://git-scm.com/docs/git-restore

Bài tập

Bài 1 — Cơ bản

Mục tiêu: tạo draft CLAUDE.md cho taskflow-ai và hiểu vì sao không được accept mù quáng.

Yêu cầu:

1. Mở terminal tại root taskflow-ai.
2. Kiểm tra trạng thái repo:

git status --short

Lệnh này hiển thị working tree. Output kỳ vọng là rỗng hoặc chỉ gồm file bạn hiểu rõ. Nếu có file lạ, không chạy /init vội vì Claude có thể hiểu state tạm thời là convention của project.

3. Mở Claude Code:

cd /path/to/taskflow-ai
claude

Lệnh này chuyển vào project rồi mở session tại thư mục hiện tại. Output kỳ vọng là Claude sẵn sàng nhận prompt. Có thể dùng /help để xem slash commands của CLI version hiện tại. Rủi ro: mở sai thư mục sẽ tạo CLAUDE.md sai vị trí.

4. Chạy slash command:

/init

Kết quả kỳ vọng: Claude đọc repo và tạo hoặc cập nhật CLAUDE.md.

Nếu CLI version đang dùng không có /init, dùng prompt tạo thủ công:

Hãy tạo CLAUDE.md cho taskflow-ai như project instructions cho Claude Code.
Chỉ ghi thông tin có bằng chứng từ repo; nếu không chắc command nào đúng, đánh dấu "verify before use".
Chỉ sửa CLAUDE.md hoặc .claude/CLAUDE.md theo convention của project.
Không đưa secret, endpoint production, hoặc dữ liệu nhạy cảm.

5. Xem diff:

git diff -- CLAUDE.md

Output kỳ vọng: một file instruction Markdown có mô tả project, commands, architecture, conventions. Nếu project chọn .claude/CLAUDE.md, dùng git diff -- .claude/CLAUDE.md. Nếu file có command không chắc đúng, đánh dấu để sửa.

Ghi lại ít nhất 5 điểm cần review:

• Command nào cần xác nhận từ package.json.
• Folder nào Claude mô tả đúng hoặc sai.
• Rule nào quá chung chung.
• Có thông tin nhạy cảm không.
• File có quá dài không.

Bài 2 — Thực tế

Mục tiêu: chỉnh CLAUDE.md thành onboarding document cho AI dùng được trong team.

Yêu cầu:

1. Dùng prompt sau trong Claude Code:

Review và chỉnh CLAUDE.md cho taskflow-ai.

Mục tiêu:
- Đây là onboarding document cho Claude Code, không phải README.
- Giữ ngắn, target dưới 200 dòng, ưu tiên rule Claude cần trong mọi session.
- Chỉ giữ thông tin có bằng chứng từ repo hoặc cần tôi xác nhận.
- Có đủ section: Project, Structure, Commands, Coding Conventions, Testing, Security, Workflow.
- Mỗi command phải ghi thư mục chạy, output kỳ vọng, và rủi ro nếu có.

Giới hạn:
- Chỉ sửa `CLAUDE.md` hoặc `.claude/CLAUDE.md` nếu project đã chọn convention đó.
- Không sửa README.md, source code, test, package.json, hoặc config khác.
- Không chạy npm install, migration, git add, git commit, git reset, git clean, hoặc lệnh xóa file.

2. Sau khi Claude sửa, kiểm tra phạm vi:

git diff --stat

Output kỳ vọng: chỉ CLAUDE.md hoặc .claude/CLAUDE.md thay đổi. Nếu có file khác, dừng lại và review.

3. Xem chi tiết:

git diff -- CLAUDE.md

Output kỳ vọng: file có nội dung tương tự cấu trúc sau, nhưng phải khớp repo thật:

# CLAUDE.md

## Project
- taskflow-ai is a task management app for engineering teams.
- Use TypeScript for backend and frontend.

## Structure
- apps/api: backend API.
- apps/web: React + Vite frontend.
- packages/shared: shared types and validation helpers.

## Commands
- Install from repo root: `pnpm install`
- API dev from repo root: `pnpm --filter api dev`
- Web dev from repo root: `pnpm --filter web dev`
- Typecheck from repo root: `pnpm typecheck`
- Unit tests from repo root: `pnpm test`

## Coding Conventions
- Read existing module patterns before adding files.
- Keep validation near API boundary or existing validation layer.
- Avoid new abstractions until at least two call sites need them.

## Testing
- Add or update tests for behavior changes.
- Do not weaken assertions just to make tests pass.

## Security
- Do not read or print `.env` values.
- Do not use production data.
- Do not run destructive Git, Docker, or database commands without explicit confirmation.

## Workflow
- Start risky changes with a plan.
- Keep diffs small.
- Summarize changed files and verification commands.
- Do not commit or push unless explicitly asked.

4. Tự sửa lại nếu sample không đúng với repo thật. Ví dụ nếu project dùng npm thì không giữ pnpm.

Bài 3 — Nâng cao

Mục tiêu: kiểm tra session mới có load đúng project instructions hay không.

Yêu cầu:

1. Thoát session Claude hiện tại.
2. Mở session mới tại root taskflow-ai:

cd /path/to/taskflow-ai
claude

Lệnh này mở Claude Code từ đúng project root. Output kỳ vọng là Claude sẵn sàng nhận prompt. Không dùng claude --continue cho bài test này vì nó tiếp tục session gần nhất trong thư mục hiện tại; dùng claude --resume hoặc /resume chỉ khi bạn muốn chọn một session cũ. Rủi ro: nếu mở sai directory, kết quả test context không có giá trị.

Không bật claude --permission-mode acceptEdits chỉ để kiểm tra context. Theo docs hiện hành, chế độ này cho phép tạo/sửa file và auto-approve một số command filesystem phổ biến trong working directory; chỉ dùng khi bạn thật sự muốn Claude edit và đã có guardrails.

3. Gửi prompt:

Không sửa file và không chạy command.
Hãy trả lời dựa trên project instructions đã load:

1. taskflow-ai dùng stack gì?
2. Các thư mục chính và trách nhiệm của từng thư mục là gì?
3. 5 command quan trọng nhất là gì, chạy ở đâu, output kỳ vọng là gì?
4. Khi sửa backend task API, workflow an toàn phải làm theo là gì?
5. Command hoặc hành động nào không được tự chạy?

Nếu bạn không thấy CLAUDE.md hoặc không chắc instruction đã load, nói rõ thay vì đoán.

4. Chấm kết quả:

• Đạt nếu Claude trả lời đúng nội dung từ CLAUDE.md.
• Chưa đạt nếu Claude nói chung chung, sai package manager, sai folder, hoặc không nhắc security rules.

5. Nếu chưa đạt, debug bằng các lệnh:

pwd
ls CLAUDE.md .claude/CLAUDE.md
git diff -- CLAUDE.md
git diff -- .claude/CLAUDE.md

pwd xác nhận thư mục hiện tại. ls xác nhận file instruction tồn tại. git diff xác nhận nội dung chưa commit có đúng không. Rủi ro thấp vì đều là read-only; nếu một trong hai path không tồn tại, git diff có thể không in gì hoặc báo path không có trong repo tùy shell/Git version.

Bài 4 — Review & Reflection

Mục tiêu: biến CLAUDE.md thành artifact có thể bảo trì lâu dài, không chỉ là file tạo cho xong.

Trả lời các câu hỏi:

1. Rule nào trong CLAUDE.md giúp Claude không sửa quá rộng?
2. Rule nào giúp giảm rủi ro security?
3. Command nào trong file có khả năng stale cao nhất khi repo đổi?
4. Nếu chuyển test runner từ Jest sang Vitest, bạn cần cập nhật những dòng nào?
5. Nếu team muốn Claude hỏi ít hơn khi sửa file, khi nào nên dùng prompt/workflow rule trong CLAUDE.md, khi nào mới cân nhắc claude --permission-mode acceptEdits hoặc permissions.defaultMode: "auto" trong .claude/settings.json?
6. Có rule nào đang quá chung chung không? Viết lại thành rule có thể kiểm tra được.

Prompt reflection gợi ý:

Review CLAUDE.md như artifact bảo trì lâu dài.

Hãy chỉ ra:
- 5 rule có giá trị cao nhất.
- 5 dòng có nguy cơ stale.
- 3 rule nên viết cụ thể hơn.
- 3 security guardrail còn thiếu.
- Cách rút gọn file để giảm context cost nhưng không mất rule quan trọng.

Không sửa file trong bước này.

Tiêu chí hoàn thành

• Đã tạo hoặc cập nhật CLAUDE.md cho taskflow-ai.
• File có đủ section Project, Structure, Commands, Coding Conventions, Testing, Security, Workflow.
• Commands ghi rõ thư mục chạy, output kỳ vọng, và rủi ro chính.
• Security rules không cho đọc/in secret, không dùng production data, không tự chạy destructive command, không tự commit/push.
• git diff --stat cho thấy chỉ CLAUDE.md hoặc .claude/CLAUDE.md thay đổi trong bài thực hành này.
• Đã mở session mới và kiểm tra Claude có load đúng project instructions.
• Đã ghi lại ít nhất 3 dòng có nguy cơ stale và cách bảo trì.
• Không sửa README.md, source code, Day khác, hoặc file ngoài phạm vi bài thực hành.

Gợi ý nếu bí

Nếu /init tạo file quá dài, dùng prompt:

CLAUDE.md hiện tại quá dài. Hãy rút gọn xuống dưới 200 dòng và giữ dạng cheat sheet dễ scan.
Giữ lại stack, structure, commands, conventions, testing, security, workflow.
Xóa phần giải thích chung chung và task tạm thời.
Không sửa file nào khác.

Nếu Claude bịa command, dùng prompt:

Không được đoán command.
Hãy đọc package.json liên quan và chỉ ghi command có script thật.
Nếu chưa chắc command chạy từ root hay package con, đánh dấu "verify before use".

Nếu Claude không nhận context ở session mới, kiểm tra:

pwd
ls CLAUDE.md
ls .claude/CLAUDE.md

Nếu cả hai vị trí đều không có file, bạn đã tạo sai chỗ. Nếu có file nhưng Claude trả lời sai, mở session mới ở đúng root và hỏi lại bằng prompt kiểm tra context.

Nếu diff chạm file ngoài CLAUDE.md, dùng:

git diff --stat
git diff -- path/to/unexpected-file

Đọc diff trước. Nếu file đó có thể là thay đổi của đồng đội hoặc thay đổi bạn cần giữ, không rollback. Nếu chắc chắn file ngoài phạm vi là do bạn vừa tạo/sửa nhầm và muốn bỏ:

git restore -- path/to/unexpected-file

Rủi ro: mất thay đổi chưa commit trong file đó, kể cả thay đổi do bạn tự viết hoặc người khác vừa tạo trong cùng working tree.

Đáp án tham khảo hoặc expected result

Kết quả kỳ vọng cho Bài 1:

• Có draft CLAUDE.md.
• Bạn xác định được ít nhất 5 điểm cần review.
• Không có secret hoặc dữ liệu nhạy cảm trong file.

Kết quả kỳ vọng cho Bài 2:

• CLAUDE.md ngắn, có section rõ ràng, không phải README dài.
• Commands khớp package.json thật.
• Security và workflow rules đủ cụ thể để Claude làm theo.
• Diff chỉ chạm CLAUDE.md.

Ví dụ rule tốt:

- Do not run `git reset --hard`, `git clean -fd`, `docker compose down -v`, database drop/truncate, or force push without explicit confirmation.
- For risky backend changes, first read the route, service, repository, and test files, then present a plan before editing.
- After edits, summarize changed files and suggest verification commands; do not commit or push.

Ví dụ rule yếu cần sửa:

- Be careful.
- Write good code.
- Run tests.

Kết quả kỳ vọng cho Bài 3:

• Session mới trả lời đúng stack, structure, commands, testing, security, workflow từ CLAUDE.md.
• Claude nói rõ nếu không thấy instruction thay vì đoán.
• Bạn phát hiện được lỗi nếu mở sai directory hoặc file đặt sai vị trí.

Kết quả kỳ vọng cho Bài 4:

• Có danh sách rule giá trị cao, rule dễ stale, và rule cần viết cụ thể hơn.
• Bạn phân biệt được nội dung nên nằm trong CLAUDE.md với cấu hình nên cân nhắc trong .claude/settings.json, và hiểu rủi ro của acceptEdits/defaultMode: "auto".
• Bạn có kế hoạch cập nhật CLAUDE.md khi architecture, commands, hoặc testing strategy thay đổi.