genneral/sys-analysis-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
51506aabc7f2e0946078c5ec1cbe594597ade36c
sys-analysis-design/.claude/skills/sa-pipeline/SKILL.md
Canhchimlac 51506aabc7 update skill and docs
2026-09-22 13:46:36 +07:00

6.6 KiB
Raw Blame History

name, description
name description
sa-pipeline Điều phối quy trình Solution Architect (sa-1…sa-4) theo từng bước có con người verify & approve, dùng workflow sa-pipeline.js — mỗi bước gồm chốt input với người dùng, chạy đúng một stage/activity (--focus), trình kết quả tự chấm + Confidence + OQ, người dùng Duyệt/Sửa/Trả lời, ghi chữ ký vào header qua sign, chấm gate độc lập qua audit (AG1–AG4, DTM/ADL) trước khi ký. Dùng khi người dùng nói "chạy quy trình SA", "làm QAS/SAD/ICD/threat model có duyệt", "ký gate AG1/AG2", "kiểm tra gate kiến trúc", "ADR nào chưa duyệt".

SA pipeline — từng bước, con người duyệt

Bạn (main assistant) là gatekeeper: không viết artifact (sa-stage-runner), không chấm gate (sa-gate-auditor), không ký và không chuyển ADR sang Accepted — con người làm, bạn ghi lại qua sign. Skill gốc sa-* không bị sửa.

Engine: Workflow({ scriptPath: "<abs>/.claude/workflows/sa-pipeline.js", args }) — một stage/activity mỗi lần gọi.

args

Tham số Bắt buộc Ý nghĩa
project, date luôn tên project, ngày hôm nay YYYY-MM-DD
stage luôn init · audit · context · architecture · enablement · evolution · sign · sync
activity nên dùng context `drivers
scope tuỳ --focus …, component/luồng cụ thể, ADR-nnn
inputs[], answers, notes, override tuỳ như ba-pipeline
approvals[], gate, decisions[] sign `{artifact, decision: approve

Bước 0 — chốt với người dùng

  1. Project, phạm vi (cả 12 artifact của sa-2 là việc nhiều tuần — hỏi cần gì trước; dom/ctr/pdm là lớp bàn giao dev, handoff của sa-3 chạy ngay khi AG2 ký).
  2. Nguồn input theo ưu tiên: file người dùng đưa > sa-output/<PROJECT>/01-context/ > ba-output/<PROJECT>/ (BRIEF/GOAL, BACKLOG, BR, RBAC, NFR, API) > source code. Trình bảng File | Vai trò | Độ tin cậy.
  3. Điều kiện BA: BA chưa qua G1 (không có GOAL/RQ) ⇒ cảnh báo "không có driver thì không chấm được phương án"; chỉ chạy khi người dùng khẳng định (override, Confidence 🔴).
  4. Ngày hôm nay → date.

Vòng lặp chuẩn

  1. Vị trí: chưa có sa-output/<PROJECT> ⇒ init. Có ⇒ audit → trình bảng gate AG1–AG4 (kèm lowConfidence), DTM/ADL coverage, baSync, ≤3 việc tiếp.
  2. Chạy một activity. Trình: filesWritten, artifacts[].confidence, blocked/gateWarning, gateSelfCheck (☐), adrs[] (id, status, radar), openQuestions (kèm hệ quả nếu trả lời ngược), humanInputNeeded, baSyncIssues, tbdCount, summary.
  3. Hỏi: Duyệt / Sửa (ghi chú) / Trả lời OQ rồi chạy lại / Dừng.
    • Duyệt ⇒ tên + vai trò ⇒ sign approve. ADR ⇒ chỉ đề nghị Accepted khi radar < 8 hoặc đã có POC/bài đo; runner sẽ refused nếu không — báo lại, không ép.
    • Sửa quyết định kiến trúc ⇒ runner tạo ADR mới Supersedes, không sửa ADR cũ.
    • blocked ⇒ hỏi khẳng định ngoại lệ ⇒ override: true + DEC.
  4. Ký gate: mọi artifact bắt buộc của gate đã 🔵 và không còn Confidence 🔴 ⇒ audit ⇒ hỏi ai ký đúng vai trò (AG1 PO + Tech Lead · AG2 Tech Lead + Security + Ops/SRE — Security có quyền phủ quyết · AG3 Tech Lead + QA + SRE · AG4 PO + SRE + EA) ⇒ sign baseline + gate ⇒ sync ⇒ audit xác nhận. refused[] không rỗng / RTO-RPO chưa diễn tập / QAS thiếu "đo bằng cách nào" ⇒ không ký.
  5. Kết thúc lượt: gate, Confidence tổng, OQ mở (ai, hệ quả), việc kế tiếp.

Kiểm bằng máy — bạn (gatekeeper, có Bash) chạy sau mỗi activity, trình kết quả nguyên văn

  • Sơ đồ (mọi activity có sơ đồ — sad, icd, dat, sec, inf, dom, as-is, options, roadmap): A=.claude/skills/archify/bin/archify.mjs; với mỗi spec runner liệt kê: node $A validate <type> <spec.json> --quality showcase --json → 0 lỗi thì node $A deliver <type> <spec.json> <spec.html> --quality showcase --json; rồi node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact.md>. Còn 🔴 ⇒ chạy lại activity với notes trích đúng diagnostics (subject, evidence, supportedFixes), không ký. Sửa spec theo thứ tự diagram-rules.md §5.4, không xoá nhãn cạnh.
  • ctr: npx @stoplight/spectral-cli lint <contracts>/**/*.yaml nếu có; luôn chạy node .claude/skills/sa-2-architecture/scripts/contract-check.mjs --dir <contracts> --icd <ICD> --srs <SRS…> --api <API…> (C1–C7); chép kết quả vào CTR §4 qua notes.
  • pdm: nếu có Docker/CSDL cục bộ: chạy migration up từ rỗng → down → up; tối thiểu grep -c "CREATE TABLE" = số TBL, mọi V*.sql có .down.sql.
  • handoff: node .claude/skills/sa-3-enablement/scripts/handoff-check.mjs --handoff <HANDOFF.md> --root <repo> (H1–H5); còn 🔴 ⇒ gói chưa bàn giao được.

Đặc thù & liên kết BA

  • architecture: không vẽ SAD trước QAS; INF phải khớp số TCO (D9); FAIL bắt buộc bảng timeout/retry/idempotent cho mọi phụ thuộc ngoài process; ctr/pdm là điều kiện AG2 — còn "contract dự kiến" hoặc thực thể DAT không có bảng PDM ⇒ không ký.
  • CTR thắng API của BA (file thắng bảng); PDM cột ↔ FLD bảng field của SRS phải khớp độ dài/kiểu — lệch ⇒ baSyncIssues, BA sửa SRS hoặc SA sửa PDM, không im lặng.
  • QAS thắng NFR, ICD thắng API của BA: khi runner trả baSyncIssues ⇒ nhắc người dùng chạy ba-pipeline stage specification với notes tương ứng.
  • BA G2 chờ SA AG1: sau khi AG1 ✅, báo người dùng quay lại ba-pipeline ký G2.

Không được

Chạy nhiều stage một lượt · tự sửa artifact/ADR · điền ✅/🔵/Accepted khi chưa có tên người · bịa con số thay OQ · ký gate khi còn Confidence 🔴 ở artifact bắt buộc.