# task-199.1 보고서: GPTaku Plugins 레포 심층 분석

- 작업 ID: task-199.1
- 팀: dev2-team (오딘)
- 분석 대상: https://github.com/fivetaku/gptaku_plugins
- 클론 위치: /home/jay/workspace/teams/dev2/temp/gptaku_plugins/
- 작성일: 2026-03-03

---

## 1. 레포 개요

**프로젝트 정체**: Claude Code 전용 플러그인 마켓플레이스. "AI Native가 되고 싶은 사람들을 위한" 도구 모음.

**구조**: 메인 레포는 마켓플레이스 인덱스(marketplace.json)이고, 8개 플러그인이 각각 독립 git 서브모듈로 분리됨.

**기술 스택**: Claude Code Plugin System (commands/*.md + skills/*/SKILL.md + references/*.md), Python 스크립트, Node.js/Bash(외부 CLI 오케스트레이션), YAML 설정

**규모**: 플러그인당 평균 10~25개 파일, SKILL.md 기준 200~1100라인. 전체 약 200개 비git 파일.

**8개 플러그인 목록**:
- docs-guide: llms.txt 기반 공식 문서 조회 (68개+ 라이브러리)
- git-teacher: 비개발자용 Git 온보딩 (6개 스킬, 5단계)
- vibe-sunsang: AI 멘토 에이전트 (4 워크스페이스 유형, 5 레벨)
- deep-research: 멀티에이전트 딥리서치 (7-Phase 파이프라인, 소스 삼각검증)
- pumasi: Claude PM + Codex CLI 병렬 코딩 (시그니처 위임 + bash 게이트)
- show-me-the-prd: 인터뷰 기반 PRD 생성 (4종 디자인 문서)
- kkirikkiri: 자연어 → AI 에이전트 팀 자동 구성 (멀티모델, 프리셋)
- skillers-suda: 4 페르소나 인터뷰 → 스킬 자동 생성

---

## 2. 핵심 발견

### 발견 1: 명시적 Phase 계약 (Phase Contract)

**출처**: deep-research/skills/deep-research-main/references/phase_contracts.md

각 Phase의 입출력을 JSON 스키마로 정의. Phase 2 출력이 Phase 3의 입력이 되는 방식으로 데이터 흐름이 타입화됨. Phase별 Success Criteria 체크리스트도 명시.

```json
// Phase 2 출력 스키마 예시
{
  "subtopics": [{"name": "...", "questions": [], "search_queries": [], "priority": 1}],
  "agent_assignments": [{"agent": "explore", "subtopic": "...", "focus": "current_state"}]
}
```

**의미**: 우리 시스템의 dispatch.py는 자유형식 task_id.md를 전달하고 팀장이 알아서 처리. Phase 간 데이터 계약이 없어서 중간 결과물의 구조가 보장되지 않음.

### 발견 2: bash 게이트 검증 (Zero-Token Verification)

**출처**: pumasi/skills/pumasi/SKILL.md L351, pumasi.config.yaml L28-36

LLM 호출 없이 bash 명령으로 결과물을 기계적 검증:
```yaml
gates:
  - name: "타입 체크"
    command: "npx tsc --noEmit src/auth/token.ts"
  - name: "시그니처 확인"
    command: "grep -q 'generateToken' src/auth/token.ts"
```

핵심 원칙(SKILL.md L351): "게이트가 강하면 Claude가 코드를 쓸 필요가 없다. tsc/build/test가 통과했다면 구현이 올바른 것이다."

게이트 실패 → Codex에 자동 재위임(autofix) → 게이트 재실행의 자동 루프까지 구현됨(pumasi.sh L138-174).

**의미**: 우리 검증은 팀장 셀프 QC + 마아트 서브에이전트(둘 다 LLM 호출). qc_verify.py가 가장 가깝지만 게이트 형식이 아닌 후행 검증.

### 발견 3: DEAD_ENDS 레지스트리

**출처**: kkirikkiri/skills/kkirikkiri/SKILL.md L498-500

공유 메모리에 성공 결과뿐 아니라 **실패한 접근**을 명시적으로 기록:
```
긍정적 발견만 기록하면 공유 메모리의 효과가 60-70%에 그치지만,
실패한 접근까지 기록하면 75-80%까지 컨텍스트를 복구할 수 있습니다
```

교체 팀원 온보딩 순서: DEAD_ENDS(하지 말 것) → TEAM_PLAN(할 것) → PROGRESS(현재 상황) → FINDINGS(참고)

**의미**: 우리 memory/reports/ 에는 성공 결과만 기록. 같은 실패를 반복하는 문제 발생 가능.

### 발견 4: 설계/구현 완전 분리 (Signature-Only Pattern)

**출처**: pumasi/skills/pumasi/SKILL.md L78-120

Claude는 시그니처+요구사항만 작성, 구현은 Codex에 위임. "Claude 토큰을 설계에만 소비하고 구현은 별도 토큰 예산에 위임."

안티패턴 방어(SKILL.md L50-74): LLM의 "과잉 친절" 성향으로 코드를 끝까지 완성하려는 문제를 원인 분석까지 포함하여 명시적으로 차단.

**의미**: 우리 dev3-team이 openclaw에 위임하는 패턴과 구조적으로 동일하지만, pumasi는 "무엇을 위임하고 무엇을 위임하지 않는가"의 경계가 시그니처 레벨까지 명확히 정의됨.

### 발견 5: 재개 가능 상태 머신 (Resumable State Machine)

**출처**: deep-research/skills/deep-research-main/scripts/orchestrator.py L228-234

```python
def get_next_pending_phase(self) -> Optional[int]:
    for i in range(1, 8):
        phase_key = f"phase_{i}"
        status = self.state["progress"].get(phase_key)
        if status in [PhaseStatus.PENDING.value, PhaseStatus.IN_PROGRESS.value]:
            return i
    return None
```

`/deep-research resume [session_id]`로 어느 Phase에서든 재개 가능. state.json에 Phase별 진행 상황 원자적 저장.

**의미**: 우리 시스템은 작업 중단 시 재개 메커니즘이 없음. task-timers.json에 상태는 기록하지만 재개 프로토콜 부재.

### 발견 6: 3-Tier 지식 계층화 실현

**출처**: 전체 플러그인 공통 구조

```
commands/*.md  → Tier 1 (항상 활성): 경량 라우터, 인수 파싱만
SKILL.md       → Tier 2 (필요시 호출): 실행 절차
references/*.md → Tier 3 (지연 로딩): 도메인 데이터
```

docs-guide 예시: SKILL.md 본문에는 4단계 전략만, 68개 URL 목록은 references/llms-txt-sites.md, 40개 기술별 전략은 references/fallback-strategies.md로 완전 분리.

**의미**: 아누 가이드 1.5절의 3-Tier 구조 목표(토큰 40-60% 절감)를 실현한 구체적 구현 패턴. 우리 스킬들은 SKILL.md 하나에 모든 것이 포함됨.

### 발견 7: AskUserQuestion 도구 강제 + EXECUTE 패턴

**출처**: show-me-the-prd/commands/show-me-the-prd.md L22, vibe-sunsang 전반

"모든 질문은 반드시 AskUserQuestion 도구로 호출한다. 텍스트로 질문하지 않는다."
모든 인터랙티브 지점에 "EXECUTE:" 접두어 + 완성된 JSON 제시로 AI 즉흥 변형 차단.

또한 deep-research/SKILL.md L33-48에서 "DO NOT just display this documentation. EXECUTE the research flow immediately." — LLM의 "문서 표시" 오류 패턴을 명시적 anti-pattern으로 방어.

### 발견 8: 인터뷰 사이 병렬 리서치 배치

**출처**: show-me-the-prd/skills/show-me-the-prd/references/research-strategy.md L65-88

```
Batch 1: Step 1 답변 직후 → WebSearch (다음 질문 준비 중 실행)
Batch 2: Step 2 기능 선택 직후 → 기능별 기술 난이도 조사
Batch 3: Step 4 Phase 확인 후 → 기술 스택 비교
원칙: "유저 대기 시간 = 0"
```

사용자 답변 사이의 빈 시간에 다음 단계 리서치를 미리 실행.

### 발견 9: 4 페르소나 병렬 스폰 + 데이터 모델 분업

**출처**: skillers-suda/skills/skillers-suda/SKILL.md L84-171, interview-guide.md L110-126

4개 Haiku 에이전트를 동시 스폰하여 각각 다른 데이터 필드를 담당:
- 기획자 → purpose, trigger_keywords
- 사용자 → input_type, output_type
- 전문가 → domain, workflow
- 검수자 → constraints, edge_cases

"기존에는 모든 항목을 사용자에게 직접 물어봤지만, 이제는 에이전트 팀이 먼저 분석하고, 불확실한 것만 사용자에게 확인합니다."

### 발견 10: 6가지 워크플로우 스텝 타입 분류

**출처**: skillers-suda/skills/skillers-suda/references/workflow-step-types.md L256-292

prompt / script / api_mcp / rag / review / generate 6가지 타입으로 스킬 워크플로우를 구조화. 강제 규칙: "api_mcp/rag 단계 뒤에는 반드시 review 또는 prompt 단계가 따라야 한다."

조합 패턴까지 정의: `기본: prompt → review → generate`, `외부 연동: script(API) → review → prompt → generate`

---

## 3. 적용 제안 (우선순위 + 난이도)

### P1 (높음, 즉시 적용 가능)

**3-1. 보고서 스키마 표준화**
- 난이도: 낮음 (프롬프트 수정만)
- 현재: 팀원 보고서가 자유형식 Markdown
- 제안: pumasi의 codex-output-schema.json처럼 보고서를 JSON/구조화 Markdown으로 표준화
- 기대 효과: 아누 followup에서 자동 파싱 가능, qc_verify.py와 연동 가능
- 예시 스키마: `{task_id, status, files_created, files_modified, tests_passed, risks, summary}`
- 수정 대상: team_prompts.py의 보고서 규칙 섹션

**3-2. DEAD_ENDS 레지스트리**
- 난이도: 낮음 (파일 경로 규칙 추가만)
- 현재: 실패한 접근이 기록되지 않음
- 제안: `memory/reports/<task_id>.dead-ends.md` 형식으로 "시도 → 실패 이유 → 근거" 기록
- 기대 효과: 라운드 반복/팀 교체 시 같은 실패 방지, 컨텍스트 복구율 향상
- 수정 대상: team_prompts.py 워크플로우 섹션에 DEAD_ENDS 기록 규칙 추가

**3-3. 스킬 references/ 외부화 (3-Tier 분리)**
- 난이도: 중간 (기존 스킬 리팩토링)
- 현재: SKILL.md에 트리거+절차+데이터 모두 포함
- 제안: GPTaku 패턴처럼 commands/*.md(Tier 1) + SKILL.md(Tier 2) + references/*.md(Tier 3) 분리
- 기대 효과: 아누 가이드 1.5절 목표 (토큰 40-60% 절감) 실현
- 우선 적용 대상: research-prompt (300줄+ 도메인 예시 외부화), competitor-analyst

### P2 (중간)

**3-4. Phase 계약 도입**
- 난이도: 중간 (dispatch.py + team_prompts.py 수정)
- 제안: memory/tasks/<task_id>/phase_N_output.json 형식으로 Phase 출력 저장, 다음 Phase에 이전 출력 경로 주입
- 기대 효과: chain.py와 연동하여 Phase 간 자동 데이터 전달, Phase 실패 지점 정확 로깅

**3-5. bash 게이트 검증 통합**
- 난이도: 중간 (qc_verify.py 리팩토링)
- 제안: dispatch.py 프롬프트에 task별 검증 게이트(bash 명령) 포함. .done 파일 생성 전에 게이트 통과 필수.
- 기대 효과: LLM 호출 없는 기계적 검증, 토큰 절약
- 예시: `[{"name": "빌드 성공", "command": "cd /path && npm run build"}]`

**3-6. 재개 가능 작업 (Resumable Task)**
- 난이도: 중간 (task-timers.json 확장)
- 제안: memory/tasks/<task_id>_state.json에 Phase 진행 상황 저장, dispatch.py에 --resume 옵션 추가
- 기대 효과: 작업 중단 후 재개 가능, 세션 사망 시 복구

**3-7. 자동 재위임 루프 (Autofix)**
- 난이도: 중간 (team_prompts.py + 게이트 시스템 필요)
- 제안: 게이트 실패 시 실패 컨텍스트를 redelegate-prompt.txt에 저장, 최대 2회 자동 재시도 후 아누 에스컬레이션
- 기대 효과: 팀장 수동 재시도 대신 자동 retry 루프

### P3 (낮음, 장기 검토)

**3-8. 스킬 자동 생성 도구 도입**
- 난이도: 높음 (skillers-suda 패턴 내재화)
- 제안: 4 페르소나 병렬 분석 → 표준화된 SKILL.md 자동 생성 + validate-skill.sh 검증
- 기대 효과: 새 스킬 생성 품질 표준화, 포맷 일관성 보장

**3-9. 환경 스캔 기반 동적 모델 배정**
- 난이도: 높음 (조직 구조 변경 필요)
- 제안: kkirikkiri처럼 런타임에 사용 가능한 도구/모델을 스캔하고 동적 배정
- 참고: 현재 runtime_note에 "세션별 모델 지정이 가능해지면 분리" 계획 존재

---

## 4. 적용 불필요/부적합

**4-1. 자연어 → 팀 자동 구성 (kkirikkiri 방식)**
- 이유: 우리 시스템은 고정 조직도 기반 매트릭스 구조가 설계 의도. 매 작업마다 팀을 새로 구성하면 조직 학습 효과(팀원 간 암묵지 공유)가 사라짐. kkirikkiri는 일회성 프로젝트용, 우리는 지속적 운영 조직.

**4-2. Haiku 사용 금지 정책 (kkirikkiri 방식)**
- 이유: kkirikkiri는 Haiku를 어떤 역할에도 배정하지 않지만, 우리 시스템은 테스터(아르고스/헤임달/호루스)에 Haiku를 의도적으로 배정. 비용-품질 트레이드오프를 이미 반영한 설계.

**4-3. 소스 삼각검증 매트릭스 (deep-research Phase 4)**
- 이유: deep-research의 핵심이지만 학술 리서치 전용 기능. 우리 시스템의 도메인(소프트웨어 개발 오케스트레이션)에서는 마아트 독립 검증이 더 적합.

**4-4. llms.txt 조회 전략 (docs-guide)**
- 이유: 우리 시스템에는 문서 조회 전용 스킬이 불필요. 개발팀이 필요 시 직접 WebSearch/WebFetch 사용.

**4-5. 비유 체계 (git-teacher glossary)**
- 이유: 현재 시스템 사용자(제이회장님)가 AI 기술 용어에 충분히 익숙. 비개발자 온보딩 시에는 유용하나 현재 우선순위 낮음.

---

## 5. 결론

GPTaku Plugins는 "Claude Code 스킬 시스템의 best practice 쇼케이스"다. 우리 시스템이 즉시 도입해야 할 핵심 3가지는 **보고서 스키마 표준화**(아누 자동 처리 효율), **DEAD_ENDS 레지스트리**(실패 학습), **스킬 references/ 외부화**(토큰 절감)이며, 중기적으로 **Phase 계약**과 **bash 게이트 검증**을 통해 작업 결과의 기계적 검증 체계를 강화해야 한다.

---

## 생성/수정 파일 목록

- (클론) /home/jay/workspace/teams/dev2/temp/gptaku_plugins/ — 분석 대상 레포 전체 (서브모듈 포함)
- (생성) /home/jay/workspace/memory/reports/task-199.1.md — 본 보고서

## 테스트 결과

리서치/분석 전용 작업으로 코드 생성 없음. 테스트 해당 없음.

## 버그 유무

없음.

## 비고

- 레포가 서브모듈 기반이라 `git submodule update --init --recursive`로 8개 플러그인 전체 클론 완료
- test-playground 서브모듈은 .gitmodules에 존재하나 README/marketplace.json에 미포함 → 분석 대상에서 제외
- 클론 레포는 아누 추가 확인 가능하도록 삭제하지 않음 (작업 지시 준수)

## 자동 검증 결과 (qc_verify.py)

```json
{
  "task_id": "task-199.1",
  "verified_at": "2026-03-03T23:29:24",
  "overall": "PASS (조건부)",
  "checks": {
    "api_health": {"status": "SKIP", "details": ["서버 작업 아님"]},
    "file_check": {"status": "PASS", "details": [
      "OK (14105 bytes): reports/task-199.1.md",
      "OK (3408 bytes): gptaku_plugins/README.md",
      ".done 파일: 워크플로우 순서상 QC 후 생성 → 정상"
    ]},
    "data_integrity": {"status": "PASS", "details": ["task-timers 정상"]},
    "test_runner": {"status": "SKIP", "details": ["리서치 작업, 테스트 해당 없음"]}
  }
}
```