English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)
Claude Code는 코드베이스를 깊이 탐색할 수 있습니다. 하지만 복잡한 작업에서 더 어려운 문제는 탐색이 아니라 결론을 내는 일입니다. 예를 들어 계정 복구 흐름을 설계하다가 토큰 처리의 실제 불일치를 발견하면, Claude가 설계 대부분을 그 문제에 할애한 나머지 정작 요청받은 복구 동작을 모호하게 남길 수 있습니다.
claude-code-workflows는 탐색이 합의된 결과를 향하도록 유지합니다. 설계 전에 목표와 제외 범위를 합의하고, 설계를 저장소와 대조하며, 커밋 전에 각 작업을 검증합니다. 규모가 큰 변경에서는 완성된 구현이 합의한 결과를 제대로 제공하는지, 불필요한 변경이 들어가지는 않았는지, 동작·신뢰성·보안에 심각한 문제가 없는지를 독립적으로 검토합니다. 이 범위 안에서 Claude는 코드베이스를 바탕으로 구현 세부 사항을 결정합니다.
목표와 안전한 구현 범위가 이미 명확하다면 Claude Code를 직접 사용하세요. 범위 합의, 오래 유지해야 하는 설계 결정, 컨텍스트 사이의 안정적인 인계 또는 독립적인 검증이 필요한 변경에는 이 워크플로를 사용하세요.
이 워크플로는 Agent 호출과 산출물을 추가하므로 그만한 가치가 있을 때 사용해야 합니다. 관련 문제를 발견한 탓에 큰 변경이 원래 목표에서 벗어날 수 있거나, 설계 자체는 일관되지만 요청한 동작을 놓칠 수 있거나, 통과한 테스트가 검증한다고 주장한 내용을 실제로 관찰하지 못할 수 있을 때 유용합니다. 모든 검사가 필요하지 않은 변경이라면 라이트 모드로 검사를 줄일 수 있습니다.
구현 범위가 승인되면 Claude는 일상적인 구현 결정을 되묻지 않고 작업별 검증, 저장소 품질 검사, 커밋, 최종 검토까지 진행합니다. 합의한 제품 결과나 제외 범위를 바꿔야 할 때, 또는 되돌릴 수 없는 외부 작업에 승인이 필요할 때만 사용자에게 결정을 요청하고, 기술 설계와 구현 선택은 Claude가 처리합니다. Claude Code 플러그인으로 제공되므로 Claude의 구체적인 작업 순서를 고정하지 않고도 팀의 여러 저장소에 같은 통제 방식을 적용할 수 있습니다.
플러그인 마켓플레이스를 지원하는 버전의 Claude Code가 필요합니다.
| 필요한 작업 | 시작 명령 | 플러그인 |
|---|---|---|
| 백엔드, API, CLI 또는 일반 변경을 처음부터 끝까지 구현 | /recipe-implement |
dev-workflows |
| 구현 전에 백엔드 또는 일반 변경을 설계 | /recipe-design |
dev-workflows |
| React / TypeScript 프런트엔드를 설계하고 구현 | /recipe-front-design → /recipe-front-plan → /recipe-front-build |
dev-workflows-frontend |
| 백엔드와 React 프런트엔드를 함께 구현 | /recipe-fullstack-implement |
dev-workflows-fullstack |
| 완성된 구현이 합의한 결과에 맞는지 검토 | /recipe-review 또는 /recipe-front-review |
dev-workflows 또는 dev-workflows-frontend |
| 저장소별 품질 규칙 설정 | /recipe-quality-profile |
모든 워크플로 플러그인 |
| 수정 방법을 정하기 전에 문제를 조사 | /recipe-diagnose |
모든 워크플로 플러그인 |
| 코드에서 기존 시스템 문서를 생성 | /recipe-reverse-engineer |
dev-workflows 또는 dev-workflows-fullstack |
| 일회성 실험이나 프로토타입 | Claude Code를 직접 사용 | 없음 |
# 1. Claude Code 실행
claude
# 2. 마켓플레이스 추가
/plugin marketplace add shinpr/claude-code-workflows프로젝트에 맞는 플러그인을 설치하세요. 설치 후 /reload-plugins 실행 안내가 나오면 recipe를 호출하기 전에 실행하세요.
# 백엔드 또는 일반 변경
/plugin install dev-workflows@claude-code-workflows
/recipe-implement "Add rate limiting to the public API"
# 프런트엔드
/plugin install dev-workflows-frontend@claude-code-workflows
/recipe-front-design "Add account recovery screens"
# 풀스택
/plugin install dev-workflows-fullstack@claude-code-workflows
/recipe-fullstack-implement "Add user authentication with JWT + login form"워크플로 플러그인은 하나만 설치하세요. dev-workflows-fullstack에는 백엔드와 프런트엔드 워크플로가 모두 포함되어 있습니다. 이전에 dev-workflows의 풀스택 recipe를 사용했다면 dev-workflows-fullstack으로 이전하세요.
/recipe-front-design은 해당하는 UI Spec과 Design Doc이 검토 및 승인되면 종료됩니다. 계속 진행하려면 /recipe-front-plan과 /recipe-front-build를 실행하세요. 백엔드나 일반 변경에는 같은 단계로 구성된 /recipe-design, /recipe-plan, /recipe-build가 있습니다.
Claude Code는 프로젝트 범위의 마켓플레이스와 플러그인을 지원합니다. 생성된 .claude/settings.json을 커밋하면 기여자도 같은 워크플로 플러그인을 사용하도록 안내할 수 있습니다.
claude plugin marketplace add shinpr/claude-code-workflows --scope project
claude plugin install dev-workflows-fullstack@claude-code-workflows --scope projectdev-workflows-fullstack은 저장소에 맞는 플러그인으로 바꾸세요. 프로젝트 범위 및 관리형 설치 방법은 Claude Code 플러그인 문서를 참고하세요.
flowchart LR
A[Request] --> B[Agree on outcome and exclusions]
B --> C{One evident implementation path?}
C -->|Yes| S[Direct task cycle]
S --> J[Complete]
C -->|No| D[Inspect, design, and review]
D --> E[Approve implementation scope]
E --> F[Per task: implement, verify, quality-check, commit]
F --> I[Independent implementation and security review]
I -->|Correction| F
I -->|Boundary changed| B
I -->|Passed| J[Complete]
경로는 파일 수가 아니라 변경에 필요한 제품 결정과 설계 결정의 수에 따라 달라집니다. 하나의 책임 안에서 기존 패턴을 따르는 단일 결과라면 바로 작업 주기로 들어갑니다. 여러 책임에 걸치거나 장기적으로 유지할 설계 결정이 필요한 변경은 먼저 검토된 Design Doc과 Work Plan을 만들고, 결정에 따라 PRD, UI Spec, ADR을 더합니다.
검토 제안이 자동으로 작업이 되지는 않습니다. 메인 세션은 어떤 발견이 합의한 결과에 포함되는지 판단하고, 나머지는 이유를 남기고 거절합니다.
/recipe-implement "Lite mode. Add rate limiting to the public API"어떤 recipe든 요청에 라이트 모드를 지정하면 됩니다. 단계와 승인 지점은 그대로 두고 검사만 줄입니다. Design Doc을 저장소나 다른 Design Doc과 대조하지 않으며, 별도의 보안 검토도 생략합니다. 저장소 품질 검사는 커밋할 때마다 실행하지 않고 마지막 작업이 끝난 뒤 한 번 실행하며, 최종 코드 검토는 그대로 진행합니다. 라이트 모드는 Claude에게 해제를 요청할 때까지 해당 세션에서 계속 적용됩니다.
mcp-local-rag의 증분 동기화 기능은 파일 시스템 스캔, 스토리지, CLI, MCP 인터페이스에 걸친 42개 파일 변경이었습니다. 독립적인 보안 검토가 구현을 두 번 돌려보냈습니다. 검증 전에 파일을 읽는 문제와 심볼릭 링크된 상위 디렉터리를 통해 경로 제한을 벗어나는 문제를 찾아냈습니다.
실행은 존재하지 않는 ADR과 Design Doc을 참조하는 Work Plan에서 시작되어 기술 결정의 승인 근거가 불분명했습니다. 사용자는 Work Plan을 기준 자료로 삼기로 했고, recipe는 이를 계획된 13개 작업으로 나눴습니다. 최종 구현에는 승인된 동작을 검증하는 데 필요한 변경이 포함되었고, watch 모드와 영속화된 작업을 제외한 이유는 PR에 기록했습니다.
/recipe-implement "Add rate limiting to the public API"recipe는 변경 범위를 정하고 현재 구현을 조사한 뒤, 결정에 필요한 문서만 만듭니다. 결정이 필요한 지점에서 승인을 요청하고, 이후 계획된 구현과 최종 검토까지 진행합니다.
# 백엔드 또는 일반 변경
/recipe-design "Design rate limiting for the public API"
/recipe-plan
/recipe-build
# React 프런트엔드
/recipe-front-design "Build a user profile dashboard"
/recipe-front-plan
/recipe-front-build설계 recipe는 기존 구현을 조사하고 범위를 확인하며 필요한 문서를 만든 뒤, 독립적인 일관성 검토를 거쳐 승인을 기다립니다. 나중에 새 컨텍스트나 다른 담당자가 승인된 산출물을 바탕으로 계획과 구현을 이어갈 수 있습니다. 각 작업은 Work Plan에서 충족해야 할 설계 결정과 수용 기준을 명시하고, 최종 검토자는 이전 대화가 아닌 같은 자료를 기준으로 완성된 코드를 확인합니다.
프런트엔드 경로는 UI 구조나 동작을 더 설계해야 할 때 UI 분석과 UI Spec을 추가하고, 컴포넌트 아키텍처, React Testing Library, TypeScript 검사도 수행합니다.
예를 들어 대시보드 컴포넌트 두 개가 각각 로딩 상태를 올바르게 처리해도, 하나는 로딩 중이고 다른 하나는 실패했을 때 전체 화면의 동작은 정의되지 않았을 수 있습니다. UI Spec은 이 상태 조합을 기록하고 통합 전에 설계 및 테스트 작업과 연결합니다.
/recipe-fullstack-implement "Add user authentication with JWT + React login form"변경에 여러 독립적인 제품 결과가 있으면 하나의 PRD가 전체 기능을 다룹니다. 백엔드와 프런트엔드 설계는 분리하고, 일관성 검사로 그 경계를 확인하며, Work Plan은 수직 슬라이스를 사용해 통합을 일찍 검증합니다.
기존 풀스택 Work Plan에서 계속하려면 /recipe-fullstack-build를 사용하세요. 풀스택 플러그인에는 필요한 백엔드와 프런트엔드 recipe도 포함되어 있습니다.
워크플로 예시 더 보기
/recipe-review검토 워크플로는 완성된 구현을 합의한 결과와 저장소 기준에 맞춰 확인한 뒤 독립적인 보안 검토를 실행합니다. 수락된 수정은 구현이나 관련 문서 담당자에게 돌아가 다시 검토됩니다.
/recipe-diagnose "API returns 500 on user login"진단 워크플로는 실행 경로를 정리하고 의심되는 실패 지점을 검증하며 해결책의 장단점을 제시합니다. 코드는 변경하지 않습니다.
/recipe-reverse-engineer "src/auth module"코드에서 PRD와 Design Doc을 만들고 구현과 대조해 검증합니다. 기능이 백엔드와 프런트엔드에 걸쳐 있다면 풀스택 옵션을 사용하세요.
전체 사례는 How I Made Legacy Code AI-Friendly with Auto-Generated Docs를 참고하세요.
/recipe-front-adjust "Align the card spacing and actions with the design source"프런트엔드 플러그인은 외부 디자인 자료에 접근하는 방법을 기록하고 변경 대상 파일을 확인한 뒤, 조정이 검사를 통과할 때까지 시각 검증을 반복합니다.
모든 워크플로 진입점은 recipe- 접두사를 사용합니다. /recipe-를 입력하고 Tab 키를 누르면 설치된 항목을 확인할 수 있습니다.
백엔드 및 일반 recipe 모두 보기
| Recipe | 목적 | 사용 시점 |
|---|---|---|
/recipe-implement |
기능을 처음부터 끝까지 구현 | 새 기능과 전체 워크플로 |
/recipe-design |
설계 문서 작성 | 아키텍처 계획 |
/recipe-plan |
설계에서 Work Plan 생성 | 계획 단계 |
/recipe-build |
기존 Work Plan 실행 | 구현 재개 |
/recipe-review |
완성된 구현이 합의한 결과에 맞는지 검토 | 구현 후 확인 |
/recipe-quality-profile |
저장소별 품질 규칙 설정 | 품질 규칙 설정 |
/recipe-diagnose |
문제를 조사하고 해결책 비교 | 근본 원인 분석 |
/recipe-reverse-engineer |
코드에서 PRD와 Design Doc 생성 | 기존 시스템 문서화 |
/recipe-add-integration-tests |
통합 또는 E2E 테스트 추가 | 기존 코드의 커버리지 확보 |
/recipe-update-doc |
기존 문서 업데이트 및 검토 | 요구 사항 또는 설계 변경 |
프런트엔드 recipe 모두 보기
프런트엔드 플러그인은 React 전용 분석, 컴포넌트 아키텍처, React Testing Library, TypeScript 검사와 필요시 프로토타입 코드에서 UI Spec을 만드는 기능을 추가합니다.
| Recipe | 목적 | 사용 시점 |
|---|---|---|
/recipe-front-design |
해당 UI Spec과 프런트엔드 Design Doc 작성 | React 컴포넌트 아키텍처 |
/recipe-front-plan |
프런트엔드 Work Plan 생성 | 컴포넌트 계획 |
/recipe-front-build |
프런트엔드 Work Plan 실행 | React 구현 재개 |
/recipe-front-adjust |
외부 검증으로 구현된 UI 조정 | 시각적 개선 |
/recipe-front-review |
완성된 프런트엔드가 합의한 결과에 맞는지 검토 | 구현 후 확인 |
/recipe-quality-profile |
저장소별 품질 규칙 설정 | 품질 규칙 설정 |
/recipe-diagnose |
문제를 조사하고 해결책 비교 | 근본 원인 분석 |
/recipe-update-doc |
기존 문서 업데이트 및 검토 | 요구 사항 또는 설계 변경 |
사용자 지정 프롬프트나 CI를 통해 이미 오케스트레이션하고 있고 모범 사례 가이드만 필요하다면 dev-skills를 사용하세요. Claude가 변경을 처음부터 끝까지 계획하고 실행하며 검증하게 하려면 용도에 맞는 워크플로 플러그인을 설치하세요.
- Agent와 recipe skill 없이 최소한의 컨텍스트만 사용
- 정해진 절차를 강제하지 않고 개발, 테스트, 설계, 문서 가이드 제공
- 작업에 맞는 skill 자동 로드
dev-skills와 워크플로 플러그인을 함께 설치하지 마세요. 두 플러그인은 같은 skill을 공유하므로 중복된 설명 때문에 컨텍스트 한도에 도달한 뒤 Claude Code가 skill을 무시할 수 있습니다.
/plugin install dev-skills@claude-code-workflows플러그인 유형을 전환하려면 다음과 같이 실행하세요.
# dev-skills -> dev-workflows
/plugin uninstall dev-skills@claude-code-workflows
/plugin install dev-workflows@claude-code-workflows
# dev-workflows -> dev-skills
/plugin uninstall dev-workflows@claude-code-workflows
/plugin install dev-skills@claude-code-workflowsQ: 오류가 발생하면 어떻게 되나요?
A: 워크플로가 승인된 목표 안에서 테스트, 타입, lint, 빌드 실패를 처리합니다. 같은 책임이나 계약에 필요한 인접 변경도 포함됩니다.
Q: OpenAI Codex CLI용 버전도 있나요?
A: 네. **codex-workflows**는 같은 워크플로 모델을 Codex CLI 환경에 맞게 조정한 버전입니다.
Q: docs/plans/의 Work Plan과 작업 파일을 커밋해야 하나요?
A: 아니요. recipe는 docs/plans/를 임시 작업 상태로 취급합니다. 사용이 끝난 작업 파일과 중간 수정 파일은 정상 완료 후 삭제됩니다. Work Plan은 검토나 나중 작업을 위해 남을 수 있으며 더 이상 필요하지 않을 때 삭제하면 됩니다. 이 작업 상태가 Git에 포함되지 않도록 프로젝트의 .gitignore에 다음 줄을 추가하세요.
docs/plans/
PRD, ADR, UI Spec, Design Doc은 각각 docs/prd/, docs/adr/, docs/ui-spec/, docs/design/에 있으며 커밋 대상입니다.
관련 자료
- Why LLMs Are Bad at 'First Try' and Great at Verification: 한 세션이 생성과 평가를 모두 맡는 것보다 외부 피드백과 새 컨텍스트가 더 신뢰할 수 있는 이유.
- When Better Models Make Old Agent Workflows Worse: 구체적인 경로를 강제하지 않으면서 경계와 근거를 엄격하게 다루는 이유.
- Reasoning Effort Is Not a Quality Setting: 탐색 범위가 넓더라도 현재 목표에 필요한 작업으로 수렴해야 하는 이유.
- Stop Putting Everything in AGENTS.md: 항상 읽는 지시는 짧게 유지하고 skill, 설계 결정, 작업 가이드는 필요할 때 불러와야 하는 이유.
MIT License. 자유롭게 사용, 수정, 배포할 수 있습니다.
자세한 내용은 LICENSE를 참고하세요.
@shinpr이 개발하고 유지보수합니다.