English · Tiếng Việt
Version: v1.4 (30/07/2026). Khi copy kit vào project mới, ghi dòng
> Khởi tạo từ ai-workflow-kit v1.4 — <ngày>vào cuốiCLAUDE.mdcủa project (bước 5 trongspecs/INIT.md) — để sau này biết project cũ đang chạy bản kit nào.
Bộ file tái sử dụng, dựng sẵn quy trình "spec-driven, AI implement, người duyệt 1 lần mỗi batch" cho project mới bất kỳ. Rút ra từ một project production thật rồi tổng quát hoá.
Vì sao có bộ này: AI code ra feature rất nhanh, và code sinh ra rồi không ai review chính là nơi bug bảo mật thật sự nằm. Kit này ra đời từ một phát hiện audit có thật — decorator phân quyền RBAC không có guard đằng sau, khiến route admin của một marketplace production trở thành công khai. Mọi thứ ở đây nhắm vào việc giữ tốc độ của AI mà không đánh mất đúng một checkpoint con người bắt được loại bug đó.
Điều khiến v1.4 khác một đống markdown: checkpoint giờ được hook cưỡng chế, không còn là
lời nhắn trong văn bản. Tới v1.3, "không implement khi chưa duyệt" chỉ là câu văn xin model tuân
thủ. Giờ một hook PreToolUse chặn mọi lệnh ghi vào file source cho tới khi có task ở trạng
thái Đang làm trong TASKS.md. Docs và spec vẫn ghi được bình thường — nên việc lên kế hoạch
không bao giờ bị chặn, chỉ có implement mới bị.
| Đường dẫn | Vai trò | Copy vào đâu trong project mới |
|---|---|---|
claude-skeleton/ |
Lớp enforcement — hook cổng duyệt, hook xử lý secret, 6 lệnh workflow | Copy vào .claude/ ở root |
CLAUDE.template.md |
Trí nhớ project — đọc đầu tiên mỗi session: stack, convention, DO NOT, lịch audit | Copy thành CLAUDE.md ở root (bắt buộc ở root để tự load) |
TASKS.template.md |
Backlog sống, có cột phụ thuộc; cổng chặn đọc đúng cột trạng thái của nó | Copy thành TASKS.md ở root |
specs-skeleton/INIT.template.md |
Quy trình init tự chứa — không cần truy cập folder kit gốc | Copy thành specs/INIT.md, xoá sau khi init xong |
specs-skeleton/00_Intake_Template.md |
Brief cấp project 1 lần + brief mỗi feature | Copy vào specs/ |
specs-skeleton/01-08_*.template.md |
Khung spec: Tech Stack, DB Schema, API Contract, Frontend Architecture, Business Logic Flows, AI Tooling Rules, Testing Strategy, Deployment Guide | Copy hết vào specs/, bỏ đuôi .template, điền dần |
specs-skeleton/09_Audit_Report_Template.md |
Khung báo cáo audit (Nghiêm trọng / Nên sửa / Đã tốt / không xác nhận được + bảng ưu tiên) | Copy thành specs/09_Audit_Report_<ngày>.md mỗi lần audit |
specs-skeleton/10_AI_Workflow.template.md |
Vòng lặp đầy đủ: Intake → Spec → Task → 1 lần duyệt → Implement tự verify → Release → Post-release | Copy thành specs/10_AI_Workflow.md |
specs-skeleton/11_Rollback_Runbook.template.md |
Ngưỡng và quy trình rollback, viết trước khi cần đến | Copy thành specs/11_Rollback_Runbook.md |
specs-skeleton/CHANGELOG.template.md |
Changelog mỗi release, có mục sự cố | Copy thành specs/CHANGELOG.md |
reference/security-baseline.md |
DO NOT bảo mật mặc định, chia Nhóm A bất biến và Nhóm B thay được | Copy vào reference/ ở root |
reference/intake-example.md |
Bản Intake A+B điền đầy đủ + checklist data + mẫu brief 1 cục | Copy vào reference/ |
reference/industry-presets.md |
Ngành → style gợi ý → câu hỏi compliance cần hỏi | Copy vào reference/ |
reference/ui-design-standards.md |
Chuẩn UI/chất lượng code chống "AI slop" | Copy vào reference/ |
reference/ai-tooling-options.md |
Ghi chú đánh giá các công cụ bổ trợ trong hệ sinh thái AI (nén context, plugin memory, meta-tool tạo skill, proxy inference bên thứ ba) — cái nào an toàn để thêm, cái nào rủi ro cho gói Claude Code | Copy vào reference/ |
i18n/vi/ |
Bản tiếng Việt đầy đủ của mọi template và file reference | Làm việc bằng tiếng Việt thì copy từ đây |
cp -R claude-skeleton/. <project>/.claude/
chmod +x <project>/.claude/hooks/*.sh
cp i18n/vi/CLAUDE.template.md <project>/CLAUDE.md
cp i18n/vi/TASKS.template.md <project>/TASKS.md
cp -R i18n/vi/specs-skeleton <project>/specs
cp -R i18n/vi/reference <project>/reference
cd <project>/specs && for f in *.template.md; do mv "$f" "${f%.template.md}.md"; doneRồi mở session trong project đó và nói: "Khởi tạo theo ai-workflow-kit — mô tả project: […]".
Toàn bộ quy trình nằm trong specs/INIT.md vừa copy.
Vì sao copy
reference/vào từng project thay vì để Claude đọc thẳng từ kit: mỗi session Claude chỉ truy cập được thư mục đã được cấp quyền. Project mới nằm chỗ khác mà không cấp lại quyền cho folder kit thì Claude không đọc đượcreference/— mất luôn ý nghĩa của việc giảm việc tay. Copy vào project giữ project tự chứa, và các đường dẫn tương đối (../reference/...) vẫn đúng. Đánh đổi: kit cải tiến thì project cũ phải copy lại thủ công — chấp nhận được, vìreference/thay đổi ít hơn nhiều so với tần suất tạo project mới.
Intake ──▶ Spec ──▶ Task ──▶ DUYỆT ──▶ Implement + tự verify ──▶ Release ──▶ Post-release
A B C D E, F G H
▲ │
└──────────── feature tiếp theo ───────────────────┘
| Lệnh | Giai đoạn | Làm gì |
|---|---|---|
/aiwk:intake |
A–C | Brief → spec → task list, tất cả ở Chờ duyệt |
/aiwk:approve |
D | Trình kiến trúc + task; chuyển ID đã duyệt sang Đang làm |
/aiwk:audit |
— | Audit bảo mật/RBAC read-only → báo cáo có ngày → task |
/aiwk:verify |
F | Review đối nghịch diff của task Critical trước khi Done |
/aiwk:release |
G–H | Checklist release, verify production thật, changelog |
/aiwk:rollback |
— | Chạy runbook rollback khi release hỏng |
- Đúng 1 checkpoint bắt buộc, và nó được cưỡng chế. Kiến trúc + task list được duyệt 1 lần mỗi batch trước khi code được viết. Không bao giờ tự động 100%, vì generate-rồi-không-review chính là chỗ con bug RBAC chui ra.
- DO NOT phải cụ thể, không được chung chung. Sau audit đầu tiên, mỗi project có DO NOT gọi
tên bug thật của chính nó. Ngoại lệ: Nhóm A bất biến trong
security-baseline.md(concurrency, migration, secrets, deploy) giữ vĩnh viễn — audit tĩnh hiếm khi chứng minh được không có race condition, nên nhóm đó tuyệt đối không được "thay mất". - Task nhỏ, tự kiểm tra được. Mỗi task đủ nhỏ để model tự chạy checklist — guard, secret, 4 state UI, migration an toàn — trước khi báo Done.
- Done nghĩa là máy chứng minh. Với feature Critical, mỗi acceptance criterion thành 1 test tự động pass, và 1 subagent context sạch review lại diff. Người viết code mang đúng cái điểm mù đã đẻ ra con bug.
- Mỗi sự cố phải quay ngược vào rule — thành 1 dòng DO NOT nếu là chuyện phán đoán, thành 1 guardrail CI nếu máy check được. Đó là thứ làm danh sách tốt lên thay vì chỉ dài ra.
- Lớp enforcement (
claude-skeleton/): cổng duyệt và guard xử lý secret giờ là hook thật, kèm 6 slash command phủ toàn bộ workflow. Đây là chỗ trước giờ kit thua các bộ chạy được như GitHub Spec Kit. - Báo cáo audit có chuẩn độ sâu và mục nói thật: mỗi phát hiện bắt buộc nêu
file:dòng, cách khai thác cụ thể và cách sửa; mỗi báo cáo phải ghi rõ nó không xác nhận được cái gì, thay vì để sự im lặng bị hiểu là an toàn. - Tiếng Anh thành ngôn ngữ chính; bộ tiếng Việt đầy đủ chuyển vào
i18n/vi/. - Post-release không còn 1 dòng: runbook rollback với ngưỡng chốt trước
(
11_Rollback_Runbook.md), lịch audit định kỳ trongCLAUDE.md, và bước đổ bài học ngược vào rule. TASKS.mdthêm cột phụ thuộc;03_API_Contractthêm cột check ownership;05_Business_Logic_Flowsthêm mục concurrency.06_AI_Tooling_Ruleskhông còn chép lạiCLAUDE.md— nó trỏ về quaAGENTS.md, vì rule chép tay là rule sẽ lệch.- Hướng dẫn chọn model & quản lý session thêm vào
10_AI_Workflow.mdmục 5.
Backlog cho v1.5: các ô staging/seed data và observability trong 08_Deployment_Guide, cùng hard
guardrails trong 01_Tech_Stack_Rules, đang để trống có chủ đích — điền bằng kết quả pilot
thật, đừng thiết kế trong chân không.
Cùng họ với GitHub Spec Kit (constitution + specify/plan/tasks/implement), Amazon Kiro spec mode, Agent OS, và BMAD-Method. Hình dạng vòng lặp không mới và cũng không cố tỏ ra mới. Cái khác là xương sống bảo mật: một baseline có các invariant về concurrency và deploy rút từ sự cố production thật, một báo cáo audit đổ ngược phát hiện vào DO NOT list của chính project, và một checkpoint được harness cưỡng chế thay vì chỉ đề nghị.
Xây và duy trì bởi Thinh Le — freelance full-stack dev chuyên tích hợp thanh toán & cứu app do AI viết. Nhận việc: levietquocthinh@gmail.com