nextjs-claude-code

NCC — nextjs-claude-code

Spec-Driven AI Development workflow for Next.js & React — from spec to shipped with Claude Code.

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

한국어 →

Features

• Spec-Driven: Feature specs with REQ-NNN traceability, compliance reporting
• Curated skills from skills.sh (community skill registry for Claude Code) — bundled core skills installed automatically, on-demand skills for library-specific best practices. Includes React, Next.js, UI/UX, testing patterns
• Architecture guides — Flat, Feature-Based, FSD, Monorepo (auto-detected from project structure; refined via /init)
• Library-aware agents — agents read your selected stack and follow its patterns
• Next.js native — App Router, Server Components, Server Actions, Pages Router
• React support — Vite and other React setups
• Monorepo ready — detects monorepo patterns (Turborepo, apps/packages) and adapts skills/rules during /init
• Claude Code native — slash commands, multi-agent coordination, PostToolUse hooks (validation scripts that run after Claude writes or edits files)

Prerequisites

• Node.js >= 18
• Claude Code installed and configured

Installation

For Humans — Installation Guide

For Claude Code — fetch the guide and follow it:

curl -s https://raw.githubusercontent.com/ByeongminLee/nextjs-claude-code/main/docs/installation.md

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

Why SDD?

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, what the current spec looks like, and what changed.

Existing spec-driven tools like Spec-kit and OpenSpec work well for independent changes, but their change-based folder structure makes it hard to see how a single feature evolves over time.

/spec payment-coupon "add coupon support to payment, Figma: https://..."   # define the spec
/dev payment-coupon                                                         # implement

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

Who is this for?

NCC is optimized for teams that iteratively implement confirmed specs on a feature-by-feature basis. It is for teams whose features keep evolving after launch — where a single payment feature grows from basic checkout to coupons to subscriptions to promotions over months.

Workflow

The core SDD loop — define what to build, then build it.

/spec [name] "describe the feature"   →  spec-writer clarifies → writes spec.md + design.md
/dev  [name]                           →  planner → lead-engineer → verifier → done
/dev  [name] --team                    →  planner → lead-engineer (+ db/ui/worker team) → verifier → done

User                    Claude Agents              Files
────                    ─────────────              ─────
/spec [name] "..."  ──→  spec-writer       ──→    spec/feature/[name]/spec.md
                                                   spec/feature/[name]/design.md

/dev [name]         ──→  planner           ──→    spec/feature/[name]/CONTEXT.md (WHY)
                            │                      spec/feature/[name]/PLAN.md (WHAT)
                            ↓ (after user confirms)
                         lead-engineer     ──→    source code
                            │  (--team: spawns db/ui/worker engineers)
                            ↓
                         verifier           ──→    (read-only verification)
                            │
                            ↓ (after verification)
                         lead-engineer     ──→    spec/feature/[name]/history/
                                                   spec/STATE.md

/review [name]      ──→  reviewer          ──→    (spec compliance report)
                         code-quality-     ──→    (code quality report)
                         reviewer

/loop [name]        ──→  loop              ──→    reviewer (REQ check)
                            │                      ↓ (if failing REQs)
                            ↓                     lead-engineer (targeted fix)
                         (repeat, max 5)           ↓ (re-verify)
                            ↓                     verifier (Level 1-3)
                         done or escalation        spec/feature/[name]/history/

/status             ──→  status            ──→    (read-only report)

/debug "..."        ──→  debugger          ──→    spec/DEBUG.md
                                                   spec/STATE.md

/rule "..."         ──→  rule-writer       ──→    spec/rules/[topic].md

Ops

Independent commands — use any of them whenever you need.

Review & Quality

Command	Description
/review [name]	Spec compliance + code quality review. Conditionally runs tester, log-auditor, and security-reviewer if their strategy files exist (TEST_STRATEGY.md / LOG_STRATEGY.md / SECURITY_STRATEGY.md).
/loop [name]	Repeat review → fix → re-review until all REQs pass (max 5 iterations).
/test [name]	Run tests based on TEST_STRATEGY.md. --browser for visual tests + Figma comparison. --setup to configure.
/log [name]	Audit logging practices. --audit for project-wide scan. --setup to configure LOG_STRATEGY.md.
/security [name]	Security audit (OWASP Top 10). --audit for project-wide scan. --diff for changed files only. --setup to configure SECURITY_STRATEGY.md.

Git & Release

Command	Description
/commit [name]	Auto-generate commit message from diff, following commit convention. Links to REQ numbers.
/pr [name] [target]	Create PR with spec-based body. Auto-detects target branch. Updates changelog + version if enabled.

Infrastructure

Command	Description
/cicd	(experimental) Set up CI/CD pipeline. Uses find-skills for platform-specific skill discovery. Generates spec/CICD.md.

Dev Utilities

Command	Description
/init	Analyze existing codebase and populate spec documents. Run once after install.
/debug "..."	Hypothesis-driven bug analysis. Records process in spec/DEBUG.md.
/status	Project status summary from spec/STATE.md.
/rule "..."	Add or update coding rules in spec/rules/.

Agent Roles

Core Agents (Workflow)

Agent	Role	Modifies code	Modifies spec docs
init	Codebase analysis, draft spec docs	No	Yes
spec-writer	Write spec.md + design.md (+ TEST.md if TDD)	No	Yes
planner	Create CONTEXT.md + PLAN.md, domain analysis + task tagging	No	Yes
lead-engineer	Implement features (solo or team leader)	Yes	Partial (STATE, history)
verifier	4-level verification	No	No (read-only)

Team Engineers (/dev --team)

Agent	Role	Model	Modifies code
db-engineer	Schema, migrations, ORM, queries, RLS	sonnet	Yes (DB files only)
ui-engineer	Components, styling, animations, responsive	sonnet	Yes (UI files only)
worker-engineer	Simple utils, types, config (≤200 lines)	haiku	Yes (assigned file only)

Note: Team mode requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable. npx install sets this in .claude/settings.json; plugin install provides it via plugin.json env.

Ops Agents

Agent	Role	Modifies code	Modifies spec docs
reviewer	Spec compliance report	No	No (read-only)
code-quality-reviewer	Code quality review	No	No (read-only)
tester	Test execution + TEST.md management	Creates test files only	Yes (TEST.md)
browser-tester	(experimental) Browser tests + Figma comparison	No	No (read-only)
committer	Auto-generate commit messages	No	No
pr-creator	PR creation + changelog + version bump	No (CHANGELOG.md + version only)	Yes (CHANGELOG.md)
git-strategy-detector	Detect branch strategy + generate templates	No	Yes (GIT_STRATEGY.md)
log-auditor	Logging audit and fixes	Fix mode only (/log [name])	No (read-only)
security-reviewer	Security audit (OWASP Top 10)	No	No (read-only)
cicd-builder	(experimental) CI/CD pipeline generation	Yes	Yes (CICD.md)
loop	Force-complete REQ compliance	Yes (via lead-engineer)	Partial (STATE, history)
status	Project status summary	No	No (read-only)
debugger	Bug fixing	Yes	Yes (DEBUG.md)
rule-writer	Manage coding rules	No	Yes (spec/rules/)

Safety Features

Checkpoints

lead-engineer pauses at these conditions and waits for user confirmation:

Type	Condition	Action
checkpoint:decision	Implementation direction choice needed, type structure changes	Present options, wait for user
checkpoint:human-verify	UI implementation complete (intermediate milestone)	Request browser verification, wait
checkpoint:auth-gate	Payment/auth manual action required	Always stop, never simulate

Auto-fix Budget

Maximum 3 retries per mode:

• /dev: shared across the entire session (persists between sessions)
• /loop: resets per iteration (independent budget per iteration)
• /debug: per bug

Attempt 1: Error analysis → targeted fix
Attempt 2: Alternative approach
Attempt 3: Minimal change
Exceeded: [Escalation] Implementation halted, report to user

Verification Levels

All /dev completions auto-trigger the verifier:

Level	Check	Method
1	All planned files exist	File existence check
2	No stubs or placeholders	grep for TODO, empty functions, dummy values
2b	Test files exist (conditional)	Required if testing: required, warning otherwise
3	Components/hooks/APIs wired correctly	Import and call tracing
4	Actually works	Browser direct verification

Resume Protocol

If /dev is interrupted (session crash, timeout, context limit), running /dev again resumes from where it left off:

• spec/STATE.md tracks each feature's phase independently: idle → planning → executing → verifying → idle (or looping during /loop)
• /dev reads the feature's phase and routes to the appropriate agent instead of restarting from scratch
• Completed tasks (- [x]) in spec/feature/[name]/PLAN.md are skipped on resume
• Auto-fix budget (Used: N) persists across sessions
• If spec.md was modified after PLAN.md was created, a warning is shown with a re-planning suggestion
• Model routing: sonnet by default, haiku for small/mechanical tasks (verifier, cleanup, simple fixes). Opus is never used. See spec/rules/_model-routing.md for criteria.

Phase	Resume behavior
idle	Fresh start → planner
planning	Check PLAN.md status → continue or advance to lead-engineer
executing	Skip completed tasks (- [x]) → continue from first - [ ]
verifying	Re-run verifier via lead-engineer
looping	Read LOOP_NOTES.md and resume from current iteration

Additional safeguards

• Spec validation: PostToolUse hooks block malformed spec.md and design.md writes
• Spec reflection: advisory hook reminds you to update the spec when code changes add new exports or routes
• Plan staleness check: /dev warns if spec.md has been modified since the feature's PLAN.md was created
• Model routing: agents use sonnet by default, haiku for small/mechanical tasks (verifier, cleanup, simple fixes). Opus is never used. See spec/rules/_model-routing.md for criteria.
• Branch strategy awareness: /commit and /pr auto-detect branch strategy and enforce commit conventions
• Conditional review agents: tester, log-auditor, and security-reviewer only join /review when their strategy files exist (TEST_STRATEGY.md, LOG_STRATEGY.md, SECURITY_STRATEGY.md)
• Changelog automation: /pr auto-updates CHANGELOG.md and bumps package.json version based on commit types (Semantic Versioning)

Troubleshooting

Issue	Solution
Plan approval stuck at "pending"	Re-run /dev [name] to restart the planning flow
Auto-fix budget exhausted	Lead-engineer stops after 3 attempts. Review the error manually and provide guidance
Team mode not working	Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set in .claude/settings.json
Spec validation blocking writes	Check that section headers match the expected format (English or Korean)
Hook errors on every file write	Edit .claude/settings.json to remove or disable specific hooks

Contributing

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

Found a bug or have a feature request? Open an issue.

License

MIT