Dự án greenfield đầu tiên

Tutorial này đưa một thư mục trống tới một build card thật. Bạn sẽ viết sáu artifact planning, mỗi cái được chấm hai lần — một lần bởi script cho kết quả không thể cãi, một lần bởi model đọc với vai trò nhà phê bình.

Cần cài skill trước: Cài đặt và lần chạy đầu.

Thời gian: một đến hai giờ, tùy bạn trung thực tới đâu ở gate Scope.

Pipeline bạn sắp đi qua

Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro
|------------------ planning (files in flow/) ------------------|  |------- shipping (inside cards/) -------|

Planning gồm stage 00 tới 05, mỗi stage là một file dưới flow/. Shipping xảy ra trong cards/. Bạn không thể tạo card cho đến khi cả sáu gate planning đã pass, hoặc đã được skip kèm debt được ghi trung thực.

Bước 1 — chọn “done” nghĩa là gì

/flow project-type web

Loại dự án quyết định bằng chứng mà harness sẽ đòi ở cuối: URL deploy đang chạy cho web, một lần gọi thật với output và exit code đúng cho cli, public API import được kèm ví dụ chạy được cho library, skill đã cài và đạt đúng done-definition của chính nó cho skill. Mặc định là web. Đặt ngay từ đầu để contract không bị sai hình dạng.

Bước 2 — quyết ai viết artifact

/flow mode teach

Mode teach — mặc định — bạn viết mọi artifact planning, agent chỉ đứng gác ở gate. Mode work thì agent phỏng vấn một lần, tự soạn stage 00 tới 05, chỉ dừng để duyệt scope. Gate áp dụng giống hệt nhau; khác nhau duy nhất là tay ai gõ phím.

Nếu đang học cách dùng harness, hãy ở teach cho dự án đầu tiên. Bạn sẽ thấy mỗi gate thực sự kiểm tra điều gì.

Bước 3 — stage 00, ý tưởng

/flow next

Runner tạo flow/00-idea.md rồi fail gate, vì template đầy [FILL] và các ô chưa được tick. Mở file, viết pitch ba câu: ai có vấn đề, họ đang làm gì, bạn sẽ làm gì khác. Tick những ô bạn thật sự đã đáp ứng. Chạy /flow next lại.

Khi script pass, agent áp dụng thử thách ngữ nghĩa cho stage vừa xong. Đây là nửa việc mà không script nào làm được: nó sẽ bác lại nếu “vấn đề” của bạn là giải pháp đội lốt, hoặc pitch mô tả feature thay vì một người đang đau.

Loại bỏ dự án ở đây là kết quả hợp lệ. Ý tưởng yếu bị loại ở stage 00 tốn một giờ. Cùng ý tưởng đó bị loại sau contract tốn một tuần.

Bước 4 — stage 01, research

Điền flow/01-research.md bằng những thứ đã tồn tại: đối thủ, hệ thống live bạn đã mở, mức giá bạn đã kiểm chứng thật. Luật của stage này là inspect first — bằng chứng, không phải cảm hứng.

Gate ngữ nghĩa ở đây sắc bén hơn thường lệ, vì research bịa là thứ dễ viết nhất và khó bắt nhất bằng script. Quote không nguồn, đối thủ chưa mở, số thị trường không link — hãy chuẩn bị trả lời câu hỏi “lấy từ đâu”.

Nếu stage thật sự không phù hợp — ví dụ tool nội bộ không có thị trường công khai — đừng bịa. Ghi debt rồi skip một cách trung thực:

/flow debt add "skip 01-research" "internal tool, no public market" "before public release"
/flow skip 01-research --reason "internal tool, no public market"

skip chỉ qua được khi có một dòng debt mở gọi tên đúng stage đó, và lý do không thuộc nhóm security-class.

Bước 5 — stage 02 tới 04: scope, PRD, ADR

Scope (flow/02-scope.md) là chỗ dự án thường được cứu hoặc mất. Hãy chấm hạng feature trung thực; gate ngữ nghĩa đang soi việc bơm hạng — viết feature hạng C thành hạng B chỉ vì bạn muốn build nó.
PRD (flow/03-prd.md) biến scope còn sống sót thành functional requirement có đánh số. Mỗi FRn viết ở đây sau này phải được một card nhận (claim) và một interface contract phục vụ — đường truy vết đó máy kiểm được.
ADR (flow/04-adr.md) ghi quyết định kiến trúc, và quan trọng hơn — những gì bạn đã loại bỏ và vì sao.

Chạy /flow next sau mỗi stage. Những gì chưa xong nằm dưới heading ## Open decisions dạng - [ ]; scanner gate cũng đếm các bullet đó, nên quyết định còn treo sẽ chặn stage cho đến khi bạn chốt nó, hoặc chủ động ghi debt.

Bước 6 — stage 05, contract

flow/05-contract.md là điểm nối (seam), và là stage duy nhất không bao giờ skip được. Viết interface trước khi có code: method, path, auth, request/response cho web — lệnh, flag, định dạng output, exit code cho CLI.

Từ đây luật tuyệt đối: backend build theo contract, UI consume từ contract. Shape sai thì sửa contract trước rồi mới sửa code. Hãy tôn trọng shape ngay từ đầu bằng null hoặc stub, dù giá trị thật chỉ ship ở card sau.

Khi gate này pass bạn sẽ thấy:

PASS: stage 05-contract gate clean. Planning is COMPLETE.
All planning stages passed (or were debt-skipped). Run '/flow card' to create build cards.

Bước 7 — tạo card đầu

/flow card

Lệnh này viết cards/C-001.md. Một card là một phiên build được giới hạn phạm vi: danh sách allowed-files, requirement mà nó implement, khối ## Verify mà bạn sẽ chạy thật, ## Independent test mô tả bằng chứng người dùng nhìn thấy, và ## Evidence bắt đầu trống.

Trước khi build, chạy /flow recall — nó đọc lại debt mở, retro gần nhất, scope card trước, playbook đã promote, để bạn bắt đầu mà nỗi đau cũ vẫn còn trong tầm mắt.

Bước 8 — build, rồi chứng minh

Chỉ build những path mà danh sách allowed-files của card cho phép. Rồi:

/flow check C-001

Card fail khi ## Evidence còn trống, dù code hoàn hảo và mọi test xanh:

  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)
FAIL: C-001 has gate violations (above).

Dán bằng chứng thật — URL đang chạy kèm output curl thật cho web, lần gọi thật và exit code cho CLI — rồi check lại:

PASS: C-001 is valid (status: done).

Bạn đã học được gì

Sáu gate planning, mỗi gate được kiểm tra cơ học rồi ngữ nghĩa.
Loại (kill) và skip kèm debt trung thực đều là kết quả hạng nhất.
Contract viết trước code và là stage duy nhất không skip được.
“Tests pass” mới chỉ là giữa pipeline; hoàn thành là bằng chứng thế giới thật.

Bước tiếp theo

Tạo và kiểm card cho vòng lặp hằng ngày.
Pipeline các stage để biết mỗi stage đang chống kiểu tự lừa nào.
Hoàn thành nghĩa là bằng chứng thế giới thật để hiểu vì sao bước 8 khắt khe như vậy.