1. Vấn đề: AI viết code nhanh, nhưng dự án Nhật không chỉ có code
Ai từng làm dự án cho khách Nhật đều biết sản phẩm bàn giao không chỉ là source code. Còn có:
要件定義書, 基本設計書, 詳細設計書
テスト仕様書 kèm kết quả và evidence cho UT, IT, ST
不具合管理表, 品質報告書, QA管理表
Và quan trọng nhất là quy trình: tài liệu nào được duyệt thì đóng băng, mọi thay đổi phải có lý do, có phạm vi, có người duyệt
Các công cụ AI coding hiện nay rất giỏi trong việc viết code theo yêu cầu. Nhưng nếu đưa nguyên một con agent vào dự án Nhật thì sẽ gặp các chuyện sau:
Agent "tự do" sẽ... | Hậu quả |
|---|---|
Đoán khi yêu cầu mơ hồ | Thiết kế sai mà không ai biết, đến UAT mới lộ |
Tự chọn công nghệ ngầm định, càng làm càng thêm thư viện | Kiến trúc phức tạp không ai duyệt, đến lúc giao khách mới hỏi "sao lại dùng cái này?" |
Sửa code ngay khi có bug | Tài liệu thiết kế lệch với code, khách hỏi "tại sao" thì không trả lời được |
Viết test theo những gì code đang làm | Test luôn xanh, nhưng sai so với yêu cầu |
Tự sửa luôn tài liệu đã được khách duyệt | Mất baseline, mất vết |
AI SDLC Harness là một repo "khung" giải quyết đúng các vấn đề này. Nó không thay AI bằng một công cụ khác. Nó đặt AI vào trong quy trình V字モデル, có gate phê duyệt của người, có traceability, và có cơ chế chặn khi AI định đi tắt.
Nói ngắn gọn:
Bạn đưa yêu cầu của khách vào. AI phân tích, tự xác định những gì cần quyết định (công nghệ, môi trường, phạm vi test...). Mục nào khách đã nói thì không hỏi, mục nào chưa có thì AI đề xuất phương án đơn giản nhất để bạn xác nhận. Bạn review Basic Design thật kỹ và approve. AI tự làm 詳細設計 → code → UT → IT → ST → LT và sinh tài liệu. Khách UAT trả bug thì AI phân tích lỗi sinh ra ở công đoạn nào, lọt qua công đoạn nào, ảnh hưởng tới đâu, rồi sửa dây chuyền từ tài liệu xuống code và test. Những gì đã được duyệt thì chỉ được sửa khi bạn đồng ý.
2. Ba nguyên tắc thiết kế
Trước khi xem kiến trúc, nên hiểu ba nguyên tắc. Mọi chi tiết phía sau đều xuất phát từ đây.
① Document-driven, không phải code-driven Code được sinh từ thiết kế đã duyệt. Không có chuyện code trước rồi viết tài liệu sau cho khớp.
② Baseline-driven Tài liệu đã approve thì bị đóng băng (lưu hash từng file). Muốn sửa phải có Change Request (CR) được duyệt, và sửa xong phải duyệt lại.
③ Quality gate độc lập với AI AI không tự tuyên bố "test pass" hay "đủ coverage". Những câu đó do test runner và script trả lời. Quyết định phê duyệt thì do người đưa ra.
3. Kiến trúc tổng quan
3.1 Vòng đời
┌──────────── BẠN (SE/PM) ────────────────────┐
│ xác nhận quyết định · review · approve · │
│ duyệt CR · giao │
└───▲──────────▲───────────▲───────────▲───────┘
gate RD│ gate BD│ duyệt CR│ release│
khách ─► input/ ─► [RD] REQ + QA ─► [BD] 基本設計 ─► [DD]─►[CODE]─►[UT]─►[IT]─►[ST]─►[LT] ─► delivery/ ─► khách
+ 決定事項 + 方式設計 └──────── AI tự chạy ────────────┘ │ UAT
▼
◄──── sửa cascade REQ→BD→DD→CODE→TEST ◄── CR ◄── RCA + impact ◄── BUG ◄─────────────┘
Xương sống là V字モデル. Mỗi tầng test kiểm chứng một tầng tài liệu:
要件定義 RD ───────────────────────────── 総合テスト ST
基本設計 BD ─────────────────── 結合テスト IT
詳細設計 DD ───────── 単体テスト UT
製造 CODE
Quy tắc rút ra: expected result của test luôn lấy từ tài liệu cùng tầng, không bao giờ lấy từ hành vi hiện tại của hệ thống.
3.2 Ba lớp
Đây là điểm quan trọng nhất của kiến trúc:
┌──────────────────────────────────────────────────────────────────────┐
│ 👤 NGƯỜI xác nhận quyết định · approve RD/BD · duyệt CR · │ QUYẾT ĐỊNH
│ release · liên lạc khách │
├──────────────────────────────────────────────────────────────────────┤
│ 🤖 AI Claude Code: slash command → subagent theo vai trò │ LÀM VIỆC
├──────────────────────────────────────────────────────────────────────┤
│ ⚙️ MÁY scripts/sdlc.py (kiểm chứng) · guard.py hook (cưỡng chế) │ KIỂM SOÁT
└──────────────────────────────────────────────────────────────────────┘
Lớp AI là phần linh hoạt: đọc tài liệu khách, đề xuất, viết thiết kế, code, test, phân tích bug.
Lớp máy là phần cứng nhắc và tất định. Lớp này không dùng AI, chạy bao nhiêu lần cũng ra cùng kết quả.
Lớp người chỉ xuất hiện ở các điểm quyết định, nhưng không thể bị bỏ qua.
3.3 Thành phần trong repo
.
├── README.md · CLAUDE.md # tổng quan cho người · quy tắc nền cho AI
├── docs/ # playbook + tham chiếu (cho người đọc)
├── .claude/ # ── LỚP AI + CƯỠNG CHẾ ──
│ ├── commands/ # 13 slash command = các bước của quy trình
│ ├── agents/ # 6 subagent theo vai trò
│ ├── hooks/guard.py # chặn AI vi phạm gate
│ └── settings.json # đăng ký hook + quyền
├── harness/ # ── KIẾN THỨC (công ty tự chỉnh) ──
│ ├── guides/ # cách viết BD, test theo V-model, RCA...
│ ├── templates/ # mẫu REQ, QA, BD, DD, test spec, BUG, CR, decisions
│ └── profiles/ # chuẩn công ty, danh sách quyết định bắt buộc,
│ # mẫu dự án dev / test-only
├── scripts/ # ── LỚP MÁY ──
│ ├── sdlc.py # validate, trace, impact, gate, baseline, decisions...
│ └── sdlc_export.py # xuất Excel giao khách
└── projects/<ID>/ # ── DỮ LIỆU từng dự án ──
Sáu vai trò AI:
Agent | Tương đương | Làm gì |
|---|---|---|
| 要件定義担当 | Tài liệu khách → REQ có nguồn gốc + câu hỏi QA + bảng quyết định dự án |
| 基本設計担当 | Viết và sửa 基本設計書, gồm cả 方式設計 |
| 第三者レビュー | Review độc lập, không phải tác giả, chỉ ghi report |
| 製造担当 | Dựng môi trường → 詳細設計 → code → UT |
| テスト担当 | IT/ST/LT, evidence, ghi BUG |
| 不具合分析 | Phân loại, RCA, impact, 横展開, 再発防止 → CR |
3.4 Một slash command chạy thế nào?
Lấy ví dụ /bd-create ABC-SHOP:
Bạn gõ /bd-create ABC-SHOP
│
▼
Claude Code đọc .claude/commands/bd-create.md (kịch bản các bước)
│
├─1─► chạy python scripts/sdlc.py gate ABC-SHOP BD
│ └─ GATE ĐÓNG (RD chưa approve) → dừng, báo bạn lý do
│
├─2─► giao việc cho subagent basic-designer
│ └─ đọc guides + rules dự án + REQ + quyết định đã chốt → viết basic-design/BD-*.md
│ (mỗi lần ghi file đều đi qua hook guard.py)
│
├─3─► giao cho subagent doc-reviewer (context riêng, độc lập)
│ └─ ghi reviews/BD-AI-xxxx.md
│
├─4─► chạy sdlc.py validate + trace (máy xác nhận coverage)
│
└─5─► báo cáo bạn: danh sách BD, chỗ nên review kỹ, lệnh approve để BẠN chạy
Mỗi subagent làm việc trong context riêng, nên session chính của bạn không bị ngập bởi tài liệu. Session chính chỉ nhận lại kết quả.
3.5 Dữ liệu: mọi thứ là file text có ID
Artifact | Ví dụ ID / file | Trỏ về |
|---|---|---|
要件 |
| file gốc của khách ( |
決定事項 |
| file gốc của khách, hoặc xác nhận của bạn |
基本設計 |
| REQ / quyết định đã chốt |
詳細設計 |
| BD |
Code |
| DD (comment |
Test case |
| BD (theo V-model) |
Bug / CR |
|
Nhờ các liên kết này, script dựng được traceability graph:
REQ-002 ◄── BD-ORDER-001 ◄── DD-ORDER-001 ◄── source/order/calc.py
▲ ▲ ▲
ST-ORDER-002 IT-ORDER-002 UT-ORDER-003
Khi BD-ORDER-001 bị phát hiện sai, lệnh sdlc.py impact đi theo graph và liệt kê mọi thứ có thể bị ảnh hưởng: DD, code, test của các tầng, kể cả các tài liệu "anh em" cần 横展開.
Tại sao lưu Markdown/YAML mà không lưu Excel? Vì AI đọc và sửa Excel kém, còn Git không diff được Excel, nên không thể làm baseline hay impact. Harness lưu text và chỉ xuất Excel theo template khách lúc giao hàng.
3.6 Quyết định dự án: AI hỏi đúng thứ cần hỏi, không hơn
Một tình huống rất thường gặp: khách chỉ đưa nghiệp vụ, còn công nghệ thì "bên anh tự chọn". Khi đó ngay từ đầu ta chưa thể biết stack, cách chạy, hay URL môi trường test (thường chỉ là localhost). Nếu bắt người dùng điền những thứ này vào file cấu hình trước thì không hợp lý. Còn nếu để AI tự chọn ngầm thì lại nguy hiểm.
Harness giải quyết bằng một danh sách quyết định bắt buộc (harness/profiles/decision-checklist.yaml), công ty tự bổ sung được. Danh sách gồm ngôn ngữ, framework, DB, cách chạy, trình duyệt hỗ trợ, URL môi trường IT/ST, có 負荷テスト không, khách có duyệt 詳細設計 không, có template Excel riêng không... Ở bước tiếp nhận yêu cầu, AI rà từng mục:
Tình huống | AI làm | Bạn làm |
|---|---|---|
Input của khách đã nói (vd "DBはPostgreSQL") | Ghi lại kèm nguồn | Không bị hỏi |
Input không nói, ta tự quyết được | Đề xuất phương án đơn giản, nhẹ nhất + lý do một câu | Xác nhận hoặc đổi |
Chỉ khách biết (vd URL hệ thống của khách) | Tạo câu hỏi QA | Hỏi khách |
"Đơn giản, nhẹ nhất" ở đây có nghĩa cụ thể: ít thành phần nhất, chạy local bằng một lệnh, công cụ phổ biến. Không thêm server, cache, SPA hay microservice nếu yêu cầu không đòi hỏi. Khi yêu cầu có dấu hiệu cần mạnh hơn (nhiều người dùng đồng thời, có con số hiệu năng), AI nâng cấp đúng mức cần thiết và ghi lý do.
Kết quả được lưu ở requirements/decisions.yaml, và:
Giá trị đã chốt được áp tự động vào cấu hình dự án (stack, URL test, có LT hay không...).
Approve RD bị chặn cho đến khi mọi mục đã chốt, không còn mục "chưa xét", "chờ xác nhận" hay "chờ khách".
Sau approve, bảng quyết định bị đóng băng cùng RD. Muốn đổi công nghệ giữa chừng phải qua CR, giống mọi thay đổi khác.
Ở bước BD, AI viết 方式設計 (
BD-ARCH-001) để chi tiết hoá đúng các quyết định đó. Ở bước code, AI dựng môi trường local và tự điền lệnh chạy test.
3.7 Gate, baseline và CR
draft/review ──👤approve──► approved (BL-BD-001, đóng băng)
│ khách báo bug
▼
CR (must_revise ∋ BD-x) ──👤cr-approve──► AI được phép sửa BD-x
│
phase BD "chờ duyệt lại": gate tầng dưới ĐÓNG
│ 👤approve
▼
approved (BL-BD-002) → AI sửa tiếp DD, code, test
Bạn duyệt hai lần: duyệt kế hoạch sửa (CR) và duyệt nội dung đã sửa. CR chỉ chạm DD/code/test (không chạm tài liệu có gate) thì được tự duyệt, không làm phiền bạn.
Ai đảm bảo AI không lách được? Có ba lớp:
Permission: các lệnh
approve,cr-approve,releasebị cấm với AI.Hook
guard.py: chạy trước mọi lần AI sửa file hoặc chạy lệnh. Nó chặn việc sửa baseline khi không có CR, chặn việc tự ghistatus: approved, chặn sửa tài liệu gốc của khách.sdlc.py verify: so hash với baseline. Mọi thay đổi lọt qua hook đều bị phát hiện và chặn các bước tiếp theo.
3.8 Hai loại dự án, một khung
|
| |
|---|---|---|
Pipeline | RD → BD → DD → CODE → UT → IT → ST | RD → BD → IT → ST |
Source | Của ta | Của khách, read-only |
Quyết định dự án điển hình | Stack, DB, cách chạy, URL localhost | URL staging của khách, có được thao tác có tác dụng phụ không |
Bug code | Sửa qua CR | Chỉ báo cáo |
Dự án test-only có một quy tắc đặc biệt: đúng/sai lấy từ yêu cầu, còn source chỉ dùng để biết cấu trúc (tên màn hình, field, API). Chỗ nào yêu cầu và code lệch nhau, AI ghi lại để bạn quyết, không tự chọn bên nào.
4. Cần gì để bắt đầu?
4.1 "AI" ở đây là gì?
Harness chạy trên Claude Code, công cụ AI agent của Anthropic. Khác với chatbot chỉ trả lời câu hỏi, Claude Code là một agent làm việc trực tiếp trên máy bạn:
Đọc và sửa file trong thư mục dự án
Chạy lệnh terminal (build, test, script)
Chia việc cho subagent, làm theo slash command, và bị kiểm soát bởi hook
Harness dùng đúng ba tính năng này: .claude/commands/ (slash command), .claude/agents/ (subagent) và .claude/hooks/ (hook). Có thể dùng Claude Code ở terminal (CLI) hoặc qua extension VS Code.
Dùng công cụ khác như Copilot hay Cursor được không? Phần
scripts/sdlc.pyvàharness/guides/là file thông thường nên công cụ nào cũng dùng được. Nhưng slash command, subagent và hook bảo vệ gate được viết cho Claude Code. Đổi công cụ thì mất lớp cưỡng chế, nên không khuyến nghị.
4.2 Danh sách chuẩn bị
Để cài đặt (một lần mỗi máy)
Thứ cần có | Ghi chú |
|---|---|
Windows 10/11, macOS hoặc Linux | Ví dụ trong bài là Windows |
Git | Windows: Git for Windows (Claude Code trên Windows cần Git Bash) |
Python ≥ 3.10 + | Cho |
Claude Code | CLI hoặc extension VS Code |
Tài khoản dùng Claude | Một trong các lựa chọn: gói Claude Pro / Max; API key từ Anthropic Console; hoặc qua cloud của công ty (Amazon Bedrock / Google Vertex AI) |
VS Code (khuyến nghị) | Xem Markdown đẹp, dùng extension Claude Code |
Để làm một dự án thật
Thứ cần có | Ghi chú |
|---|---|
Tài liệu yêu cầu của khách | Excel, PDF, mail, biên bản... Ràng buộc kỹ thuật của khách (nếu có, vd "phải dùng Java", "chạy trên Azure") cũng bỏ vào đây |
Quy định của khách (nếu có) | Thuật ngữ, naming, coding rule, template Excel |
Thời gian review của bạn | Đặc biệt ở bước Basic Design. Đây là phần không thể giao cho AI |
Những thứ không cần chuẩn bị trước: stack công nghệ, công cụ test, URL môi trường test. Nếu khách không chỉ định, AI sẽ đề xuất và hỏi bạn ở bước đầu tiên (mục 3.6). Bạn chỉ cần cài thêm runtime tương ứng khi đã chốt (ví dụ JDK, Node.js, Docker), và AI sẽ nói rõ cần cài gì.
⚠️ Bảo mật thông tin khách: tài liệu khách sẽ được gửi tới model AI để xử lý. Hãy kiểm tra hợp đồng/NDA và chính sách công ty trước. Nhiều công ty chọn Bedrock/Vertex hoặc gói doanh nghiệp vì lý do này.
5. Setup từng bước
Ví dụ dưới đây dùng Windows. Lệnh cho macOS/Linux ghi chú bên cạnh.
Bước 1: Cài Git
winget install --id Git.Git -e
(macOS: brew install git; Ubuntu: sudo apt install git)
Kiểm tra: git --version
Bước 2: Cài Python và thư viện
winget install -e --id Python.Python.3.12 --scope user
Đóng và mở lại terminal / VS Code, rồi chạy:
python --version # phải ra Python 3.12.x
python -m pip install pyyaml openpyxl
💡 Lỗi hay gặp trên Windows:
pythonmở Microsoft Store hoặc không in ra gì. Nguyên nhân là Windows có sẵn một lệnhpython"giả" (stub). Có hai cách xử lý: mở lại terminal sau khi cài, hoặc vào Settings → Apps → Advanced app settings → App execution aliases và tắtpython.exe/python3.exe. Nếu bỏ qua lỗi này, hook bảo vệ sẽ không chạy.
Bước 3: Cài Claude Code
Có nhiều cách cài, và cách khuyến nghị có thể thay đổi theo thời gian. Hãy xem trang hướng dẫn chính thức: Advanced setup - Claude Code Docs. Hiện tại thường dùng:
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
Hoặc nếu máy có Node.js 18+: npm install -g @anthropic-ai/claude-code
Kiểm tra: claude --version
Extension VS Code (khuyến nghị): vào Extensions, tìm Claude Code (publisher Anthropic) và cài đặt.
Bước 4: Đăng nhập
Chạy claude trong terminal (hoặc mở panel Claude Code trong VS Code). Lần đầu sẽ có hướng dẫn đăng nhập:
Gói Claude Pro/Max: đăng nhập bằng tài khoản claude.ai.
API key (Anthropic Console): đăng nhập bằng tài khoản Console, chi phí tính theo lượng dùng.
Bedrock / Vertex của công ty: đặt biến môi trường theo hướng dẫn của bộ phận IT (ví dụ với Bedrock:
CLAUDE_CODE_USE_BEDROCK=1cùng thông tin AWS). Chi tiết ở tài liệu chính thức.
Đăng nhập xong, gõ thử một câu "xin chào" để chắc chắn mọi thứ hoạt động.
Bước 5: Lấy repo harness về
git clone <repo-url> modern_sdlc
cd modern_sdlc
(Nếu nhận repo dạng file zip thì giải nén rồi chạy git init && git add -A && git commit -m "init". Git là bắt buộc về mặt thực tế, vì baseline và approval cần được lưu vết.)
Bước 6: Kiểm tra môi trường
python scripts/sdlc.py doctor
Kết quả mong đợi:
Python 3.12.x
[OK] yaml
[OK] openpyxl
[OK] .claude/settings.json
[OK] .claude/hooks/guard.py
[OK] git repository
Dự án: SAMPLE-SHOP
Bước 7: Kiểm tra hook bảo vệ có hoạt động không
Đây là bước nhiều người bỏ qua, nhưng lại là bước quan trọng nhất. Mở Claude Code tại đúng thư mục gốc của repo (trong VS Code: File → Open Folder → modern_sdlc), rồi gõ:
chạy giúp tôi: python scripts/sdlc.py approve SAMPLE-SHOP BD --by test
✅ Đúng: lệnh bị từ chối hoặc bị chặn (thông báo permission denied hoặc [SDLC guard] ... chỉ NGƯỜI phụ trách được chạy). ❌ Sai: lệnh chạy được. Khi đó hãy xem lại Bước 2 (vấn đề PATH của python) và FAQ.
Thử thêm một câu:
sửa giúp tôi projects/SAMPLE-SHOP/basic-design/BD-ORDER-001.md, đổi 10% thành 8%
✅ Đúng: bị chặn, vì tài liệu này thuộc baseline đã duyệt và chưa có CR.
Xong bước này là bạn đã sẵn sàng.
6. Chạy thử 20 phút với dự án mẫu
Repo có sẵn dự án SAMPLE-SHOP. Đây là một module tính tiền đơn hàng đã giao v1.0 và cố ý chứa một lỗi ở Basic Design:
Yêu cầu khách ghi: coupon được trừ từ giá đã có thuế.
BD lại thiết kế: trừ coupon trước rồi mới tính thuế.
DD, code, UT, IT đều làm đúng theo BD sai, nên đều pass. ST thì không kiểm tra tổng tiền.
Khách UAT và phát hiện ra lỗi.
Đây là tình huống kinh điển: code không sai, thiết kế sai. Các bước tập:
/project-status SAMPLE-SHOP
/bug-intake SAMPLE-SHOP projects/SAMPLE-SHOP/input/2026-11-20_UAT-01/UAT指摘一覧.md
/bug-analyze SAMPLE-SHOP BUG-001
Xem AI phân tích và so với đáp án:
Phân loại : defect (REQ-002 ghi rõ 税込金額から値引)
混入工程 : BD (BD-ORDER-001 §3.1)
流出工程 : BD-review, ST (ST không kiểm tra số tiền)
CR-001 : CẦN BẠN DUYỆT (chạm baseline BD)
Tiếp theo bạn chạy trong terminal:
python scripts/sdlc.py cr-approve SAMPLE-SHOP CR-001 --by "Tên bạn"
/bug-fix SAMPLE-SHOP CR-001 ← AI sửa BD rồi DỪNG chờ bạn
python scripts/sdlc.py approve SAMPLE-SHOP BD --by "Tên bạn" --comment "CR-001"
/bug-fix SAMPLE-SHOP CR-001 ← AI sửa DD, code, UT, IT, bổ sung ST, chạy regression, đóng CR
/deliver-prepare SAMPLE-SHOP 1.1
python scripts/sdlc.py release SAMPLE-SHOP 1.1 --by "Tên bạn"
Mở projects/SAMPLE-SHOP/delivery/v1.1/ để xem bộ Excel: 基本設計書 có 改訂履歴, テスト仕様書兼結果, 不具合管理表, và 品質報告書 có bảng 混入工程 × 流出工程.
Hướng dẫn chi tiết: docs/playbook/90-tutorial-sample.md
SAMPLE-SHOP được dựng từ trước khi có tính năng quyết định dự án, nên công nghệ được ghi thẳng trong
project.yamlvà bước 3.6 được tắt riêng cho nó. Muốn thử bước 3.6, hãy tạo một dự án mới như mục 7.
7. Bắt đầu một dự án thật
7.1 Tạo dự án
python scripts/sdlc.py new ABC-SHOP --type dev --name "ABC 通販" # hoặc --type test-only
Gần như không cần chỉnh gì trong projects/ABC-SHOP/project.yaml: công nghệ, môi trường test, có LT không... đều sẽ được chốt qua bảng quyết định ở bước 7.3. Chỉ điền tay những gì bạn biết chắc và muốn cố định.
Phần bạn nên chuẩn bị là quy định của khách: đặt vào projects/ABC-SHOP/rules/ dưới dạng file Markdown (thuật ngữ, naming, coding rule, văn phong tài liệu...). Mọi agent đọc thư mục này trước tiên.
7.2 Đưa yêu cầu vào
Mỗi đợt nhận tài liệu tạo một thư mục mới, giữ nguyên file gốc:
projects/ABC-SHOP/input/2026-11-07_initial/要件一覧.xlsx
projects/ABC-SHOP/input/2026-11-07_initial/RFP.pdf ← có ràng buộc kỹ thuật thì để chung ở đây
Khách chỉ nói qua họp hoặc chat? Gõ thẳng: /req-intake ABC-SHOP Khách yêu cầu dùng Java 21, chạy trên Azure. Nội dung được lưu nguyên văn vào input/ trước khi phân tích, để sau này có bằng chứng.
7.3 Chốt yêu cầu và quyết định dự án
/req-intake ABC-SHOP
AI tách yêu cầu thành REQ, lập câu hỏi QA cho khách, và trình bày bảng quyết định:
✅ Theo input: stack.database = postgresql (RFP.pdf trang 3) ← khách đã nói thì không hỏi
❓ Đề xuất: stack.language = python (web nhỏ, cấu hình ít nhất)
stack.framework = FastAPI + Jinja (SSR, không cần SPA)
environments.st.url = http://localhost:8000
phases.LT = false (không có yêu cầu hiệu năng)
⏳ Chờ khách: (không có)
Bạn đồng ý tất cả đề xuất, hay muốn đổi mục nào?
Bạn trả lời bằng lời bình thường:
/decisions ABC-SHOP ok hết, riêng framework dùng Django
AI chỉ ghi nhận những gì bạn nói rõ. Câu trả lời mơ hồ thì AI hỏi lại, không tự coi là đồng ý. Xem lại bảng bất cứ lúc nào bằng /decisions ABC-SHOP.
Khi đã chốt hết, gửi QA cho khách và review REQ xong, bạn chạy:
python scripts/sdlc.py approve ABC-SHOP RD --by "Tên bạn"
Lệnh này in lại toàn bộ bảng quyết định để bạn xem lần cuối, rồi mới đóng băng cùng RD.
7.4 Các bước tiếp theo
# | Bạn gõ | Bạn làm |
|---|---|---|
1 |
| Xác nhận đề xuất, gửi QA cho khách, review REQ → |
2 |
| Review kỹ (gồm cả 方式設計 |
3 |
| AI dựng môi trường local, viết DD → code → UT. Bạn trả lời khi AI dừng lại hỏi |
4 |
| Xem kết quả |
5 |
|
|
6 |
| Duyệt CR, approve lại tài liệu bị sửa |
Không nhớ bước tiếp theo là gì? Gõ /project-status ABC-SHOP. Phần cuối kết quả luôn có dòng "Gợi ý bước tiếp theo".
7.5 Bạn thực sự phải làm gì?
Nhiều người lo "giao cho AI thì mình làm gì?". Câu trả lời: bạn chuyển từ người viết sang người quyết định. Bảy thời điểm bạn bắt buộc phải có mặt:
Xác nhận quyết định dự án mà AI đề xuất (công nghệ, môi trường, phạm vi test)
Approve RD: chốt phạm vi và đóng băng các quyết định
Approve BD: quan trọng nhất, vì mọi thứ sau đó AI sinh ra từ đây
Gửi và nhận QA với khách
Duyệt CR chạm vào tài liệu đã cam kết, hoặc là 仕様変更 (ảnh hưởng chi phí)
Approve lại tài liệu đã sửa
Release bản giao
Ngoài ra là những lúc AI chủ động dừng lại hỏi: khi thiết kế thiếu thông tin, khi cần một công nghệ khác với quyết định đã chốt, khi test fail mãi, hoặc khi môi trường không rõ. Đó là hành vi được thiết kế có chủ đích. AI không bịa để chạy cho xong.
8. Mẹo cho người mới
Đưa ràng buộc của khách vào
input/ngay từ đầu. Thứ gì khách đã nói, AI sẽ không hỏi lại. Thứ gì không có, AI sẽ đề xuất, và bạn tiết kiệm được một vòng trao đổi.Đừng xác nhận đề xuất cho có. Bảng quyết định bị đóng băng sau approve RD, nên muốn đổi DB giữa chừng sẽ phải qua CR. Nếu chưa chắc, trả lời "để hỏi khách" để AI chuyển mục đó thành QA.
Review BD bằng cách tự tính ví dụ số. Lỗi trong SAMPLE-SHOP chỉ lộ ra khi bạn tự tính "1,000 yên, coupon 100 yên thì phải ra bao nhiêu".
Commit Git sau mỗi lần approve hoặc release. Git history là bằng chứng cuối cùng của quy trình.
Đọc file review của AI trước khi tự review.
doc-reviewerthường bắt được lỗi thiếu, lỗi không nhất quán, giúp bạn tập trung vào nghiệp vụ.Dự án lớn thì chia theo AREA:
/construct ABC-SHOP ORDER,/doc-review ABC-SHOP BD BD-ORDER-*.Biến 再発防止策 thành hành động thật: thêm mục vào checklist trong
harness/guides/02-basic-design.md. Từ lần sau, cả agent viết lẫn agent review đều dùng checklist đó. Tương tự, thấy dự án nào cũng phải hỏi một thứ thì thêm nó vàoharness/profiles/decision-checklist.yaml.Không sửa tay file Excel trong
delivery/. Excel được sinh ra từ Markdown, lần xuất sau sẽ ghi đè.
9. Giới hạn hiện tại
Nói rõ để bạn kỳ vọng đúng:
Chất lượng phụ thuộc vào review của bạn. Harness đảm bảo quy trình đúng, còn nội dung BD đúng hay sai vẫn là trách nhiệm của người review.
Xác nhận quyết định qua chat. Trạng thái "đã xác nhận" do AI ghi lại theo câu trả lời của bạn. Chốt chặn cuối cùng là lệnh
approve RDdo chính bạn chạy, và lệnh này in lại toàn bộ bảng quyết định trước khi đóng băng.Template Excel của khách: hỗ trợ dạng bảng (要件一覧, 不具合管理表, 試験仕様書). Thiết kế dạng 方眼紙 tự do của khách cần viết thêm phần render.
Hook không phải ranh giới bảo mật tuyệt đối. Nó chặn AI đi tắt, và
verifyphát hiện những gì lọt qua. Nhưng đây không phải hệ thống phân quyền.LT và test trên hệ thống khách cần cho phép bằng văn bản. Harness mặc định không chạy LT.
Chi phí: chạy agent tốn token. Một dự án nhỏ chạy hết vòng tốn chi phí đáng kể so với hỏi đáp thông thường, nên hãy theo dõi bằng lệnh
/usagetrong Claude Code.
10. Tóm lại
AI SDLC Harness không cố biến AI thành "lập trình viên tự động". Nó biến AI thành một team tuân thủ quy trình dự án Nhật:
Biết hỏi đúng thứ cần hỏi ngay từ đầu, và chủ động đề xuất phương án đơn giản khi khách không chỉ định.
Viết tài liệu trước khi code, test theo thiết kế.
Khi có bug thì tìm đúng công đoạn gây lỗi.
Và quan trọng nhất là không bao giờ vượt qua quyết định của bạn.
Bắt đầu từ đâu:
Setup theo mục 5 (khoảng 30 phút)
Chạy thử SAMPLE-SHOP theo mục 6 (khoảng 20 phút)
Đọc README.md → bức tranh lớn → playbook
Thử với một chức năng nhỏ của dự án thật trước khi áp dụng cho cả dự án
Chúc bạn có những 基本設計書 không còn bị khách trả về vì 計算順序 😄
