Day 06 - Prompt engineering cho coding task

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

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

• Viết prompt coding task theo cấu trúc Context -> Goal -> Constraints -> Acceptance Criteria -> Verification.
• Tách prompt cho 4 loại việc thường gặp: bug fix, refactor, feature, review.
• Ép Claude Code hỏi lại khi thiếu thông tin thay vì tự đoán architecture, API contract hoặc test strategy.
• Dùng plan mode để yêu cầu Claude Code đọc codebase, nêu bằng chứng, lập plan, rồi mới sửa code.
• Thiết kế prompt thực tế cho taskflow-ai: tạo API CRUD task, review API, và yêu cầu viết test trước khi implement.
• Kiểm soát security, maintainability, performance, cost và context khi giao task cho Claude Code.

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

Prompt mơ hồ là nguyên nhân phổ biến khiến AI tạo code "có vẻ đúng" nhưng không dùng được trong repo thật. Ví dụ prompt:

Add CRUD API for tasks.

Prompt này thiếu gần như mọi thông tin quan trọng: module nào, framework nào, API contract ra sao, validation ở đâu, test command nào, file nào được sửa, có migration không, có auth không, có rollback không. Claude Code có thể tự tạo architecture mới, đổi convention hiện có, thêm dependency không cần thiết, hoặc sửa nhiều file ngoài scope.

Trong taskflow-ai, một task CRUD API nhỏ vẫn có nhiều quyết định kỹ thuật:

• Endpoint dùng Fastify route hay NestJS controller?
• DTO/validation dùng schema nào?
• Task có assigneeId, status, dueDate, createdBy chưa?
• Database đã có migration chưa hay chỉ đang dùng in-memory repository?
• Test là unit, integration hay e2e?
• Response error format hiện tại là gì?
• Có yêu cầu authorization không?

Claude Code giải quyết tốt việc đọc codebase, lập plan, chỉnh file và chạy test khi prompt đủ rõ. Nhưng Claude Code không nên bị giao quyền quyết định mọi thứ khi yêu cầu chưa đủ. Với task có blast radius lớn, prompt tốt phải làm Claude dừng lại và hỏi lại.

Không nên dùng Claude Code để implement ngay khi:

• Bạn chưa biết acceptance criteria.
• Bạn chưa biết file/module nào liên quan.
• Repo đang có thay đổi chưa review.
• Task liên quan tới auth, permission, billing, secret, migration, production data hoặc data deletion.
• Bạn chưa có command verify tối thiểu.

3. Kiến thức nền

Một prompt coding task tốt không phải là câu lệnh dài. Nó là một contract ngắn giữa developer và agent.

Format nên dùng:

Context:
- Repo, module, stack, trạng thái hiện tại, file liên quan nếu biết.

Goal:
- Kết quả business/technical cần đạt, không chỉ "sửa code".

Constraints:
- Giới hạn file, command, dependency, architecture, security, permission.

Acceptance Criteria:
- Điều kiện để coi task hoàn thành. Viết như checklist có thể review.

Verification:
- Command kiểm tra, thư mục chạy, output kỳ vọng, và khi nào phải dừng.

Trong Claude Code, format này hiệu quả vì nó khớp với agentic loop:

Observe -> Plan -> Act -> Verify

Context giúp Claude biết cần quan sát gì. Goal giúp Claude chọn hướng. Constraints chặn thay đổi ngoài phạm vi. Acceptance Criteria giúp review diff khách quan. Verification ép Claude hoặc developer kiểm tra kết quả bằng command cụ thể.

Điểm khác giữa prompt cho coding task và prompt hỏi đáp thông thường:

Nguyên tắc quan trọng: yêu cầu Claude đọc file liên quan trước khi đề xuất edit. Tài liệu Claude Code hiện hành khuyến nghị dùng plan mode để đọc và hiểu codebase trước khi sửa; có thể vào bằng Shift+Tab, prefix prompt với /plan, hoặc mở CLI bằng claude --permission-mode plan. Với task lặp lại, có thể đóng gói prompt thành custom slash command trong .claude/commands/. Với context dài hạn, project memory nên nằm trong CLAUDE.md hoặc .claude/CLAUDE.md; lệnh /init có thể hỗ trợ sinh CLAUDE.md chứa commands, architecture và conventions. Permission mode vẫn phải được kiểm soát khi cho Claude chạy command hoặc edit file.

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

Mục tiêu thực hành: viết prompt để Claude Code lập plan và implement API CRUD cho tasks trong taskflow-ai, nhưng không để Claude tự ý đổi architecture hoặc chạy command nguy hiểm.

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 hiển thị working tree ở dạng ngắn. Output kỳ vọng là rỗng hoặc chỉ có file bạn hiểu rõ. Rủi ro: nếu working tree đang có thay đổi của bạn hoặc đồng đội, patch do Claude tạo ra có thể bị trộn lẫn và khó rollback.

Nếu muốn biết branch hiện tại:

git branch --show-current

Lệnh này in tên branch đang active. Output kỳ vọng là branch feature như feature/tasks-crud-api, không phải main. Rủi ro: làm trực tiếp trên branch chính khiến review và rollback khó hơn.

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

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

claude --permission-mode plan

Lệnh này mở Claude Code ở chế độ ưu tiên đọc và lập plan trước khi sửa. Output kỳ vọng là Claude Code sẵn sàng nhận prompt. Rủi ro thấp hơn implement trực tiếp, nhưng plan vẫn có thể sai nếu prompt không yêu cầu Claude nêu bằng chứng từ file đã đọc.

Gửi prompt khám phá:

Context:
- Repo hiện tại là taskflow-ai.
- Mục tiêu dài hạn là backend API quản lý tasks cho team kỹ thuật.
- Tôi chưa chắc module tasks hiện đã có route/service/repository hay chưa.

Goal:
- Khảo sát codebase để xác định cách project hiện tại tổ chức backend API.
- Lập plan cho CRUD tasks nhưng chưa sửa file.

Constraints:
- Chỉ đọc file cần thiết.
- Không edit file.
- Không chạy npm install, migration, git command destructive, hoặc command ghi dữ liệu.
- Không tự giả định framework nếu chưa đọc config/package.

Acceptance Criteria:
- Liệt kê file đã đọc và bằng chứng chính từ từng file.
- Xác định framework backend đang dùng.
- Xác định nơi nên đặt route/controller, service, repository, validation, test.
- Nêu rõ thông tin còn thiếu cần hỏi lại.

Verification:
- Không có file thay đổi sau bước này.
- Nếu thiếu thông tin, hỏi tôi trước thay vì tự thiết kế.

Kết quả kỳ vọng: Claude nêu file đã đọc, architecture hiện tại, plan ngắn, và câu hỏi còn thiếu. Nếu Claude đưa plan nhưng không nêu file đã đọc, phản hồi:

Plan chưa đủ bằng chứng. Hãy đọc file liên quan và cập nhật lại plan.
Không implement.
Mỗi nhận định architecture phải gắn với file đã đọc.

Bước 3: Viết prompt feature CRUD có giới hạn rõ

Sau khi Claude đã khảo sát và bạn đồng ý hướng đi, chuyển sang session implement có permission kiểm soát:

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

Chạy ở thư mục gốc 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 một số command verify hẹp. Output kỳ vọng là session Claude Code mới hoặc tiếp tục sẵn sàng. Rủi ro: --allowedTools chỉ bỏ bước hỏi quyền cho pattern đã nêu, không deny mọi command khác; command ngoài pattern sẽ hỏi theo default mode. Pattern Bash(npm run test *) vẫn có thể chạy script test tốn thời gian hoặc chạm database test; đọc package.json trước nếu repo chưa tin cậy.

Prompt implement feature:

Context:
- Bạn đã khảo sát backend taskflow-ai và có plan được duyệt.
- Hãy dùng convention hiện có của project, không tạo architecture mới.
- API cần phục vụ task management nội bộ cho team kỹ thuật.

Goal:
- Implement API CRUD tasks tối thiểu: create, list, get by id, update, delete.

Constraints:
- Chỉ sửa các file trong backend module tasks hoặc file đăng ký route/module bắt buộc.
- Không thêm dependency mới.
- Không đổi format lỗi chung của project.
- Không tạo migration nếu schema/database chưa được plan rõ; nếu cần migration, dừng và hỏi.
- Không xử lý auth nếu project chưa có pattern auth; ghi rõ TODO bảo mật thay vì tự chế.
- Không chạy git add, git commit, git reset, git clean, rm, hoặc docker compose down -v.

Acceptance Criteria:
- Create validate title sau khi trim không được rỗng.
- List hỗ trợ pagination cơ bản nếu project đã có pattern; nếu chưa có, trả danh sách theo pattern hiện tại.
- Get/update/delete trả 404 theo error format hiện có khi task không tồn tại.
- Update không cho title toàn khoảng trắng.
- Delete idempotency phải theo convention hiện có; nếu chưa rõ, hỏi lại.
- Không đổi public contract ngoài endpoints tasks mới.

Verification:
- Trước khi sửa, nhắc lại file dự kiến chạm vào.
- Sau khi sửa, chạy hoặc đề xuất command test phù hợp.
- Tóm tắt diff theo file.
- Nếu test fail, dừng lại và phân tích nguyên nhân trước khi sửa tiếp.

Kỳ vọng: Claude chỉ sửa file liên quan, không cài package, không tự tạo migration nguy hiểm, không commit. Nếu Claude đề xuất thêm dependency, yêu cầu giải thích vì sao dependency hiện tại không đủ.

Bước 4: Viết prompt yêu cầu test trước khi implement

Với task có rủi ro behavior, bắt Claude viết hoặc cập nhật test trước. Prompt:

Context:
- Repo taskflow-ai đang chuẩn bị thêm CRUD tasks.
- Tôi muốn dùng test-first workflow để khóa API contract trước khi implement.

Goal:
- Viết test mô tả behavior mong muốn cho tasks CRUD trước.

Constraints:
- Đọc test pattern hiện có trước.
- Chỉ sửa file test hoặc tạo file test theo convention hiện có.
- Không sửa production code trong lượt này.
- Không snapshot large response nếu assertion cụ thể đủ dùng.
- Không mock quá sâu khiến test không phát hiện lỗi integration quan trọng.

Acceptance Criteria:
- Có test create task thành công.
- Có test reject title rỗng hoặc chỉ có khoảng trắng.
- Có test get/update/delete task không tồn tại trả 404 theo convention hiện có.
- Test name mô tả behavior, không mô tả implementation.

Verification:
- Chạy test command hẹp cho file test nếu có thể.
- Output kỳ vọng ban đầu có thể fail vì production code chưa implement.
- Nếu test fail do setup, phân biệt rõ setup lỗi hay behavior chưa implement.

Sau khi test được tạo, chạy trong package backend, ví dụ taskflow-ai/backend nếu package.json nằm ở đó:

npm run test -- --run

Lệnh này chạy test một lần với Vitest nếu project dùng Vitest. Output kỳ vọng ở bước test-first có thể là fail đúng behavior chưa implement. Rủi ro: nếu script test dùng database thật hoặc service ngoài, cần kiểm tra .env.test và Docker Compose trước.

Nếu project dùng Jest:

npm test -- --runInBand

Lệnh này chạy Jest tuần tự, hữu ích cho integration test dùng database test. Output kỳ vọng là danh sách test fail/pass rõ ràng. Rủi ro: chạy lâu hơn, và nếu config sai có thể dùng nhầm database dev.

Bước 5: Review diff và rollback

Sau khi Claude edit, tự chạy trong root taskflow-ai:

git diff --stat

Lệnh này cho biết số file và số dòng thay đổi. Output kỳ vọng khớp với plan, ví dụ file route/service/test của tasks. Rủi ro: diff stat không cho thấy logic sai, chỉ giúp phát hiện patch quá rộng.

Xem diff chi tiết:

git diff

Output kỳ vọng:

• Không có file ngoài module tasks nếu prompt đã giới hạn.
• Không có secret, credential, .env hoặc config production.
• Không có dependency mới nếu constraints cấm.
• Test hoặc command verify được cập nhật hợp lý.

Nếu Claude sửa sai một file và bạn chắc chắn muốn bỏ:

git restore -- backend/src/tasks/task.service.ts

Chạy ở root taskflow-ai, thay path bằng file thật. Lệnh này rollback 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ả thay đổi bạn tự viết. Không chạy nếu chưa đọc diff.

Nếu patch quá rộng, phản hồi Claude:

Patch quá rộng so với constraints.
Không sửa thêm.
Hãy phân loại các thay đổi hiện tại thành: cần giữ, cần bỏ, cần hỏi lại.
Đề xuất rollback từng file bằng command cụ thể, nhưng không tự chạy command destructive.

Bước 6: Đóng gói prompt lặp lại bằng custom slash command

Khi team đã thống nhất format prompt, có thể tạo custom slash command trong project thật ở .claude/commands/. Ví dụ file .claude/commands/api-plan.md có thể chứa prompt lập plan API.

Command tạo thư mục trên macOS/Linux/Git Bash, chạy ở root taskflow-ai:

mkdir -p .claude/commands

Lệnh này tạo thư mục chứa slash command nếu chưa có. Output kỳ vọng thường không có gì. Rủi ro thấp, nhưng vẫn là thay đổi filesystem; chỉ tạo trong repo bạn muốn version control hoặc đã thống nhất với team.

Nội dung slash command tham khảo. Frontmatter giúp mô tả command và giới hạn tool ngay trong file command:

---
description: Lập plan API có bằng chứng trước khi sửa code
allowed-tools: Read, Bash(git status *), Bash(git diff *)
---

Context:
- Repo này là taskflow-ai.
- Đọc CLAUDE.md trước nếu có.
- Luôn đọc file liên quan trước khi đề xuất edit.

Goal:
- Lập plan cho một API task do user mô tả.

Constraints:
- Chưa sửa file.
- Nêu file đã đọc và bằng chứng.
- Hỏi lại nếu thiếu API contract, validation, auth, database, hoặc test command.

Acceptance Criteria:
- Plan tối đa 6 bước.
- Mỗi bước có file dự kiến chạm vào.
- Chỉ rõ rủi ro security, maintainability, performance.

Verification:
- Đề xuất test command và thư mục chạy.

Sau này trong Claude Code, team có thể gọi slash command này thay vì copy prompt dài. Vẫn cần review nội dung command vì nó trở thành project convention cho AI.

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

Prompt khám phá codebase

Context:
- Repo taskflow-ai.
- Tôi cần hiểu backend API convention trước khi giao task CRUD.

Goal:
- Map luồng request cho module tasks hoặc module API tương tự nhất.

Constraints:
- Chỉ đọc file.
- Không sửa file.
- Không tự giả định nếu project chưa có module tasks.

Acceptance Criteria:
- Liệt kê file đã đọc.
- Chỉ ra entrypoint, route/controller, service, repository/database layer, validation, error handling, test pattern.
- Nêu 3 rủi ro nếu implement CRUD khi chưa có thêm thông tin.

Verification:
- Không có diff sau prompt này.
- Nếu thiếu thông tin, hỏi lại bằng câu hỏi cụ thể.

Prompt lập plan

Context:
- Dựa trên file bạn đã đọc trong taskflow-ai.
- Tính năng cần thêm là tasks CRUD API.

Goal:
- Lập plan implement nhỏ, dễ review.

Constraints:
- Chưa implement.
- Không thêm dependency.
- Không tạo migration nếu chưa xác nhận schema.
- Plan phải tách test và production code.

Acceptance Criteria:
- Plan tối đa 6 bước.
- Mỗi bước ghi file dự kiến chạm vào và lý do.
- Nêu rollback strategy nếu patch sai.
- Nêu command verify và thư mục chạy.

Verification:
- Tôi sẽ approve hoặc yêu cầu chỉnh plan trước khi bạn sửa.

Prompt implement feature

Context:
- Plan tasks CRUD đã được duyệt.
- Backend dùng convention hiện có của taskflow-ai.

Goal:
- Implement phần production code nhỏ nhất để test tasks CRUD pass.

Constraints:
- Chỉ sửa file đã nêu trong plan.
- Không thêm dependency.
- Không đổi error format chung.
- Không tự commit.
- Nếu cần sửa file ngoài plan, dừng và hỏi.

Acceptance Criteria:
- CRUD behavior đúng test đã viết.
- Validation title trim rỗng bị reject.
- 404 nhất quán với convention hiện có.
- Không có logic duplicate lớn.

Verification:
- Chạy test command hẹp nếu được phép.
- Báo test pass/fail và diff summary.

Prompt bug fix

Context:
- Bug: update task với title toàn khoảng trắng vẫn được lưu.
- Repo: taskflow-ai.
- Tôi chưa chắc validation nằm ở route schema hay service.

Goal:
- Sửa bug bằng thay đổi nhỏ nhất.

Constraints:
- Đọc file liên quan trước.
- Không đổi API response thành công.
- Không đổi database schema.
- Không refactor module tasks trong lượt này.

Acceptance Criteria:
- `"   "` bị reject giống title rỗng.
- Title hợp lệ vẫn được trim hoặc xử lý theo convention hiện có.
- Test regression được thêm hoặc cập nhật.

Verification:
- Chạy test liên quan tới tasks.
- Nếu không tìm được test command, đọc package.json và đề xuất command.
- Nếu thiếu convention trim, hỏi lại trước khi sửa.

Prompt refactor

Context:
- Module tasks trong taskflow-ai đã có CRUD nhưng service đang chứa validation, mapping response và database call trong cùng một hàm dài.

Goal:
- Refactor để code dễ maintain hơn nhưng giữ nguyên behavior public API.

Constraints:
- Không đổi endpoint, status code, response shape, database schema.
- Phải có characterization test hoặc test hiện có pass trước khi refactor.
- Refactor theo từng bước nhỏ, không viết lại toàn module.
- Không tạo abstraction nếu chỉ dùng một lần.

Acceptance Criteria:
- Diff thể hiện tách trách nhiệm rõ hơn.
- Test trước và sau refactor pass.
- Không tăng số query database cho hot path list tasks.

Verification:
- Chạy test tasks trước khi sửa nếu có thể.
- Sau mỗi bước refactor, báo diff summary.
- Nếu test coverage không đủ, dừng để đề xuất test trước.

Prompt review

Context:
- Tôi đã có diff cho tasks CRUD API trong taskflow-ai.

Goal:
- Review như senior backend reviewer, không sửa file.

Constraints:
- Chỉ đọc diff và file cần thiết để hiểu context.
- Không edit.
- Không chạy command destructive.
- Ưu tiên finding có impact thực tế, không nitpick style nếu formatter xử lý được.

Acceptance Criteria:
- Phân loại finding theo: correctness, security, maintainability, performance, test gap.
- Mỗi finding có file/path, behavior rủi ro, và đề xuất fix.
- Nêu rõ phần nào đủ tốt không cần đổi.

Verification:
- Kết luận diff có thể merge, cần sửa trước khi merge, hay cần redesign.

Prompt viết test

Context:
- Tôi muốn thêm tasks CRUD API theo test-first workflow.

Goal:
- Viết test mô tả API contract trước khi implement.

Constraints:
- Đọc test convention hiện có.
- Chỉ sửa file test.
- Không sửa production code.
- Không tạo mock sâu nếu integration test hiện có phù hợp hơn.

Acceptance Criteria:
- Test cover create/list/get/update/delete.
- Test cover validation title rỗng sau trim.
- Test cover 404 cho id không tồn tại.
- Test data độc lập, không phụ thuộc thứ tự chạy.

Verification:
- Chạy test file mới.
- Nếu fail vì production chưa có endpoint, ghi rõ đó là expected fail của test-first.

6. Trade-offs

Prompt có cấu trúc dài hơn prompt tự nhiên, nhưng giảm chi phí sửa sai. Với task một dòng như rename biến local, format đầy đủ có thể quá nặng. Với API, refactor, review hoặc bug production-like, format này đáng dùng.

plan mode làm workflow chậm hơn ở bước đầu, nhưng giúp Claude đọc codebase trước khi sửa. Điều này đặc biệt quan trọng trong repo có convention riêng, module nhiều tầng hoặc test setup phức tạp.

Test-first prompt có thể làm Claude mất thêm thời gian, nhưng khóa API contract sớm. Trade-off là bạn phải chấp nhận test fail ban đầu và phân biệt fail do behavior chưa implement với fail do setup sai.

Custom slash command giúp team tái sử dụng prompt chuẩn. Rủi ro là prompt lỗi sẽ được lặp lại nhiều lần. Slash command nên được review như code: version control, pull request, và cập nhật khi architecture đổi.

Ràng buộc quá chặt có thể làm Claude không hoàn thành task. Ràng buộc quá lỏng làm Claude tự quyết định ngoài phạm vi. Điểm cân bằng tốt là giới hạn file/command/dependency rõ, nhưng cho phép Claude hỏi lại khi cần mở rộng scope.

7. Best practices

• Luôn yêu cầu Claude đọc file liên quan và nêu bằng chứng trước khi đề xuất edit.
• Mọi task từ mức trung bình trở lên nên bắt đầu bằng prompt Context -> Goal -> Constraints -> Acceptance Criteria -> Verification.
• Với yêu cầu thiếu dữ kiện, thêm câu: "Nếu thiếu thông tin, hỏi lại trước; không tự giả định."
• Không giao chung một prompt cho feature, refactor, test, docs và performance tuning cùng lúc.
• Với bug fix, yêu cầu reproduction hoặc failing test trước khi sửa.
• Với refactor, yêu cầu behavior lock bằng test trước và không đổi public contract.
• Với review, yêu cầu finding có impact và file/path cụ thể, tránh nhận xét chung chung.
• Không đưa secret, .env, token, production credential, customer data hoặc log nhạy cảm vào prompt.
• Không cho Claude tự chạy command destructive: rm -rf, git reset --hard, git clean -fd, docker compose down -v, migration drop/truncate, force push.
• Ghi rules quan trọng vào CLAUDE.md hoặc .claude/CLAUDE.md để session mới có project memory ổn định. Có thể dùng /init để khởi tạo rồi chỉnh lại thủ công.
• Những prompt lặp lại như API plan, API review, test-first có thể đưa vào .claude/commands/ thành custom slash command sau khi team review.

8. Performance / cost / context

Prompt engineering tốt không chỉ để code đúng hơn, mà còn giảm token và context waste.

Các nguyên nhân tốn context:

• Bắt Claude đọc toàn repo khi chỉ cần module tasks.
• Gộp feature, refactor và review vào một session dài.
• Không nêu acceptance criteria, khiến Claude sửa đi sửa lại.
• Để Claude chạy test suite toàn repo khi chỉ cần test file/module.
• Không dùng CLAUDE.md, khiến session nào cũng phải giải thích lại architecture, commands và conventions.

Cách tối ưu:

• Bắt đầu bằng prompt khám phá hẹp: module, file nghi ngờ, command cần đọc.
• Yêu cầu Claude tóm tắt file đã đọc và quyết định kỹ thuật quan trọng, không paste toàn bộ code.
• Sau plan, chuyển sang implement prompt hẹp với danh sách file được sửa.
• Chạy test hẹp trước, test rộng sau. Ví dụ test module tasks trước rồi mới full backend suite.
• Dùng custom slash command cho prompt lặp lại để giảm thời gian nhập và giảm sai lệch giữa các developer.
• Khi context dài, yêu cầu Claude tạo summary tập trung vào decisions, files touched, commands run, remaining risks. Không giữ log dài không cần thiết.

Ví dụ verify theo tầng:

npm run test -- --run backend/src/tasks

Chạy trong package backend nếu script hỗ trợ path filter. Output kỳ vọng là test tasks pass. Rủi ro: path filter có thể khác giữa Vitest/Jest; nếu command fail vì syntax, đọc package.json và test config trước khi kết luận code sai.

npm run typecheck

Chạy trong package có TypeScript config. Output kỳ vọng là exit code 0, không có type error. Rủi ro: typecheck toàn project có thể lộ lỗi cũ không liên quan; cần phân biệt regression mới với nợ kỹ thuật có sẵn.

9. Checklist cuối bài

• Tôi viết được prompt theo format Context -> Goal -> Constraints -> Acceptance Criteria -> Verification.
• Tôi biết khi nào dùng prompt bug fix, refactor, feature, review, test-first.
• Tôi biết ép Claude hỏi lại khi thiếu API contract, auth rule, database schema hoặc test command.
• Tôi đã dùng plan mode để yêu cầu Claude đọc code trước khi sửa.
• Tôi biết giới hạn file, command, dependency và permission mode trong prompt.
• Tôi biết review git diff --stat và git diff sau khi Claude edit.
• Tôi có rollback strategy bằng git restore -- path/to/file và hiểu rủi ro mất thay đổi local.
• Tôi biết khi nào nên đưa prompt lặp lại vào .claude/commands/.
• Tôi biết rule nào nên đưa vào CLAUDE.md để giảm context lặp lại.
• Tôi đã cân nhắc security, maintainability, performance, cost và context trước khi cho Claude implement.

10. Bài tập

Bài cơ bản: viết prompt khám phá backend taskflow-ai theo format 5 phần. Prompt phải yêu cầu Claude chỉ đọc file, liệt kê bằng chứng, và hỏi lại nếu chưa rõ module tasks.

Bài nâng cao: viết prompt test-first cho tasks CRUD API. Prompt phải cấm sửa production code, yêu cầu đọc test convention, tạo test cho create/list/get/update/delete, validation title, và 404.

Bài áp dụng project cá nhân: chọn một bug thật trong repo cá nhân. Viết 2 prompt: prompt bug diagnosis trong plan mode, và prompt bug fix sau khi plan được duyệt. Mỗi prompt phải có rollback, command verify và điều kiện dừng khi thiếu thông tin.

Tài liệu

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

Prompt engineering cho coding task là cách biến yêu cầu mơ hồ thành một contract có thể thực thi và review. Với Claude Code, prompt tốt cần chỉ rõ Claude phải đọc gì, sửa gì, không được làm gì, và kiểm chứng bằng command nào.

Format chuẩn:

Context -> Goal -> Constraints -> Acceptance Criteria -> Verification

Ý nghĩa từng phần:

• Context: repo, module, stack, trạng thái hiện tại, file liên quan nếu biết, convention cần giữ.
• Goal: kết quả cần đạt ở mức behavior hoặc technical outcome.
• Constraints: giới hạn file, command, dependency, architecture, permission, security.
• Acceptance Criteria: điều kiện cụ thể để coi task xong, có thể review bằng diff/test.
• Verification: command kiểm tra, thư mục chạy, output kỳ vọng, rủi ro khi chạy.

Nguyên tắc vận hành:

• Dùng plan mode cho bước đọc codebase và lập plan trước khi edit.
• Có thể vào plan mode bằng Shift+Tab, prefix prompt với /plan, hoặc chạy claude --permission-mode plan.
• Yêu cầu Claude nêu file đã đọc và bằng chứng trước khi đề xuất fix.
• Với thiếu dữ kiện, prompt phải ghi rõ: hỏi lại trước, không tự giả định.
• Dùng CLAUDE.md hoặc .claude/CLAUDE.md cho project memory: commands, architecture, conventions, security rules.
• Dùng /init để khởi tạo memory rồi chỉnh lại thủ công theo team.
• Dùng custom slash commands trong .claude/commands/ cho prompt lặp lại như API plan, API review, test-first.
• Permission/default mode cần được kiểm soát khi cho Claude chạy command hoặc edit file.

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

Luồng prompt cho coding task:

Nhận yêu cầu
  |
  v
Viết Context
  |
  v
Xác định Goal
  |
  v
Đặt Constraints
  |
  v
Viết Acceptance Criteria
  |
  v
Gắn Verification
  |
  v
Chạy Claude ở plan mode
  |
  v
Claude đọc file + nêu bằng chứng
  |
  +-- Thiếu thông tin -> Claude hỏi lại
  |
  +-- Đủ thông tin -> Developer duyệt plan
  |
  v
Implement bằng default mode/tool hẹp
  |
  v
Review git diff + chạy test
  |
  v
Accept / sửa tiếp / rollback

Luồng áp dụng cho taskflow-ai:

Prompt khám phá backend
  -> xác định framework + module/API pattern
  -> prompt test-first CRUD tasks
  -> tạo test theo convention
  -> prompt implement production code nhỏ nhất
  -> npm run test -- --run
  -> git diff --stat
  -> prompt review API
  -> fix nhỏ nếu cần

Luồng ép Claude hỏi lại:

Prompt có "Nếu thiếu thông tin, hỏi lại trước"
  |
  v
Claude gặp thiếu API contract/auth/schema/test command
  |
  +-- Hỏi lại cụ thể -> developer trả lời -> tiếp tục
  |
  +-- Tự giả định -> developer dừng -> yêu cầu plan lại với bằng chứng

Bảng so sánh

Lỗi thường gặp

1. Prompt thiếu acceptance criteria
   Claude có thể tạo endpoint nhưng thiếu validation, thiếu 404, hoặc response shape lệch convention.

2. Prompt feature nhưng thực chất là feature + refactor + migration + test + docs
   Task quá rộng làm context dài, diff khó review, rollback khó.

3. Không yêu cầu Claude đọc code trước
   Claude dễ tạo pattern mới thay vì dùng convention hiện có của taskflow-ai.

4. Không ép Claude hỏi lại
   Khi thiếu auth rule, database schema hoặc test command, Claude có thể tự quyết định sai.

5. Verification mơ hồ
   "Chạy test" không đủ. Cần biết chạy ở đâu, command nào, output kỳ vọng, rủi ro môi trường.

6. Dùng prompt review nhưng cho phép edit
   Review nên là read-only trước. Nếu vừa review vừa sửa, finding dễ bị che bởi patch mới.

7. Quên rollback strategy
   Khi patch rộng hoặc sai, developer mất thời gian gỡ từng thay đổi.

8. Đưa secret hoặc log nhạy cảm vào prompt
   Prompt có thể trở thành rủi ro bảo mật. Nên sanitize .env, token, customer data, production log.

Cách debug

Khi Claude tự giả định thay vì hỏi lại:

Bạn vừa giả định thông tin chưa được xác nhận.
Dừng implement.
Liệt kê các giả định bạn đã dùng, file nào chứng minh hoặc không chứng minh được từng giả định.
Sau đó hỏi tôi tối đa 5 câu cần thiết để tiếp tục.

Khi patch quá rộng:

git diff --stat

Chạy ở root taskflow-ai. Nếu số file vượt plan, dừng edit. Tiếp theo:

Patch hiện tại vượt scope.
Không sửa thêm.
Hãy phân loại từng file trong diff: cần giữ, cần bỏ, cần hỏi lại.
Đề xuất rollback từng file bằng git restore, nhưng không tự chạy.

Khi test fail:

Test đang fail. Chưa sửa code.
Hãy phân tích failure output theo 3 nhóm:
1. Test setup/environment.
2. Behavior chưa implement.
3. Regression do patch mới.
Với mỗi nhóm, nêu bằng chứng từ log và file liên quan.

Khi Claude đề xuất command nguy hiểm:

Không chạy command đó.
Giải thích command làm gì, dữ liệu nào có thể mất, và đề xuất command read-only thay thế để kiểm tra trạng thái.

Ví dụ thay docker compose down -v bằng command đọc trạng thái:

docker compose ps

Chạy ở root repo có docker-compose.yml. Lệnh này xem container đang chạy. Output kỳ vọng là danh sách service. Rủi ro thấp hơn vì không xóa volume, nhưng vẫn cần đảm bảo Docker context đang trỏ đúng môi trường local.

Khi cần rollback một file:

git restore -- backend/src/tasks/task.service.ts

Chạy ở root taskflow-ai. Output kỳ vọng thường trống. Rủi ro: mất mọi thay đổi chưa commit trong file đó. Nếu trong file có cả thay đổi của bạn, dùng git diff -- backend/src/tasks/task.service.ts trước và cân nhắc rollback thủ công.

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

• Claude Code overview: https://code.claude.com/docs/en/overview
• Claude Code common workflows: https://code.claude.com/docs/en/common-workflows
• Claude Code best practices: https://code.claude.com/docs/en/best-practices
• Claude Code memory: https://code.claude.com/docs/en/memory
• Claude Code slash commands: https://code.claude.com/docs/en/slash-commands
• Claude Code permissions: https://code.claude.com/docs/en/permissions
• Claude Code settings: https://code.claude.com/docs/en/settings
• Git diff documentation: https://git-scm.com/docs/git-diff
• Git restore documentation: https://git-scm.com/docs/git-restore
• Vitest CLI: https://vitest.dev/guide/cli
• Jest CLI options: https://jestjs.io/docs/cli

Bài tập

Bài 1 — Cơ bản

Mục tiêu: viết prompt khám phá codebase theo format 5 phần, chưa cho Claude sửa file.

Yêu cầu:

1. Mở terminal tại thư mục gốc taskflow-ai.
2. Kiểm tra working tree:

git status --short

Lệnh này chạy ở root taskflow-ai. Output kỳ vọng là rỗng hoặc chỉ có file bạn hiểu rõ. Rủi ro: nếu bỏ qua file lạ, bạn có thể nhầm patch của Claude với thay đổi sẵn có.

3. Mở Claude Code ở plan mode:

claude --permission-mode plan

Lệnh này chạy ở root taskflow-ai. Output kỳ vọng là Claude Code sẵn sàng nhận prompt và chưa sửa file. Rủi ro: plan vẫn có thể thiếu nếu prompt không yêu cầu đọc file cụ thể và nêu bằng chứng.

4. Viết prompt theo format:

Context:
- Repo là taskflow-ai.
- Tôi cần hiểu backend API convention trước khi thêm tasks CRUD.
- Tôi chưa chắc project dùng Fastify hay NestJS.

Goal:
- Khảo sát backend và xác định nơi phù hợp để thêm tasks CRUD API.

Constraints:
- Chỉ đọc file.
- Không sửa file.
- Không chạy command ghi dữ liệu.
- Không tự giả định framework hoặc database layer nếu chưa đọc config.

Acceptance Criteria:
- Liệt kê file đã đọc.
- Xác định framework backend, route/controller pattern, service/repository pattern, validation pattern, test pattern.
- Nêu thông tin còn thiếu để implement an toàn.

Verification:
- Không có file thay đổi sau bước này.
- Nếu thiếu thông tin, hỏi lại trước khi lập plan implement.

Kết quả cần có:

• Claude liệt kê file đã đọc.
• Claude nêu evidence từ codebase, không chỉ suy đoán.
• Claude hỏi lại nếu thiếu schema, auth, test command hoặc module tasks chưa tồn tại.

Bài 2 — Thực tế

Mục tiêu: viết prompt tạo API CRUD task cho taskflow-ai có constraints, acceptance criteria, verification rõ.

Yêu cầu:

1. Dựa trên output Bài 1, viết prompt feature CRUD. Prompt phải có đủ 5 phần.
2. Prompt phải bao gồm tối thiểu các acceptance criteria sau:

• Create task reject title rỗng sau khi trim.
• List tasks trả dữ liệu theo convention hiện có.
• Get/update/delete task không tồn tại trả 404 theo error format hiện có.
• Update không cho title toàn khoảng trắng.
• Không thêm dependency mới.
• Không tự tạo migration nếu chưa được approve.

3. Mở Claude Code bằng default mode với tool hẹp:

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

Lệnh này chạy ở root taskflow-ai. Output kỳ vọng là session Claude Code sẵn sàng. --tools giới hạn nhóm tool khả dụng; --allowedTools chỉ auto-approve các Bash pattern đã nêu, không deny mọi command khác. Rủi ro: npm run test có thể chạy lâu hoặc phụ thuộc database test; nếu chưa rõ script, yêu cầu Claude đọc package.json trước.

4. Gửi prompt feature. Ví dụ:

Context:
- Dựa trên plan đã duyệt từ Bài 1.
- Repo taskflow-ai dùng convention backend hiện có; không tạo architecture mới.

Goal:
- Implement tasks CRUD API tối thiểu cho backend.

Constraints:
- Chỉ sửa file trong module tasks hoặc file đăng ký route/module bắt buộc.
- Không thêm dependency.
- Không tạo migration nếu chưa có quyết định schema rõ; nếu cần, dừng và hỏi.
- Không tự thêm auth nếu project chưa có pattern auth.
- Không chạy git add, git commit, git reset, git clean, rm, hoặc docker compose down -v.

Acceptance Criteria:
- Create validate title sau khi trim không được rỗng.
- List/get/update/delete hoạt động theo API convention hiện có.
- Not found trả 404 theo error format hiện có.
- Update reject title toàn khoảng trắng.
- Không đổi behavior module khác.

Verification:
- Trước khi sửa, nhắc lại file dự kiến chạm vào.
- Sau khi sửa, chạy hoặc đề xuất test command hẹp.
- Báo diff summary theo file.
- Nếu thiếu thông tin, hỏi lại trước thay vì tự giả định.

5. Sau khi Claude sửa, tự kiểm tra:

git diff --stat

Output kỳ vọng là số file thay đổi khớp plan. Rủi ro: nếu thấy file ngoài scope, dừng và không approve thêm edit.

6. Xem chi tiết:

git diff

Output kỳ vọng là API CRUD đúng criteria, không có secret, không có dependency mới, không đổi config production.

Bài 3 — Nâng cao

Mục tiêu: viết prompt yêu cầu test trước khi implement và dùng test fail/pass để kiểm soát behavior.

Yêu cầu:

1. Reset hoặc dùng branch sạch nếu bạn đã làm Bài 2 trên cùng repo. Không dùng lệnh destructive nếu chưa hiểu diff.
2. Viết prompt test-first:

Context:
- Tôi muốn thêm tasks CRUD API trong taskflow-ai.
- Trước khi implement production code, tôi muốn có test mô tả API contract.

Goal:
- Viết test cho tasks CRUD theo convention hiện có.

Constraints:
- Đọc test pattern hiện có trước.
- Chỉ sửa hoặc tạo file test.
- Không sửa production code.
- Không thêm dependency.
- Không dùng snapshot lớn nếu assertion cụ thể đủ rõ.
- Nếu chưa rõ test runner hoặc setup database test, hỏi lại.

Acceptance Criteria:
- Test create task thành công.
- Test reject title rỗng hoặc chỉ gồm khoảng trắng.
- Test list/get/update/delete theo contract dự kiến.
- Test get/update/delete id không tồn tại trả 404.
- Test data độc lập giữa test cases.

Verification:
- Chạy test file mới nếu command rõ.
- Expected result ban đầu có thể fail vì production code chưa implement.
- Nếu fail do setup, phân tích setup trước khi sửa production code.

3. Sau khi Claude tạo test, chạy command phù hợp ở package backend. Nếu dùng Vitest:

npm run test -- --run

Output kỳ vọng: test mới fail vì endpoint chưa implement, hoặc pass nếu production code đã có sẵn behavior. Rủi ro: nếu test đang dùng database thật, dừng và kiểm tra config.

Nếu dùng Jest:

npm test -- --runInBand

Output kỳ vọng: test chạy tuần tự và báo failure rõ. Rủi ro: command có thể chậm hơn, nhưng hữu ích khi integration test dùng database shared.

4. Viết prompt implement sau test:

Context:
- Test tasks CRUD đã được viết theo convention hiện có.
- Một số test đang fail vì production code chưa implement.

Goal:
- Implement production code nhỏ nhất để test tasks CRUD pass.

Constraints:
- Không sửa test trừ khi test sai rõ ràng và phải hỏi trước.
- Chỉ sửa file production trong plan.
- Không thêm dependency.
- Không đổi API contract đã khóa trong test.

Acceptance Criteria:
- Test tasks CRUD pass.
- Typecheck pass nếu command có sẵn.
- Không đổi behavior module khác.

Verification:
- Chạy lại test tasks.
- Báo test output summary, diff summary, và rủi ro còn lại.

5. Nếu cần rollback một file test hoặc production đã đọc kỹ:

git restore -- path/to/file

Chạy ở root taskflow-ai, thay path/to/file bằng file thật. Output kỳ vọng thường trống. Rủi ro: mất thay đổi chưa commit trong file đó.

Bài 4 — Review & Reflection

Mục tiêu: viết prompt review API và rút ra rule dùng lại cho team.

Yêu cầu:

1. Sau khi có diff tasks CRUD hoặc diff test-first, gửi prompt review read-only:

Context:
- Đây là diff tasks CRUD API trong taskflow-ai.
- Tôi muốn review trước khi commit.

Goal:
- Review như senior backend reviewer.

Constraints:
- Không sửa file.
- Chỉ đọc diff và file cần thiết.
- Không chạy command destructive.
- Không nitpick style nếu formatter xử lý được.

Acceptance Criteria:
- Finding phải phân loại theo correctness, security, maintainability, performance, test gap.
- Mỗi finding có file/path, mô tả rủi ro behavior, và đề xuất fix.
- Chỉ block merge với issue có impact thực tế.

Verification:
- Kết luận: có thể merge, cần fix nhỏ, hay cần redesign.
- Nêu test command nên chạy trước khi commit.

2. Dựa trên review, viết 5 rule đưa vào CLAUDE.md cho project taskflow-ai. Rule phải cụ thể, ví dụ:

• Luôn dùng format 5 phần cho task backend từ mức trung bình trở lên.
• Với API mới, test-first trước khi implement nếu API contract chưa ổn định.
• Không tự thêm dependency, migration hoặc auth pattern mới nếu chưa hỏi.
• Không chạy destructive command.
• Sau mọi edit, báo diff summary và command verify.

3. Viết một ý tưởng custom slash command trong .claude/commands/, ví dụ /api-review hoặc /api-plan. Chỉ cần nội dung prompt, không bắt buộc tạo file. Nếu viết thành file thật, dùng Markdown và có thể thêm frontmatter như description và allowed-tools để command dễ hiểu và ít quyền hơn.

4. Trả lời reflection:

• Prompt nào của bạn khiến Claude hỏi lại đúng lúc?
• Prompt nào còn quá rộng?
• Acceptance criteria nào giúp review diff dễ nhất?
• Verification command nào có rủi ro môi trường?
• Nếu dùng prompt này trong repo công ty, bạn sẽ thêm guardrail security nào?

Tiêu chí hoàn thành

• Có đủ 3 prompt: tạo API CRUD task, review API, test trước khi implement.
• Mỗi prompt dùng đủ Context -> Goal -> Constraints -> Acceptance Criteria -> Verification.
• Prompt có câu yêu cầu Claude hỏi lại khi thiếu thông tin.
• Đã dùng plan mode cho bước đọc codebase hoặc giải thích được vì sao chưa chạy.
• Đã kiểm tra git status --short trước khi edit.
• Đã review git diff --stat và git diff sau khi Claude sửa.
• Có command verify kèm thư mục chạy, output kỳ vọng và rủi ro.
• Có rollback strategy bằng git restore -- path/to/file.
• Có ít nhất 3 guardrail về security/permission/destructive command.
• Có nhận xét về performance/cost/context khi prompt quá rộng hoặc test quá lớn.

Gợi ý nếu bí

Nếu không biết project dùng framework nào:

Hãy đọc package.json và entrypoint backend để xác định framework.
Chỉ đọc file.
Không implement.
Nếu có nhiều package.json, liệt kê từng package và vai trò.

Nếu Claude không hỏi lại dù thiếu thông tin:

Dừng lại.
Liệt kê những giả định bạn vừa dùng.
Với mỗi giả định, nêu file nào chứng minh hoặc nói rõ chưa có bằng chứng.
Sau đó hỏi tôi tối đa 5 câu cần trả lời trước khi implement.

Nếu Claude muốn tạo migration:

Chưa tạo migration.
Hãy giải thích schema hiện tại, dữ liệu có thể bị ảnh hưởng, rollback plan, và test database nào sẽ dùng.
Chỉ sau khi tôi approve mới được đề xuất file migration.

Nếu diff quá rộng:

Patch vượt scope.
Không sửa thêm.
Hãy đề xuất cách tách thành 2-3 PR nhỏ hơn và file nào nên rollback.

Nếu test command không rõ:

Đọc package.json và test config liên quan.
Không sửa file.
Đề xuất command test hẹp nhất cho module tasks, kèm thư mục chạy và rủi ro môi trường.

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

Expected result cho Bài 1:

• Prompt có đủ 5 phần.
• Claude đọc package.json, entrypoint backend, module API tương tự hoặc module tasks nếu có.
• Claude nêu rõ file đã đọc và không sửa file.
• Claude hỏi lại nếu chưa rõ schema, auth hoặc test command.

Expected result cho Bài 2:

• Prompt feature không chỉ nói "CRUD" mà có endpoint behavior, validation, 404, dependency, migration, auth và verification.
• Diff sau implement chỉ chạm file đúng plan.
• Không có npm install, không có dependency mới, không có migration tự phát, không có commit tự động.
• Claude báo command test nên chạy và diff summary.

Expected result cho Bài 3:

• Test được viết trước production code hoặc ít nhất prompt thể hiện test-first rõ ràng.
• Test cover create/list/get/update/delete, validation title, 404.
• Failure ban đầu được phân loại đúng: expected fail do chưa implement, setup issue, hoặc regression.
• Production implement sau đó không sửa test tùy tiện để làm pass.

Expected result cho Bài 4:

• Prompt review là read-only và phân loại finding theo impact.
• Reflection chỉ ra prompt nào quá rộng và cách thu hẹp.
• Có rule cụ thể để đưa vào CLAUDE.md.
• Có ý tưởng slash command có thể dùng lại, ví dụ:

---
description: Review API diff hiện tại với tiêu chí senior backend
allowed-tools: Read, Bash(git diff *), Bash(git status *)
---

Context:
- Repo taskflow-ai. Đọc CLAUDE.md trước nếu có.

Goal:
- Review API diff hiện tại như senior backend reviewer.

Constraints:
- Không sửa file.
- Không chạy command destructive.
- Chỉ đọc diff và file cần thiết.

Acceptance Criteria:
- Finding phân loại correctness, security, maintainability, performance, test gap.
- Mỗi finding có file/path, impact, đề xuất fix.

Verification:
- Kết luận merge/fix/redesign và test command cần chạy.