spec-lite

Bộ skills spec-driven development cho Claude Code — phỏng vấn có cấu trúc để xây dựng PRD, kiến trúc hệ thống, và integration specs. Domain knowledge và component/feature artifacts mọc dần qua cascade — từ pha mô tả (/spec-frd), pha thiết kế (/spec-sad), lẫn integration (/spec-new).

Lưu ý: Hiện tại chỉ hoạt động với Claude Code (thư mục .claude/).

Cài đặt

npx spec-lite@latest install

Lệnh này copy skills/ và templates/ vào thư mục .claude/ của project.

Greenfield — dự án mới chưa có code

Chạy một lần để bootstrap main artifacts, sau đó vào Integration Pipeline.

/spec-prd → /spec-sad
                │
                ▼
        /spec-frd [F-XXX]   (tùy chọn — BA author frd.md trước, spec-first)
                │
                ▼
        Integration Pipeline

/spec-prd

Tạo hoặc cập nhật .specs/main/prd.md thông qua interview có cấu trúc. Đồng thời scaffold .specs/main/domain.md skeleton. Nhận tùy chọn một nguồn baseline (path/@file/paste proposal/BRD) để pre-fill interview.

Sections: Problem Statement · Target Users · Scope · Features · Components · Non-Functional Requirements · Business Constraints

/spec-sad

Tạo hoặc cập nhật .specs/main/sad.md. Yêu cầu prd.md và domain.md đã tồn tại.

Sections: Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails · ADR Log

/spec-frd [F-XXX] (tùy chọn)

BA author .specs/main/feature/{F-XXX}-*/frd.md trực tiếp qua interview, trước khi DEV bắt đầu integration — spec-first ở feature level. Cặp greenfield đối xứng với /spec-brownfield-feature. Nhận F-XXX (hoặc chọn từ Feature Index) + tùy chọn nguồn baseline (path/@file/paste).

Hai gate input (làm chặt): (1) Single-feature — nguồn liên quan đúng 1 feature; xác định >1 → dừng, mô tả rõ lý do tách, redirect /spec-prd. (2) Create-only — frd.md đã tồn tại → dừng, redirect /spec-new (thay đổi feature đã spec đi qua integration để delta cascade + tech/test). Feature mới đơn lẻ chưa có trong Index → skill offer register một row vào prd Features rồi author.

Phạm vi hẹp: chủ yếu frd.md (+ tối đa một feature row vào prd nếu register). Reference component frd phụ thuộc (Components Used); component cần-nhưng-chưa-có ghi như candidate để /spec-sad/architect chốt boundary. KHÔNG tạo crd.md/cdd.md — component artifacts sinh ở integration time qua /spec-new cascade. Change History operation = manual. Nếu bỏ qua bước này, /spec-new vẫn tự tạo frd làm fallback.

Sections: Overview · User Flows · Feature Acceptance Criteria (end-to-end) · Non-Functional Requirements · Data & Migration (nếu có) · User Stories · Verification Rules · Scope · Dependencies

Brownfield — project đã có code

Scan codebase để extract main artifacts, sau đó vào Integration Pipeline. Thứ tự bắt buộc: init → component → feature.

/spec-brownfield-init
         │
         ▼
/spec-brownfield-component
         │
         ▼
/spec-brownfield-feature
         │
         ▼
/spec-test-design [F-XXX]   (tùy chọn — bootstrap test-design.md cho từng feature)
         │
         ▼
(fill in NEEDS_CLARIFY khi có thêm context)
         │
         ▼
Integration Pipeline

/spec-brownfield-init [path]

Scan codebase, tạo prd.md (không có Component/Feature Index), domain.md (Glossary only), sad.md. Interview 5 phần: Problem Statement · Target Users · Scope · NFRs · Business Constraints. Component Index và Feature Index để placeholder — sẽ được điền bởi hai skill tiếp theo.

/spec-brownfield-component [path]

Scan module dirs, tạo crd.md + cdd.md cho từng component, điền Component Index vào prd.md, cascade Shared Entities vào domain.md. Yêu cầu init đã chạy.

/spec-brownfield-feature [path]

Scan routes/use cases/tests, tạo frd.md + fdd.md cho từng feature, điền Feature Index vào prd.md. Yêu cầu component đã chạy (fdd.md cần C-XXX IDs từ Component Index).

/spec-test-design [F-XXX]

Bootstrap feature/{F-XXX}/test-design.md (Test Design Document) trực tiếp từ frd.md — mechanical derive Test Scenarios + Test Cases (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative, mỗi FAC → E2E TC, mỗi NFR → Non-functional TC, mỗi DM → Data & Migration TC). Không interview, không cần integration. Dùng sau /spec-brownfield-feature để có test coverage tracking từ ngày 1, hoặc khi test-design drift khỏi frd cần regenerate fresh.

NEEDS_CLARIFY: Các mục chưa rõ khi scan được đánh dấu [NEEDS_CLARIFY] — không block workflow, fill in dần khi có thêm context.

Integration Pipeline — dùng cho cả greenfield và brownfield

Mỗi requirement mới đều đi qua pipeline này.

/spec-new [requirement]
   (human review + apply cascade proposals + approve)
          │
          ├─────────────────┐
          ▼                 ▼
   /spec-tech         /spec-test   (song song — cả hai chỉ phụ thuộc spec.md)
   (DEV approve)      (QC approve, cascade lên feature/*/test-design.md)
          │                 │
          └────────┬────────┘
                  ▼
               /plan
          (human approve)
                  │
           /build ◄──────────────┐
                  │               │
           /review-integration    │ (nếu Critical/Important → sửa và build lại)
                  │               │
             [approve] ───────────┘ (nếu chỉ Suggestion hoặc không có finding)

/spec-new [requirement]

Tạo .specs/integrations/{slug}/spec.md cho một integration mới.

• Có argument → dùng trực tiếp làm raw requirement
• Không có argument → hiển thị danh sách features TODO từ prd.md để chọn

/spec-tech [number]

Tạo .specs/integrations/{slug}/tech.md sau khi spec.md được approve. Chạy bởi DEV.

• Có argument → chọn integration theo số thứ tự luôn
• Không có argument → hiển thị danh sách tất cả integrations

/spec-test [number]

Tạo .specs/integrations/{slug}/test.md sau khi spec.md được approve. Chạy bởi QC, song song / độc lập với /spec-tech — cả hai chỉ phụ thuộc spec.md. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → E2E TC, NFR → Non-functional TC, DM → Data & Migration TC), priority deterministic. Cascade lên feature/{F-XXX}/test-design.md qua Changes blocks. Gate: integration phải có features: non-empty (component-thuần không áp dụng).

/spec-test-exec [F-XXX]

Sinh bundle test-executions (bản thực thi) cho một feature từ test-design.md. Layer EXECUTION — test-design.md là source of truth, skill đọc-xuống một chiều (không cascade, không sửa test-design), inherit TC-F* nguyên văn. Output: cycle bundle .specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/ (plane 2 tầng, ephemeral per chu kỳ test). Sinh tới 6 doc theo scope×harness — func-manual/func-auto, e2e-manual/e2e-auto, nfr, dm (nfr/dm bỏ nếu rỗng); team chọn harness theo kỹ năng. KHÔNG versioned. Feature-level, chạy sau khi có test-design (không thuộc per-integration pipeline).

/plan

Tạo plan.md và todo.md từ spec.md + tech.md.

/build

Implement từng task trong plan.md/todo.md theo TDD incremental.

/review-integration

Review implementation sau /build theo năm trục: correctness, readability, architecture, security, performance. Đối chiếu trực tiếp với spec.md và tech.md.

• Critical/Important → dừng, sửa, re-review
• Chỉ Suggestion hoặc không có finding → approve, tiếp tục /build task tiếp theo

/review-everything

Review toàn bộ codebase ở project level đối chiếu với prd.md / domain.md / sad.md. Spawn 5 subagent song song theo năm axis của code-review-and-quality.

Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Critical+Required / +Optional / All / Bỏ qua). Nếu chọn fix → gom selected findings thành raw requirement và auto-invoke /spec-new để tạo integration. Findings full snapshot được lưu vào .specs/integrations/{NNN}-{slug}/review-findings.md.

Maintenance — migrate artifacts khi template thay đổi

Skill ad-hoc dùng khi template đã được update và artifacts hiện có cần migrate. Không phải pipeline — chạy khi cần.

Mỗi main template mang template_version (số nguyên) trong frontmatter; main artifact copy nó lúc được tạo. Khi template đổi structure, main artifact cũ thành "lỗi thời" — hai skill dưới phát hiện và migrate. Chỉ áp dụng cho main artifacts (integration artifacts ephemeral nên không versioned). Quy ước đầy đủ: conventions.md §7.

/artifact-audit [type]

Phát hiện main artifact lỗi thời. So template_version của artifact với version đọc thẳng từ template. Versioned: == → up-to-date; != → out-dated (vX → vY) → migrate. Legacy thiếu version → presence-check (đủ required ## headings + không còn section đã migrations.remove): conform → stamp version; lệch → out-dated. Chỉ phát hiện + stamp, KHÔNG migrate. Scope theo arg (1 main type / list) hoặc mọi main type.

/artifact-migrate [path]

Migrate main artifact lỗi thời lên structure mới (mọi main type). Tự chạy /artifact-audit (classify-only) để phát hiện, rồi áp delta từ block migrations của template: add required section thiếu (skeleton từ template; nội dung mới → interview hoặc NEEDS_CLARIFY, không bịa), remove section đã migrations.remove (có confirm; giữ content tác giả khác), update section đổi format (giữ section + ngữ nghĩa, vd ASCII → Mermaid; show cũ + đề xuất mới, không bịa). Rename = remove+add → hỏi carry-over. Single-artifact, không cascade. Pre-flight git clean — rollback dùng git, không .bak. No-op nếu đã up-to-date.

Files được tạo ra

| Command | Output | |---------|--------| | /spec-prd | .specs/main/prd.md, .specs/main/domain.md (skeleton) | | /spec-sad | .specs/main/sad.md | | /spec-frd | .specs/main/feature/{F-XXX}-*/frd.md (+ register feature row vào prd.md nếu feature mới) | | /spec-brownfield-init | .specs/main/prd.md, .specs/main/domain.md, .specs/main/sad.md | | /spec-brownfield-component | .specs/main/component/{C-XXX}-*/crd.md + cdd.md | | /spec-brownfield-feature | .specs/main/feature/{F-XXX}-*/frd.md + fdd.md | | /spec-test-design | .specs/main/feature/{F-XXX}-*/test-design.md | | /artifact-audit | (báo cáo out-dated; + stamp template_version cho main artifact legacy conform) | | /artifact-migrate | (modify in-place main artifact lỗi thời lên structure mới + set template_version) | | /spec-new | .specs/integrations/{slug}/spec.md | | /spec-tech | .specs/integrations/{slug}/tech.md | | /spec-test | .specs/integrations/{slug}/test.md, cascade: feature/{F-XXX}/test-design.md | | /spec-test-exec | .specs/test-executions/{F-XXX}-*/{NNN}-*/test-exec-*.md (derived từ test-design) | | /plan | .specs/integrations/{slug}/plan.md, todo.md | | /build | (implements tasks từ plan.md/todo.md) | | /review-integration | (findings report — không tạo file) | | /review-everything | .specs/integrations/{NNN}-{slug}/review-findings.md (qua /spec-new) |

Feature artifacts (frd.md) ở greenfield có thể author trước bằng /spec-frd, hoặc mọc dần qua cascade proposals từ integrations (/spec-new fallback). Component artifacts (crd.md/cdd.md) ở greenfield chỉ mọc qua cascade — không có skill author trực tiếp (/spec-frd chỉ reference component, không tạo crd/cdd).

Ngoài main/ và integrations/, còn plane thứ ba .specs/test-executions/ (execution layer): bundle thực thi derived từ test-design.md qua /spec-test-exec, đánh số per-feature 2 tầng ({F-XXX}-{slug}/{NNN}-{cycle-slug}/), ephemeral per chu kỳ test, không versioned. Xem conventions.md §8.