NCC — nextjs-claude-code

Spec-Driven AI Development — define and build in just two commands.

Define your feature. Claude builds exactly what the spec says — every change traced back to a requirement.

/spec auth "email login"  →  spec.md + design.md
/dev auth                 →  plan → implement → verify → done

한국어 →

Two Commands. That's It.

Specify & Build — /spec + /dev

The core workflow. Define what to build, then build it — with every change traced to a REQ.

/spec auth "user login with email and OAuth"   # spec-writer → spec.md + design.md
/dev auth                                       # planner → lead-engineer → verifier → done
/dev auth --team                                # parallel team (db/ui engineers)
/loop auth                                      # review → fix → re-verify until all REQs pass

Don't have a plan yet? → /create

Turn a raw idea into a validated product concept. Seven forcing questions sharpen your thinking into a real product — then a virtual C-suite (CEO, CTO, CPO, CMO, CDO) debates your idea as a team, catching blind spots before you write a single spec. Details →

/create "AI recipe app that suggests meals from fridge photos"
# → 7 forcing questions → 3 approaches → C-suite team debate
# → VISION.md + C-REVIEW.md + DECISION.md → convert to /spec

Have a legacy project? → /reforge

Transform an existing codebase into spec-driven development. Analyzes legacy code, accepts change specifications, generates feature specs — blending existing logic with requested modifications.

/reforge ./_legacy/old-project "Switch to App Router, add Tailwind"
# → analysis → change spec → delta → spec generation → validation
# → spec.md + design.md per feature → /dev [feature]

Ops — Review, Test, Ship

Independent commands for quality, security, and deployment. Full command list →

/review auth      # spec compliance + code quality
/security --audit # OWASP Top 10 project-wide scan
/commit auth      # auto-generate commit with REQ links
/pr auth          # create PR with spec-based body

Quick Start

npx nextjs-claude-code@latest     # install SDD workflow
/init                              # analyze codebase, populate spec docs
/spec auth "user login with email" # define a feature spec
/dev auth                          # implement the feature

Prerequisites: Node.js >= 18, Claude Code

Installation guide: For Humans | For Claude Code: curl -s https://raw.githubusercontent.com/ByeongminLee/nextjs-claude-code/main/docs/en/installation.md

Why Spec-Driven?

Features are never completed in a single iteration. You ship a basic checkout, add coupons a month later, then subscriptions, then promotions. At every step you need to know what was built before and what changed.

• Feature-unit, not change-unit. Each feature has a fixed location (spec/feature/[name]/) that persists throughout the project. Changes accumulate as history entries.
• Built for progressive development. Spec, design, and implementation history live together so each iteration builds on the last.
• Spec accuracy over speed. spec-writer clarifies before writing, lead-engineer follows a confirmed plan, verifier checks "it works" not just "files exist."

Features

• Spec-Driven: REQ-NNN traceability, compliance reporting
• TDD by default: MSW API mocking, tests first
• Curated skills from skills.sh — core bundled, on-demand per library
• Architecture guides — Flat, Feature-Based, FSD, Monorepo (auto-detected)
• C-level ideation — CEO/CTO/CPO/CMO/CDO review pipeline via /create
• Legacy reforge — /reforge transforms existing projects into spec-driven development
• Next.js + React — App Router, Server Components, Pages Router, Vite
• Wave execution — dependency-grouped parallel dispatch
• Multi-agent team — db/ui/worker engineers in --team mode
• Hook profiles — minimal / standard / strict intensity control
• Context optimization — repo profiler, compact recovery, artifact size limits

Workflow

User                    Claude Agents              Files
────                    ─────────────              ─────
/create "idea"     ──→  create-orchestrator ──→    spec/create/[name]/VISION.md
                         c-ceo/cto/cpo/cmo/cdo     spec/create/[name]/C-REVIEW.md
                                                   spec/create/[name]/DECISION.md

/reforge [path]    ──→  reforge-orchestrator──→    spec/reforge/[name]/ANALYSIS.md
  "changes"              codebase-analyzer          spec/reforge/[name]/DELTA.md
                         reforge-spec-gen    ──→    spec/feature/[name]/spec.md + design.md

/spec [name] "..." ──→  spec-writer        ──→    spec/feature/[name]/spec.md
                                                   spec/feature/[name]/design.md

/dev [name]        ──→  planner            ──→    spec/feature/[name]/PLAN.md
                            ↓ (user confirms)
                         lead-engineer      ──→    source code
                            ↓ (--team: db/ui/worker)
                         verifier           ──→    verification report
                            ↓
                         completion          ──→    spec/STATE.md + history/

Safety

| Feature | Description | |---------|-------------| | Checkpoints | decision (direction choice), human-verify (UI check), auth-gate (payment/auth) | | Auto-fix budget | 3 retries per mode, then escalation | | Verification | 5 levels: files exist → no stubs → tests/mocks exist → wired correctly → browser test → human verify | | Resume protocol | /dev resumes from where it left off (phase-aware) | | Hook profiles | minimal (security only) → standard → strict (all guards) | | Token isolation | /create docs in spec/create/, /reforge docs in spec/reforge/ — never loaded by /spec or /dev |

Detailed Documentation

• Commands Reference — full command list with options
• Agent Roles — all agents with permissions matrix
• /create Workflow — ideation pipeline details
• Installation Guide — setup instructions

Troubleshooting

| Issue | Solution | |-------|----------| | Plan approval stuck | Re-run /dev [name] to restart | | Auto-fix budget exhausted | Edit Used: 0 in PLAN.md after manual fixes | | Team mode not working | Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings | | Hook errors on writes | Set NCC_HOOK_PROFILE=minimal in settings |

References

NCC incorporates proven patterns from GSD, gstack, Everything Claude Code, Oh My OpenAgent, Superpowers, Vercel Plugin, Spec Kit, and OpenSpec.

Contributing

Issues and PRs welcome at github.com/ByeongminLee/nextjs-claude-code.

License

MIT