nextjs-claude-code

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