peach-team-analyze

Peach Think Team

어떤 주제든 받아서 스스로 팀을 설계하고 조사→분석→타당성 검토→결과 도출까지 자동 처리하는 범용 오케스트레이터 스킬.

---

0. 환경 체크

0-1. 에이전트 팀 기능 활성화 확인

cat ~/.claude/settings.json | grep -i "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"

• "1" 없으면 즉시 중단하고 안내:

⚠️  에이전트 팀 기능이 비활성화되어 있습니다.

~/.claude/settings.json에 아래 내용을 추가한 후 Claude Code를 재시작하세요:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

0-2. tmux 환경 감지

echo "${TMUX:-not_in_tmux}"

• not_in_tmux이면 → 안내 출력 후 계속 진행 (tmux 없어도 in-process 모드로 동작):

💡 tmux 환경이 아닙니다.
   팀원을 실시간으로 동시에 확인하려면 tmux 세션 안에서 실행하세요:

   tmux new-session -s think && claude

   지금은 in-process 모드로 진행합니다. (Shift+Down으로 팀원 전환)

0-3. Codex 플러그인 감지

cat ~/.claude/settings.json | grep -i "openai-codex"

• "codex@openai-codex": true 있으면 → CODEX_AVAILABLE=true
• 없으면 → CODEX_AVAILABLE=false (critic 팀원으로 대체, 안내 출력)

ℹ️  Codex 플러그인 미감지 — critic 팀원으로 교차 검증을 대체합니다.
   (Codex 활성화: settings.json에 "codex@openai-codex": true 추가)

---

Inputs

/peach-team-analyze [주제]

# 옵션
# model=sonnet|opus|haiku  (팀원 모델 override, 기본값: sonnet)

model 옵션:

• 미지정: 기본값 sonnet으로 모든 팀원 실행
• 지정 시: 모든 팀원(analyst, critic)을 해당 모델로 override
• 팀원 투입(§5) 시 각 Agent 호출의 model 파라미터로 전달

---

1. 복잡도 판단 — 팀 vs 단독

주제를 받으면 팀을 꾸리기 전에 먼저 복잡도를 판단한다. 오버엔지니어링을 방지하기 위함이다.

복잡도 점수표

항목	조건	점수
관점 다양성	2개 이상의 독립적 관점이 필요한가	+1
병렬 분리	동시에 처리 가능한 독립 영역이 2개 이상인가	+1
교차 검증	결론에 반론/타당성 검토가 의미 있는가	+1

판단 기준

점수	처리 방식
0점	단독 처리 — 팀 없이 바로 답변
1점	경계 — 사용자에게 확인 후 결정
2~3점	팀 구성 → 에이전트 팀 실행

0점 예시 (단독 처리):

• "React Query v5 마이그레이션 방법 알려줘"
• "이 코드 버그 원인 찾아줘"
• "A vs B 간단 비교"

2~3점 예시 (팀 필요):

• "우리 서비스 인증 아키텍처 어떻게 바꿔야 해?" (보안/성능/유지보수 3관점)
• "이 기능 개발 전략 잡아줘" (조사+설계+리스크 분리)
• "경쟁사 3곳 분석해줘" (병렬 조사 후 종합)

1점일 때 사용자 확인 예시:

이 주제는 단독으로도 처리 가능합니다.
팀으로 진행하면 더 다각적이지만 시간이 걸립니다.

[1] 팀으로 진행  [2] 단독으로 바로 답변

---

2. 팀 유형 자율 결정

점수 2~3점이면 주제 성격에 따라 팀 유형을 자율 결정한다.

팀 유형

유형	언제	구성
조사 팀	정보 수집·비교·현황 파악	PM + 분석가 N명(관점별) + critic
실행 팀	설계·계획·산출물 생성	PM + 개발자 N명(영역별) + critic
검증 팀	품질·타당성·리스크 검토	PM + reviewer + tester + critic
혼합 팀	복합 과제	PM + 조사+실행+검증 혼합 + critic

critic 역할 (항상 포함)

• 팀원 결론에 반론을 시도하는 독립 검토자
• 주제 복잡도에 따라 critic 투입 시점 결정:
  • 단순(2점): 마지막에 한 번만
  • 복잡(3점): 중간 + 마지막

---

3. 팀 구성안 제시 → 사용자 확인

팀을 꾸리기 전에 반드시 구성안을 먼저 보여준다. 엉뚱한 팀 구성으로 리소스를 낭비하지 않기 위함이다.

📋 팀 구성안

주제: [주제 한 줄 요약]
팀 유형: [조사/실행/검증/혼합]

팀원:
├─ PM(리더): 종합 판단 및 결과 도출
├─ [역할1]: [담당 관점/영역]
├─ [역할2]: [담당 관점/영역]
├─ [역할3]: [담당 관점/영역] (복잡도 높을 때)
└─ critic: 결론 타당성 반론 검토

🔍 Codex 교차검증
├─ 적용 여부: [적용 / 스킵]
├─ 사유: [코드 분석 필요 / 문서 분석만으로 충분 / etc.]
├─ 검증 초점: [구체적으로 Codex에게 무엇을 확인시킬지]
└─ 작업 디렉토리: [절대경로]

예상 산출물: [결과물 형태]

이 구성으로 진행할까요? 교차검증 범위를 조정하시겠습니까? [Y/n]

Codex 적용 자동 판단 기준 (사용자가 오버라이드 가능):

• 코드 분석/실행이 필요한 경우 → 자동 적용
• 문서 분석/설계 판단만으로 충분한 경우 → 자동 스킵
• 사용자가 명시적으로 [적용/스킵]을 지정하면 → 해당 선택 우선

사용자가 수정 요청하면 구성안 수정 후 재확인. 5초 내 응답 없거나 Y이면 → 바로 실행.

---

4. 팀 생성 및 태스크 등록

TeamCreate: team_name="think-[주제-축약]-team"

# 조사 팀 예시
TaskCreate:
1. "[관점1] 조사" (owner: analyst-1)
2. "[관점2] 조사" (owner: analyst-2)
3. "[관점3] 조사" (owner: analyst-3)  ← 관점 수에 따라 가변
4. "종합 판단" (blockedBy: 1,2,3, owner: pm)
5. "타당성 검토" (blockedBy: 4, owner: critic)

# 실행 팀 예시
TaskCreate:
1. "[영역1] 작성" (owner: dev-1)
2. "[영역2] 작성" (owner: dev-2)
3. "통합 검증" (blockedBy: 1,2, owner: pm)
4. "타당성 검토" (blockedBy: 3, owner: critic)

태스크 의존성 규칙:

• 병렬 가능한 조사/작업: blockedBy 없음
• PM 종합: 모든 팀원 완료 후
• critic: PM 종합 후

---

5. 팀원 투입 (병렬 실행)

모든 팀원을 같은 turn에서 run_in_background: true로 동시 투입한다.

팀원 프롬프트 필수 원칙

1. 역할 선언: "너는 [역할]이다. Task #N 담당."
2. 배경 충분히: 팀원은 대화 이력을 전혀 모름 — 주제, 목적, 맥락을 상세히
3. 파일 경로 절대경로: 참조할 파일이 있으면 절대경로로 명시
4. 완료 프로토콜: "완료 후 TaskUpdate Task #N → completed, PM(team-lead@팀이름)에게 SendMessage로 보고. 150줄 이내"
5. 출력 제한: 보고서 줄 수 명시 (토큰 절약)

critic 팀원 프롬프트 핵심

너는 독립 비판 검토자(critic)이다. Task #N 담당.

PM의 종합 판단 결과를 받아 아래 관점에서 반론을 시도하라:
1. 빠진 관점이나 증거는 없는가?
2. 논리적 비약이나 과도한 단순화는 없는가?
3. 리스크나 부작용이 충분히 다뤄졌는가?

반론이 타당하면 → "수정 필요: [구체적 항목]"
결론이 견고하면 → "타당성 확인: [근거]"

보고는 PM에게 SendMessage. 100줄 이내.

---

6. 보고 수집 및 PM 종합

PM이 모든 팀원 보고를 수신하면:

1. 선정 기준 먼저 선언 — 결론을 내리기 전에 평가 기준을 명시한다

   평가 기준:
   - 독립 분해 가능한가? (병렬 처리가 의미 있는가)
   - 검증 가능한 산출물이 있는가?
   - 역할 분담이 단독 대비 실질적 이점이 있는가?
   

2. 공통점/합의점 정리
3. 충돌점/이견 명시
4. critic 반론 반영 여부 결정
5. 최종 결론 도출

팀원 무응답 대응

1. SendMessage로 보고 재요청 → 3분 대기
2. 응답 없으면 → 새 팀원(v2)으로 재투입
3. config.json에서 무응답 팀원 강제 제거 후 TeamDelete 진행

---

7. Codex 교차 검증 (CODEX_AVAILABLE=true 시)

PM 종합 완료 후 codex:codex-rescue 서브에이전트를 스폰하여 교차검증을 실행한다.

/codex:adversarial-review는 disable-model-invocation 제약으로 오케스트레이터가 자동 호출할 수 없다. 대신 codex:codex-rescue로 Codex CLI에 교차검증 작업을 task로 전달한다.

프롬프트 작성 규칙 (필수)

codex-rescue는 독립 컨텍스트에서 실행되므로, 판단에 필요한 모든 정보를 프롬프트에 인라인으로 포함해야 한다. 컨텍스트 없이 "약점을 찾아줘"만 보내면 무응답이 된다.

프롬프트 템플릿:

Agent(
  subagent_type="codex:codex-rescue",
  run_in_background=true,
  prompt="""
아래 분석 결론의 약점을 찾아줘.
critic이 이미 검토한 항목은 중복 제외하고, 외부 관점에서 놓친 점만 보고.

## PM 종합 결론
[PM 종합 판단 본문 전체를 여기에 인라인]

## critic 검토 결과 (중복 제외 대상)
[critic 보고 본문 전체를 여기에 인라인]

## 질문
- 이 결론에 놓친 리스크가 있는가?
- [주제 특화 질문]

50줄 이내 보고.
"""
)

인라인 기준:

• PM 종합: 핵심 발견 + 결론 + 권고 (전문 권장, 200줄 이하로 압축)
• critic 보고: 수정 필요/타당성 확인 판정표 전체
• 관련 파일: 코드 경로만 명시 (codex-rescue가 Bash로 파일 내용을 읽을 수 있음)

critic → Codex 순서 정의

critic과 Codex는 역할이 다르다. 중복을 방지하기 위해 순서를 정의한다:

1. critic (§5에서 실행): 내부 논리 검증 — 빠진 관점, 논리적 비약, 과도한 단순화
2. Codex (§7에서 실행): critic 보고서를 전달받아 critic이 언급하지 않은 외부 관점 + 반사실적 시나리오만 검토

피드백 반영 루프

• Codex 피드백이 결론 수정을 요구하면 → PM 재종합 1회 허용
• 재종합 후 Codex가 재반론하면 → PM 최종 확정 우선, 루프 종료
• Codex 피드백이 경미하면 → 최종 결과에 "반영" 또는 "검토 완료, 이견 없음"으로 명시

Codex 실행 결과 사용자 확인

Codex 교차검증 결과를 받은 후, PM이 바로 반영하지 않고 사용자에게 먼저 보여준다:

🔍 Codex 교차검증 결과

[Codex 보고 요약 3~5줄]

이 피드백을 결론에 반영할까요?
[1] 반영  [2] 무시  [3] 추가 검증 요청

• [1] 반영: PM이 Codex 피드백을 반영하여 재종합
• [2] 무시: Codex 피드백을 무시하고 현재 결론 확정
• [3] 추가 검증: 사용자가 지정한 항목으로 Codex 재실행

작업 디렉토리 고정 (필수)

Codex에 전달하는 프롬프트에 반드시 작업 디렉토리를 명시한다. 컨텍스트 이탈(다른 프로젝트 파일 읽기) 방지:

Agent(
  subagent_type="codex:codex-rescue",
  prompt="""
  작업 디렉토리: /절대경로/프로젝트
  이 디렉토리 밖의 파일은 읽지 마라.
  ...
  """
)

fallback

• CODEX_AVAILABLE=false: critic 팀원 결과로 대체. 별도 안내 없이 진행.
• 사용자가 §3에서 Codex 스킵 선택: §7 전체 생략, critic 결과로 최종 확정.
• Codex 무응답/타임아웃: 60초 대기 → 응답 없으면 스킵, critic 결과로 진행.
• Codex 결과 부실: 프롬프트를 보강하여 1회 재시도 → 재시도 후에도 부실하면 critic 결과로 진행.
• Codex 컨텍스트 이탈 감지: Codex가 작업 디렉토리 밖 파일을 읽은 경우 → 결과 무효, critic 결과로 대체.

---

8. 팀 정리

SendMessage(shutdown_request) → 모든 팀원에게
TeamDelete → 팀 정리

TeamDelete 실패 시 (active members 오류):

# config.json에서 팀원 강제 제거 후 재시도
python3 -c "
import json, os
path = os.path.expanduser('~/.claude/teams/[팀이름]/config.json')
with open(path) as f: data = json.load(f)
data['members'] = [m for m in data['members'] if m['name'] == 'team-lead']
with open(path, 'w') as f: json.dump(data, f, indent=2)
"

---

9. 최종 결과 출력

## [주제] — 분석 결과

### 팀 구성
- 팀 유형: [유형]
- 팀원: [역할 목록]
- Codex 교차검증: [적용/미적용]

### 핵심 발견
1. [발견 1]
2. [발견 2]
3. [발견 3]

### 선정 기준
- 독립 분해 가능성: [평가]
- 산출물 검증 가능성: [평가]
- 역할 분담 실질 이점: [평가]

### 결론
[PM 종합 판단 — 명확하고 직접적으로]

### critic 검토
[타당성 확인 / 수정 반영 내역]
※ "조건부 타당" 판정이 있으면 해당 조건을 결론에 반드시 병기

### Codex 교차검증 (적용 시)
[이견 없음 / 반영된 수정 사항]

### 다음 액션
→ [권장 행동 1]
→ [권장 행동 2]

---

참조 문서

• references/team-patterns.md — 팀 유형별 상세 프롬프트 예시, 팀 운영 실전 패턴, tmux pane 관리 참고

---

사용 예시

# 어떤 주제든 그냥 전달
/peach-think-team 우리 서비스 인증 아키텍처 JWT vs Session 어떻게 결정해야 해?

/peach-think-team 경쟁사 3곳(토스, 카카오페이, 네이버페이) 결제 UX 분석해줘

/peach-think-team 이 PR diff를 보고 설계 상 문제점 찾아줘

/peach-think-team 내년 기술 로드맵 어떻게 잡으면 좋을지 다각도로 검토해줘