shinpr/claude-code-workflows

설계 문서(Design docs) 및 테스트와 일치하는 코드를 생성하는 Claude Code용 엔드투엔드(End-to-end) 개발 워크플로(Workflows). 전문화된 에이전트(Agents)가 요구사항, 설계, 구현 및 품질 검사를 처리하므로, 실제로 테스트를 통과하고 설계 문서와 일치하는 코드를 얻을 수 있습니다.

작업 유형	설치
백엔드(Backend), API, CLI 도구 또는 일반 프로그래밍	dev-workflows
...

# 1. Claude Code 시작
claude
# 2. 마켓플레이스(Marketplace) 추가
...

# 백엔드 또는 일반
/plugin install dev-workflows@claude-code-workflows
/reload-plugins
...

풀스택 레시피(Fullstack recipes)는 레이어별(백엔드 + 프론트엔드)로 별도의 설계 문서(Design Docs)를 생성하고, 설계 동기화(Design-sync)를 통해 레이어 간 일관성을 검증하며, 파일 이름 패턴에 따라 작업을 적절한 실행기(Executor)로 라우팅합니다. 자세한 내용은 풀스택 워크플로(Fullstack Workflow)를 참조하세요.

마이그레이션 공지 (v0.19.0): dev-workflows-fullstack이 풀스택 레시피의 새로운 홈입니다. 현재 dev-workflows와 dev-workflows-frontend를 모두 설치하여 사용할 수 있지만, 이는 스킬 설명(Skill descriptions)이 중복되어 컨텍스트 예산(Context budget)을 두고 경쟁하게 만듭니다. 다음 릴리스에서는 dev-workflows에서 recipe-fullstack-*를 제거할 예정입니다. 풀스택 작업을 수행한다면 지금 바로 dev-workflows-fullstack으로 전환하세요.

이 선택적 플러그인(Plugins)들은 워크플로의 인접한 단계들을 다룹니다:

• claude-code-discover: 기능 아이디어를 근거가 뒷받침된 PRD(제품 요구사항 문서)로 변환합니다.
• metronome: 지름길을 택하려는 행동을 감지하고 Claude가 단계별로 진행하도록 유도합니다.
• linear-prism: 요구사항을 구조화된 Linear 작업으로 변환합니다. 분해(Decomposing) 전에 검증을 수행하므로 후속 설계가 깔끔하게 시작됩니다.

/plugin install discover@claude-code-workflows
/plugin install metronome@claude-code-workflows
/plugin install linear-prism@claude-code-workflows

이미 자체적인 오케스트레이션(Orchestration, 커스텀 프롬프트, 스크립트, CI 기반 루프 등)을 갖추고 있으며 베스트 프랙티스(Best-practice) 가이드만 원하는 경우 dev-skills를 사용하세요. Claude가 엔드투엔드(End-to-end)로 계획, 실행 및 검증하기를 원한다면 dev-workflows를 설치하세요.

• 최소한의 컨텍스트 점유율 (에이전트나 레시피 스킬이 로드되지 않음)
• 기존 워크플로를 변경하지 않고도 즉시 적용 가능한 베스트 프랙티스 (Best practices)
• 사용자 정의 오케스트레이터 (Orchestrator)를 위한 규칙 세트 (Ruleset) 레이어로 작동

dev-workflows, dev-workflows-frontend 또는 dev-workflows-fullstack과 함께 설치하지 마세요. 중복된 스킬은 조용히 무시됩니다. 자세한 내용은 아래를 참조하세요.

# 스킬 전용 플러그인 설치
/plugin install dev-skills@claude-code-workflows

스킬은 관련이 있을 때 자동으로 로드됩니다. coding-principles는 구현 중에 활성화되고, testing-principles는 테스트 작성 중에 활성화되는 식입니다.

플러그인 간 전환:

# dev-skills -> dev-workflows
/plugin uninstall dev-skills@claude-code-workflows
/plugin install dev-workflows@claude-code-workflows
...

경고: dev-skills와 dev-workflows / dev-workflows-frontend / dev-workflows-fullstack은 동일한 스킬을 공유합니다. 이 중 두 개 이상을 설치하면 시스템 컨텍스트 (System context)에 스킬 설명이 여러 번 나타나게 됩니다. Claude Code는 스킬 설명을 컨텍스트 창 (Context window)의 약 2%로 제한합니다. 이 제한을 초과하면 스킬이 조용히 무시됩니다. 풀스택 (Fullstack) 작업을 위해서는 dev-workflows-fullstack만 설치하세요 (dev-workflows 또는 dev-workflows-frontend와 함께 설치하지 마세요).

graph TB
A[User Request] --> B[requirement-analyzer]
B --> |"Large (6+ files)"| C[prd-creator]
...

이 그림은 요청이 크기(작음 / 중간 / 큼)에 따라 어떻게 라우팅(Routing)되는지 보여줍니다. 규모가 큰 작업은 구현 단계에 도달하기 전에 PRD, 코드베이스 분석 및 설계를 거칩니다. 규모가 작은 작업은 이 과정을 건너뜁니다.

graph LR
P[Problem] --> INV[investigator]
INV --> |Failure Points| VER[verifier]
...

진단 흐름(Diagnosis flow)은 경로 커버리지(Path coverage)가 충분해질 때까지 조사자(Investigator)와 검증자(Verifier) 사이를 루프하며, 그 후 트레이드오프 분석(Tradeoff analysis)을 위해 해결사(Solver)에게 전달됩니다.

graph TB
subgraph Phase1[Phase 1: PRD Generation]
CMD["/recipe-reverse-engineer"] --> SD[scope-discoverer unified]
...

역공학 (Reverse engineering)은 두 단계로 실행됩니다. 먼저 PRD (제품 요구사항 문서)가 생성되며 (발견된 기능당 하나씩), 그 다음 디자인 문서 (Design Docs)가 범위를 재발견하지 않고 기존 범위를 재사용합니다.

분석 (Analysis). requirement-analyzer가 작업 복잡도를 결정하고 워크플로우를 선택합니다. 코드베이스 이해 (Codebase Understanding). codebase-analyzer가 디자인 단계 전에 기존 모듈과 의존성(인증 흐름, 스키마 정의, 의존성 그래프 등)을 스캔합니다. 계획 (Planning). 복잡도에 따라 PRD, UI 명세서 (UI Spec), 디자인 문서 (Design Doc), 작업 계획 (work plan)이 생성됩니다. 실행 (Execution). 특화된 에이전트 (Specialized agents)가 계획을 자율적으로 구현합니다. 품질 (Quality). 테스트가 실행되고, 타입 체크 (types check)가 이루어지며, 오류가 수정됩니다. 검토 (Review). 구현 내용이 디자인 문서와 일치하는지 검증합니다. 완료 (Done). 검토 및 테스트가 완료되어 커밋 (commit)할 준비가 됩니다.

각 단계는 새로운 에이전트 컨텍스트 (agent context)에서 실행되므로, 이전 단계가 컨텍스트를 비대하게 만들거나 이후의 결정에 간섭하지 않습니다.

모든 워크플로우 진입점은 지식 기술 (knowledge skills)과 구분하기 위해 recipe- 접두사를 사용합니다. /recipe-를 입력하고 탭 완성 (tab completion) 기능을 사용하면 사용 가능한 모든 레시피 (recipes)를 확인할 수 있습니다.

레시피 (Recipe)	목적 (Purpose)	사용 시기 (When to Use)
/recipe-implement	엔드 투 엔드 (End-to-end) 기능 개발	새로운 기능, 전체 워크플로우
/recipe-fullstack-implement	엔드 투 엔드 풀스택 (fullstack) 개발	현재 사용 중단 (Deprecated) — 다음 릴리스에서 dev-workflows-fullstack으로 이동 예정
/recipe-task	단일 작업을 정밀하게 실행	버그 수정, 작은 변경 사항
/recipe-design	디자인 문서 생성	아키텍처 계획
/recipe-plan	디자인으로부터 작업 계획 생성	계획 단계
/recipe-prepare-implementation	구현 준비 상태 확인 및 격차 해소	작업 계획이 구현 가능한지 확인하는 빌드 전 점검
/recipe-build	기존 작업 계획으로부터 실행	구현 재개
/recipe-fullstack-build	풀스택 작업 계획 실행	현재 사용 중단 (Deprecated) — 다음 릴리스에서 dev-workflows-fullstack으로 이동 예정
/recipe-review	디자인 문서와 대조하여 코드 검증	구현 후 점검
/recipe-diagnose	문제 조사 및 해결책 도출	버그 조사, 근본 원인 분석 (root cause analysis)

| /recipe-reverse-engineer | 기존 코드로부터 PRD/설계 문서 생성 | 레거시 시스템 문서화, 코드베이스 이해 |
| /recipe-add-integration-tests | 기존 코드에 통합/E2E 테스트 추가 | 기존 구현 사항에 대한 테스트 커버리지 |
| /recipe-update-doc | 리뷰를 통한 기존 설계 문서 업데이트 | 사양 변경, 리뷰 피드백, 문서 유지 관리 |

프론트엔드 플러그인은 React 특화 에이전트(컴포넌트 아키텍처, Testing Library, TypeScript 우선 품질 검사)와 선택적 프로토타입 코드를 통한 UI 사양 (UI Spec) 생성 기능을 추가합니다.

레시피 (Recipe)	목적	사용 시점
/recipe-front-design	UI 사양 + 프론트엔드 설계 문서 생성	React 컴포넌트 아키텍처, UI 사양
/recipe-front-plan	프론트엔드 작업 계획 생성	컴포넌트 분해 계획
/recipe-front-build	프론트엔드 작업 계획 실행	React 구현 재개
/recipe-front-adjust	MCP 기반 검증을 통한 기구현 UI 조정	디자인 소스 비교가 필요한 시각적 수정, 컴포넌트 개선
/recipe-front-review	설계 문서와 코드를 대조하여 검증	구현 후 점검
/recipe-task	단일 작업을 정밀하게 실행	컴포넌트 수정, 소규모 업데이트
/recipe-diagnose	문제 조사 및 해결책 도출	버그 조사, 근본 원인 분석 (root cause analysis)
/recipe-update-doc	리뷰를 통한 기존 설계 문서 업데이트	사양 변경, 리뷰 피드백, 문서 유지 관리

팁: 두 플러그인 모두 /recipe-task, /recipe-diagnose, /recipe-update-doc를 공유합니다. /recipe-update-doc은 문서의 레이어를 자동으로 감지합니다. 프로젝트에 프론트엔드 설계 문서가 있다면, 이를 업데이트하기 위해 프론트엔드 플러그인이 필요합니다. 역공학 (Reverse engineering)의 경우, /recipe-reverse-engineer를 풀스택 (fullstack) 옵션과 함께 사용하여 단일 워크플로에서 백엔드와 프론트엔드 설계 문서를 모두 생성할 수 있습니다.

이 워크플로는 개발 생명주기(development lifecycle)의 각 단계에 특화된 에이전트를 사용합니다.

이 에이전트들은 REST API를 구축하든 React 앱을 구축하든 동일한 방식으로 작동합니다:

에이전트 (Agent)	역할
requirement-analyzer	작업의 복잡도를 파악하고 적절한 워크플로우 (workflow)를 선택합니다
codebase-analyzer	설계를 시작하기 전 기존 코드베이스 (codebase)를 분석하여 기술 설계자 (technical-designer)를 위한 집중적인 가이드를 생성합니다
work-planner	설계 문서 (design docs)를 실행 가능한 작업 단위로 분해합니다
task-decomposer	작업을 커밋 (commit) 가능한 작은 단위로 나눕니다
code-reviewer	설계 문서와 코드를 대조하여 누락된 부분이 없는지 확인합니다
document-reviewer	단일 문서의 품질, 완결성 및 규칙 준수 여부를 검토합니다
design-sync	여러 설계 문서 간의 일관성을 검증하고 충돌을 감지합니다
investigator	실행 경로를 매핑하고, 문제 진단을 위해 인과 관계 사슬 (causal chains)을 통해 실패 지점을 식별합니다
verifier	실패 지점을 검증하고, 악마의 변호인 (Devil's Advocate) 방식을 사용하여 경로 커버리지 (path coverage)를 확인합니다
solver	트레이드오프 (tradeoff) 분석과 구현 단계가 포함된 솔루션을 생성합니다
security-reviewer	모든 작업이 완료된 후 구현 사항의 보안 준수 여부를 검토합니다

에이전트 (Agent)	역할
prd-creator	복잡한 기능에 대한 제품 요구사항 문서 (PRD)를 작성합니다
technical-designer	아키텍처 (architecture) 및 기술 스택 (tech stack) 결정을 계획합니다
scope-discoverer	역공학 (reverse engineering)을 위해 코드베이스에서 기능적 범위를 찾아냅니다
code-verifier	문서와 코드 구현 사이의 일관성을 검증합니다
acceptance-test-generator	요구사항으로부터 E2E (End-to-End) 및 통합 테스트 (integration test) 스캐폴드 (scaffolds)를 생성합니다
integration-test-reviewer	통합/E2E 테스트가 스켈레톤 (skeleton) 구조를 준수하는지 및 품질을 검토합니다
task-executor	TDD (Test-Driven Development)를 통해 백엔드 기능을 구현합니다
quality-fixer	테스트 실행, 타입 에러 (type errors) 수정, 린팅 (linting) 처리 등 품질과 관련된 모든 작업을 수행합니다
rule-advisor	현재 작업에 가장 적합한 코딩 규칙 (coding rules)을 선택합니다

Agent	역할
prd-creator	복잡한 기능에 대한 제품 요구 사항 문서 (PRD) 작성
ui-spec-designer	PRD 및 선택적 프로토타입 코드를 기반으로 UI 사양 (UI Specifications) 생성
ui-analyzer	프로젝트의 external-resources 파일을 읽고, 상속된 MCP 액세스를 통해 디자인 / 디자인 시스템 / 가이드라인 소스를 가져오며, 기존 UI 코드를 분석
technical-designer-frontend	React 컴포넌트 아키텍처 및 상태 관리 (state management) 계획
task-executor-frontend	Testing Library를 사용하여 React 컴포넌트 구현
code-verifier	문서와 코드 구현 간의 일관성 검증
quality-fixer-frontend	React 특화 테스트, TypeScript 체크 및 빌드 처리
rule-advisor	현재 작업에 가장 적합한 코딩 규칙 (coding rules) 선택
design-sync	여러 디자인 문서 간의 일관성을 검증하고 충돌 감지

백엔드 플러그인은 어떤 언어에서도 작동하는 검증된 모범 사례 (best practices)를 포함합니다:

코딩 원칙 (Coding Principles). 코드 품질 표준.
테스트 원칙 (Testing Principles). TDD, 커버리지 (coverage), 테스트 패턴.
구현 접근 방식 (Implementation Approach). 디자인 결정 및 트레이드오프 (trade-offs).
문서화 표준 (Documentation Standards). 명확하고 유지보수 가능한 문서.
외부 리소스 컨텍스트 (External Resource Context). 저장소 외부의 리소스(디자인 소스, 디자인 시스템, API 스키마, IaC 등)에 접근하는 방법을 기록하는 2단계 파일. 세 가지 플러그인 모두에서 사용 가능.

이것들은 기술 (skills)로 로드되며, 관련이 있을 때 에이전트(agents)에 의해 자동으로 적용됩니다.

프론트엔드 플러그인에는 React 및 TypeScript 특화 규칙이 내장되어 있습니다.

/recipe-implement "JWT를 사용한 사용자 인증 추가"
# 결과물:
# - PRD, ADR (해당하는 경우), 그리고 수락 기준 (acceptance criteria)이 포함된 디자인 문서 (Design Doc)
...

/recipe-front-design "사용자 프로필 대시보드 구축"
# 1. requirement-analyzer가 규모를 결정
# 2. External-resource hearing이 디자인 소스 / 디자인 시스템 / 시각적 검증 액세스를 캡처
...

UI 사양 (UI Spec)이 존재하는 이유. 프로토타입은 시각적인 표면을 포착하지만, 통합 과정에서 나타나는 로딩 (loading), 에러 (error), 빈 상태 (empty), 그리고 부분적 상태 (partial states)를 포착하는 경우는 드뭅니다.

예를 들어, 두 개의 컴포넌트가 각각 자신의 로딩 상태 (loading state)를 깔끔하게 처리할 수는 있지만, 이들을 결합한 대시보드 (dashboard)의 경우 하나는 여전히 로딩 중이고 다른 하나는 에러 (error)가 발생했을 때 정의된 동작 (defined behavior)이 없을 수 있습니다. UI 명세 (UI Spec)는 이러한 상태-표시 행렬 (state-x-display matrices)을 포착하여 디자인 문서 (Design Doc)와 테스트 스켈레톤 (test skeletons)으로 추적하므로, 통합 과정에서의 결함 (integration breakage)을 조기에 발견할 수 있습니다.

/recipe-fullstack-implement "Add user authentication with JWT + React login form"
# 발생하는 과정:
# 1. 요구사항 분석기 (requirement-analyzer)가 규모를 결정함
...

풀스택 레시피 (fullstack recipes)를 설치하세요. 작업 (Tasks)은 파일 이름 패턴 (dev-workflows-fullstack, *-backend-task-*, *-frontend-task-*)을 기반으로 라우팅 (routed)됩니다. 기존 풀스택 코드베이스 (codebases)를 역공학 (reverse engineering)하려면 풀스택 옵션과 함께 /recipe-reverse-engineer를 사용하세요.