elephant-goldfish-model

무엇인가

elephant-goldfish-model은 소프트웨어 설계를 초안 작성과 검토로 분리해 AI 코딩 에이전트에 주입하는 오픈소스 플러그인이다. 단일 규칙 파일이 아니라 여러 스킬을 묶은 플러그인으로, 기능 구현 전에 요구사항·트레이드오프·구현 계획을 문서로 합의하는 절차를 규율한다. Elephant 역할은 프로젝트 맥락과 이전 결정을 보유한 채 문제를 탐색하고 명세 초안을 작성한다. Goldfish 역할은 앞선 대화 없이 문서와 문서가 참조하는 원천 자료만 보고 누락된 가정과 사각지대를 찾는다. 사용자는 목표와 제약을 제공하고 아키텍처 트레이드오프를 결정하며 명세를 승인한다. 적용 범위는 설계 결정이 필요한 기능이다. 작고 명확한 버그 수정은 일반 코딩 워크플로로 처리하도록 전제한다. README 기준으로 Brainstorm, Draft, Resolve, Bootstrap, Review, Review loop, Drift report 스킬을 제공하며, 각 스킬은 필요할 때 선택해 쓸 수 있고 전체 순서를 강제하지 않는다. 설계 문서는 concepts_brief.md와 design_draft.md로 남고, 승인된 명세는 docs/designs/ 아래에 저장하는 흐름을 안내한다. 즉 이 플러그인은 코드 스타일 규칙이 아니라 설계 승인 게이트와 검토 절차를 에이전트 작업 흐름에 삽입한다.

어떻게 동작하나

이 규칙이 없으면 에이전트는 초안 작성과 자기 검토를 같은 대화 맥락에서 연속 수행한다. 그러면 초안에 이미 들어간 가정이 검토 단계에서도 전제로 남고, 검토자는 자신이 작성한 문서를 우호적으로 읽기 쉽다. 요구사항이 명시되지 않은 채 구현 세부로 먼저 내려가거나, 대안 비교 없이 첫 설계를 확정하거나, 실패·중복·재시도 같은 경계 조건이 문서에서 빠질 수 있다. 웹훅 전달 실패나 동일 이벤트 중복 도착처럼 설계 결정이 필요한 조건이 대표적이다. 또한 탐색 대화와 승인된 명세가 섞여, 나중에 구현자가 무엇을 합의했는지 추적하기 어려워진다. Elephant가 프로젝트 맥락을 많이 보유할수록 문서 밖의 합의를 당연시하는 경향도 커진다. Goldfish 검토는 대화 맥락을 제거해 이런 암묵적 전제를 문서 표면으로 끌어올리는 데 목적이 있다. 같은 맥락을 공유한 에이전트는 자신의 누락을 독립적으로 찾기 어렵다. 리뷰에서 지적된 사항을 반영하지 않은 채 구현을 시작하면 설계 부채가 코드로 굳어진다. 검토가 없으면 그럴듯한 설계 초안이 그대로 코드로 넘어가고, 비용이 큰 수정은 구현 후에 발생한다.

무엇과 다른가

규칙 설계의 중심 원리는 역할 분리와 맥락 최소화다. Elephant에게는 프로젝트 맥락과 이전 결정을 주고, Goldfish에게는 문서와 참조 원천만 준다. 이 비대칭이 검토를 독립적으로 만든다. Goldfish는 앞선 대화를 모르므로 문서에 적히지 않은 요구사항을 추론하지 못하고, 그 공백이 곧 결함으로 드러난다. 신선한 서브에이전트 생성은 선택 사항이 아니라 하드 제약이다. 에이전트가 새 서브에이전트를 만들 수 없으면 EGM은 검토를 중단한다. 같은 세션의 기억을 재사용하면 무맥락 검토라는 전제가 깨지기 때문이다. 초안 작성이 섹션마다 사용자 피드백을 기다리는 것도 승인 게이트를 만들기 위해서다. 리뷰는 다섯 단계에 걸쳐 설계 자체, 명료성, 코드와의 적합성, 구현 계획을 확인하고, 사용자는 지적 중 무엇을 반영할지 결정한다. 테스트와 인간 판단을 대체하지 않는다는 한계도 규칙에 포함된다. 검토 결과를 기계적으로 수용하지 않고 아키텍처 트레이드오프를 승인하는 책임은 사용자에게 남는다.

어떻게 쓰나

Claude Code에서는 플러그인 마켓플레이스에 저장소를 추가한 뒤 egm@egm을 설치하고 새 세션을 시작한다. 설치 후 스킬은 /egm: 접두사가 붙은 슬래시 명령으로 호출한다. 예를 들어 /egm:egm-brainstorm은 설계 아이디어를 탐색하고 concepts_brief.md를 남기며, /egm-draft는 브리프나 기존 메모를 design_draft.md로 바꾸고 섹션마다 피드백을 받는다. /egm-review design_draft.md는 신선한 서브에이전트로 초안을 검토한다. 브레인스토밍과 리뷰는 새 서브에이전트를 만들 수 있는 세션을 요구하므로, 그 능력이 없는 환경에서는 검토가 진행되지 않는다. 전체 플러그인을 설치해야 스킬이 리뷰어 프롬프트와 문서 표준을 읽을 수 있다. Review loop는 특정 리뷰 작업에 구성된 리뷰어 그룹을 실행하고, Drift report는 체크인된 문서와 현재 소스 코드를 비교한다. 자동 상시 적용이 아니라 사용자가 필요한 스킬을 선택해 호출하는 방식이며, 전체 순서를 강제하지 않는다. Claude Code에서 /egm: 접두사를 빠뜨리면 해당 스킬 호출로 이어지지 않는다. 첫 사용에서는 새 세션 여부, /egm: 접두사, 생성된 concepts_brief.md와 design_draft.md 경로를 확인한다.

전제와 한계

내부 구성은 산출물 단위로 나뉜다. Brainstorm은 아이디어를 검증하고 개념 브리프 concepts_brief.md를 남긴다. Draft는 브리프나 기존 메모를 design_draft.md로 전환하며 섹션마다 사용자 피드백을 기다린다. Resolve는 리뷰 지적을 하나씩 처리해 무엇을 바꿀지 합의한다. Bootstrap은 기존 코드베이스의 문서를 만들거나 갱신한다. Review는 설계 자체, 명료성, 코드와의 적합성, 구현 계획을 다섯 단계로 나눠 신선한 리뷰어에게 배분한다. Review loop는 특정 리뷰 작업에 맞춰 구성된 리뷰어 그룹을 실행하는 절차이고, Drift report는 체크인된 문서와 현재 소스 코드를 비교해 어긋난 지점을 보고한다. 스킬은 리뷰어 프롬프트와 문서 표준을 읽어 동작하므로 전체 플러그인 설치가 전제이며, 승인된 명세는 docs/designs/ 아래에 남긴다. 산출물 경로가 고정되어 있어 대화가 끊긴 다음 세션에서도 이전 결정을 문서로 추적할 수 있고, 리뷰 지적과 반영 결과가 같은 파일 계층에 축적된다.

프롬프트를 매번 손으로 쓰는 방식과 다르다. 프롬프트 직접 작성은 검토 관점과 산출물 형식이 대화마다 달라지고, 리뷰어에게 무엇을 주고 무엇을 숨길지 사용자가 매번 정해야 한다. CLAUDE.md나 AGENTS.md 같은 상시 규칙 파일은 모든 작업에 로드되어 코딩 스타일과 금지 사항을 상시 규율하지만, 설계 국면의 절차나 리뷰어 역할 분리를 정의하지 않는다. EGM은 상시 규칙이 아니라 설계 결정이 필요한 시점에 호출되는 절차와 고정된 산출물 경로를 제공한다. 단일 SKILL.md 한 파일과도 다르다. 리뷰어 프롬프트와 문서 표준을 함께 담은 묶음이므로 파일 하나만 복사해서는 검토가 성립하지 않는다. 린터나 코드 리뷰 도구와도 층위가 다르다. 그것들은 작성된 코드를 검사하고, EGM은 코드 이전의 설계 문서와 그 문서가 참조하는 원천을 검사한다.

실무에서는 프로젝트 레이아웃을 먼저 확인한다. 워크플로 가이드가 탐색 대화, 브리프, 초안, 승인, 구현의 순서와 각 산출물 위치를 규정한다. 설계 결정이 필요한 기능을 골라 브레인스토밍을 호출하고, 브리프가 생기면 초안 작성으로 넘어간다. 초안 경로는 에이전트가 반환한 값을 그대로 리뷰 명령에 넘긴다. 리뷰 후 지적 목록에서 반영할 항목을 사용자가 고르고, Resolve로 변경을 합의한 뒤 구현을 지시한다. 첫 사용에서 확인할 것은 세 가지다. 새 세션으로 시작했는지, 각 에이전트의 명령 접두사나 스킬 피커에서 해당 스킬을 정확히 골랐는지, concepts_brief.md와 design_draft.md가 예상 경로에 생성됐는지다. 승인된 명세를 docs/designs/에 커밋해 두면 이후 Drift report의 비교 기준이 된다.

전제는 신선한 서브에이전트를 만들 수 있는 세션이다. 그 능력이 없으면 EGM은 리뷰를 중단한다. 검토는 테스트와 인간 판단을 대체하지 않으며, 문서에 적히지 않은 요구사항은 무맥락 리뷰어도 찾지 못한다. 따라서 초안의 완결성이 검토 품질의 상한이 된다. 지원 환경과 검증 한계는 별도 문서로 명시되어 있고, 에이전트별로 명령 체계가 갈린다. Antigravity CLI는 접두사 없는 이름이 접두사 명령으로 완성되는 버전과 그렇지 않은 버전이 나뉘고, Codex는 슬래시 명령 대신 스킬 피커에서 해당 스킬을 고른다. Claude Code는 /egm: 접두사를 요구한다. 라이선스는 Apache 2.0이며 구글의 공식 지원 제품이 아니라는 점도 도입 전 확인 대상이다.

선택 기준은 설계 결정의 유무다. 실패 처리, 중복 이벤트, 재시도 정책처럼 대안 비교가 필요한 기능이면 Brainstorm부터 시작해 Draft와 Review를 거친다. 브리프 없이 요구사항이 이미 정리되어 있으면 Draft부터 호출한다. 승인된 초안이 있고 지적만 남아 있으면 Review와 Resolve만 돌린다. 문서가 없는 기존 코드베이스에 설계 기록을 붙이려면 Bootstrap을 먼저 쓴다. 체크인된 문서와 코드가 어긋난 정황이 있으면 Drift report로 차이를 확인한 뒤 문서를 갱신한다. 반대로 원인이 분명하고 범위가 좁은 버그 수정이나 오탈자 교정은 일반 코딩 워크플로로 처리한다. 서브에이전트 생성이 막힌 환경이면 Review 계열을 빼고 Draft까지의 산출물만 활용한다.