Day 20 - Capstone: build feature end-to-end

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

Sau Day 20, học viên có thể dùng Claude Code để đi hết một feature thật trong taskflow-ai theo workflow:

clarify -> plan -> implement -> test -> review -> document

Kết quả cần đạt:

Tổng hợp project memory (CLAUDE.md, .claude/CLAUDE.md, .claude/rules/), permissions, hooks, skills, subagents, MCP/docs search, GitHub workflow, testing, security và context summary.
Thêm feature task comments end-to-end.
Đánh giá output của Claude Code bằng acceptance criteria, test evidence và review diff.
Viết PR description và postmortem trung thực.
Biết rollback khi Claude sửa sai.

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

Feature nhỏ như “comment trong task” thường chạm nhiều lớp:

Database/schema hoặc storage.
Backend API.
Authorization.
Validation.
Frontend UI.
Unit/integration/e2e tests.
GitHub PR, review, docs, rollback.

Claude Code mạnh ở đọc codebase, đi theo pattern có sẵn, sinh test và sửa lỗi lặp. Nhưng Claude có thể đoán sai architecture, bỏ sót authorization, viết test happy path quá mỏng hoặc sửa lan sang module không liên quan. Human vẫn chịu trách nhiệm review và merge.

3. Kiến thức nền

Acceptance criteria cho `task comments`

API:

GET /api/tasks/:taskId/comments: liệt kê comments theo task, sort ổn định.
POST /api/tasks/:taskId/comments: thêm comment, trim content, reject rỗng, max 1000 ký tự.
DELETE /api/tasks/:taskId/comments/:commentId: xóa comment.
Nếu dùng database thật, comment có foreign key tới task và index phục vụ query theo taskId + createdAt.

Security/authorization:

Chỉ user có quyền xem task được list/create comment.
Delete chỉ cho comment author hoặc task owner.
Nếu chưa có auth thật, dùng x-user-id trong dev/test helper, không hard-code user trong service.

Frontend:

Task detail có comments section.
Có loading, error, empty state.
Form add comment có validation client-side.
Delete action chỉ hiện khi user có quyền.
Sau add/delete, UI cập nhật bằng refetch hoặc optimistic update có kiểm soát.

Tests:

Backend integration tests cho list/create/delete/validation/auth.
Test case phải bắt lỗi comment-task mismatch, ví dụ gọi DELETE /tasks/A/comments/commentOfTaskB.
UI/component tests cho render, submit, validation, delete.
E2E flow nếu project đã có setup.

Kỹ năng Claude Code nối lại

Project memory: CLAUDE.md hoặc .claude/CLAUDE.md; project rules trong .claude/rules/; personal rules trong ~/.claude/rules/.
Permissions/settings: dùng /permissions, permission mode và .claude/settings.json để giới hạn tool, command, protected paths và command nguy hiểm.
Hooks: auto check hoặc chặn hành vi nhạy cảm qua các event như PreToolUse, PostToolUse, UserPromptSubmit.
Skills/subagents: tách backend, frontend, reviewer, tester; project skills nằm trong .claude/skills/<skill-name>/SKILL.md, project subagents nằm trong .claude/agents/.
MCP/docs search: tra docs framework/API hiện hành khi cần.
Context/session commands: /plan, /context, /compact, /clear, /rewind, /usage.
GitHub workflow: branch, PR, review, checks.

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

Bước 0: Chuẩn bị branch

Chạy ở root taskflow-ai.

git status --short
git switch -c feature/task-comments

Thông tin lệnh:

Command	Mục đích	Output kỳ vọng	Rủi ro / lưu ý
`git status --short`	Kiểm tra working tree trước khi giao Claude sửa code	Không có output hoặc chỉ có thay đổi đã hiểu rõ	Nếu có file bẩn của người khác, không dùng rollback diện rộng
`git switch -c feature/task-comments`	Tạo branch riêng cho capstone	Git báo đã chuyển sang branch mới	Nếu branch đã tồn tại, dùng `git switch feature/task-comments` sau khi kiểm tra đúng branch

Bước 1: Khám phá codebase

Chạy ở root taskflow-ai.

rg -n "task|tasks|Task|route|controller|spec|test" . --glob "!node_modules/**" --glob "!dist/**" --glob "!coverage/**"

Lệnh tìm code liên quan task, route, UI và tests. Output kỳ vọng là các file ứng viên như route/controller/service, component task detail và test files. Rủi ro: output lớn; chỉ đưa path liên quan vào prompt, không paste toàn bộ kết quả nếu có nhiều dòng.

Prompt:

Bạn đang ở repo taskflow-ai. Trước khi code, hãy đọc cấu trúc liên quan đến task detail, task API, auth hiện có và test setup. Không chỉnh file.

Trả lời:
1. Stack backend/frontend/test đang dùng.
2. Các file nhiều khả năng cần sửa.
3. Convention API và error response hiện tại.
4. Những câu hỏi cần clarify trước khi implement.

Bước 2: Clarify

Prompt:

Clarify feature task comments cho taskflow-ai.

Yêu cầu bắt buộc:
- add/list/delete comments theo task
- validate content: trim, required, max 1000 chars
- link comment với task
- auth giả lập bằng x-user-id nếu chưa có auth thật
- delete chỉ author hoặc task owner
- test backend + UI + e2e
- PR description + postmortem

Hãy hỏi tối đa 7 câu cần thiết. Nếu repo đã có convention rõ, tự chọn theo convention và ghi assumption. Chưa sửa file.

Bước 3: Plan

Prompt:

Dựa trên câu trả lời clarify và codebase taskflow-ai, lập implementation plan cho feature task comments.

Plan phải có:
- data model/schema thay đổi nếu cần
- backend endpoints
- frontend components/state
- test plan backend/UI/e2e
- security/authorization checks
- migration hoặc seed nếu cần
- rollback plan
- danh sách file dự kiến sửa

Không code. Đánh dấu việc nào cần human confirm.

Review plan: có auth không, validation server-side không, tests có forbidden path không, file list có ngoài scope không. Nếu plan đề xuất tạo framework mới, đổi response shape cũ hoặc sửa file không liên quan đến task comments, yêu cầu Claude thu hẹp lại trước khi implement.

Bước 4: Implement backend

Prompt:

Implement backend cho task comments theo plan đã duyệt.

Ràng buộc:
- Đi theo pattern route/controller/service/repository hiện có.
- Không đổi response shape API cũ.
- Nếu chưa có auth thật, đọc user id từ header x-user-id trong test/dev helper.
- Validate content server-side: trim, required, max 1000 chars.
- Delete chỉ cho comment author hoặc task owner.
- Thêm integration tests cho list, create, validation, task not found, unauthorized, delete by author, delete by task owner, reject delete by other user.

Sau khi sửa, chạy đúng lệnh test backend đã có. Với mỗi lệnh, báo cwd, command, mục đích, expected output, risk.

Command thường dùng, chạy ở root taskflow-ai hoặc backend workspace nếu repo tách package:

npm run test:backend
git diff --stat

Command	Mục đích	Output kỳ vọng	Rủi ro / rollback
`npm run test:backend`	Kiểm tra API/service/repository và validation/auth	Test runner pass; nếu fail, log chỉ rõ test case	Có thể cần test DB/env; không tự sửa config lớn khi chưa đọc docs repo
`git diff --stat`	Xem blast radius sau backend phase	Chỉ các file backend/schema/test liên quan	Nếu diff lan rộng, dừng và dùng `/rewind` hoặc `git restore -- path/to/file` cho từng file

Bước 5: Implement frontend

Prompt:

Implement frontend UI cho task comments.

Yêu cầu:
- Tìm task detail page/component hiện có.
- Thêm comments section theo design hiện tại.
- Có loading, error, empty state.
- Form add comment: textarea, submit disabled khi rỗng/loading, lỗi max length.
- Delete button chỉ hiện với user có quyền.
- Sau add/delete cập nhật list.
- Không đổi layout lớn.
- Thêm UI/component tests theo stack hiện có.

Command thường dùng, chạy ở root taskflow-ai hoặc frontend workspace nếu repo tách package:

npm run test:frontend
npm run lint
npm run typecheck

Command	Mục đích	Output kỳ vọng	Rủi ro / lưu ý
`npm run test:frontend`	Kiểm tra component/UI behavior	UI tests pass, có coverage cho empty/loading/error/add/delete	Script có thể tên khác; đọc `package.json` trước khi đổi
`npm run lint`	Bắt lint/style issue	Không còn lint error	Lint autofix có thể tạo diff format lớn, review `git diff --stat`
`npm run typecheck`	Bắt type error giữa API client và UI	Typecheck pass	Nếu fail do generated types, tìm command generate đã có trong repo

Bước 6: E2E hoặc test thay thế

Prompt:

Thêm e2e test cho task comments nếu project đã có setup.

Flow:
1. Mở task detail.
2. Thấy empty state hoặc list comments.
3. Add comment "Ship review notes".
4. Comment xuất hiện.
5. Reload/refetch, comment vẫn còn.
6. Delete comment.
7. User khác không thấy delete hoặc API từ chối.

Nếu chưa có e2e setup, đề xuất integration/component test thay thế và ghi rõ gap.

Command, chạy ở root taskflow-ai hoặc workspace e2e nếu repo tách package:

npm run e2e

Output kỳ vọng: browser test pass cho flow add/delete comment. Rủi ro: cần dev server/test DB/seed ổn định; nếu chưa có setup, không dựng framework lớn chỉ cho một bài mà ghi rõ gap và tăng integration/component coverage.

Bước 7: Review diff

Chạy ở root taskflow-ai.

git diff --stat
git diff
git status --short

Command	Mục đích	Output kỳ vọng	Rủi ro / lưu ý
`git diff --stat`	Xem phạm vi thay đổi	Chỉ file liên quan feature, test, migration/docs cần thiết	Diff quá rộng là dấu hiệu phải chia lại phase
`git diff`	Review logic cụ thể	Dễ đọc, không có formatting churn lớn	Output dài; review theo từng file hoặc path
`git status --short`	Bắt untracked/changed files	Không có file lạ ngoài plan	Không dùng `git restore .` trong repo có nhiều người cùng sửa

Prompt:

Review toàn bộ diff như senior reviewer.

Tập trung:
- security/authz bug
- validation gap
- stale UI state
- consistency với pattern hiện có
- test có thật sự bắt bug không
- migration/seed risk
- breaking change với API cũ
- file ngoài phạm vi feature hoặc ngoài file list trong plan

Trả findings trước, severity cao đến thấp, có file/line. Không sửa file.

Bước 8: PR description và postmortem

Prompt PR:

Viết PR description cho feature task comments.

Format:
## Summary
## Acceptance Criteria
## Implementation Notes
## Tests
## Security / Authorization
## Screenshots hoặc UI Notes
## Rollback Plan
## Postmortem

Dựa trên diff hiện tại và test output đã chạy. Không phóng đại. Nếu test nào chưa chạy, ghi rõ Not run và lý do.

Prompt postmortem:

Viết postmortem ngắn cho lần dùng Claude Code implement task comments:
- Claude làm tốt gì
- Claude sai/suýt sai gì
- Guardrail cần thêm vào CLAUDE.md/settings/hooks/tests
- Điều human phải review thủ công trước merge

Bước 9: Rollback khi Claude làm sai

Ưu tiên /rewind hoặc Esc + Esc trong Claude Code để mở checkpoint menu. Chọn restore code, restore conversation, hoặc summarize tùy lỗi. Lưu ý: checkpointing chỉ theo dõi file Claude sửa bằng tool edit; thay đổi do Bash command, migration tự chạy hoặc thao tác ngoài Claude Code có thể không được undo bởi /rewind.

Nếu cần git, rollback từng file:

git diff -- path/to/file
git restore -- path/to/file

git restore -- path/to/file mất toàn bộ thay đổi chưa commit của file đó. Không dùng với . nếu workspace có thay đổi của người khác. Nếu đã thêm migration, cần rollback migration theo cơ chế của stack hiện có và xác nhận test database không còn schema dư.

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

Clarify:

Trước khi code, hãy clarify feature task comments. Hỏi tối đa 7 câu. Nếu repo có convention rõ thì tự chọn và ghi assumption. Không sửa file.

Plan:

Lập plan end-to-end cho task comments: backend API, UI, tests, auth, validation, rollback, file list. Không code.

Backend:

Implement backend task comments theo pattern hiện có. Thêm API list/create/delete, validation server-side, owner/author authorization, integration tests.

Frontend:

Implement comments section trong task detail. Có list, empty/loading/error, add form, delete action, refetch hoặc optimistic update.

Tests:

Audit test coverage cho task comments. Bổ sung validation, auth, UI state, e2e happy path và forbidden path. Không viết test chỉ kiểm tra implementation detail.

Review:

Review diff như senior reviewer. Findings trước, severity cao đến thấp, file/line cụ thể. Tập trung auth, validation, API compatibility, stale UI, missing tests.

PR:

Viết PR description từ diff và test output hiện tại. Ghi rõ test chưa chạy.

6. Trade-offs

Quyết định	Option A	Option B	Chọn khi
Delete comment	Hard delete	Soft delete	Hard delete cho capstone đơn giản; soft delete nếu cần audit
Sort comments	`createdAt ASC`	`createdAt DESC`	ASC cho thread đọc tự nhiên; DESC nếu ưu tiên activity mới
Auth	Auth thật	`x-user-id` giả lập	Dùng auth thật nếu có; giả lập chỉ cho học/test
UI update	Refetch sau mutate	Optimistic update	Refetch ít bug hơn; optimistic khi UX cần nhanh
E2E	Full browser	API + component	Full browser nếu setup sẵn; không dựng framework lớn chỉ cho 1 bài
Context	Một session dài	Chia theo phase	Chia phase nếu repo lớn hoặc context gần đầy
Pagination	List hết comments	Cursor/page limit	List hết chỉ ổn cho capstone nhỏ; thêm limit/cursor nếu task có thể có nhiều comments
Query performance	Không index	Index `taskId, createdAt`	Index khi comments lưu DB và list theo task thường xuyên

7. Best practices

Bắt Claude clarify trước khi sửa.
Yêu cầu Claude đọc pattern hiện có, không tự tạo architecture mới.
Viết acceptance criteria trước implementation.
Test auth và validation trước UI polish.
Review diff theo file, không chỉ đọc summary của Claude.
Dùng /compact với focus khi session dài.
Dùng /context để xem context đang bị tiêu hao bởi phần nào trước khi compact.
Dùng /clear khi chuyển task.
Đưa rule bền vững vào CLAUDE.md.
Scope MCP tools và permissions tối thiểu.
Không dùng bypassPermissions ngoài container/VM cô lập; với capstone, ưu tiên plan hoặc acceptEdits rồi review diff.
Không render comment bằng raw HTML. Nếu sau này hỗ trợ Markdown, sanitize output và test XSS.
Human chịu trách nhiệm cuối cùng với security, migration và merge.

8. Performance / cost / context

Không paste toàn bộ repo vào prompt; dùng rg và file liên quan.
Tách backend, frontend, tests, review thành phase riêng.
Dùng subagent cho review/docs search khi có lợi.
Dùng docs search/MCP khi đụng framework/API thay vì đoán; ưu tiên official docs và ghi nguồn nếu quyết định phụ thuộc API/tooling hiện hành.
Dùng /usage hoặc /cost nếu cần kiểm tra mức tiêu thụ, và lưu test evidence ngắn thay vì paste log dài vào context.
Dùng /compact trước khi context đầy và ghi rõ focus.
Sau compact, xác nhận lại API shape, auth rule, files changed, tests run.
Với command output dài, chỉ giữ phần fail liên quan.

9. Checklist cuối bài

10. Bài tập

Hoàn thành feature task comments trong taskflow-ai bằng workflow chuẩn.

Deliverables:

Backend API + tests.
Frontend UI + tests.
E2E hoặc ghi rõ gap.
PR description.
Postmortem 10-15 dòng.
Một update nhỏ cho CLAUDE.md hoặc .claude/CLAUDE.md rút ra từ bài học.

Tài liệu

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

Day 20 là capstone: dùng Claude Code build feature task comments end-to-end trong taskflow-ai.

Workflow chuẩn:

clarify -> acceptance criteria -> plan -> backend -> frontend -> tests -> review -> PR -> postmortem

Các năng lực cần nối lại:

Project memory: CLAUDE.md hoặc .claude/CLAUDE.md; project rules trong .claude/rules/; personal rules trong ~/.claude/rules/.
Permissions/settings/hooks, gồm /permissions, permission mode, .claude/settings.json và hook events như PreToolUse, PostToolUse.
Skills/subagents cho backend, frontend, reviewer, tester; project skill nằm trong .claude/skills/<skill-name>/SKILL.md, project subagent nằm trong .claude/agents/.
MCP/docs search khi cần API/framework docs hiện hành.
GitHub workflow: branch, PR, checks, review.
Context/session commands: /plan, /context, /compact, /clear, /rewind, /usage.
Human review/merge là bắt buộc.

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

Clarify requirement
  -> write acceptance criteria
  -> plan files and tests
  -> backend API
  -> backend tests
  -> frontend UI
  -> UI tests
  -> e2e or documented gap
  -> review diff
  -> PR description
  -> postmortem and guardrails

Luồng feature:

User opens task detail
  -> UI calls GET /api/tasks/:taskId/comments
  -> API checks task access
  -> user submits comment
  -> API validates content and user
  -> DB/storage creates comment
  -> UI refetches or updates list
  -> user deletes comment
  -> API checks author or task owner

Bảng so sánh

Chủ đề	Cách yếu	Cách tốt trong capstone
Requirement	“Thêm comment”	Acceptance criteria rõ
Prompt	Một prompt dài làm hết	Chia clarify, plan, backend, frontend, tests, review
Context	Đọc lan toàn repo	Dùng `rg`, file liên quan, compact có focus
Auth	Bỏ qua vì project học	Auth thật nếu có, fallback `x-user-id` có test
Validation	Chỉ validate frontend	Validate server-side
Test	Chỉ happy path	Có validation, forbidden, not found
Data integrity	Comment chỉ có `commentId`	Comment luôn scoped bởi `taskId` và FK/index nếu có DB
Performance	List không giới hạn mãi mãi	Capstone có thể đơn giản, nhưng ghi rõ khi cần limit/cursor
Review	Tin Claude nói done	Đọc diff, chạy test, review security
Rollback	Revert cả branch	`/rewind` cho checkpoint Claude edit, hoặc restore từng file
Docs	PR chung chung	PR có test evidence, risk, rollback

Lỗi thường gặp

Claude tạo API route khác convention.
Response shape không giống API cũ.
Comment không kiểm tra task tồn tại.
Comment của task A bị xóa qua URL task B.
Thiếu index theo taskId, createdAt, list comment chậm khi dữ liệu tăng.
Không đặt giới hạn số comments trả về dù product có thể dùng lâu dài.
Chỉ author được xóa, quên task owner.
Validate client-side nhưng backend vẫn nhận content rỗng.
Render comment bằng raw HTML hoặc Markdown không sanitize, tạo XSS risk.
UI không xử lý loading/error/empty.
Test mock quá sâu, không bắt bug route/service thật.
E2E phụ thuộc dữ liệu local không seed ổn định.
Claude sửa formatting lớn làm diff khó review.
Compact làm mất decision vì không có summary tốt.

Cách debug

Chạy ở root taskflow-ai:

git status --short
git diff --stat
git diff -- path/to/file
npm run lint
npm run test
npm run e2e

Ý nghĩa:

git status --short: xem file changed/untracked.
git diff --stat: xem blast radius.
git diff -- path/to/file: review một file.
npm run lint: bắt lint/style issue.
npm run test: chạy suite chính nếu có.
npm run e2e: kiểm tra flow browser nếu setup sẵn.

Rủi ro: script có thể tên khác hoặc cần service/test DB. Đọc package.json và docs repo trước khi chạy.

Debug theo triệu chứng:

API 404: kiểm tra task seed, route param, comment-task relation.
API 403: kiểm tra user hiện tại, x-user-id, owner/author logic.
Add comment thành công nhưng UI không đổi: kiểm tra cache/refetch/state update.
Delete biến mất rồi reload lại xuất hiện: optimistic update đang che lỗi API.
Test pass nhưng manual fail: test mock sai layer hoặc thiếu integration.
Claude đi sai hướng: dừng, /rewind, chia lại backend-only.
/rewind không undo được thay đổi do Bash command tạo ra: kiểm tra git diff và rollback bằng Git/migration tool nếu cần.

Checklist debug nhanh:

Cwd	Command	Mục đích	Output kỳ vọng	Rủi ro
Root `taskflow-ai`	`git status --short`	Xác nhận file changed/untracked	Chỉ file feature đã biết	Không dùng restore diện rộng khi có thay đổi của người khác
Root `taskflow-ai`	`git diff --stat`	Xem blast radius	File list khớp plan	Diff lớn dễ che bug logic
Root hoặc workspace backend	`npm run test:backend` hoặc script tương đương	Kiểm tra API/auth/validation	Pass hoặc fail rõ test case	Có thể cần test DB/env
Root hoặc workspace frontend	`npm run test:frontend` hoặc script tương đương	Kiểm tra UI states	Pass	Test mock sai layer vẫn có thể bỏ sót integration bug
Root hoặc workspace e2e	`npm run e2e`	Kiểm tra browser flow	Pass với seed ổn định	Có thể cần dev server/test DB

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

Claude Code Overview: https://code.claude.com/docs/en/overview
Claude Code Memory: https://code.claude.com/docs/en/memory
Claude Code Commands: https://code.claude.com/docs/en/commands
Claude Code Checkpointing: https://code.claude.com/docs/en/checkpointing
Claude Code Permission Modes: https://code.claude.com/docs/en/permission-modes
Claude Code Settings: https://code.claude.com/docs/en/settings
Claude Code Hooks: https://code.claude.com/docs/en/hooks
Claude Code Skills: https://code.claude.com/docs/en/skills
Claude Code Subagents: https://code.claude.com/docs/en/sub-agents
Claude Code MCP: https://code.claude.com/docs/en/mcp
Claude Code GitHub Actions: https://code.claude.com/docs/en/github-actions
GitHub Pull Requests: https://docs.github.com/en/pull-requests
Fastify Docs: https://fastify.dev/docs/latest/
PostgreSQL Docs: https://www.postgresql.org/docs/
Vitest Docs: https://vitest.dev/guide/
React Docs: https://react.dev/
Playwright Docs: https://playwright.dev/docs/intro

Bài tập

Bài 1 — Cơ bản

Mục tiêu: clarify và plan feature task comments, chưa code.

Yêu cầu:

Chạy Claude Code trong repo taskflow-ai.
Yêu cầu Claude đọc code liên quan task, API, UI, test.
Tạo acceptance criteria cho list, add, delete, validation, authorization, tests.
Tạo implementation plan có file list dự kiến.
Không sửa file trong bài này.

Chạy ở root taskflow-ai:

git status --short
rg -n "task|tasks|Task" . --glob "!node_modules/**" --glob "!dist/**" --glob "!coverage/**"

Chi tiết lệnh:

Command	Mục đích	Output kỳ vọng	Rủi ro / lưu ý
`git status --short`	Đảm bảo biết rõ trạng thái repo trước khi nhờ Claude đọc/sửa	Không có output hoặc chỉ có thay đổi đã hiểu rõ	Nếu có file bẩn của người khác, không dùng rollback diện rộng
`rg -n "task	tasks	Task" . --glob "!node_modules/" --glob "!dist/" --glob "!coverage/**"`	Tìm code task liên quan đến API, UI, test

Prompt:

Bạn là planning agent. Hãy đọc code liên quan đến task trong taskflow-ai, không sửa file. Tạo acceptance criteria và implementation plan cho feature task comments. Ghi rõ assumption, file dự kiến sửa, test plan và câu hỏi cần human confirm.

Bài 2 — Thực tế

Mục tiêu: implement backend + frontend.

Backend:

GET /api/tasks/:taskId/comments
POST /api/tasks/:taskId/comments
DELETE /api/tasks/:taskId/comments/:commentId
Validate content: trim, required, max 1000 chars.
Gắn comment với task.
Delete chỉ comment.authorId hoặc task.ownerId.

Frontend:

Comments section trong task detail.
List, empty/loading/error state.
Form add comment.
Delete button theo quyền.
UI cập nhật sau add/delete.

Prompt:

Implement feature task comments theo plan đã duyệt. Làm backend trước, test backend pass rồi mới làm frontend. Bám pattern repo hiện có. Không đổi API cũ. Sau mỗi phase, báo file đã sửa, test đã chạy, lỗi còn lại.

Commands:

npm run test:backend
npm run test:frontend
npm run lint
git diff --stat

Các lệnh chạy ở root taskflow-ai hoặc workspace tương ứng nếu repo tách apps/api, apps/web, packages/*.

Command	Mục đích	Output kỳ vọng	Rủi ro / lưu ý
`npm run test:backend`	Kiểm tra backend API/service/repository cho comments	Pass các case list/create/delete/validation/auth	Script có thể tên khác; kiểm tra `package.json`, test DB và env
`npm run test:frontend`	Kiểm tra component/UI comments section	Pass các state empty/loading/error/add/delete	Mock quá sâu có thể bỏ sót lỗi API integration
`npm run lint`	Bắt lỗi lint/style	Không còn lint error	Autofix có thể tạo diff lớn, cần review lại
`git diff --stat`	Kiểm tra phạm vi thay đổi sau mỗi phase	Chỉ file liên quan feature/test/migration	Nếu diff lan sang module không liên quan, dừng và review

Bài 3 — Nâng cao

Mục tiêu: hoàn thiện test, review, rollback và guardrail.

Thêm backend tests cho:

Add/list/delete happy path.
Empty content.
Too long content.
Task not found.
Comment-task mismatch: không xóa được comment của task khác qua URL hiện tại.
Unauthorized user.
Delete by author.
Delete by task owner.
Reject delete by other user.

Thêm UI tests cho:

Render empty state.
Submit valid comment.
Show validation error.
Delete allowed comment.
Hide/disable delete for unauthorized user.

Nếu có e2e setup, thêm flow browser. Nếu không, ghi rõ gap và tăng integration/component coverage.

Prompt review:

Review diff hiện tại như senior reviewer. Findings trước, có severity và file/line. Tập trung security, validation, stale UI state, test gap, API compatibility. Không sửa file.

Prompt guardrail:

Từ lỗi hoặc rủi ro phát hiện trong feature task comments, đề xuất một rule ngắn để thêm vào CLAUDE.md. Rule phải cụ thể, kiểm chứng được, không chung chung.

Commands:

npm run test
npm run e2e
git diff

Chạy ở root taskflow-ai hoặc workspace tương ứng.

Command	Mục đích	Output kỳ vọng	Rủi ro / rollback
`npm run test`	Chạy suite chính sau khi backend + frontend hoàn tất	Pass hoặc fail rõ test case	Có thể lâu; nếu fail unrelated, ghi rõ evidence và không sửa lan
`npm run e2e`	Kiểm tra browser flow add/delete comment	Pass với seed/test DB ổn định	Có thể cần dev server/test DB; nếu chưa có setup, ghi gap
`git diff`	Review logic thật trước khi viết PR	Diff đọc được, không có formatting churn lớn	Output dài; review theo path hoặc yêu cầu Claude review từng nhóm file

Rollback nếu Claude đi sai hướng:

Dùng /rewind hoặc Esc + Esc trong Claude Code để mở checkpoint menu cho thay đổi do Claude edit.
Nếu thay đổi đến từ Bash command hoặc migration, checkpoint có thể không undo được; dùng git diff -- path/to/file, git restore -- path/to/file và rollback migration theo tool của repo.
Không dùng git restore . nếu workspace có thay đổi của người khác.

Bài 4 — Review & Reflection

Viết PR description dựa trên diff và test evidence:

Viết PR description cho feature task comments.

Format:
## Summary
## Acceptance Criteria
## Implementation Notes
## Tests
## Security / Authorization
## Screenshots hoặc UI Notes
## Rollback Plan
## Postmortem

Dựa trên diff và test output đã chạy. Test nào chưa chạy thì ghi rõ Not run và lý do.

Viết postmortem 10-15 dòng:

Claude làm tốt gì?
Claude sai hoặc suýt sai gì?
Prompt nào giúp cải thiện chất lượng?
Test nào bắt được bug?
Guardrail nào nên thêm?
Phần nào human bắt buộc review trước merge?
Nếu làm lại, bạn sẽ chia phase khác không?

Prompt:

Dựa trên toàn bộ session và diff feature task comments, viết postmortem ngắn. Không tô hồng. Nêu rõ Claude làm tốt gì, sai gì, test/guardrail nào cần thêm, và human phải review gì trước merge.

Tiêu chí hoàn thành

Gợi ý nếu bí

Nếu không biết stack, yêu cầu Claude đọc package.json, routes, test files trước.
Nếu test command fail vì thiếu env, yêu cầu Claude tìm test setup, không tự tạo config mới ngay.
Nếu auth chưa có, dùng x-user-id trong helper/middleware test/dev, không rải trong controller.
Nếu UI state rối, dùng refetch sau mutate trước, optimistic update sau.
Nếu hiển thị comment rich text/Markdown, yêu cầu sanitize; mặc định dùng text rendering, không raw HTML.
Nếu e2e chưa có, ghi gap và tăng integration/component test.
Nếu Claude sửa quá nhiều file, dừng, git diff --stat, /rewind, chia lại backend-only.
Nếu dùng docs search/MCP, yêu cầu Claude ưu tiên official docs cho Fastify/NestJS, React, Vitest/Jest, Playwright, PostgreSQL và Claude Code.

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

Expected API:

GET /api/tasks/:taskId/comments
- 200: [{ id, taskId, authorId, content, createdAt }]
- 403/404 nếu user không có quyền hoặc task không tồn tại

POST /api/tasks/:taskId/comments
- 201/200: comment mới
- 400/422 nếu content rỗng hoặc quá 1000 ký tự

DELETE /api/tasks/:taskId/comments/:commentId
- 204/200 khi author hoặc task owner xóa
- 403 nếu user không có quyền
- 404 nếu comment/task không tồn tại hoặc không thuộc task

Expected UI:

Task detail hiển thị Comments.
User submit comment hợp lệ thì comment xuất hiện.
Content rỗng/quá dài hiển thị lỗi.
Author hoặc task owner thấy delete action.
User khác không thấy delete hoặc API từ chối.
Reload trang vẫn thấy comment đã tạo.

Expected PR:

## Summary
- Added task comments API for list/create/delete.
- Added comments UI on task detail.
- Added validation and owner/author delete checks.

## Tests
- npm run test:backend
- npm run test:frontend
- npm run e2e

## Security / Authorization
- Create/list requires task access.
- Delete requires comment author or task owner.

## Rollback Plan
- Revert PR.
- Roll back migration if one was added.

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

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

3. Kiến thức nền

Acceptance criteria cho task comments

Kỹ năng Claude Code nối lại

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

Bước 0: Chuẩn bị branch

Bước 1: Khám phá codebase

Bước 2: Clarify

Bước 3: Plan

Bước 4: Implement backend

Bước 5: Implement frontend

Bước 6: E2E hoặc test thay thế

Bước 7: Review diff

Bước 8: PR description và postmortem

Bước 9: Rollback khi Claude làm sai

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

6. Trade-offs

7. Best practices

8. Performance / cost / context

9. Checklist cuối bài

10. Bài tập

Tài liệu

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

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

Bảng so sánh

Lỗi thường gặp

Cách debug

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

Bài tập

Bài 1 — Cơ bản

Bài 2 — Thực tế

Bài 3 — Nâng cao

Bài 4 — Review & Reflection

Tiêu chí hoàn thành

Gợi ý nếu bí

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

Acceptance criteria cho `task comments`