Spec-driven Development with Claude Code

Turn an idea into production-ready software — one command at a time.
A complete, opinionated SDLC kit for Claude Code: specialized agents, slash-command workflows, mandatory engineering rules, and quality gates that keep AI honest from /spec to /deploy.

🌏 Tiếng Việt → README_VN.md

I've been there myself — let AI code for me, super fast, super satisfying, a real wow moment — then two weeks later the bugs surface, fixing one thing breaks another, and I can't answer "has this been tested? is it secure?" Vibe-coding wins on speed, but it trades away the one thing real engineering can't afford to lose: control.

I built this kit to take back that control — without losing the speed.

What is this?

This is not an application. It is a .claude/ configuration kit you drop into any project so that Claude Code stops being a clever autocomplete and starts behaving like a disciplined engineering team.

Instead of asking the AI to "build me an app" and hoping for the best, you drive a 12-step pipeline where each step:

• is owned by a specialized agent (Business Analyst, Architect, Backend Dev, Security Auditor, …),
• produces a concrete artifact (specs/, architecture/, plans/, src/, tests/, reports/…),
• and must pass a quality gate before the next step begins.

The result is the same discipline you'd expect from a real software team — requirements before code, tests before implementation, security before deploy — but executed by AI agents you orchestrate with a single slash command.

In short, the kit is a harness — a layer of explicit rules and verification loops that forces every SDLC command to follow the same standards and stay reproducible, instead of the model improvising differently on each run.

💡 Inspired by the agentic-workflow philosophy of BMAD-METHOD, adapted into a strict, gate-driven SDLC for C# / ASP.NET Core 8 (with first-class Node.js / Next.js and PHP / Laravel overrides).

Why use it?

The 12-step pipeline

PHASE 1 — REQUIREMENTS & DESIGN        PHASE 2 — DEVELOPMENT & QUALITY      PHASE 3 — SECURITY & DEPLOY
┌─────────────────────────────┐        ┌──────────────────────────┐        ┌───────────────────────────────────┐
│ /spec  → Business Analyst   │        │ /build → Frontend/Backend│        │ /scan   → Security Auditor        │
│ /arch  → Systems Architect  │   ──▶  │ /test  → Test Engineer   │   ──▶  │ /infra  → Backend Developer       │
│ /plan  → Project Manager    │        │ /review→ Code Reviewer   │        │ /docs   → Technical Writer        │
│ /secure→ Security Auditor   │        │                          │        │ /verify → Test Engineer           │
└─────────────────────────────┘        └──────────────────────────┘        │ /deploy → Release Manager         │
        specs/ architecture/                  src/ tests/ reports/          └───────────────────────────────────┘
        plans/ security/                                                         security/ docker/ docs/ reports/

Each arrow is a quality gate. You can't promote a build that fails its tests, and you shouldn't /deploy an artifact /verify never blessed. (Optional steps are marked in the docs; security gates are blocking.)

Quick start (the simplest path)

1. Get the kit into your project

# Option A — start a brand-new project from this kit
git clone https://github.com/dinhnguyenngoc/spec-driven-claude-code.git my-new-project
cd my-new-project
rm -rf .git && git init        # make it your own

# Option B — copy the kit into an existing project
cp -r path/to/spec-driven-claude-code/.claude  my-existing-project/.claude

The only thing that matters is that the .claude/ folder sits at your project root. Open the folder in Claude Code (CLI, VS Code, or JetBrains) and you're ready.

2. Tell it what you want to build

/spec I want to build LinkVault — a personal bookmark manager where a user
can register, save bookmarks (URL, title, tags), search them, and mark favorites.

The Business Analyst agent will ask clarifying questions, then write specs/SPEC.md with User Stories and Acceptance Criteria. Review and approve it before moving on.

3. Walk the pipeline

Run the commands in order, reviewing each artifact as you go:

/arch      → system design, ADRs, API contracts   → architecture/
/plan      → tasks broken into vertical slices     → plans/todo.md
/secure    → STRIDE threat model (optional)        → security/
/build     → TDD implementation                    → src/ + web/ + tests/
/test      → real-dependency QA gate               → tests/
/review    → five-axis code review                 → reports/
/scan      → vulnerability scan                     → security/
/infra     → Docker setup                          → docker/ + docker-compose.yml
/docs      → documentation                         → docs/
/verify    → exercise the real artifact            → reports/VERIFY_REPORT.md
/deploy    → stage the verified artifact → STAGED (production promote = manual, RUNBOOK §8)

That's the whole loop. For a quick prototype you can run just /spec → /plan → /build → /test. For production, walk the full 12 steps.

4. Keep the to-do list honest

Open plans/todo.md anytime to see what's done (- [x]) and what's next. The orchestrator ticks tasks only after they're verified.

The commands

Core SDLC pipeline

_{⃰ = optional step, but blocking if run (security gates are non-negotiable).}

Optional parameters (so you know they exist):

• /spec — for UI products, ASCII wireframes are produced by default; add --prototype (or say "with prototype") to also generate a clickable HTML prototype for stakeholder click-through sign-off. For a brownfield REVERSE baseline wireframes are waived by default — add --wireframes to opt in as-is wireframes documented from the shipped UI (works post-hoc on an approved baseline too).
• /arch — Rejection ADRs (intentionally-excluded stack components) default to one consolidated table; add --adr=per-component (or say "a separate ADR per component") to emit one full ADR per excluded component (e.g. audit/compliance).

Supporting commands

The agents

Each command invokes a specialist with its own playbook (in .claude/agents/):

Two modes: Greenfield & Brownfield

The kit auto-detects which situation you're in (declared in .claude/PROJECT_PROFILE.md, cross-checked against the actual repo state):

🧭 First time? Follow the step-by-step first-run checklist for your mode: getting-started-greenfield.md · getting-started-brownfield.md (covers the one-time Phase A onboarding vs the per-feature Phase B loop, and single-repo vs multi-repo install).

Brownfield discipline (auto-activated): characterization tests before touching untested legacy code, backward-compatibility by default, ADR required to change architecture, and the strangler-fig pattern for upgrades. See .claude/rules/brownfield.md.

What gets enforced (the rules)

Every line of code obeys the mandatory rules in .claude/rules/. Highlights:

• Clean Architecture — Api → Core ← Infrastructure, no cross-layer leaks
• Clean Code & SOLID — ≤3 params, single-purpose methods, no flag params, async correctness
• TDD — failing test first, ≥80% line / ≥75% branch coverage
• Security first — no hardcoded secrets, parameterized queries, JWT discipline, OWASP checks
• RFC 7807 errors, REST conventions, structured logging with correlation IDs
• Docker baseline — multi-stage build, non-root user, health checks, resource limits, image scanning

Quality gates (you can't skip the blocking ones)

/spec → /arch     PRD approved · every story has acceptance criteria
/arch → /plan     architecture reviewed · ADRs documented · API contracts defined
/build → /test    all unit tests pass · code compiles
/test → /review   coverage ≥ 80% · all tests pass
/scan → /infra    no critical/high vulnerabilities (if /scan run)
/infra → /docs    docker builds · compose up healthy
/verify → /deploy artifact tested == artifact promoted (if /verify run)

Customizing for your stack

The kit ships with a default stack (C# 12 + ASP.NET Core 8 + EF Core 8 + SQL Server + Next.js). To use a different peripheral technology, edit .claude/PROJECT_PROFILE.md (the user-owned CONFIG layer — kit upgrades never touch it) and the matching override kicks in automatically:

Overrides only replace the dialect/backend-specific parts — all agnostic principles (parameterized queries, structured logging, TDD…) stay the same.

The Profile also declares the artifacts' Output Language (default: Vietnamese) — set English (or any language name) and every artifact and conversation renders in that language, while code, identifiers, and standard technical terms always stay English.

Repository layout

.claude/
├── CLAUDE.md          # The brain — pipeline, gates, Project Profile, rules index
├── commands/          # 20 slash-command workflows (/spec, /arch, /build, …)
├── agents/            # 11 specialized agent playbooks
├── rules/             # 17 mandatory engineering rules
│   └── overrides/     # 11 stack-specific overrides (Postgres, Node.js, PHP/Laravel, ELK, …)
├── skills/            # Reusable techniques (tdd, code-review, …)
├── references/        # 10 references/checklists (security, testing, docker, a11y, multi-repo, …)
├── templates/         # fill-only templates: STRIDE · OWASP · TEST_REPORT · VERIFY_REPORT · CODE_REVIEW · RUNBOOK_RELEASE · wireframes · system (/discover-system) · export-docs (mapping-manifest schema)
├── hooks/             # Lifecycle hooks (command stats)
└── scripts/           # Security scanners (dotnet, nodejs, python, php, docker) + DB-schema export

# Generated as you work:
specs/  architecture/  plans/  security/  src/  web/  tests/  reports/  docker/  docs/  exports/

📖 The single source of truth for the whole workflow is .claude/CLAUDE.md — start there if you want the deep dive.

A worked example: LinkVault

This kit ships with a sample brief, README1.txt, for LinkVault — a personal bookmark manager (auth, bookmark CRUD, tags, search, simple web UI). It's the perfect first run:

/spec        # paste the LinkVault requirements from README1.txt
/arch        # design the Clean Architecture solution + API
/plan        # break it into buildable slices
/build       # implement, test-first
/test        # prove it with real dependencies

By the end you'll have a working, tested, documented ASP.NET Core + Next.js app — and a feel for how the whole pipeline flows.

FAQ

Do I have to run all 12 steps?
No. Required steps are /spec, /arch, /plan, /build, /test, /infra, /deploy. The rest (/secure, /review, /scan, /docs, /verify) are optional — but if you run them, their gates are blocking. For production, running them all is strongly recommended.

Can I use it for languages other than C#?
Yes — the kit has Node.js / TypeScript and PHP / Laravel overrides today, and the architecture is designed so peripheral tech (DB, observability) swaps via the Project Profile.

What language are the generated artifacts in?
Whatever Output Language declares in .claude/PROJECT_PROFILE.md — Vietnamese by default (the kit's original audience); change one line to English or any other language. Code, identifiers, and standard technical terms always stay English.

Where do I change the default model or behavior?
.claude/settings.json (model, permission mode, hooks).

What's the difference between /fix-issue and /hotfix?
/fix-issue fixes code during the dev cycle (not yet released). /hotfix restores something that's already live — it adds rollback triage, re-verification, and an incident runbook.

License

This project is licensed under the MIT License — see the LICENSE file for details.

The workflow philosophy draws inspiration from BMAD-METHOD.