Day 07 - Khám phá codebase lớn

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

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

• Dùng Claude Code để khám phá một repo lớn theo hướng có bằng chứng, không hỏi chung chung kiểu "giải thích toàn bộ codebase".
• Yêu cầu Claude map architecture của taskflow-ai: frontend, backend, database, cache, test, tooling, và luồng runtime chính.
• Tạo dependency map ở mức module: module nào gọi module nào, phụ thuộc qua import, API, database table, queue, cache, hoặc config.
• Tìm entrypoint quan trọng: server bootstrap, route registration, frontend bootstrap, test setup, migration/seed, Docker Compose.
• Nhận diện bounded context trong project: tasks, users/auth, comments, notifications, reporting, shared infrastructure.
• Phân biệt hot path với code ít dùng để ưu tiên đọc đúng file trước khi sửa feature.
• Nhận diện và giảm rủi ro hallucination khi Claude chưa đọc đủ file nhưng vẫn tự tin kết luận.
• Cho Claude Code tạo ARCHITECTURE.md trong taskflow-ai và yêu cầu Claude chỉ ra module cần đọc trước khi sửa một feature mới.

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

Ở repo nhỏ, bạn có thể đọc vài file là hiểu flow. Ở repo team sau vài tháng, taskflow-ai có thể đã có backend TypeScript, frontend React, database migration, Redis cache, test integration, GitHub workflow, và nhiều convention nằm rải rác trong code. Khi nhận task "thêm comments cho task" hoặc "thêm rule SLA", lỗi phổ biến là nhảy thẳng vào file có tên gần đúng rồi sửa. Với AI, lỗi này còn nguy hiểm hơn vì Claude Code có thể viết patch rất nhanh dựa trên giả định chưa kiểm chứng.

Claude Code hữu ích nhất ở giai đoạn này khi bạn dùng nó như một architectural scout: đọc có mục tiêu, ghi lại bằng chứng, hỏi lại khi thiếu thông tin, và tạo artifact để team dùng lại. Artifact tốt không chỉ là mô tả đẹp; nó phải trả lời được câu hỏi thực dụng: "Trước khi sửa feature này, cần đọc file/module nào, theo thứ tự nào, và vì sao?"

Không nên dùng Claude Code để tự động khám phá codebase khi:

• Repo chứa secret, production dump, log khách hàng, hoặc file nhạy cảm chưa được loại khỏi context.
• Bạn đang ở incident production cần thao tác khẩn cấp và chưa có người chịu trách nhiệm review.
• Codebase có nhiều thay đổi local chưa commit, khó phân biệt artifact của AI với thay đổi của developer khác.
• Bạn muốn Claude "đọc toàn bộ repo" mà không có câu hỏi cụ thể; cách này tốn token, nhiễu context, và dễ tạo kết luận sai.

3. Kiến thức nền

Khám phá codebase lớn nên đi theo hướng evidence-first. Claude Code có thể suy luận nhanh, nhưng mọi kết luận quan trọng phải gắn với file đã đọc, symbol đã thấy, hoặc command read-only đã chạy. Nếu Claude nói "module tasks dùng repository pattern", bạn cần yêu cầu nó chỉ ra file nào chứng minh điều đó.

Các khái niệm cần dùng trong Day 07:

Trong một repo TypeScript phổ biến, entrypoint có thể là backend/src/main.ts, backend/src/server.ts, frontend/src/main.tsx, docker-compose.yml, hoặc script trong package.json. Nhưng bạn không được hardcode giả định này vào prompt. Hãy yêu cầu Claude tìm bằng rg --files, package.json, import graph, route registration, và script test/build thật.

Dependency map có nhiều lớp:

• Compile-time dependency: import/export giữa file TypeScript.
• Runtime dependency: route gọi service, service gọi repository, repository gọi database.
• Data dependency: module phụ thuộc table, enum, migration, cache key.
• Operational dependency: Docker service, environment variable, CI workflow, test database.
• Ownership dependency: module nào có convention riêng trong CLAUDE.md hoặc tài liệu team.

Claude Code docs hiện hành khuyến nghị dùng plan mode để đọc và hiểu codebase trước khi sửa. Slash commands như /context và /compact có thể hỗ trợ quản lý session khi exploration dài. Project memory trong CLAUDE.md giúp giữ conventions qua session mới. Permissions nên được hạn chế khi mới exploration: ưu tiên đọc, grep, list file, diff; chưa cấp quyền edit hoặc command nguy hiểm. Subagents/agents có thể dùng để tách context cho backend, frontend, security review, nhưng Day 07 chỉ nhắc ở mức chiến lược; phần triển khai sâu dành cho Day 14.

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

Mục tiêu thực hành: cho Claude Code khám phá taskflow-ai, tạo ARCHITECTURE.md, và sinh danh sách module cần đọc trước khi sửa feature task comments.

Bước 1: Kiểm tra trạng thái repo

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

git status --short

Lệnh này kiểm tra working tree. Output kỳ vọng là rỗng hoặc chỉ có file bạn hiểu rõ. Rủi ro: nếu repo đang có thay đổi của bạn hoặc đồng đội, artifact ARCHITECTURE.md có thể lẫn với diff khác, làm review khó hơn.

Xem cấu trúc file ở mức cao:

rg --files -g "package.json" -g "docker-compose*.yml" -g "CLAUDE.md" -g "README.md"

Chạy ở root taskflow-ai. Lệnh này liệt kê các file định hướng project. Output kỳ vọng có package.json, có thể có backend/package.json, frontend/package.json, docker-compose.yml, CLAUDE.md. Rủi ro thấp vì read-only; nếu không có rg, dùng công cụ tìm file tương đương của môi trường.

Bước 2: Mở Claude Code ở plan mode

Chạy trong root taskflow-ai:

claude --permission-mode plan

Lệnh này mở Claude Code ở mode phù hợp để đọc và lập plan trước khi sửa. Output kỳ vọng là session Claude sẵn sàng nhận prompt. Rủi ro chính không nằm ở command, mà ở prompt quá rộng khiến Claude đọc lan man và tốn context.

Prompt exploration:

Bạn đang ở repo taskflow-ai. Hãy khám phá codebase để tạo bản đồ architecture, nhưng chưa sửa file.

Mục tiêu:
- Tìm entrypoint backend, frontend, test, migration/seed, Docker/local dev nếu có.
- Xác định bounded context chính: tasks, users/auth, comments, notifications, shared infrastructure.
- Tạo dependency map cấp module: route/controller -> service -> repository/data/cache/external.
- Chỉ ra hot path cho các luồng: tạo task, cập nhật task status, list task board.
- Với mỗi kết luận quan trọng, ghi file đã đọc và bằng chứng ngắn.

Ràng buộc:
- Chỉ dùng read-only exploration.
- Không đọc file secret như .env, private key, production dump, log khách hàng.
- Không chạy install, build, migration, test dài, Docker, Git command destructive.
- Nếu thiếu thông tin, ghi rõ "chưa đủ bằng chứng" thay vì đoán.
- Trước khi tạo tài liệu, hãy đề xuất outline ARCHITECTURE.md để tôi duyệt.

Kết quả tốt: Claude liệt kê file đã đọc, phân nhóm module, nêu rõ entrypoint, và đánh dấu phần chưa chắc. Kết quả chưa đạt: Claude mô tả kiến trúc chung chung mà không có path file.

Bước 3: Ép Claude phân biệt fact và inference

Gửi tiếp trong session plan:

Hãy chuyển kết quả exploration thành bảng gồm 4 cột:
1. Claim
2. Evidence file/path
3. Confidence: high/medium/low
4. What to read next before editing

Không thêm claim nếu chưa có evidence. Với claim medium/low, nêu file hoặc command read-only cần kiểm chứng tiếp.

Bước này giảm hallucination. Với senior developer, đây là phần quan trọng hơn bản đồ đẹp: bạn cần biết Claude chắc ở đâu, đang đoán ở đâu, và phải đọc gì trước khi cho sửa code.

Bước 4: Tạo ARCHITECTURE.md

Sau khi duyệt outline, mở session có quyền ghi rất hẹp:

claude --permission-mode default --tools "Read,Write,Edit,Bash" --allowedTools "Bash(git status *)" "Bash(git diff *)"

Chạy ở root taskflow-ai. Lệnh này giới hạn built-in tool family vào Read, Write, Edit, Bash, đồng thời auto-approve riêng các Bash command khớp git status * hoặc git diff *. Output kỳ vọng là session sẵn sàng. Rủi ro: --allowedTools không khóa toàn bộ Bash command khác, nó chỉ cho phép chạy không cần hỏi với pattern đã nêu; Write/Edit cũng không tự khóa theo path, nên prompt phải nêu rõ chỉ được tạo hoặc cập nhật ARCHITECTURE.md và vẫn phải review diff.

Prompt tạo tài liệu:

Tạo file ARCHITECTURE.md ở root taskflow-ai dựa trên exploration đã duyệt.

Giới hạn:
- Chỉ tạo hoặc sửa ARCHITECTURE.md.
- Không sửa source code, config, package lock, test, migration, README, CLAUDE.md.
- Mỗi section phải ghi source file/path đã dùng làm bằng chứng.
- Tách rõ "Fact from code" và "Inference / needs verification".
- Có section "Before editing a feature, read these modules first".
- Có section "Hot paths and risk areas".
- Có section "Rollback and verification commands".
- Sau khi ghi file, chạy git diff -- ARCHITECTURE.md và tóm tắt.

Output kỳ vọng: ARCHITECTURE.md có cấu trúc hữu ích cho team, không chỉ là văn mô tả. Nếu Claude sửa file khác, dừng lại và rollback file ngoài phạm vi sau khi review.

Bước 5: Kiểm tra artifact

Chạy trong root taskflow-ai:

git diff --stat -- ARCHITECTURE.md

Lệnh này cho biết file architecture có thay đổi bao nhiêu. Output kỳ vọng là chỉ ARCHITECTURE.md. Rủi ro thấp; đây là command read-only.

Xem nội dung diff:

git diff -- ARCHITECTURE.md

Kết quả kỳ vọng:

• Có entrypoint thật, không đoán tên file.
• Có dependency map module dựa trên file đã đọc.
• Có hot path tạo task/cập nhật status/list board.
• Có danh sách "read before editing" theo feature.
• Có phần "unknowns" hoặc "needs verification".

Bước 6: Yêu cầu danh sách module cần đọc trước feature

Gửi prompt:

Giả sử task tiếp theo là thêm feature task comments.

Hãy đề xuất module/file cần đọc trước khi sửa, theo thứ tự ưu tiên.
Với mỗi mục, ghi:
- Vì sao cần đọc.
- Bằng chứng từ architecture map hoặc source file.
- Rủi ro nếu bỏ qua.
- File nào tuyệt đối chưa được sửa trước khi hiểu rõ contract.

Chưa implement feature. Chỉ lập reading plan và risk map.

Kết quả tốt không phải là "sửa backend rồi frontend". Kết quả tốt phải nêu được đọc route/controller tasks, service/repository/data model, auth/current user, migration pattern, API client frontend, component task detail/list, test pattern, và Docker/test setup nếu feature cần database.

Bước 7: Rollback khi tài liệu sai hoặc quá rộng

Nếu ARCHITECTURE.md là file đã tracked và bạn muốn bỏ toàn bộ thay đổi:

git restore -- ARCHITECTURE.md

Lệnh này đưa file về trạng thái trong Git. Rủi ro: mất toàn bộ thay đổi chưa commit trong file đó, kể cả chỉnh sửa thủ công của bạn.

Nếu ARCHITECTURE.md là file mới chưa tracked, trước tiên kiểm tra:

git status --short -- ARCHITECTURE.md

Nếu output là ?? ARCHITECTURE.md và bạn chắc chắn muốn bỏ, có thể xóa file thủ công hoặc dùng:

git clean -f -- ARCHITECTURE.md

Lệnh này xóa file untracked được chỉ định. Rủi ro: git clean là destructive; chỉ dùng với path cụ thể sau khi git status xác nhận đúng file. Không chạy git clean -fd ở root repo nếu chưa hiểu toàn bộ file untracked.

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

Prompt khám phá codebase

Hãy khám phá repo taskflow-ai theo hướng evidence-first.

Chưa sửa file.
Tìm entrypoint backend/frontend/test/devops.
Map bounded context chính và dependency giữa các module.
Mỗi claim phải kèm file/path đã đọc.
Nếu chưa có bằng chứng, ghi "unknown" thay vì suy đoán.

Prompt lập plan

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

Plan tối đa 6 bước:
- Bước nào đọc file nào.
- Bước nào tạo dependency map.
- Bước nào kiểm tra hallucination risk.
- Bước nào viết tài liệu.

Không sửa file trước khi tôi approve outline.

Prompt implement

Tạo ARCHITECTURE.md theo outline đã duyệt.

Giới hạn:
- Chỉ sửa ARCHITECTURE.md.
- Không sửa source code, README, CLAUDE.md, package files, migration, test.
- Tách Fact, Inference, Unknown.
- Thêm section "Read before editing feature".
- Sau khi ghi, tóm tắt diff và command verify.

Prompt review

Review ARCHITECTURE.md như senior engineer onboarding vào repo.

Tập trung:
- Claim nào thiếu evidence file/path.
- Dependency nào có vẻ suy đoán.
- Hot path nào thiếu test hoặc thiếu observability.
- Phần nào có thể làm developer mới sửa nhầm module.

Không sửa file trong bước review này. Trả về findings theo severity.

Prompt viết test

Từ architecture map hiện tại, đề xuất test cần đọc trước khi sửa feature task comments.

Yêu cầu:
- Chỉ đọc test pattern hiện có.
- Không viết test mới.
- Chỉ ra test unit/integration/e2e nào đang bảo vệ hot path tasks.
- Nếu chưa có test cho hot path, ghi rõ rủi ro và đề xuất test tối thiểu.

6. Trade-offs

Exploration rộng giúp bạn hiểu kiến trúc tổng thể, nhưng tốn token và dễ nhiễu context. Exploration hẹp tiết kiệm hơn, nhưng có thể bỏ sót dependency ngầm như auth middleware, cache key, hoặc migration convention. Cách cân bằng là bắt đầu bằng map cấp cao, sau đó zoom vào bounded context liên quan tới feature.

Tạo ARCHITECTURE.md giúp session sau nhanh hơn và hỗ trợ onboarding, nhưng tài liệu có thể stale. Nếu team không cập nhật khi architecture đổi, Claude và developer mới có thể bị dẫn sai. Vì vậy artifact phải ghi "last verified" hoặc ít nhất ghi source path, để người đọc biết cần kiểm chứng lại.

Yêu cầu Claude nêu "fact vs inference" làm output dài hơn, nhưng giảm rủi ro hallucination. Với codebase lớn, một kết luận sai về dependency có thể dẫn tới patch đúng cú pháp nhưng sai behavior.

Subagents/agents có thể tách exploration backend/frontend/security để giảm context collision, nhưng thêm orchestration cost và có thể tạo kết quả mâu thuẫn. Day 07 chỉ nên dùng khi repo lớn rõ rệt; nếu taskflow-ai còn nhỏ, một session plan mode là đủ.

Slash commands như /compact giúp giữ summary khi context dài, nhưng compact sai trọng tâm sẽ làm mất chi tiết quan trọng. Trước khi compact, hãy yêu cầu Claude giữ lại entrypoint, hot path, unknowns, accepted decisions, và file scope.

7. Best practices

• Luôn bắt đầu bằng plan mode hoặc quyền read-only khi khám phá repo lớn.
• Yêu cầu Claude liệt kê file đã đọc; không accept architecture claim không có evidence.
• Tách rõ Fact from code, Inference, và Unknown / needs verification.
• Không đọc .env, private key, production dump, customer log, hoặc file chứa credential.
• Không cho Claude chạy npm install, migration, Docker, test dài, hoặc command destructive trong phase exploration.
• Dependency map nên nói rõ loại dependency: import, runtime call, database, cache, config, CI, hoặc ownership.
• Với bounded context, ghi cả boundary và leak: module nào đang phụ thuộc chéo, shared helper nào dễ thành God module.
• Với hot path, ưu tiên đọc test và observability trước khi sửa logic.
• Đưa convention bền vững vào CLAUDE.md, nhưng để chi tiết architecture thay đổi thường xuyên trong ARCHITECTURE.md.
• Sau khi tạo architecture artifact, review như code: diff nhỏ, evidence rõ, không biến tài liệu thành nơi chứa suy đoán.

8. Performance / cost / context

Khám phá codebase lớn có thể đốt context nhanh hơn implement một bug nhỏ. Lockfile, generated file, build output, snapshot, log, và node_modules là nguồn nhiễu lớn. Prompt tốt phải hướng Claude dùng công cụ tìm kiếm file/symbol trước, rồi chỉ đọc file có liên quan.

Cách tối ưu:

• Bắt đầu bằng file định hướng: package.json, README.md, CLAUDE.md, docker-compose.yml, route/module index.
• Yêu cầu Claude đọc theo lớp: entrypoint -> route/module registration -> service -> data access -> test.
• Dùng /context để kiểm tra tình trạng context khi session dài.
• Dùng /compact sau khi đã có summary có cấu trúc, không compact khi Claude vẫn đang lẫn fact và inference.
• Chia exploration thành backend, frontend, devops/test nếu repo lớn. Có thể dùng agents/subagents về sau để tách context, nhưng không cần áp dụng sớm.
• Không yêu cầu "đọc toàn repo". Thay bằng "đọc đủ để trả lời câu hỏi X, nêu phần chưa đủ bằng chứng".
• Lưu artifact tốt vào ARCHITECTURE.md để session sau không phải khám phá lại từ đầu.

Chi phí thật không chỉ là token. Một architecture map sai có thể làm bạn sửa nhầm bounded context, tạo dependency vòng, hoặc bỏ qua authorization hot path. Vì vậy trả thêm vài phút cho evidence-first exploration thường rẻ hơn rollback một patch lớn.

9. Checklist cuối bài

• Tôi đã chạy git status --short trước khi cho Claude Code khám phá repo.
• Tôi dùng plan mode hoặc quyền read-only ở phase exploration.
• Tôi yêu cầu Claude tìm entrypoint backend, frontend, test, migration/seed, Docker/local dev.
• Tôi có dependency map phân biệt import, runtime, data, cache, config.
• Tôi xác định được bounded context chính trong taskflow-ai.
• Tôi xác định được hot path cho tạo task, cập nhật status, list board.
• Tôi yêu cầu Claude tách Fact, Inference, và Unknown.
• Tôi tạo hoặc review được ARCHITECTURE.md chỉ từ bằng chứng đã đọc.
• Tôi có reading plan trước khi sửa feature task comments.
• Tôi biết rollback ARCHITECTURE.md nếu tài liệu sai hoặc quá rộng.

10. Bài tập

Bài cơ bản: mở taskflow-ai bằng claude --permission-mode plan, yêu cầu Claude tìm entrypoint backend/frontend/test/devops và trả về bảng evidence.

Bài nâng cao: cho Claude tạo ARCHITECTURE.md với giới hạn chỉ sửa đúng file này, rồi review git diff -- ARCHITECTURE.md để tìm claim thiếu bằng chứng.

Bài áp dụng project cá nhân: chọn một repo thật có ít nhất backend hoặc frontend. Yêu cầu Claude tạo reading plan trước khi sửa một feature nhỏ. Không implement feature cho đến khi bạn có danh sách module cần đọc và rủi ro nếu bỏ qua.

Tài liệu

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

Khám phá codebase lớn bằng Claude Code không phải là hỏi "repo này làm gì?". Mục tiêu là tạo hiểu biết có thể kiểm chứng: entrypoint ở đâu, bounded context nào tồn tại, dependency giữa module ra sao, hot path nào có rủi ro cao, và trước khi sửa feature cần đọc file nào.

Nguyên tắc Day 07:

• Dùng plan mode hoặc quyền read-only ở phase exploration.
• Yêu cầu Claude ghi rõ file/path đã đọc cho từng claim.
• Tách Fact from code, Inference, và Unknown / needs verification.
• Tạo ARCHITECTURE.md như artifact onboarding và context cache cho session sau.
• Không để Claude đọc secret, production data, generated output, lockfile dài, hoặc thư mục build nếu không cần.
• Trước khi sửa feature, yêu cầu Claude tạo reading plan theo module và rủi ro.

ARCHITECTURE.md tốt nên có:

• System overview.
• Entrypoints.
• Bounded contexts.
• Dependency map.
• Hot paths.
• Data and external dependencies.
• Testing and verification map.
• Read-before-editing guide.
• Unknowns and stale-risk notes.

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

Nhận task trên codebase lớn
  |
  v
Kiểm tra Git state
  |
  v
Mở Claude Code bằng plan/read-only mode
  |
  v
Tìm file định hướng
  |-- README.md / CLAUDE.md
  |-- package.json / workspace config
  |-- docker-compose.yml
  |-- backend/frontend entrypoint
  |
  v
Map architecture cấp cao
  |
  +-- Entrypoint
  +-- Bounded context
  +-- Dependency map
  +-- Hot path
  +-- Test/verification map
  |
  v
Phân loại claim
  |
  +-- Fact from code
  +-- Inference
  +-- Unknown
  |
  v
Tạo hoặc cập nhật ARCHITECTURE.md
  |
  v
Review diff và evidence
  |
  v
Tạo reading plan trước khi sửa feature

Luồng đọc cho feature task comments trong taskflow-ai:

Feature request
  |
  v
Đọc architecture map
  |
  v
Đọc bounded context tasks
  |
  v
Đọc auth/current user contract
  |
  v
Đọc data model + migration pattern
  |
  v
Đọc API route/service/repository
  |
  v
Đọc frontend API client + task detail/list UI
  |
  v
Đọc test pattern unit/integration/e2e
  |
  v
Mới lập plan implement

Bảng so sánh

Lỗi thường gặp

1. Hỏi Claude "giải thích toàn bộ repo"
   Output thường dài, chung chung, tốn token, và không hướng tới task cụ thể.

2. Tin architecture claim không có evidence
   Claude có thể suy luận theo pattern phổ biến của Node.js/React, nhưng repo thật có thể dùng convention khác.

3. Đọc quá nhiều file generated hoặc lockfile
   Context bị nhiễu bởi dist, coverage, snapshot, lockfile lớn, hoặc code generated.

4. Bỏ qua auth và authorization path
   Feature tasks thường phụ thuộc current user, team membership, permission, audit log. Nếu chỉ đọc service tasks, patch có thể lộ data.

5. Nhầm bounded context với folder
   Một folder shared có thể chứa validation, types, error, config. Đó không phải bounded context nghiệp vụ, nhưng có thể là dependency quan trọng.

6. Tạo ARCHITECTURE.md quá tự tin
   Tài liệu không có Unknown làm người sau tưởng mọi thứ đã được kiểm chứng.

7. Compact session quá sớm
   Nếu chưa chốt fact/inference, /compact có thể giữ lại kết luận sai và bỏ mất bằng chứng cần kiểm tra.

8. Cho quyền edit trong phase exploration
   Claude có thể "dọn dẹp" hoặc sửa docs/source khi bạn chỉ muốn đọc. Với repo lớn, đây là blast radius không cần thiết.

Cách debug

Khi Claude đưa architecture map chung chung:

Output này thiếu evidence. Hãy viết lại thành bảng Claim / Evidence file / Confidence / Next file to read.
Không thêm claim mới nếu chưa đọc file chứng minh.

Khi Claude đề xuất sửa feature trước khi đọc đủ module:

Chưa implement. Hãy tạo reading plan trước.
Với mỗi file/module cần đọc, ghi vì sao, rủi ro nếu bỏ qua, và claim nào cần kiểm chứng.

Khi ARCHITECTURE.md có claim nghi ngờ:

1. Chạy:

git diff -- ARCHITECTURE.md

2. Tìm claim không có path file.
3. Prompt lại:

Trong ARCHITECTURE.md, hãy tìm mọi câu không có evidence file/path.
Phân loại:
- Có thể bổ sung evidence bằng file đã đọc.
- Cần đọc thêm file.
- Nên xóa vì suy đoán.
Không sửa file, chỉ báo cáo.

Khi context bắt đầu dài:

• Dùng /context để xem tình trạng context nếu phiên bản Claude Code của bạn hỗ trợ.
• Trước khi /compact, yêu cầu Claude tạo summary có cấu trúc:

Chuẩn bị compact session. Hãy tạo summary giữ lại:
- Entrypoints đã xác minh.
- Bounded contexts và evidence.
- Dependency map quan trọng.
- Hot paths.
- Unknowns.
- Decisions đã approve.
- File tuyệt đối không sửa.

Khi muốn rollback artifact:

git status --short -- ARCHITECTURE.md

Nếu file tracked:

git restore -- ARCHITECTURE.md

Nếu file untracked và bạn chắc chắn muốn xóa:

git clean -f -- ARCHITECTURE.md

Không dùng git reset --hard hoặc git clean -fd để rollback một file tài liệu nhỏ.

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

• Claude Code Quickstart: https://code.claude.com/docs/en/quickstart
• Claude Code Best Practices: https://code.claude.com/docs/en/best-practices
• Claude Code Permissions: https://code.claude.com/docs/en/permissions
• Claude Code Memory: https://code.claude.com/docs/en/memory
• Claude Code Slash Commands: https://code.claude.com/docs/en/slash-commands
• Claude Code Subagents: https://code.claude.com/docs/en/sub-agents
• Git diff documentation: https://git-scm.com/docs/git-diff
• Git clean documentation: https://git-scm.com/docs/git-clean

Bài tập

Bài 1 — Cơ bản

Mục tiêu: dùng Claude Code khám phá taskflow-ai ở chế độ read-only và tạo bản đồ evidence.

Yêu cầu:

1. Mở terminal tại thư mục gốc taskflow-ai.
2. Kiểm tra trạng thái repo:

git status --short

Lệnh này giúp biết có file nào đang thay đổi trước khi bắt đầu. Kết quả kỳ vọng là rỗng hoặc chỉ gồm file bạn hiểu rõ. Nếu có file lạ, dừng lại và đọc diff trước.

3. Mở Claude Code:

claude --permission-mode plan

Lệnh này mở Claude ở mode phù hợp để đọc và lập plan. Không cấp quyền edit trong bài này.

4. Gửi prompt:

Hãy khám phá repo taskflow-ai ở mức architecture, chưa sửa file.

Tìm và trả về bảng:
- Entrypoint backend.
- Entrypoint frontend.
- Test setup.
- Migration/seed setup nếu có.
- Docker/local dev setup nếu có.
- Bounded context chính.

Mỗi dòng phải có:
- Claim.
- Evidence file/path.
- Confidence high/medium/low.
- File cần đọc tiếp nếu confidence chưa high.

Không đọc secret, .env, production dump, customer log, hoặc generated output.

Kết quả cần có: bảng evidence rõ ràng, không chỉ mô tả chung chung. Nếu Claude không ghi path file, yêu cầu làm lại.

Bài 2 — Thực tế

Mục tiêu: tạo ARCHITECTURE.md như artifact dùng lại cho team.

Yêu cầu:

1. Từ kết quả Bài 1, yêu cầu Claude đề xuất outline:

Dựa trên exploration vừa rồi, đề xuất outline ARCHITECTURE.md cho taskflow-ai.

Outline phải có:
- System overview.
- Entrypoints.
- Bounded contexts.
- Dependency map.
- Hot paths.
- Testing and verification map.
- Read before editing feature.
- Unknowns / needs verification.

Chưa tạo file. Chờ tôi approve.

2. Sau khi duyệt outline, mở Claude Code với quyền ghi hẹp:

claude --permission-mode default --tools "Read,Write,Edit,Bash" --allowedTools "Bash(git status *)" "Bash(git diff *)"

Lệnh này giới hạn built-in tool family vào đọc file, tạo/sửa file và Bash, đồng thời auto-approve riêng các Bash command khớp git status * hoặc git diff *. Rủi ro: nếu prompt không khóa phạm vi, Claude vẫn có thể sửa nhầm file khác bằng Write/Edit; vì vậy prompt tiếp theo phải khóa phạm vi vào ARCHITECTURE.md và vẫn cần review diff.

3. Gửi prompt:

Tạo ARCHITECTURE.md ở root taskflow-ai theo outline đã duyệt.

Giới hạn bắt buộc:
- Chỉ tạo hoặc sửa ARCHITECTURE.md.
- Không sửa source code, README, CLAUDE.md, package files, lockfile, migration, test, workflow.
- Mỗi section phải có evidence file/path.
- Tách rõ Fact from code, Inference, Unknown.
- Không tự commit.
- Sau khi ghi file, chạy git diff --stat -- ARCHITECTURE.md và git diff -- ARCHITECTURE.md, rồi tóm tắt.

4. Tự kiểm tra:

git diff --stat -- ARCHITECTURE.md

Kết quả kỳ vọng: chỉ ARCHITECTURE.md thay đổi.

5. Xem chi tiết:

git diff -- ARCHITECTURE.md

Kết quả kỳ vọng: tài liệu có path file cụ thể, có unknowns, không khẳng định quá mức.

Bài 3 — Nâng cao

Mục tiêu: dùng architecture map để lập reading plan trước khi sửa feature.

Feature giả định: thêm task comments cho taskflow-ai.

Yêu cầu:

1. Gửi prompt cho Claude:

Dựa trên ARCHITECTURE.md và source code hiện tại, hãy lập reading plan trước khi implement feature task comments.

Chưa sửa file.
Trả về bảng:
- Thứ tự đọc.
- File/module cần đọc.
- Vì sao cần đọc.
- Bounded context liên quan.
- Hot path bị ảnh hưởng.
- Rủi ro nếu bỏ qua.
- Claim cần verify.

Đặc biệt kiểm tra auth/current user, task ownership, database migration pattern, API contract, frontend API client, UI task detail/list, và test pattern.

2. Yêu cầu Claude tạo dependency map cho feature:

Hãy vẽ dependency map dạng text cho feature task comments:

Frontend UI -> API client -> Backend route/controller -> Service -> Repository/database -> Test layers.

Ghi rõ dependency nào đã có evidence và dependency nào chỉ là expected design.
Không implement.

3. Chọn 3 claim có confidence thấp và yêu cầu Claude đọc thêm đúng file cần thiết:

Chọn 3 claim confidence thấp nhất trong reading plan.
Với mỗi claim, chỉ đọc file tối thiểu để verify.
Sau đó cập nhật confidence và giải thích bằng evidence.
Không sửa file.

Kết quả cần có: trước khi implement, bạn biết chính xác module nào cần đọc và rủi ro nếu bỏ qua.

Bài 4 — Review & Reflection

Mục tiêu: đánh giá chất lượng exploration và biến nó thành rule làm việc.

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

1. Trong ARCHITECTURE.md, claim nào có evidence mạnh nhất? Vì sao?
2. Claim nào có vẻ là inference và cần đọc thêm file?
3. Hot path nào của taskflow-ai rủi ro nhất khi thêm task comments: tạo task, cập nhật status, list board, hay auth/current user?
4. Nếu Claude đề xuất implement ngay sau exploration, bạn sẽ phản hồi bằng prompt nào?
5. Bạn sẽ thêm rule gì vào CLAUDE.md để buộc Claude tách Fact, Inference, Unknown khi khám phá codebase lớn?

Prompt reflection gợi ý:

Review quá trình exploration Day 07.

Hãy giúp tôi soạn 8 rule ngắn cho CLAUDE.md về khám phá codebase lớn:
- Evidence required.
- Không đọc secret.
- Không implement trước reading plan.
- Giới hạn permissions.
- Cách dùng /context và /compact.
- Cách cập nhật ARCHITECTURE.md.

Chỉ draft rule, chưa sửa file.

Tiêu chí hoàn thành

• Đã chạy git status --short trước khi exploration.
• Đã dùng claude --permission-mode plan cho phase đọc codebase.
• Có bảng entrypoint, bounded context, dependency map, hot path kèm evidence file/path.
• Có ARCHITECTURE.md hoặc draft đủ chi tiết để tạo file.
• ARCHITECTURE.md tách rõ Fact, Inference, Unknown.
• Đã review git diff --stat -- ARCHITECTURE.md và git diff -- ARCHITECTURE.md.
• Có reading plan cho feature task comments.
• Reading plan nêu rõ module cần đọc trước khi sửa, rủi ro nếu bỏ qua, và claim cần verify.
• Không sửa source code, migration, config, README, hoặc Day khác trong bài tập này.

Gợi ý nếu bí

Nếu Claude trả lời quá chung:

Output này chưa đủ. Hãy viết lại thành bảng Claim / Evidence file / Confidence / Next file to read.
Không có evidence thì chuyển sang Unknown.

Nếu không tìm được entrypoint:

Hãy dùng read-only search để tìm package.json scripts, file bootstrap server, route registration, React mount point, và test config.
Liệt kê command hoặc file đã đọc.
Không sửa file.

Nếu Claude muốn đọc .env:

Không đọc .env hoặc secret file. Hãy suy luận từ .env.example, config schema, README, hoặc code validation nếu có.
Nếu không đủ bằng chứng, ghi Unknown.

Nếu Claude muốn implement feature:

Chưa implement. Quay lại reading plan.
Hãy chỉ ra module cần đọc, risk map, và acceptance criteria cần xác nhận trước khi sửa code.

Nếu ARCHITECTURE.md sai hoặc quá rộng:

git status --short -- ARCHITECTURE.md
git diff -- ARCHITECTURE.md

Nếu file đã tracked và muốn bỏ thay đổi:

git restore -- ARCHITECTURE.md

Nếu file mới untracked và chắc chắn muốn xóa:

git clean -f -- ARCHITECTURE.md

Chỉ dùng lệnh rollback sau khi đã xác nhận đúng path. Không dùng git reset --hard để xử lý một file tài liệu.

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

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

Claim: Backend entrypoint is backend/src/main.ts
Evidence: backend/src/main.ts imports createServer from ...
Confidence: high
Next file to read: backend/src/app.ts for route registration

Nếu repo của bạn dùng tên khác, path khác vẫn đúng miễn là có evidence thật.

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

ARCHITECTURE.md có outline tương tự:

# Architecture — taskflow-ai

## Last verified source files
## System overview
## Entrypoints
## Bounded contexts
## Dependency map
## Hot paths
## Testing and verification map
## Read before editing feature
## Unknowns / needs verification

Mỗi section có file/path. Ví dụ tốt:

Fact from code:
- The tasks API is registered from backend/src/tasks/tasks.routes.ts.

Inference / needs verification:
- Comments likely belong near the tasks bounded context, but no comments module exists yet.

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

Reading plan cho task comments nên bao gồm ít nhất:

• Tasks route/controller hoặc tương đương.
• Tasks service/domain logic.
• Data access layer hoặc ORM model/migration pattern.
• Auth/current user middleware.
• Shared API types/validation schema nếu có.
• Frontend API client.
• Task detail/list component.
• Unit/integration/e2e test pattern.

Dependency map mẫu:

TaskComments UI
  -> task API client
  -> comments route/controller
  -> comments service
  -> task ownership/auth check
  -> comments table/repository
  -> integration tests
  -> e2e task detail flow

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

Rule mẫu có thể đưa vào CLAUDE.md:

- Khi khám phá codebase lớn, mọi architecture claim phải có evidence file/path.
- Tách Fact from code, Inference, và Unknown trước khi lập plan sửa code.
- Không implement feature mới trước khi có reading plan theo bounded context.
- Không đọc .env, secret, production dump, customer log, generated output nếu không được yêu cầu rõ.
- Với session dài, dùng /context để kiểm tra context và chỉ /compact sau khi đã tạo summary có entrypoint, hot path, unknowns, file scope.