Một artifact prototype tốt không tự biến thành production code. Nó là bằng chứng: flow này có vẻ đúng, UI này có vẻ dùng được, business rule này có vẻ rõ. Từ đó đến repo thật vẫn còn một bước handoff.

Handoff tốt giúp developer hoặc Claude Code không phải đoán. Handoff kém biến vibe coding thành nợ kỹ thuật: một đống screenshot, chat dài 300 tin, sample data không rõ thật giả, và câu “làm giống cái này”.

Bài này là một workflow cụ thể: Claude Artifacts để dựng prototype, Claude Desktop để tổ chức context local, Claude Code để inspect repo và implement có kiểm soát.

Bước 1: dựng artifact để trả lời câu hỏi product

Đừng bắt artifact làm mọi thứ. Vòng đầu chỉ cần trả lời:

  • Flow có đúng không?
  • Màn hình nào cần có?
  • Người dùng bấm gì trước, bấm gì sau?
  • Dữ liệu chính là gì?
  • Trạng thái nào dễ bị quên?

Prompt tốt cho artifact:

Build một prototype tương tác cho flow tạo booking nội bộ.
Audience là ops staff.
Tập trung vào workflow: search customer, chọn service, chọn ngày,
review price, confirm booking.
Dùng sample data rõ ràng, đánh dấu đây là sample.
Đừng thêm payment, auth, hoặc backend thật.

Bạn đang giữ artifact ở đúng vai trò: mô phỏng workflow. Không đòi nó làm hệ thống thật.

Bước 2: test artifact như người dùng

Trước khi handoff, bấm qua prototype ít nhất ba lần.

Lần 1: happy path. Đi từ đầu đến cuối như user bình thường.

Lần 2: input xấu. Bỏ trống field, nhập duplicate, nhập ngày quá khứ, chọn option bị disable.

Lần 3: viewport khác. Thu nhỏ màn hình như mobile, xem bảng có vỡ không, nút có mất không, text có tràn không.

Sau mỗi lần, ghi lại bug bằng format ngắn:

Screen: Booking review
Expected: nếu service chưa chọn thì nút Confirm disabled
Actual: nút Confirm vẫn active
Evidence: screenshot booking-review-confirm-active.png

Đây là vàng cho bước implement. Bug có screenshot và expected/actual rõ sẽ sửa nhanh hơn rất nhiều.

Bước 3: tạo handoff folder

Tạo một folder local cho feature, ví dụ:

booking-flow-handoff/
├── README.md
├── screenshots/
│   ├── 01-search-customer.png
│   ├── 02-select-service.png
│   └── 03-review-confirm.png
├── sample-data.json
├── acceptance-checklist.md
└── open-questions.md

Không cần fancy. Cần rõ.

README.md nên có:

  • Feature name.
  • User type.
  • Main job-to-be-done.
  • Link hoặc note artifact source.
  • What is in scope.
  • What is out of scope.

acceptance-checklist.md nên có các dòng test được:

- User can search customer by phone or name.
- User cannot confirm booking without service and date.
- Cancelled service is visible but cannot be selected.
- Mobile view keeps primary action visible.
- API error shows a readable message.

open-questions.md là chỗ ghi những gì chưa quyết:

- Nếu customer có 2 phone numbers thì search theo cái nào?
- Service price lấy từ API nào?
- Có cần audit log khi booking được confirm không?

Những câu hỏi này không phải lỗi. Chúng là boundary. Đừng để Claude Code tự quyết silently.

Bước 4: dùng Claude Desktop để organize, không phải để ship thẳng

Claude Desktop hữu ích ở bước này vì nó gần với file, doc, screenshot, conversation hơn terminal. Với Desktop extensions/connectors, tùy setup hiện tại, Claude có thể hỗ trợ làm việc với local folder hoặc tài liệu. Product behavior có thể đổi theo plan và version, nên coi Desktop là nơi tổ chức handoff, không phải nơi tự động đẩy code vào repo.

Prompt tốt trong Desktop:

Đọc folder handoff này.
Kiểm tra xem README, screenshot, sample data, acceptance checklist,
open questions đã đủ để một developer implement chưa.
Nếu thiếu context, liệt kê thiếu gì. Đừng viết production code.

Bạn có thể yêu cầu Claude Desktop làm sạch tài liệu:

  • Gộp feedback trùng.
  • Đổi bug report thành expected/actual.
  • Tách must-have và nice-to-have.
  • Làm acceptance checklist ngắn lại.
  • Tóm tắt open questions cho dev.

Đây là việc non-tech nên dùng AI làm nhiều: biến context lộn xộn thành handoff rõ.

Bước 5: mở Claude Code trong repo thật

Khi handoff pack đã rõ, mới mở Claude Code ở project root.

Câu đầu tiên:

Bạn đang ở repo thật. Hãy inspect read-only trước.
Tôi có handoff folder ở đường dẫn này: <path>.
Đọc handoff, rồi map prototype behavior vào repo:
- route/page hiện tại liên quan
- component có thể reuse
- API/hook/helper hiện có
- file dự kiến sửa
- command test/build có sẵn
Chưa edit file.

Mục tiêu là mapping, không phải code ngay.

Claude Code nên trả lời kiểu:

Prototype screen "Review booking" map vào:
- Route: src/pages/bookings/[id].tsx
- Component: src/features/bookings/BookingDetail.tsx
- Existing hook: useBookingDetail(id)
- Existing helper: formatBookingStatus()
- Files likely touched: ...

Nếu nó không tìm thấy endpoint/hook, bảo nó nói thật:

Nếu không tìm thấy API/hook có sẵn, dừng lại và nói rõ.
Không invent endpoint mới.

Bước 6: plan implementation theo repo, không theo artifact code

Artifact code có thể dùng làm reference, nhưng không nên mặc định paste vào production.

Prompt:

Viết plan implement dựa trên repo hiện có.
Không paste nguyên artifact code.
Map behavior từ artifact vào component, route, API hook,
style convention hiện có.
Plan cần liệt kê file sửa/tạo, rủi ro, command kiểm tra.

Đọc plan và hỏi ba câu:

  • Có file nào ngoài feature scope bị chạm không?
  • Có endpoint/dependency/config mới không?
  • Có thứ gì thuộc auth/payment/customer data cần dev review không?

Nếu câu trả lời có rủi ro, dừng. Nếu scope nhỏ và rõ, approve edit.

Bước 7: audit final diff bằng checklist

Sau khi Claude Code sửa xong, đừng so với trí nhớ. So với checklist.

Mở acceptance-checklist.md, đi từng dòng:

  • Đã implement chưa?
  • Test bằng mắt được chưa?
  • Nếu chưa, vì sao?
  • Có bug mới không?
  • Có behavior nào trong artifact bị bỏ sót không?

Sau đó hỏi Claude Code:

So sánh diff hiện tại với acceptance checklist.
Đánh dấu từng item: done, partial, not done.
Với partial/not done, giải thích ngắn và không tự sửa thêm.

Đây là cách giữ quyền quyết định ở phía bạn. Agent không tự định nghĩa “done”; checklist định nghĩa “done”.

Bước 8: chuẩn bị review cho developer

Nếu feature chạm repo thật, cuối cùng nên có một summary cho reviewer:

Tạo review summary:
- User goal
- Handoff folder path
- Files changed
- Behavior implemented
- Commands run and result
- Known limitations
- Items needing dev review

Summary này giúp developer review nhanh hơn. Họ không cần đọc toàn bộ chat. Họ có artifact screenshots, checklist, diff, và command output.

Đây là vai trò tốt nhất của non-tech trong vibe coding: không phải tự thay developer, mà là giảm ambiguity trước khi developer chạm vào.

Tham khảo