Claude Code không phải chatbot viết code để bạn copy paste. Nó là một agent chạy trong terminal, có thể đọc repo, sửa file, chạy command, xem diff. Với developer, đây là sức mạnh. Với non-tech, đây cũng là chỗ dễ bấm nhầm.

Bạn không cần trở thành developer để dùng Claude Code cho prototype-to-repo handoff. Nhưng bạn cần một quy trình chậm hơn bản năng một chút: đọc trước, plan trước, sửa sau, review diff, rồi mới chạy test/build hiện có.

Bài này là workflow tôi sẽ đưa cho một founder, PM, ops lead hoặc designer muốn dùng Claude Code mà không phá repo.

Bước 0: mở đúng project root

Claude Code nên chạy ở folder gốc của project. Project root thường là nơi có package.json, src/, .git/, README.md, hoặc file config framework.

Nếu bạn không chắc mình đang ở đâu, câu đầu tiên nên là:

Hãy cho tôi biết đây có phải project root không.
Đọc cấu trúc folder ở mức cao, giải thích repo này là app gì,
framework gì, và command nào có sẵn trong package/config.
Chưa sửa file.

Đừng bắt đầu bằng “thêm tính năng X” khi Claude Code chưa hiểu repo. Một agent đang đứng sai folder có thể tạo file ở sai chỗ, đọc nhầm repo, hoặc invent structure mới.

Bước 1: yêu cầu codebase overview trước khi edit

Non-tech không cần đọc hết source code. Nhưng bạn cần hiểu vùng nào sắp bị chạm.

Prompt tốt:

Tôi muốn implement flow trong screenshot/prototype này.
Trước tiên hãy inspect repo ở chế độ đọc-only:
1. Feature tương tự đang nằm ở route/component nào?
2. Data đang lấy qua hook/API/helper nào?
3. Có design system hoặc component reuse nào không?
4. Nếu làm task này, dự kiến sẽ sửa/tạo file nào?
Chưa edit file.

Bạn đang buộc Claude Code làm việc như một người mới join project: đọc trước khi sửa. Nếu nó trả lời bằng tên file cụ thể, bạn đã có cơ sở review. Nếu nó trả lời chung chung kiểu “tôi sẽ cập nhật components”, yêu cầu cụ thể hơn.

Bước 2: bật plan mode cho thay đổi thật

Theo docs hiện tại, Claude Code có Plan Mode để phân tích codebase bằng thao tác read-only và tạo plan trước khi execution. Trong app, cách bật UI/phím tắt có thể đổi theo version, nhưng nguyên tắc không đổi: bạn muốn một plan được review trước khi disk bị edit.

Prompt thực tế:

Vào plan mode cho task này. Chỉ viết plan, chưa sửa file.
Plan cần có:
- File sẽ sửa/tạo
- Lý do từng file
- Command kiểm tra sẽ chạy
- Rủi ro hoặc điểm cần tôi confirm
- Những thứ không được chạm

Plan tốt không cần dài. Với non-tech, plan nên đọc được trong một phút. Nếu Claude viết 40 dòng implementation detail, bảo nó rút lại:

Plan này quá dài. Rút gọn cho non-tech:
file nào chạm, vì sao chạm, kiểm tra bằng gì, rủi ro gì.

Bạn approve plan khi bạn hiểu phạm vi. Không hiểu thì hỏi lại. Đừng approve vì model nghe tự tin.

Bước 3: giới hạn quyền sửa

Trước khi cho sửa, nói rõ boundary:

Approve plan này với ranh giới:
- Chỉ sửa các file đã liệt kê.
- Không thêm dependency mới nếu chưa hỏi.
- Không tạo endpoint mới nếu repo đã có endpoint/hook phù hợp.
- Không chạy deploy command.
- Không commit hoặc push.

Câu “không commit hoặc push” rất quan trọng. Trong nhiều workflow developer, commit/push là bước bình thường. Nhưng với non-tech, commit là mốc phải có ý định rõ. Claude Code có thể chuẩn bị diff, nhưng bạn không muốn nó tự ghi lịch sử git khi bạn chưa review.

Nếu cần backup, dùng branch trước khi làm. Bạn có thể nhờ Claude Code hướng dẫn tạo branch, nhưng vẫn phải hiểu ý nghĩa: branch là nơi thử thay đổi riêng, không đẩy thẳng vào main.

Bước 4: review diff bằng ngôn ngữ người

Sau khi Claude Code sửa file, đừng chỉ hỏi “done chưa”. Hỏi diff.

Giải thích diff bằng tiếng Việt dễ hiểu:
- File nào đã đổi?
- Mỗi file đổi để làm gì?
- Có file nào ngoài plan bị chạm không?
- Có behavior cũ nào có thể bị ảnh hưởng không?

Nếu bạn dùng IDE hoặc Git desktop, mở diff và nhìn bằng mắt. Bạn không cần hiểu từng syntax. Hãy nhìn các dấu hiệu này:

  • Có quá nhiều file đổi so với plan.
  • Có file config, env, deploy, auth, payment bị chạm dù task chỉ là UI.
  • Có đoạn sample/mock data xuất hiện trong production path.
  • Có dependency mới trong package.json.
  • Có console log hoặc comment debug.
  • Có text lạ, copy tiếng Anh lạc tone, hoặc hard-coded data.

Khi thấy bất thường, đừng để Claude tự trấn an. Hỏi:

Tại sao file này bị sửa? Có cách nào làm mà không chạm file này không?
Nếu đây là unrelated change, revert riêng phần đó.

Bước 5: chỉ chạy command có sẵn

Claude Code rất giỏi đề xuất command, nhưng non-tech không nên để nó invent deploy workflow.

Với task bình thường, chỉ chạy các command đã tồn tại trong repo:

  • npm run build
  • npm run test
  • npm run lint
  • command tương đương trong package.json hoặc README

Prompt tốt:

Chỉ chạy command test/build đã có trong repo hoặc README.
Không invent deploy command.
Không chạy command thay đổi cloud, database, payment, hoặc production.
Nếu cần command ngoài danh sách hiện có, hỏi trước.

Nếu build fail, yêu cầu Claude giải thích lỗi theo cách bạn hiểu:

Build fail ở đâu? Lỗi này do thay đổi vừa rồi hay lỗi có sẵn?
Chỉ sửa nếu liên quan trực tiếp tới task này.

Điểm này tránh một pattern xấu: agent thấy build fail vì lỗi cũ, rồi bắt đầu refactor unrelated area để “làm build xanh”.

Bước 6: test bằng mắt trước khi gọi là xong

Diff pass và build pass chưa đủ. Với vibe coding, bạn phải mở app và dùng flow.

Checklist nhỏ:

  • Flow chính chạy từ đầu tới cuối.
  • Refresh page không mất trạng thái quan trọng.
  • Mobile không vỡ layout.
  • Empty/loading/error state không xấu.
  • Data đang là sample hay real API được ghi rõ.
  • Text đúng ngôn ngữ và đúng business.

Sau đó feed bug lại bằng screenshot:

Ảnh này là bug sau khi chạy thay đổi.
Expected: nút Confirm ẩn khi booking cancelled.
Actual: nút vẫn hiện.
Sửa đúng lỗi này, không chỉnh layout phần khác.

Screenshot tốt hơn mô tả mơ hồ. Nó giúp Claude Code nối bug với UI cụ thể.

Khi nào dừng và gọi dev

Non-tech dùng Claude Code tốt nhất ở vùng UI, workflow, copy, glue code nhỏ, hoặc chuẩn bị PR cho developer review. Hãy dừng khi task chạm:

  • Auth, role, permission.
  • Payment, invoice, subscription.
  • Customer data hoặc file upload.
  • Database migration.
  • Production deploy.
  • Security config.
  • Dependency lớn hoặc framework change.

Bạn vẫn có thể nhờ Claude Code chuẩn bị summary cho developer:

Tóm tắt cho developer review:
- User goal
- Files changed
- Commands run
- Known risks
- Screenshots/QA notes
- Questions needing human decision

Đó là handoff tốt. Non-tech không cần tự ship mọi thứ. Giá trị của bạn là biến ý tưởng thành flow rõ, test được, có context tốt để developer review nhanh hơn.

Tham khảo