Playbooks — copy các bước, dán vào Claude
Sáu tình huống thật, hai bộ kit. Chọn việc bạn đang làm, copy từng bước. Không cần nhớ lệnh.
Trang này không phải để đọc — để dùng. Chọn bộ kit hợp với việc bạn đang làm, chọn tình huống, rồi copy từng bước một.
Nếu bạn đang bắt đầu một dự án mới, dùng buildflow. Nếu bạn đang chạy một task trong repo đã có, dùng autocode-kit. Phần giải thích sâu nằm gọn phía dưới mỗi playbook — mở ra khi cần.
Chọn việc bạn đang làm.
Copy các bước.
Hai bộ kit, sáu tình huống. Mỗi bước cho bạn thấy chính xác thứ cần gõ — ô sẫm là câu nói với AI, ô đen là lệnh gõ trong Claude. Bấm COPY rồi dán vào.
Bạn tự viết mọi artifact, AI chỉ gác cổng và từ chối những chỗ hời hợt. Đây là cách học phương pháp.
Copy repo buildflow vào thư mục dự án mới, mở Claude Code trong đó, rồi kiểm tra mode.
/flow mode
mode: teach là đúng đường. Bạn luôn gõ /flow — nó tự chạy script bash bên dưới.Nói cho AI biết bạn muốn gì, rồi mở chặng đầu tiên.
Mình muốn dựng một app nhỏ giúp chủ tiệm spa quản lý lịch hẹn. Mình dùng buildflow, mode teach. Bắt đầu giúp mình.
/flow next
flow/00-idea.md và dừng lại chờ bạn viết.Mở flow/00-idea.md. Viết pitch đúng 3 câu. Nêu tên một người thật đang có nỗi đau này. Tự tick các ô gate.
Tick xong các ô gate trong file, ký tên vào chặng đó. Không ký thì cổng không mở.
$ bash .claude/skills/flow/runner/flow.sh sign 00-idea
/flow next báo
"unsigned: no operator signature". Sửa file sau khi ký thì chữ ký hết hiệu lực và cổng đóng lại.
Xin qua cổng. Đạt thì nó mở chặng sau; chưa đạt thì nó chỉ đúng chỗ còn thiếu.
/flow next
Đọc flow/01-research.md giúp mình. Chỗ nào còn hời hợt hay thiếu bằng chứng thật? Đừng sửa hộ, chỉ chỉ ra thôi.
Xong contract, sinh card build đầu tiên.
/flow card
/healthz trên một URL công khai.Trước khi code, để AI trích test case từ chính app thay vì bịa ra từ chữ trong card.
/verify-plan C-001Xây đúng phần ## Scope, chỉ chạm file trong ## Allowed files. Chạy từng bước ## Verify thật, dán output thật vào ## Evidence, rồi mới đặt status: done.
Xây card cards/C-001.md giúp mình. Chỉ chạm các file trong mục Allowed files. Xong thì dừng lại, đừng tự đánh dấu done — mình sẽ tự chạy phần Verify.
Cổng ra của card.
/flow check C-001
Layer: đã khai → chặn. Evidence trống → hook đã chặn từ trước đó rồi.Xong hết card thì khép vòng lại. Ba câu hỏi, ba file.
/flow retro
RETRO.md (bạn lướt cổng nào, và trả giá gì?) · playbooks/ (stack dạy bạn bài học nào?) · FLOW-FEEDBACK.md (bản thân buildflow nên sửa gì?)Nó dừng lại đúng một chỗ: cổng scope. Gates và luật "xong" không đổi — chỉ đổi ai cầm bút.
Đổi mode sang work.
/flow mode work
Kể trước bối cảnh — nó sẽ không hỏi lại những gì bạn đã nói. Càng kể kỹ, càng ít bị phỏng vấn.
Mình dựng app đặt lịch cho một tiệm spa thật ở Đà Nẵng — chị chủ đang ghi sổ tay và hay trùng lịch. Ngân sách: 2 tuần, làm buổi tối. Stack: Cloudflare Workers + Hono + D1. Deploy lên Cloudflare. Bắt buộc có: đặt lịch, xem lịch trong ngày. Cắt được: thanh toán online, app mobile. Thành công = chị ấy bỏ hẳn sổ tay sau 2 tuần.
/flow next
Nó dừng ở cổng scope và đưa bạn: bảng impact×grade, ba tính năng nó tự đề xuất (mặc định để OUT), danh sách cắt, và khuyến nghị GO / KILL.
flow/ làm hồ sơ, mở bản buildflow mới cho ý tưởng kế tiếp.Duyệt bảng scope xong, ký vào chặng đó. Mode work đổi ai cầm bút — không đổi việc ai ký.
$ bash .claude/skills/flow/runner/flow.sh sign 02-scope
Duyệt scope xong, nó chạy tiếp tới hết chặng 05. Sinh bộ card trước đã — không có card thì hai lệnh sau đều từ chối.
/flow card
/flow ready trả lời "No cards yet — /flow card", còn /flow auto báo "PREFLIGHT FAIL — no cards". Chạy lệnh này trước.Duyệt scope xong, nó chạy tiếp tới hết chặng 05 và giao cả bộ card trong một bản tóm tắt. Xem card nào xây được ngay.
/flow ready
Để nó tự xây. Nó tự chạy preflight trước — chỉ đi tiếp khi thấy PREFLIGHT OK.
/flow auto
## Verify, không tin lời subagent báo về.Đọc AUTO-LOG.md — không phải đọc scrollback. Card cần credential, cần bạn duyệt mock UI, hay deploy lần đầu → nó tự gắn blocked-on-operator rồi đi làm card khác.
Đọc AUTO-LOG.md rồi tóm tắt giúp mình: card nào xong, card nào đang chờ mình, card nào fail và vì sao.
App đã chạy thật. Ba cổng thay vì sáu. Card đầu tiên không phải tính năng mới.
Đổi đường ngay lập tức, trước khi làm bất cứ việc gì khác.
/flow track brownfield
rm -rf flow/* TRACK rồi chạy lại. Đã có file trong flow/ thì không đổi track được — cố ý như vậy, để artifact không bị mồ côi.Quét app thật. Mọi finding đều phải trích file:line.
App này là API đặt lịch, chạy Cloudflare Workers + D1. Mình muốn thêm gửi email xác nhận, mà sợ làm vỡ luồng thanh toán. Quét giúp mình trước.
/auditflow/00-xray.md: findings F1..Fn xếp theo severity × evidence, tách riêng khỏi phần đề xuất. Bạn mới là người quyết đề xuất nào thành card.Đóng băng findings, để về sau diff được xem mình đã sửa gì.
/flow rescan baseline
Đi qua ba cổng: 00-xray → 01-scope → 02-contract-delta. Chạy lệnh này ba lần.
/flow next
Ba cổng brownfield, mỗi cổng một chữ ký: 00-xray, 01-scope, 02-contract-delta.
$ bash .claude/skills/flow/runner/flow.sh sign 00-xray
Sinh card đầu tiên.
/flow card
Trích test case từ chính app: Zod schema, ràng buộc DB, route surface, test sẵn có.
/verify-plan C-001
Bạn luôn gõ trong Claude: /flow …, /audit, /verify-plan C-NNN.
/flow tự gọi script bash flow.sh bên dưới rồi trả kết quả nguyên văn cho bạn.
Còn /flow audit thì không tồn tại — /audit là một skill riêng.
Một lệnh, không tham số. File chính là trạng thái — nó đọc thư mục và nói bạn đang đứng ở đâu.
Hỏi thẳng nó.
/flowĐọc kỹ dòng cảnh báo hook, nếu có.
buildflow coi bỏ cuộc đúng lúc là một lối ra hợp lệ, không phải thất bại. Bạn vừa tiết kiệm chính thời gian của mình.
Để AI soạn nhanh tới cổng scope.
/flow mode work
Đi tới khi nó dừng ở 02-scope và đưa bảng impact × grade kèm khuyến nghị GO / KILL.
/flow next
Đọc bảng. Không có kênh cụ thể để lấy 10 người dùng đầu? Không nêu được một người thật đang có nỗi đau này? Đó chính là tín hiệu KILL.
flow/ làm hồ sơ, rồi mở một bản buildflow mới cho ý tưởng kế tiếp.Chỉ dành cho brownfield. Đóng băng trước khi sửa — không có ảnh chụp lúc đầu thì về sau không so được.
Quét xong (/audit), đóng băng danh sách findings.
/flow rescan baseline
/audit thì nó từ chối: "no flow/00-xray.md — run /audit first".Xây các card sửa lỗi như bình thường.
Quét lại, rồi so với ảnh chụp lúc đầu.
/audit/flow rescan report
[STILL OPEN] — lỗi cũ chưa sửa — và [NEW] — lỗi bạn vừa tạo ra khi sửa. Cột thứ hai mới là cột đáng sợ.Hiểu sâu hơn về buildflow — sáu cổng, giải phẫu một card, sơ đồ 11 ô
Một câu luật, mọi thứ khác theo sau
Nếu bạn chỉ nhớ một dòng từ buildflow, hãy nhớ dòng này.
Xong = bằng chứng ngoài đời thật.
"Test xanh" chỉ là giữa đường.
Mỗi card phải nêu done-evidence ngay từ đầu: một URL bạn bấm được, output của một lệnh
curl, một dòng thật trong database. Một hook bash exit 2 sẽ chặn nếu bạn
đánh dấu status: done mà mục ## Evidence còn trống.
Dừng ý tưởng ở cổng scope là một thành công, không phải thất bại.
Bạn vừa tiết kiệm chính ngân sách thời gian của mình. Giữ lại thư mục flow/
làm hồ sơ, rồi mở một bản buildflow mới cho ý tưởng kế tiếp.
Sáu chặng, sáu cổng
Chạy /flow next: nó kiểm cổng của chặng hiện tại. Đạt → mở template chặng sau.
Chưa đạt → nó nói đúng chỗ còn thiếu. Dưới đây là checklist thật của từng cổng.
Contract là cái mối nối.
Nó được viết trước khi có một dòng code nào. Backend xây theo nó, UI tiêu thụ từ nó.
Không bên nào được ứng biến. Nếu contract sai — sửa flow/05-contract.md trước, rồi mới code theo.
Một card = một ô
Đây là thước đo "card này có to quá không". Mỗi card khai báo đúng một ô trên dòng
Layer:. /flow check đọc diff và chặn nếu bạn chạm sang ô khác.
Card chạm hai ô = hai trách nhiệm = hai card.
Giải phẫu một card
Card là brief của một phiên làm việc. Một phiên, một card. /flow check là cổng ra.
gate-before-code.sh — không cho ghi source code khi các cổng kế hoạch còn mở.
no-done-without-evidence.sh — không cho đặt status: done khi mục Evidence trống.
Một skill là lời khuyên — model có thể tự nói vòng qua nó. Một hook là luật:
exit 2 và lệnh ghi file không bao giờ xảy ra. Cả hai hook đều
fail-open: hook lỗi thì cho qua, vì một cái cổng kẹt cứng còn tệ hơn không có cổng.
Thứ tự xây, không phải thứ tự thích
Contract trước, rồi một lát cắt dọc mỏng tới URL đã deploy, rồi mới đi rộng. Lát cắt sớm vừa là liều động lực, vừa là bằng chứng tích hợp.
/healthz trên URL công khaiURL healthzVì sao mock trước framework: sửa một mock tốn vài giây, sửa một framework tốn cả lượt deploy.
Hai đường: app mới và app đang chạy
Mặc định là greenfield. App đã có code? Đổi đường ngay lập tức, trước khi làm gì khác.
Từ một ý tưởng chưa có dòng code nào.
00-idea → 01-research → 02-scope03-prd → 04-adr → 05-contract/flow card → C-001 = scaffoldBạn không pitch ý tưởng — bạn nâng cấp một hệ thống đang sống.
00-xray → 01-scope → 02-contract-delta/audit quét code, mọi finding trích file:line/flow card → C-001 = characterization
Tất cả đều gõ trong Claude. /flow track|next|card|check là cổng máy móc —
nó chạy script bash bên dưới rồi trả kết quả nguyên văn. /audit và /verify-plan
là skill — AI đọc code, thả agent đi dò. /flow audit không tồn tại.
Bảy lệnh, và bạn chỉ thật sự làm việc ở hai chỗ: chốt Scope OUT, và đọc card trước khi dispatch.
Xem mình đang đứng ở đâu trước khi động vào gì.
/mindful brief
PRD → ADR → journey → ExecPlan → cards → dispatch → review → merge, card nào đang bay, tín hiệu gì từ ba retro gần nhất.Viết PRD. Nó phỏng vấn bạn 8–10 câu rồi mới soạn — và từ chối brief dưới 20 chữ.
/prd-author Thêm tính năng rút gọn link cho dashboard. Người dùng là marketer, họ đang dán link dài vào bài post và không đo được click. Cần đếm click theo ngày. Chưa cần custom domain trong v1.
docs/prd/0001-<slug>.md. Nó không cho chốt khi thiếu Scope OUT và Open questions.Mài phần Scope OUT. Đây là việc đắt giá nhất trong cả tính năng — mọi thứ sau đó đều nở ra từ đây.
Mỗi quyết định kiến trúc một ADR. Lặp lệnh này 2–4 lần cho mỗi tính năng.
/adr-author Lưu mapping slug → URL ở đâu: Postgres hay Redis? Cần đọc rất nhiều, ghi ít.
proposed — bạn tự đổi thành accepted.Journey = hợp đồng "xong" của tính năng, viết bằng thứ người dùng quan sát được.
/journey-author PRD-0001Chia phase. Phase 0 luôn là "viết E2E từ journey, xác nhận nó fail".
/execplan-author PRD-0001Sinh card. Mỗi card có allowed_files, acceptance criteria, và cách tự verify.
/task-card T-001 tạo bảng links + migration
/task-graph <feature> để vẽ DAG. Plan tuần tự tầm thường thì nó từ chối vẽ.Đọc từng card trước khi dispatch. Đây là 25 phút có đòn bẩy cao nhất trong cả quy trình.
Đọc docs/tasks/url-shortener/T-001.md giúp mình. Scope có bị rộng quá không? allowed_files có thiếu file nào mà chắc chắn phải sửa không? Chỉ ra, đừng sửa.
Thả card vào worktree riêng. Nó tạo nhánh t-001-<slug> và spawn một executor mới.
/task-dispatch T-001 --dry-run
/task-dispatch T-001allowed_files → từ chối dispatch.Executor báo về bằng PR. Chấm nó.
/review-pass T-001file:line. Nhiều hơn 3 comment nghĩa là card đã quá to.PASS rồi thì merge. Chưa có scheduler tự động — bạn gõ tay.
$ gh pr merge --squash --delete-branchKhông PRD, không ADR. Cái test bạn viết ra mới là thứ ngăn nó quay lại.
Tái tạo bug tại chỗ. Xác nhận bạn thấy nó bằng mắt, không phải đoán.
Viết một test fail đúng lý do — pha đỏ. Đây là bước khoá bug lại.
Bug: slug có ký tự hoa thì redirect trả 404, mà lẽ ra phải không phân biệt hoa thường. Viết cho mình một test fail đúng vì lý do đó, chạy trên HEAD. Chưa sửa code vội.
Soạn card sửa. Thường một card là đủ, đôi khi hai.
/task-card T-042 sửa lookup slug thành không phân biệt hoa thường; test vừa viết phải chuyển xanh
Thả vào worktree. Executor sửa trong đó, không đụng vào cây làm việc của bạn.
/task-dispatch T-042Chấm rồi merge.
/review-pass T-042$ gh pr merge --squash --delete-branchBug này có phải dấu hiệu của một luật còn thiếu không?
/mindful tune slug lookup phân biệt hoa thường
.harness/invariants.yaml, gắn source: trỏ về đúng con bug này. Chỉ thêm khi đã bị đau thật — không bao giờ thêm trước.Pre-flight khắt khe: sai một điều là nó dừng. Đó là điểm cộng, không phải phiền toái.
Mở một phiên Claude Code trong repo autocode-kit (không phải trong dự án đích). Xem trước nó định làm gì.
/harness-bootstrap /duong/dan/toi/du-an --dry-run
.harness/ phải vắng mặt (cài mới) hoặc có mặt (nâng cấp); CLAUDE.md của bạn được giữ nguyên.Ổn rồi thì cài thật.
/harness-bootstrap /duong/dan/toi/du-an.harness/ sang, rồi ghi dự án vào watched-projects.yaml. Nâng cấp về sau: thêm --upgrade.cd sang dự án đích, mở phiên Claude Code mới ở đó, rồi xem harness đứng đâu.
/mindful brief
Kiểm cái cổng máy. Lúc này nó chưa có luật nào, và đó là chủ ý.
$ python3 .harness/check_invariants.py --fullrules: []. Bạn chỉ thêm luật khi một ADR hoặc một con bug đã làm nó trở nên cụ thể — không bao giờ thêm phòng xa.Mỗi tuần, nhìn lại chỗ nào card hay kẹt, hay bị REQUEST-CHANGES. Chọn đúng một thứ để siết.
/mindful drift
invariants.yaml, hoặc một convention rõ hơn trong CLAUDE.md, hoặc sửa template card. Tuần sau harness chặt hơn tuần này.Harness chỉ đáng tin khi bộ test đã xanh ổn định và bạn đã chạy tay quy trình ít nhất một lần. Tự động hoá một quy trình chưa đáng tin chỉ nhân rộng những chỗ còn lệch.
Thang của kit: prd → adr → journey → execplan → cards → dispatch → review → merge. Hỏi nó, đừng đoán.
Hỏi bước kế tiếp. Nó đọc trạng thái trên đĩa rồi trả lời.
/mindful next
mindful — nó là router, không phải một chặng trong pipeline.Nghi ngờ harness đang lỏng dần? Bắt nó tự soi.
/mindful drift
/mindful tune.Không cần chạy cả pipeline. Một lệnh review, một lệnh merge.
Soi diff của đúng một card.
/review-pass T-203
file:line. Tối đa 3 nhận xét — nhiều hơn nghĩa là card quá to. Diff chạm file ngoài allowed_files → tự động ESCALATE.PASS rồi thì merge. Chưa có skill auto-merge — đây là bước cơ học duy nhất bạn gõ tay.
$ gh pr merge --squash --delete-branchChạy không cần trông. Nhưng đọc kỹ cảnh báo dưới đây trước khi bấm.
Ở chế độ go và block, planner tự review rồi tự merge chính việc của executor mình — không có cổng người thứ hai ở bước merge.
Mô tả epic (ít nhất ~20 chữ) rồi thả nó chạy.
/mindful block "thêm luồng đặt lịch cho tiệm spa: chọn dịch vụ, chọn giờ, xác nhận qua email, huỷ trước 2 tiếng"
Muốn từng bước một, có phanh? Dùng go thay vì block.
/mindful go
[go N/10] để bạn thấy đang ở vòng nào.Đọc log của run, không đọc scrollback.
Hiểu sâu hơn về autocode-kit — chín bước, cái cổng, bốn việc chỉ bạn làm được
Công việc của bạn đổi chỗ
Đây là toàn bộ lời hứa của autocode-kit, gói trong một câu đổi vai.
Nút cổ chai là tốc độ gõ phím và ngân sách chú ý của bạn.
Nút cổ chai giờ là phán đoán của bạn. Đó là thứ đáng để dành.
Chín bước, mỗi bước một lệnh
Mỗi bước phỏng vấn bạn rồi mới soạn. Không có bước nào tự chạy ngầm —
cả 12 skill đều disable-model-invocation, tức là chỉ chạy khi bạn gọi tên.
Mỗi skill đều biết nói không
Đây là thứ làm autocode-kit khác một đống prompt. Một skill không từ chối được thì không đáng tin để chạy khi bạn ngủ. Dưới đây là những lời từ chối có thật, trích từ chính mã nguồn.
Dưới 20 chữ là nó trả lại và yêu cầu bạn viết thêm bối cảnh. Cũng không cho chốt PRD khi thiếu Scope OUT và Open questions.
Bắt buộc ít nhất 2 phương án thay thế và phải viết ra mặt tiêu cực bạn chấp nhận. Mặc định trạng thái là proposed, không phải accepted.
Journey chỉ được nói về thứ người dùng quan sát được. Nhắc tới class, bảng, endpoint là nó trả lại.
Nhiều hơn 8 nghĩa là bạn chưa chia nhỏ vấn đề. Phase 0 luôn là "viết E2E từ journey, xác nhận nó fail".
Plan chạy tuần tự tầm thường thì nó không vẽ đồ thị — nó bảo bạn dùng cờ phase của ExecPlan cho gọn.
Card thiếu allowed_files thì không được phép dispatch. Chọn cmux mà không có cmux? Nó từ chối, chứ không lặng lẽ tụt về tmux.
Integration test không được mock DB — dùng testcontainers thật. Mỗi hàm public phải có đủ happy + edge + error.
Chỉ được assert vào hành vi quan sát được. Một test luôn đúng thì không phải test.
Tối đa 0–3 comment. Nhiều hơn nghĩa là card đã quá to — vấn đề nằm ở khâu chia card, không phải khâu review.
Pre-flight: phải là git repo, .harness/ phải vắng mặt (cài mới) hoặc có mặt (nâng cấp), CLAUDE.md phải được giữ nguyên. Sai một điều là dừng.
Cái cổng thay bạn gác
Khi bạn buông tay, phải có thứ gì đó vẫn nói không. Đó là .harness/invariants.yaml —
và điều đáng chú ý nhất là nó ship ra với con số không luật nào.
Cấm một regex xuất hiện trong đường dẫn được chỉ định
Cấm import một package nhất định
Bắt buộc một người thật nhìn qua
Thư mục này không được phép tồn tại
Đường dẫn này bắt buộc phải có
Đúng một, không hơn — ví dụ một binary dưới cmd/
Mọi rule khi được thêm vào đều là BLOCKING. Không có warn level.
Thấy một rule quá chặt trong thực tế? Hạ nó qua retro, công khai — chứ không lặng lẽ bỏ qua.
Mỗi rule mang một trường source truy ngược về đúng cái ADR hoặc cái bug đã sinh ra nó.
Card chạy ở đâu, ai chấm
Mỗi card được thả vào một thế giới riêng, để nó có hỏng thì cũng hỏng một mình.
/task-dispatch tạo một git worktree trên nhánh t-NNN-<slug>,
rồi spawn một executor Claude Code hoàn toàn mới trong đó. Tự dò cmux > tmux > print.
Operator phải gõ "yes" trước khi spawn — đó mới là cái cổng thật, không phải một cái cờ config.
/review-pass chia đôi: runner bash kiểm scope và chạy lệnh verify một cách
tất định; LLM đi qua từng acceptance criteria và soi convention. Mỗi finding phải trích
file:line. Không có "trông ổn đấy".
Card đạt. Mở đường cho merge.
Có việc phải sửa, và đã chỉ đúng dòng.
Vượt tầm card này. Cần một con người.
Bốn việc chỉ bạn mới làm được
Thuộc bốn dòng này. Mọi thứ khác đã có skill hoặc script lo.
Kit này chưa có scheduler tự động — tài liệu STEPS.md có mô tả một
scheduler.py, nhưng SKILLS.md nói rõ nó chưa được xây.
Hôm nay bạn dispatch thủ công, từng card một, qua /task-dispatch.
Muốn auto-merge? Chạy gh pr merge --squash sau khi /review-pass trả PASS.