JW's AI_Stash

SKILL

14 min read

4명의 전문가 에이전트(Architect · Pragmatist · Critic · User-Advocate)가 독립 분석 → 상호 토론 → 최적안 종합하는 3라운드 토론 기반 계획서를 작성한다.

STEP 1 — 사전 준비

  1. pwd로 현재 프로젝트 루트 확인
  2. 저장 폴더 = {프로젝트루트}/ai_history/work-plan/
  3. --path {경로} 인수가 있으면 해당 경로를 저장 폴더로 사용
  4. 저장 폴더가 없으면 mkdir -p로 생성

인덱스 결정

  • 저장 폴더 내 숫자.*.md 패턴 파일 목록 확인
  • 가장 큰 숫자 + 1 → 다음 인덱스 (파일이 없으면 01)
  • 항상 2자리 zero-padding (01, 02, 09, 10, 11 …)

kebab-case 이름

  • 작업의 핵심 기능을 영문 kebab-case 3~5단어로 표현
  • 접미사 -debate 를 붙인다
  • 예: map-layer-toggle-debate, upload-progress-ui-debate

최종 파일명: {인덱스}.{kebab-case}.md

STEP 2 — Round 1: 독립 분석 (병렬 실행)

4개의 Agent를 동시에 실행한다. 각 에이전트에게 아래 공통 정보를 전달한다:

  • 사용자의 원본 요청 (프롬프트)
  • 현재 프로젝트 루트 경로
  • “코드를 수정하지 말고 분석만 수행하라”는 지시

각 에이전트의 프롬프트에는 역할·관점·핵심 질문을 명확히 지정한다.

Agent 1: Architect (설계자)

당신은 소프트웨어 아키텍트 역할입니다.
아래 작업 요청을 "코드 구조·설계 패턴·확장성·모듈화" 관점에서 분석하세요.

[작업 요청]
{사용자 프롬프트}

[프로젝트 경로]
{프로젝트루트}

[분석 지침]
1. 관련 코드를 Glob/Grep/Read로 탐색하여 현재 구조를 파악하세요.
2. 아래 형식으로 분석 결과를 작성하세요. 코드 파일은 절대 수정하지 마세요.

[출력 형식]
## Architect 분석

### 현재 구조 파악
- 관련 파일/모듈 목록
- 현재 아키텍처 패턴

### 제안 방향
- 추천하는 설계 방식과 그 이유
- 수정 대상 파일 목록 (파일명 > 함수명 — 신규/수정/삭제: 설명)

### 확장성 고려
- 향후 유사 기능 추가 시 고려사항
- 패턴 일관성 (기존 코드와의 정합성)

### 리스크
- 이 설계 방식의 약점이나 단점

Agent 2: Pragmatist (실용주의자)

당신은 실용주의 개발자 역할입니다.
아래 작업 요청을 "최소 변경·구현 속도·단순성·현실적 제약" 관점에서 분석하세요.

[작업 요청]
{사용자 프롬프트}

[프로젝트 경로]
{프로젝트루트}

[분석 지침]
1. 관련 코드를 Glob/Grep/Read로 탐색하여 현재 구조를 파악하세요.
2. 아래 형식으로 분석 결과를 작성하세요. 코드 파일은 절대 수정하지 마세요.

[출력 형식]
## Pragmatist 분석

### 현재 상태 파악
- 관련 파일/모듈 목록
- 기존 코드 재활용 가능 요소

### 제안 방향
- 가장 빠르고 간단한 구현 방법과 그 이유
- 수정 대상 파일 목록 (파일명 > 함수명 — 신규/수정/삭제: 설명)
- 건드리지 않아도 되는 파일 (과도한 수정 방지)

### 구현 난이도
- 예상 복잡도 (낮음/중간/높음)
- 의존성 변경 필요 여부

### 리스크
- 이 방식의 약점이나 기술 부채 가능성

Agent 3: Critic (비평가)

당신은 시니어 코드 리뷰어이자 QA 전문가 역할입니다.
아래 작업 요청을 "엣지케이스·회귀 위험·보안·안정성" 관점에서 분석하세요.

[작업 요청]
{사용자 프롬프트}

[프로젝트 경로]
{프로젝트루트}

[분석 지침]
1. 관련 코드를 Glob/Grep/Read로 탐색하여 현재 구조를 파악하세요.
2. 특히 수정 예정 함수를 호출하는 모든 위치, import 의존성을 파악하세요.
3. 아래 형식으로 분석 결과를 작성하세요. 코드 파일은 절대 수정하지 마세요.

[출력 형식]
## Critic 분석

### 영향 범위
- 수정 시 영향받는 모듈/파일 목록
- 주요 호출부 (파일명:라인)
- 동일 패턴이 여러 곳에 존재하는지 여부

### 위험 요소
- 회귀 위험 지점 (구체적으로)
- 엣지케이스 시나리오
- 보안 고려사항 (해당 시)

### 반드시 확인할 사항
- 구현 후 반드시 검증해야 할 체크리스트
- 놓치기 쉬운 사이드 이펙트

Agent 4: User-Advocate (사용자 대변인)

당신은 UX 디자이너 겸 프론트엔드 개발 리드 역할입니다.
아래 작업 요청을 "사용자 경험·개발자 경험·유지보수성·가독성" 관점에서 분석하세요.

[작업 요청]
{사용자 프롬프트}

[프로젝트 경로]
{프로젝트루트}

[분석 지침]
1. 관련 코드를 Glob/Grep/Read로 탐색하여 현재 구조를 파악하세요.
2. UI/UX가 관련된 경우 사용자 흐름을 분석하세요.
3. 아래 형식으로 분석 결과를 작성하세요. 코드 파일은 절대 수정하지 마세요.

[출력 형식]
## User-Advocate 분석

### 사용자/개발자 영향
- 이 변경이 최종 사용자에게 미치는 영향
- 이 변경이 다른 개발자에게 미치는 영향 (API 변경, 코드 가독성 등)

### 제안 방향
- UX/DX 관점에서 추천하는 구현 방식
- 수정 대상 파일 목록 (파일명 > 함수명 — 신규/수정/삭제: 설명)

### 개선 포인트
- 추가하면 사용자 경험이 좋아지는 요소
- 네이밍, 인터페이스 설계 관련 제안

### 리스크
- 사용자 혼란 가능성
- 기존 사용 패턴과의 불일치

STEP 3 — Round 2: 상호 토론 (순차 실행)

Round 1의 4개 분석 결과를 모두 모아 하나의 Debate Agent에게 전달한다.

당신은 기술 토론 진행자(Moderator) 역할입니다.
4명의 전문가가 아래와 같이 각자의 관점에서 분석했습니다.
이들의 의견을 비교·대조하여 토론 결과를 정리하세요.

[작업 요청]
{사용자 프롬프트}

[Architect 분석]
{Round 1 Agent 1 결과}

[Pragmatist 분석]
{Round 1 Agent 2 결과}

[Critic 분석]
{Round 1 Agent 3 결과}

[User-Advocate 분석]
{Round 1 Agent 4 결과}

[토론 지침]
아래 형식으로 토론 결과를 작성하세요.

## 토론 결과

### 합의 사항 (모든 관점이 동의하는 부분)
- 항목별 나열

### 쟁점 사항 (관점 간 충돌이 있는 부분)
각 쟁점별로:
- **쟁점**: 무엇이 충돌하는가
- **Architect 입장**: ...
- **Pragmatist 입장**: ...
- **Critic 입장**: ...
- **User-Advocate 입장**: ...
- **트레이드오프 분석**: 각 선택지의 장단점 비교
- **권장 방향**: 종합적으로 어떤 방향이 더 나은지와 그 이유

### 추가 발견
- 한 관점에서만 발견된 중요한 사항
- 교차 분석으로 새롭게 드러난 리스크나 기회

### 최종 권장 접근법
- 채택할 방향 요약
- 핵심 주의사항

STEP 4 — Round 3: 최종 계획서 종합 (순차 실행)

Round 2의 토론 결과를 바탕으로 최종 계획서를 작성한다. 이 단계는 메인 에이전트가 직접 수행한다. (추가 Agent 호출 없음)

date 명령으로 오늘 날짜를 확인한 뒤, 아래 템플릿으로 계획서를 Write한다.

- **작업날짜**: YYYY-MM-DD
- **작업자**: Claude Code (claude-sonnet-4-6) — plan-debate
- **방식**: 4-Agent Debate (Architect · Pragmatist · Critic · User-Advocate)
 
### 1차 작업
 
- **프롬프트**: {사용자 요청 원문 — 한 글자도 수정하지 않고 그대로 기록}
 
- **토론 요약**:
 
  #### 합의 사항
  {Round 2에서 도출된 합의 사항}
 
  #### 주요 쟁점 및 결론
  {각 쟁점별로: 쟁점 내용 → 채택된 방향 → 채택 이유 (1~2줄)}
 
  #### 기각된 대안
  {검토했으나 채택하지 않은 접근법과 그 이유}
 
- **계획**: (토론 결과를 반영한 최종 계획. 각 항목은 "어디에 무엇을" 수준으로 간결하게 작성.
  실제 코드는 쓰지 않는다.
  비직관적 로직·특수 순서 등 오해 소지가 있는 케이스만 추가 설명을 기재한다.
  동일 패턴이 여러 곳에 존재하면 모든 위치를 항목으로 나열한다.)
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - 예상 결과: 한 줄
 
- **영향 범위**:
  - 영향받는 모듈: {파일명 나열, 없으면 "없음"}
  - 주요 호출부: {파일명:라인 나열, 없으면 "없음"}
  - 회귀 위험: {위험 지점 설명, 없으면 "없음"}
 
- **에이전트 사용 계획**: {구현 시 사용할 에이전트. 사용하지 않으면 "없음"}
  - 에이전트 이름
  - 사용 목적
  - 사용 시점 (구현 중 / 결과 검증 시)
 
- **작업 내용**: 계획 수립 완료
- **결과**: 계획 수립 완료

STEP 5 — 완료 보고

저장 후 사용자에게 다음을 알린다.

  • 저장된 파일 전체 경로
  • 토론 하이라이트: 주요 쟁점 1~3개와 채택된 결론 (각 1줄)
  • 최종 계획 요약 (3~5줄)
  • 영향 범위 요약 — 회귀 위험이 있으면 강조 표시
  • “구현을 진행하려면 말씀해 주세요.”

참고 — 사용 가능한 에이전트 목록

Round 1의 각 전문가 에이전트 내부에서 아래 에이전트를 활용할 수 있다.

에이전트사용 상황
Explore코드베이스 전체 탐색, 파일 패턴·키워드 검색, 영향 범위 파악
Plan구현 전략·아키텍처 설계, 트레이드오프 분석이 필요할 때
gemini-researcher외부 웹 검색, 최신 기술 동향, 라이브러리 API 정보 조사
general-purpose위 외의 복합적 멀티스텝 조사·분석 (prompt로 역할 지정)

주의사항

  • Round 1의 4개 에이전트는 반드시 병렬로 실행한다 (하나의 메시지에 4개 Agent tool 호출).
  • 각 에이전트는 코드를 읽기만 하고, 절대 수정하지 않는다.
  • Round 2 Debate Agent는 Round 1 결과가 모두 도착한 후 순차 실행한다.
  • Round 3 계획서 작성은 메인 에이전트가 직접 수행한다.

중요 — 스킬 종료 규칙

STEP 5 완료 보고 후 반드시 여기서 멈춘다. 사용자가 명시적으로 “계획대로 해줘” 등 구현 지시를 내리기 전까지 코드 파일을 절대 수정하지 않는다. 계획서 파일 외에는 어떤 파일도 Edit/Write하지 않는다.

Graph View