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
— TDD by default Test-Driven Development with MSW API mocking out of the box
— Curated skills from skills.sh — bundled core skills auto-installed, on-demand skills matched from package.json
— Architecture guides Flat, Feature-Based, FSD, Monorepo (auto-detected from project structure)
— 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 Turborepo workspace-aware installation
— Claude Code native slash commands, multi-agent coordination, lifecycle hooks (SessionStart, PreToolUse, PostToolUse, Stop)
— Hook profiles NCC_HOOK_PROFILE controls hook intensity: minimal, standard (default), strict
— Wave execution tasks grouped into dependency waves for parallel dispatch
— Path-specific rules .claude/rules/ with paths frontmatter — coding patterns load only for matching files

Prerequisites

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

Installation

For Humans

For Claude Code — fetch the guide and follow it:

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

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.
— 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."

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.

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 team) → verifier → done

Commands

Ideation & Design

/create "..."	Ideation-to-validation pipeline with C-suite review
/brainstorm "..."	Quick design exploration with trade-offs
/reforge "[path]" "..."	Transform legacy project into spec-driven development

Review & Quality

/review [name]	Spec compliance + code quality review
/loop [name]	Repeat review → fix → re-review until all REQs pass (max 5)
/qa	Playwright E2E tests, visual regression, accessibility audits
/test [name]	Run tests based on TEST_STRATEGY.md
/log [name]	Audit logging practices
/security [name]	Security audit (OWASP Top 10)

Git & Release

/commit [name]	Auto-generate commit message from diff
/pr [name] [target]	Create PR with spec-based body

Infrastructure

/cicd

Set up CI/CD pipeline

Issue Reporting

/issue-reporter "..."

Report NCC bug or feature request to GitHub (sanitizes project data, requires confirmation)

Dev Utilities

/init	Analyze existing codebase and populate spec documents
/debug "..."	Hypothesis-driven bug analysis
/status	Project status summary
/rule "..."	Add or update coding rules

Upgrade

/ncc-upgrade	Upgrade NCC from within Claude Code (plugin or npx)
npx nextjs-claude-code upgrade	Upgrade from terminal (npx only)

Agent Roles

Claude Code agents work in coordination, each with specific responsibilities and permissions.

Core Agents

spec-writer	Write spec.md + design.md
planner	Create CONTEXT.md + PLAN.md, domain analysis + task tagging
lead-engineer	Orchestrate implementation via fresh-context subagents. Wave-based parallel dispatch.
verifier	5-level verification (incl. browser check)

Fresh-Context Subagents (/dev)

task-executor	Implements [lead] tasks (types, utils, hooks, API routes)
browser-tester	AI-driven browser testing via Playwright MCP

Team Engineers (/dev --team)

db-engineer	Schema, migrations, ORM, queries
ui-engineer	Components, styling, animations

Safety Features

— Checkpoints lead-engineer pauses for user confirmation at decision points, UI milestones, and auth/payment gates
— Auto-fix Budget Maximum 3 retries per mode — error analysis → alternative approach → minimal change → escalation
— Verification Levels 5 levels from file existence to browser verification
— Resume Protocol Interrupted /dev sessions resume from where they left off
— Hook Profiles minimal (security only), standard (default), strict (+ deprecation guard, comment checker, todo enforcer)
— Spec Validation PostToolUse hooks block malformed spec writes and remind spec updates

References

NCC was built by studying what works best across the Claude Code ecosystem and incorporating those proven patterns into a cohesive workflow. Wave execution, context engineering, agent orchestration, token optimization, verification loops, and spec-driven planning were all refined with insights from GSD, gstack, Everything Claude Code, Oh My OpenAgent, Superpowers, Vercel Plugin, Spec Kit, and OpenSpec.

NCC — nextjs-claude-code

Next.js & React를 위한 Spec-Driven AI 개발 워크플로우. Claude Code 전용.

기능 단위로 명세를 정의하고, 정의한 대로 정확하게 구현합니다 — 모든 변경은 요구사항까지 추적됩니다.

주요 기능

— Spec-Driven REQ-NNN 추적 가능한 feature spec, 준수 보고서
— TDD 기본 MSW API 목킹과 함께 Test-Driven Development가 기본
— 큐레이션 스킬 skills.sh에서 core 스킬 자동 설치, package.json 기반 on-demand 스킬 매칭
— 아키텍처 가이드 Flat, Feature-Based, FSD, Monorepo (프로젝트 구조에서 자동 감지)
— 라이브러리 인식 에이전트 선택한 스택에 맞춰 코드 작성
— Next.js 네이티브 App Router, Server Components, Server Actions, Pages Router
— React 호환 Vite 등 다른 React 셋업도 지원
— Monorepo 지원 Turborepo 워크스페이스 인식 설치
— Claude Code 네이티브 slash commands, 멀티 에이전트 조합, lifecycle hooks (SessionStart, PreToolUse, PostToolUse, Stop)
— Hook profiles NCC_HOOK_PROFILE로 훅 강도 조절: minimal, standard (기본), strict
— Wave 실행 태스크를 의존성 기반 wave로 그룹화하여 병렬 디스패치
— Path-specific rules .claude/rules/에 paths 프론트매터로 매칭 파일에서만 로드되는 코딩 패턴

사전 요구사항

— Node.js >= 18
— Claude Code 설치 및 설정 완료

설치

직접 설치

Claude Code용 — 가이드를 가져와서 따라 실행:

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

왜 SDD인가?

기능은 한 번에 완성되지 않습니다. 결제 기능을 기본 체크아웃으로 먼저 출시하고, 한 달 후 쿠폰을 추가합니다. 매번 이전에 무엇을 만들었는지, 현재 스펙이 무엇인지, 무엇이 바뀌었는지를 알아야 합니다.

Spec-kit, OpenSpec 같은 기존 SDD 도구는 독립적인 변경사항에는 잘 동작하지만, 변경사항별 폴더 구조는 하나의 기능이 시간에 따라 어떻게 발전했는지 파악하기 어렵게 만듭니다.

/spec payment-coupon "payment에 쿠폰 기능 추가, Figma: https://..."   # 스펙 정의
/dev payment-coupon                                                    # 구현

— 변경 단위가 아니라 기능 단위. 각 기능은 프로젝트 전체 기간 동안 유지되는 고정된 위치(spec/feature/[이름]/)를 가집니다.
— 점진적 개발을 위한 구조. 스펙, 디자인, 구현 이력이 함께 유지되어 매 반복이 처음부터가 아닌 이전 결과 위에 쌓입니다.
— 속도보다 스펙 정확성. spec-writer는 작성 전 모호한 점을 질문하고, lead-engineer는 확인된 계획을 따르며, verifier는 "동작한다"를 확인합니다.

누구를 위한 도구인가?

NCC는 확정된 스펙을 기능 단위로 반복적으로 구현하고 추적하는 개발 방식에 최적화되어 있습니다. 출시 후에도 계속 진화하는 기능을 다루는 팀을 위한 도구입니다.

워크플로우

핵심 SDD 루프 — 무엇을 만들지 정의하고, 만듭니다.

/spec [이름] "기능 설명"   →  spec-writer가 질문 → spec.md + design.md 작성
/dev  [이름]               →  planner → lead-engineer → verifier → 완료
/dev  [이름] --team        →  planner → lead-engineer (+ db/ui 팀) → verifier → 완료

명령어

아이디에이션 & 디자인

/create "..."	아이디에이션→검증 파이프라인 (C-suite 리뷰)
/brainstorm "..."	빠른 디자인 탐색 + 트레이드오프
/reforge "[경로]" "..."	레거시 프로젝트를 spec-driven 개발로 전환

리뷰 & 품질

/review [이름]	스펙 준수 + 코드 품질 리뷰
/loop [이름]	리뷰 → 수정 → 재검증 반복, 모든 REQ 통과까지 (최대 5회)
/qa	Playwright E2E 테스트, visual regression, 접근성 감사
/test [이름]	TEST_STRATEGY.md 기반 테스트 실행
/log [이름]	로깅 관행 감사
/security [이름]	보안 감사 (OWASP Top 10)

Git & 릴리스

/commit [이름]	diff 기반 커밋 메시지 자동 생성
/pr [이름] [target]	스펙 기반 PR 본문 생성

인프라

/cicd

CI/CD 파이프라인 설정

이슈 리포팅

/issue-reporter "..."

NCC 버그/기능 요청을 GitHub에 제출 (프로젝트 데이터 자동 제거, 사용자 확인 필요)

개발 유틸리티

/init	기존 코드베이스 분석 + spec 문서 초안 생성
/debug "..."	가설 기반 버그 분석
/status	프로젝트 상태 요약
/rule "..."	코딩 규칙 추가 또는 수정

업그레이드

/ncc-upgrade	Claude Code 내에서 NCC 업그레이드 (플러그인/npx 자동 감지)
npx nextjs-claude-code upgrade	터미널에서 NCC 업그레이드 (npx 전용)

Agent 역할

Claude Code 에이전트들이 각자의 역할과 권한을 가지고 협력합니다.

Core Agents

spec-writer	spec.md + design.md 작성
planner	CONTEXT.md + PLAN.md 생성, 도메인 분석 + 태스크 태깅
lead-engineer	fresh-context subagent로 구현 오케스트레이션. Wave 기반 병렬 디스패치.
verifier	5단계 검증 (브라우저 체크 포함)

Fresh-Context Subagents (/dev)

task-executor	[lead] 태스크 구현 (타입, 유틸, 훅, API 라우트)
browser-tester	Playwright MCP 기반 AI 브라우저 테스트

Team Engineers (/dev --team)

db-engineer	스키마, 마이그레이션, ORM, 쿼리
ui-engineer	컴포넌트, 스타일링, 애니메이션

안전 장치

— Checkpoints lead-engineer가 의사결정, UI 완료, 인증/결제 시 사용자 확인을 받고 진행
— Auto-fix Budget 모드별 최대 3회 재시도 — 에러 분석 → 다른 접근법 → 최소 변경 → 에스컬레이션
— Verification Levels 파일 존재부터 브라우저 검증까지 5단계
— Resume Protocol 중단된 /dev 세션을 중단 지점부터 재개
— Hook Profiles minimal (보안만), standard (기본), strict (+ deprecation guard, comment checker, todo enforcer)
— 스펙 검증 PostToolUse 훅이 잘못된 스펙 작성을 차단하고 스펙 업데이트를 리마인드

References

NCC는 Claude Code 생태계에서 검증된 최선의 패턴을 연구하고, 이를 하나의 일관된 워크플로우로 통합하여 만들어졌습니다. Wave 실행, 컨텍스트 엔지니어링, 에이전트 오케스트레이션, 토큰 최적화, 검증 루프, 스펙 기반 계획 등 핵심 기능은 GSD, gstack, Everything Claude Code, Oh My OpenAgent, Superpowers, Vercel Plugin, Spec Kit, OpenSpec의 인사이트를 반영하여 개선되었습니다.