🐘🐟 코끼리 금붕어 개발 패턴 (Elephant & Goldfish Pattern)
📌 개요
- 🐘 코끼리 (Coordinator, 즉 당신): 전체 맥락을 기억합니다. 커뮤니케이션, CUJ 명세 작성, 작업 할당, 결과 검토를 담당합니다. 직접 코드를 작성하거나 테스트를 실행하지 않습니다.
- 🐟 금붕어 (Coder / Tester / Reviewer): 과거 이력이 없는 무상태(stateless) 서브 에이전트. CUJ만 보고 작업하며, 완료 후 소멸되어 컨텍스트 오염을 방지합니다.
🚦 Step 0: 먼저 이 작업이 본 워크플로우를 따라야 하는지 판단하세요
이것이 첫 번째 결정입니다. 건너뛰지 마세요.
| 작업 유형 | 본 워크플로우 적용? |
|---|---|
| 새로운 기능 또는 모듈 추가 | ✅ |
| 기존 기능의 동작 수정 | ✅ |
| 외부 인터페이스 변경을 수반하는 리팩터링 | ✅ |
| 로직 변경이 필요한 버그 수정 | ✅ |
| 순수 문서 업데이트 (README, 주석) | ❌ |
| 코드 포맷팅 / 린트 | ❌ |
| 의존성 버전 업그레이드 (동작 변경 없음) | ❌ |
| 설정 파일 미세 조정 | ❌ |
| 긴급 핫픽스 (이미 배포된 심각한 버그) | ❌ 즉시 수정, 사후에 반드시 Tester 검증 추가 |
판단이 어려울 때의 기본값: 변경사항이 10줄 이하이고 외부에서 관찰 가능한 동작을 변경하지 않음 → 워크플로우를 따르지 않음.
❌ 적용되지 않는 경우, 프로젝트 기존 규칙에 따라 작업하고, 본 Skill을 언급하거나 CUJ를 작성하기 위해 워크플로우를 억지로 따르지 마세요.
🎯 핵심 원칙
- 금붕어 테스트 기준: 완전히 새로운 서브 에이전트(금붕어)가 CUJ 문서만 보고 설명 → 구현 → 테스트 전체 과정을 독립적으로 완료할 수 있어야 합니다. 불가능하다면, 명세가 충분히 잘 작성되지 않은 것입니다. AI가 충분히 똑똑하지 않은 것이 아닙니다.
- 역할 엄격 분리: 코드를 작성하는 사람(Coder)이 자신의 시험지를 채점할 수 없습니다(Tester / Reviewer).
- 명세 + 테스트: CUJ는 '무엇을 원하는지' 정의하고, 테스트는 '얻었는지' 증명합니다. 둘 중 하나가 없으면 CUJ는 사람이 읽는 문서로 전락하며, 금붕어의 실행 가능한 계약이 아닙니다.
- Markdown만 신뢰하지 말고, 스크립트를 신뢰하세요:
scripts/validate_cuj.py를 사용하여 객관적인 검사를 수행하고, 자기 만족에 의존하지 마세요.
🚀 워크플로우
Step 1: 필요에 따라 참고 자료 로드
한 번에 모두 읽지 마세요. 현재 실제 필요에 따라 로드하는 것이 점진적 공개(Incremental Disclosure)의 핵심입니다:
| 언제 읽는가 | 어떤 자료를 읽는가 |
|---|---|
| 금붕어를 할당하기 전 (필독) | references/dispatch-prompts.md |
| 특정 역할이 특정 작업을 할 수 있는지 확실하지 않을 때 | references/role-separation.md |
| CUJ를 어느 수준까지 작성해야 하는지, 또는 검증이 계속 실패할 때 | references/cuj-workflow.md |
| CUJ 작성을 시작할 때 | assets/cuj-template.md (형식)assets/cuj-001-user-login.md (합격 기준) |
| 사용 중인 도구에 서브 에이전트 메커니즘이 없을 때 | references/role-separation.md의 도구 간 비교표 |
Step 2: CUJ 작성
- 템플릿 형식에 따라 프로젝트의
cuj/디렉토리에 파일 이름cuj-XXX-간단한-설명.md으로 저장합니다. - frontmatter의
id는 반드시 파일 이름 접두사와 일치해야 합니다(Gotchas 참조). - 요구사항에 모호한 부분이 있으면 먼저 명확히 한 후 작성합니다. 명확히 하는 메커니즘은
cuj-workflow.mdStep 2를 참조하세요(본 Skill의 책임 범위 밖).
Step 3: CUJ 검증 (객관적 관문)
python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/
- exit code 0인 경우에만 Step 4로 진행 가능합니다.
- 0이 아닌 경우 → 오류 메시지에 따라 CUJ를 수정하고, 통과할 때까지 다시 실행하세요. 우회하지 마세요.
- 통과 후에도 여전히 금붕어 테스트 질문을 스스로에게 해야 합니다. 스크립트는 구조를 검증하고, 이 질문은 사용성을 검증합니다.
Step 4: 금붕어 할당 및 수렴
할당 전 필독 references/dispatch-prompts.md의 '❌ 포함 금지' 목록. 역할 분리가 가장 자주 무너지는 순간은 바로 할당하는 순간입니다.
순서대로 실행하며, 병렬 실행이나 역할 병합은 허용되지 않습니다:
- 4a. Coder 할당 — CUJ 경로와 수정할 파일 경로만 제공하고, 대화 기록은 제공하지 않습니다.
- 4b. Tester 할당 (독립 서브 에이전트) — CUJ의 승인 기준과 테스트 케이스만 제공하고, Coder의 구현 설명이나 산출물 요약은 제공하지 않습니다.
- 4c. 테스트 실패 시 — 실패 메시지를 새로운 Coder 금붕어에게 전달하여 수정하고, 4b로 돌아가 재테스트합니다. 동일한 Coder가 반복해서 수정하여 통과하도록 하지 마세요. 이는 자신의 시험지를 채점하는 것과 같습니다.
- 4d. Reviewer 할당 (독립 서브 에이전트, 선택 사항) — 코드 경로와 승인 기준만 제공하고, Tester의 결과는 제공하지 않습니다.
- 4e. Coordinator 취합 — CUJ의
status를 업데이트하고, 사용자에게 실제 결과를 보고합니다.
수렴 조건: 모든 승인 기준에 해당 테스트가 존재하고 모두 통과해야 합니다.
실패 상한: 동일한 CUJ에 대해 4b ↔ 4c 루프를 3회 실행했음에도 수렴하지 않는 경우 → 맹목적 수정을 중단하고,
Step 2로 돌아가 CUJ 자체에 문제가 있는지 검토합니다(명세 모순, 측정 불가능한 승인 기준, 전제 조건 누락).
⚠️ 주의사항 (Gotchas)
알지 못하면 빠지는 환경적 사실:
id는 반드시 파일 이름 접두사와 일치해야 합니다 —id: cuj-001은cuj-001-*.md에 대응해야 하며, 일치하지 않으면 즉시 실패로 간주합니다.- 디렉토리 모드는
cuj-*.md만 스캔합니다 — 파일 이름을 잘못 지정하면(예:cju-001-x.md) '실패'가 아닌 '건너뜀'으로 분류되므로, 출력 시 건너뛴 목록을 주의 깊게 확인하세요. - 섹션 콘텐츠 임계값은 언어에 따라 다릅니다 — 중일한 문자 10자, 순수 서양 문자 30자로 섹션별로 판단합니다.
--min-section-chars N으로 재정의할 수 있습니다. - 검증 스크립트는 Python 3.12+가 필요합니다. 프로젝트 자체가 Python 프로젝트가 아니더라도 마찬가지입니다.
- '건너뜀'은 '통과'와 같지 않습니다 — 요약 줄의
통과숫자를 확인하고, ✅ 표시만 보지 마세요. - 스크립트는 구조만 검증하고, 의미는 검증하지 않습니다 — 'It should work correctly'는 구조적으로 구체적인 승인 기준과 다르지 않으며, 스크립트를 통과할 수 있습니다. 스크립트는 바닥이고, 금붕어 테스트 체크포인트가 천장입니다.
🛑 자기합리화 방지 및 위험 신호 (Anti-Rationalization & Red Flags)
적용 범위: 다음 규칙은 본 워크플로우를 따르는 기능 개발 중에만 유효하며, 항상 적용되는 철칙은 아닙니다. 운영 점검, 배포 전 검증, 긴급 핫픽스는 프로젝트 기존 규칙에 따라 처리합니다. 도입 시 프로젝트 기존 규범과 충돌하는 경우, 영역을 나누어 해결하고 상호 덮어쓰지 마세요.
- ❌ 절대 금지 Coordinator가 직접 10줄이 넘는 변경 사항을 작성하거나 테스트 명령을 실행하는 것.
- ❌ 절대 금지 Coder의 구현 맥락을 Tester에게 복사하는 것. Tester는 깨끗한 컨텍스트에서 CUJ 승인 기준에 따라 독립적으로 테스트해야 합니다.
- ❌ 절대 금지 검증 스크립트가 ✅를 출력했다고 해서 통과한 것으로 간주하는 것. 요약 줄의
통과숫자를 확인하세요. - ❌ 절대 금지 테스트를 통과시키기 위해 테스트를 수정하거나 승인 기준을 완화하는 것. 테스트 실패는 가치 있는 정보입니다.
더 많은 일반적인 변명과 반박은 references/role-separation.md의 Anti-Rationalization 표를 참조하세요.
🔲 책임 범위
본 Skill은 코끼리 금붕어 메커니즘 자체만 담당하며, 전체 개발 수명 주기를 포괄하지 않습니다:
| 단계 | 본 Skill | 설명 |
|---|---|---|
| ① 요구사항 정의 | 범위 밖 | 인간의 책임 |
| ② 요구사항 명확화 | 범위 밖 (계약 정의) | 각 도구가 자체적으로 처리, cuj-workflow.md Step 2 참조 |
| ③ CUJ 생성 | ✅ 핵심 | CUJ 템플릿 + validate_cuj.py |
| ④ 개발 | ✅ 핵심 | 네 역할 분리 + 할당 프롬프트 템플릿 |
| ⑤ 사후 분석 (Post-mortem) | 범위 밖 | 각 도구의 자체 메커니즘 (예: Claude Code의 memory) |
하나의 Skill은 한 가지 일만 합니다. 요구사항 명확화, 학습 축적에는 이미 성숙된 독립 Skill이 있으므로, 재발명할 가치가 없습니다.
⚙️ 전제 조건
| 항목 | 요구사항 |
|---|---|
scripts/validate_cuj.py, scripts/install.py | Python 3.12+ (서드파티 패키지 불필요) |
| Skill 자체 테스트 | pytest |
위 항목은 Skill 자체의 실행 요구사항이며, 이 Skill을 사용하는 프로젝트의 기술 스택과는 무관합니다.