01
이럴 때 써
상황별로 어떤 에이전트/스킬을 쓰면 되는지 바로 찾기
새 시작
아이디어가 생겼을 때
사업 아이디어 하나 → GO/HOLD/KILL 판정 → 전체 파이프라인 자동 실행
idea-to-deploy@expert-planner@decision
기능 추가
새 기능을 추가해야 할 때
아키텍처 문서가 있는 상태에서 기능 범위 정의 → Task 분해 → 구현
@task-breakdown@implementationtestgen-automation
버그/장애
프로덕션에서 에러가 났을 때
오류 메시지 → 근본 원인 분석 → 핫픽스 경로 제안 → 자동 수정 시도
@incident-responder@healerpost-deploy
배포 전
배포하기 전 점검이 필요할 때
보안·성능·시크릿 유출·UX까지 배포 전 전체 게이트 자동 실행
@security-tester@performance-auditor@secret-guard
코드 리뷰
PR 올리기 전 코드를 검토할 때
변경 diff → 위험 라인 선별 → 코드 냄새 감지 → 아키텍처 정합성 확인
@pr-reviewer@code-quality@architecture-drift-detector
팀 인계
새 팀원이 프로젝트를 인수받을 때
코드베이스 구조·실행경로·리스크를 빠르게 파악해 온보딩 가이드 생성
@codebase-onboarding@code-analyzer
마케팅/성장
제품을 런칭하거나 마케팅이 필요할 때
GTM 전략 → 채널별 콘텐츠 생성 → 그로스 루프 설계까지 자동화
@gtm-strategist@marketing-content@growth-loop-designer
주간 점검
매주 코드베이스 건강도를 확인할 때
코드품질·레거시·보안·성능·설계 정합성 6가지 자동 점검 후 리포트
weekly-review-automation
비용 관리
API 비용이 걱정될 때
에이전트 체인 실행 전 예상 토큰/비용 추정 → 예산 초과 시 자동 HOLD
@cost-guard
레거시 정리
오래된 코드를 정리하고 싶을 때
미사용 코드·의존성 식별 → 안전한 제거 순서 → 마이그레이션 경로 제안
@legacy-cleaner@dev-auditor
데이터 분석
사용자 행동 데이터를 분석할 때
코호트/리텐션 분석 → 이탈 패턴 → LTV 추정 → 이벤트 스키마 설계
@cohort-analyst@event-schema-designer@data-analyst
인프라 설계
클라우드 인프라를 코드로 관리할 때
Terraform/Pulumi/CDK 모듈 구조 설계 → 환경 분리 → 비용 최적화
@iac-designer@finops-advisor@cicd-designer
02
Phase 완전 가이드
아이디어 → 분석 → 개발 → 운영까지 8단계 전체 흐름
Pre
0
0
사업 기획 — "이 아이디어 사업이 되나?"
시장 분석, 경쟁사 조사, 수익 모델 설계. 개발 시작 전에 사업 타당성을 검증한다. 비개발자도 Claude Chat만으로 이 단계를 완료할 수 있다.
1
Decision — "GO / HOLD / KILL 판정"
context·market·user·journey·solution 5개 문서를 분석해 사업 실행 여부를 AI가 판정한다. 근거 없는 HOLD는 무효. GO 판정 시 decision-lock.md 생성.
2
Scope / Iteration — "MVP 범위 확정"
출시 가능한 최소 기능 정의. '이번 스프린트에 뭘 할지' 범위를 고정한다. 범위 밖 기능 추가 요청은 자동 차단.
3
Decision Lock — "되돌릴 수 없는 확정"
범위와 방향을 잠근다. decision-lock.md 없이는 Phase 4 이후 진입 불가. 변경이 필요하면 반드시 [HUMAN_OBJECTION] 포맷으로 근거 제출.
3.5
Architecture — "어떻게 만들지 설계"
시스템 구조, 기술 스택, API 명세, DB 스키마, 화면 설계를 자동 생성한다. 이 단계의 설계가 이후 모든 구현의 기준이 된다.
4
Execution Gate — "실행 준비 완료 확인"
선행 조건(decision-lock, architecture 문서)을 자동 점검하고 OPEN/HOLD를 판정한다. GATE OPEN 이후에만 코드 작성 시작 허용.
5
Task Breakdown — "무엇부터 만들지"
아키텍처 문서를 기반으로 구현 Task를 분해하고 의존성·우선순위를 정렬한다. 이 리스트가 구현의 유일한 기준.
6
Implementation — "실제로 코드 작성"
Task 단위로 코드를 구현한다. 구현 완료 시 TestGen → UX Gate → Code Review가 자동 실행된다. 3~5 Task마다 Execution Review.
7
Execution Review — "계속 / 종료 / 피벗"
현재까지의 구현을 평가하고 계속·종료·보류·피벗·중단 중 하나를 판정한다. 판정 결과가 [JUDGMENT] 태그로 자동 기록.
8+
Post-Deploy — "배포 후 운영 자동화"
장애·피드백·성장 3가지 신호를 자동 감지해 분기한다. 장애 → @incident-responder, 피드백 → 분석·우선순위화, 성장 → GTM 자동화.
03
에이전트 카탈로그
71개 Builder 에이전트 — 카테고리별 정리. 호출: @에이전트명
사업 기획 / 의사결정
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @expert-planner | 서비스 분석 → Target·Value·수익 모델·경쟁 분석·사업계획서 | docs/business/ |
| @researcher | 시장·경쟁·기술 자료 조사. 결론 중심 요약 제공 | 리서치 요약 |
| @decision | GO/HOLD/KILL 판정. 근거 없는 HOLD 불가 | [GATE]/[REASON] |
| @okr-coach | OKR 설계·품질 검증·분기 회고·팀 정렬 | OKR 문서 |
| @business-impact-prioritizer | 개발 중 Task를 매출·전환율·유지율 기준으로 P0~Drop 재정렬 | 우선순위 리스트 |
설계
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @mvp-builder | docs/05~08.md 자동 생성 — scope·mvp·architecture·execution 계획 | docs/05~08.md |
| @architecture | 시스템 아키텍처 설계. docs/07_architecture.md 생성 | 07_architecture.md |
| @screen-designer | 전체 화면 목록·구성요소·전환 플로우·UI 상태 명세 | docs/screens/ |
| @api-designer | 엔드포인트·요청/응답 스키마·인증·에러코드·OpenAPI 3.0 초안 | docs/api/ |
| @db-designer | ERD·테이블 정의서·SQL DDL·Prisma 스키마·마이그레이션 전략 | docs/db/ |
| @stack-advisor | 프레임워크 추천 + 보일러플레이트 디렉토리 구조 제공 | 스택 명세 |
| @event-schema-designer | 사용자 행동 이벤트 스키마·퍼널 맵·CRM 연동·대시보드 설계 | 이벤트 정의표 |
개발 / 실행
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @task-breakdown | 아키텍처 기반으로 Task 분해·의존성·우선순위 정렬 | tasks/task-list.md |
| @implementation | 코드 작성 전담. Task ID 기반 구현 | 소스 코드 |
| @implementation-orchestrator | 구현 선행조건 확인 + 시작 안내 | 실행 준비 체크 |
| @execution-manager | Execution Gate 통제 — decision-lock 확인 후 OPEN/HOLD 판정 | [GATE]: OPEN/HOLD |
| @execution-review | 3~5 Task마다 중간 점검. 계속/종료/피벗 판정 | [JUDGMENT] |
| @pipeline-coordinator | Phase 전환 조건 자동 판별 + 상태 스냅샷 갱신 | Phase 상태 |
QA 파이프라인
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @testgen | Playwright/Jest/Vitest/pytest 테스트 자동 생성 | tests/ |
| @healer | 테스트 실패 원인 분석 + 수정 제안. Self-Healing | 수정 패치 |
| @testops | 테스트 결과 집계·Flaky 감지·트렌드 추적 | 테스트 리포트 |
| @code-quality | 코딩 규칙 검증·중복 감지·ESLint/TS 검사 | 품질 리포트 |
| @ux-gate | 화면·플로우·전체 사용자 여정 UI/UX 종합 검증 (WCAG AA) | UX 판정 |
| @security-tester | API·권한·취약점 보안 검증. 릴리즈 전 보안 게이트 | 보안 리포트 |
| @integration-tester | FE-BE 연동 시나리오·API 계약 검증 | 연동 결과 |
| @performance-auditor | LCP·TTI·번들 크기·API 지연 점검. READY/HOLD 판정 | 성능 리포트 |
| @pr-reviewer | GitHub PR 위험 라인·코드 냄새·보안 이슈 자동 분석 | PR 리뷰 |
| @secret-guard | 커밋 전 API Key·Secret·.env 유출 방지 게이트 | 보안 게이트 |
배포 / 운영
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @deployment | 배포 전 체크리스트·배포 후 검증·롤백 안내 | 배포 가이드 |
| @deployment-secrets-auditor | 배포 환경 시크릿 감사. CI/CD 시크릿 보안 검증 | 감사 리포트 |
| @incident-responder | 프로덕션 장애 → 근본 원인 가설·즉시 조치 체크리스트·핫픽스 포인트 | 대응 가이드 |
| @devops-guard | 개발 환경 감시·Docker/Git 문제 진단 | 환경 진단 |
| @release-manager | Semantic Versioning 판정 + CHANGELOG.md + 릴리즈 노트 생성 | CHANGELOG.md |
| @cicd-designer | GitHub Actions 워크플로우 + 환경별 배포 파이프라인 설계 | .github/workflows/ |
| @iac-designer | Terraform/Pulumi/AWS CDK 인프라 코드 설계 + 환경 분리 | IaC 코드 초안 |
| @finops-advisor | AWS/GCP/Azure 비용 가시화·이상 탐지·Right-Sizing 전략 | 비용 최적화 계획 |
| @feature-flag-manager | Feature Flag 설계·Canary 롤아웃·A/B 실험 셋업·Kill Switch | Flag 설계서 |
마케팅 / 성장
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @gtm-strategist | 배포 후 Go-to-Market 전략·마케팅 채널·유저 획득 프레임워크 | docs/marketing/ |
| @marketing-content | 소셜 포스팅·광고 카피·이메일 시퀀스·블로그·콘텐츠 달력 | 콘텐츠 초안 |
| @growth-loop-designer | AARRR 병목 진단·PLG/Viral 루프 설계·리텐션 전략·NSM 정의 | 그로스 플랜 |
| @cohort-analyst | D1/D7/D30 리텐션 커브·Churn 분석·LTV 추정 | 코호트 리포트 |
| @seo-specialist | Technical SEO 감사·키워드 전략·콘텐츠 갭·Core Web Vitals | SEO 리포트 |
| @qualitative-analyst | 인터뷰/VOC/NPS 정성 데이터 → 패턴·인사이트·기회 영역 추출 | 정성 분석 |
| @ops-issue-triage | VOC/CS/이탈 포인트·반복 오류 → P0~P3 운영 이슈 분류 | 이슈 우선순위 |
| @cs-support-agent | CS 티켓 버그/기능/결제/기타 분류 + 표준 응답 초안 생성 | 응답 초안 |
분석 / 감사 / 도구
| 에이전트 | 역할 | 출력 |
|---|---|---|
| @dev-auditor | 코드베이스 종합 건강도·기술 부채·배포 이슈·설계 대비 구현 분석 | 감사 리포트 |
| @architecture-drift-detector | 설계 문서 vs 실제 구현 정합성 자동 감지. 구조 불일치 경고 | 드리프트 리포트 |
| @legacy-cleaner | 미사용 코드·의존성 식별 + 안전한 제거 순서 + 마이그레이션 경로 | 정리 로드맵 |
| @code-analyzer | 코드베이스 구조 파악·TASK 관련 파일 식별·변경 영향 분석 | 분석 리포트 |
| @codebase-onboarding | 기존 프로젝트 인수 전 구조·실행경로·리스크 빠른 파악 | 온보딩 가이드 |
| @data-analyst | CSV/JSONL/SQL 결과 분석·통계 요약·이상값 탐지·트렌드 분석 | 데이터 리포트 |
| @data-pipeline-designer | 원천 데이터 수집/ETL/저장/분석 레이어 전체 파이프라인 설계 | 파이프라인 설계 |
| @cost-guard | 에이전트 체인 실행 전 토큰/비용 추정. 예산 초과 시 HOLD | [GATE]: HOLD/OPEN |
| @agent-evaluator | 에이전트 출력 계약 회귀 테스트. 필수 포맷 자동 검증 | 검증 리포트 |
| @agent-log-auditor | 에이전트 실행 로그 분석·응답 품질·라우터 태그 커버리지 리포트 | 로그 리포트 |
| @pattern-extractor | 채널별 반복 패턴 클러스터링 → Skill/Agent 자동화 후보 도출 | [PATTERN_ANALYSIS] |
| @memory-manager | 프로젝트 컨텍스트 저장/복원. 대화 단절 후 상태 복원 | 메모리 파일 |
| @git-helper | 커밋 메시지 생성·브랜치 관리·머지 충돌 해결 | Git 명령 |
| @writer | 기획서/투자자료 톤 변환. AI 냄새 제거·자연어 재작성 | 재작성 문서 |
| @ide-router-verifier | Claude Code/Cursor/Codex/Windsurf/VS Code 라우터 정합성 검증 | 검증 리포트 |
04
커맨드 레퍼런스
Claude Code에서 /커맨드명으로 직접 실행
/decision
docs/00~04.md를 분석해 GO/HOLD/KILL 판정 실행. decision-lock.md 생성.
언제: Phase 1 완료 후, 사업 방향 확정 필요 시
/execution
decision-lock.md 확인 후 Execution Phase 시작. @execution-manager 자동 호출.
언제: GO 판정 후, 개발 시작 전
/task-breakdown
docs/07_architecture.md 기반으로 tasks/task-list.md 자동 생성.
언제: Architecture 완료 후, 구현 시작 전
/ux-gate
전체 화면·플로우 UI/UX 종합 검증 실행. WCAG AA 기준 점검.
언제: 구현 완료 후, 배포 전
/review
코드 품질 검증. ESLint·TypeScript·중복·코드 냄새 분석.
언제: PR 전, 스프린트 완료 후
/pr-review
GitHub PR 자동 리뷰. 위험 라인·보안 이슈·영향도 판정.
언제: PR 생성 직후
/brainstorm
기능·방향·접근법에 대한 아이디어 다양화. 결론 없이 가능성 탐색.
언제: 방향이 막혔을 때, 초기 기획 시
/standards-check
프로젝트 코딩 표준·컨벤션 준수 여부 자동 검증.
언제: 신규 팀원 합류 후, 스프린트 시작 전
/planner-review
서비스 기획 종합 리뷰. 불필요 기능 식별, 남은 작업 정리.
언제: 스프린트 리뷰, 제품 방향 재검토 시
/debug
버그 원인 분석. @healer 자동 연동으로 수정 제안까지.
언제: 테스트 실패, 런타임 에러 발생 시
/commit
4가지 게이트(보안·범위·형식·Task연결) 체크 후 커밋 메시지 생성.
언제: 코드 변경 후 커밋 전
/fast
Fast mode 토글. 동일 Opus 4.6 모델, 출력 속도 향상.
언제: 빠른 반복 작업 시
05
실전 레시피
실제 상황별 단계별 실행 가이드
R-01
새 아이디어 → 배포까지 (전체 파이프라인)
▶
1
"~만들고 싶어" 입력 →
idea-to-deploy 스킬 자동 실행2
@expert-planner가 docs/business/ 사업 문서 생성3
/decision 실행 → GO 판정 → decision-lock.md 생성4
@architecture + @api-designer + @db-designer로 설계 완료5
/execution → Gate OPEN → /task-breakdown6
Task 단위 구현 → TestGen → UX Gate → Code Review 자동 반복
7
@secret-guard + @security-tester → @deployment → 배포8
post-deploy 스킬 → 장애/피드백/성장 자동 분기 운영
R-02
기능 하나 추가하기 (기존 프로젝트)
▶
1
"[기능명] 추가해줘" →
@planner-review로 현황 파악2
아키텍처 영향도 확인 →
@architecture-drift-detector3
Task 추가 →
/task-breakdown 재실행 또는 수동 추가4
@implementation으로 구현 → testgen-automation 자동 실행5
/review + /ux-gate → /commit → PR 생성
R-03
프로덕션 버그 긴급 수정
▶
1
오류 메시지/스택 트레이스 입력 →
@incident-responder 호출2
P0~P3 등급 분류 + 근본 원인 가설 + 즉시 조치 체크리스트
3
@healer로 수정 제안 → hotfix/ 브랜치에서 구현4
@security-tester로 패치 검증 → /commit → 즉시 배포5
배포 후
post-deploy로 재발 방지 루프 작동
R-04
새 팀원이 프로젝트 인수받기
▶
1
"이 프로젝트 온보딩해줘" →
@codebase-onboarding2
구조·실행경로·리스크 3가지 자동 파악 → 온보딩 가이드 생성
3
@code-analyzer로 핵심 파일·변경 영향도 지도 확인4
@dev-auditor로 현재 기술 부채·건강도 전체 파악5
tasks/task-list.md 확인 → 남은 Task부터 순서대로 착수
R-05
배포 전 전체 게이트 체크
▶
1
@secret-guard → .env·API Key 노출 여부 확인2
@security-tester → OWASP Top 10 기반 취약점 스캔3
@performance-auditor → LCP·번들 크기·API 지연 점검4
/ux-gate → 모바일·접근성·빈 상태 UI 검증5
@deployment-secrets-auditor → CI/CD 환경 변수 감사6
모두 PASS →
@deployment로 최종 배포 체크리스트 실행06
FAQ
자주 묻는 질문들
"지침에 따라서"가 뭔가요?
AI-SYSTEM의 라우터 트리거 문구입니다. 이 말을 하면 Claude가 현재 프로젝트 상태(어떤 파일이 있는지, 어디까지 진행됐는지)를 자동으로 파악하고, 적절한 Phase의 에이전트/커맨드를 알아서 실행합니다. 매번 어떤 명령어를 써야 하는지 기억하지 않아도 됩니다.
에이전트와 스킬의 차이가 뭔가요?
에이전트(
@이름)는 특정 역할을 가진 전문 AI입니다. 직접 호출하거나 라우터가 자동으로 선택합니다. 스킬은 에이전트들을 순서대로 자동 실행하는 파이프라인입니다. 예를 들어 testgen-automation 스킬은 @testgen → @healer → @testops를 자동으로 연결 실행합니다.[GATE]: OPEN이 뭔가요?
Phase 4 Execution Gate의 판정 결과입니다. decision-lock.md가 존재하고 아키텍처 문서가 완비되었을 때 OPEN이 됩니다. OPEN 이전에는 코드 작성을 시작하지 않습니다. HOLD가 나오면 [REASON]에 명시된 조건을 충족한 후 다시 시도하세요.
비개발자도 쓸 수 있나요?
네. Phase 0~3(사업 분석·판단)은 Claude.ai 채팅만으로 완료할 수 있습니다. 터미널이나 IDE가 필요 없습니다.
prompts/01_decision.md를 Claude Chat에 복사·붙여넣기 하면 됩니다. 개발이 필요한 Phase 5~7부터 개발자와 협업하세요.Cursor, VS Code, Windsurf 중 어떤 IDE를 써야 하나요?
세 IDE 모두 동일하게 지원합니다. 현재 쓰는 IDE를 계속 사용하세요. AI 지원이 가장 강력한 순서는 Claude Code > Cursor > Windsurf > VS Code입니다. Claude Code는 터미널 기반으로 에이전트 모든 기능을 100% 활용할 수 있습니다.
HOLD가 나왔을 때 어떻게 해야 하나요?
응답의 [REASON] 섹션을 확인하세요. 누락된 문서나 조건이 명시되어 있습니다. 그 조건을 충족한 후 다시 같은 커맨드를 실행하면 됩니다. "느낌상 HOLD", "그냥 더 생각해보자" 같은 근거 없는 HOLD는 시스템이 무효 처리합니다.
에이전트 응답에서 태그 블록([GATE], [JUDGMENT] 등)이 왜 중요한가요?
태그 블록은 AI의 판단을 기계가 읽을 수 있는 형식으로 기록한 것입니다. Stop Hook이 이 태그를 파싱해 자동으로 파일을 생성하거나 태스크를 업데이트합니다. 예를 들어
[DECISION]: GO가 나오면 decision-lock.md가 자동 생성되고, [TASK_COMPLETE]: T-XX가 나오면 task-list.md가 자동 업데이트됩니다.설정 없이 바로 시작할 수 있나요?
npm install @wjj1113/ai-system 또는 git clone 후 npm run setup을 실행하면 모든 에이전트와 설정이 자동으로 구성됩니다. Claude Code 기준 약 2분이면 준비 완료. npm run setup:validate로 설치 상태를 확인하세요.