analyze

/pilot:analyze

Confluence 기획서(docs/)를 분석하여 기능별 구조화된 명세(features/)를 생성한다. PM이 작성한 표 중심 기획서를 AI가 읽기 쉬운 형태로 변환한다.

대상: $ARGUMENTS

---

사전 확인

preamble.md 의 P-1, P0, P1 수행.

• P-1: TodoWrite 선로딩 (다단계 스킬).
• P0: {PROJECT} 와 $ARGUMENTS 키워드로 memory-hint 실행. 출력된 메모를 Read 하여 과거 분석·구현 이력 확인.
• P1: {PROJECT} 획득. 실패 시 messages.md 의 workspace_missing / no_active_project 출력 후 종료.

추가: workspace/projects/{PROJECT}/docs/ 폴더를 Glob 으로 확인한다.

• 폴더가 없거나 .md 파일이 없으면 messages.md 의 docs_missing 출력 후 종료.

---

인자 판별

$ARGUMENTS에서 --force · --regen-agents 플래그를 먼저 분리하고, 나머지 텍스트로 모드를 결정한다.

플래그 / 나머지 텍스트	모드	동작
--regen-agents (단독)	재생성 전용	docs/features 변화 여부와 무관하게 현재 features/ 기반으로 prompts/*.md 만 재작성. 상세: references/regen-mode.md
없음 (빈 문자열)	전체 분석	docs/ 내 모든 원본 파일의 전체 내용 분석
파일명 또는 page_id	파일 지정	해당 파일만 분석
그 외 텍스트 (키워드)	필터 분석	docs/ 전체 파일에서 키워드 관련 기능만 추출하여 분석

필터 분석 모드

기획서에는 여러 영역 (프론트엔드, API, 어드민 등) 의 기능이 혼재되어 있다. 키워드가 주어지면 docs/ 전체 파일을 읽되, 키워드와 관련된 섹션만 추출하여 features/ 파일을 생성한다.

• 예: /pilot:analyze <도메인 키워드> → 해당 도메인 영역 기능만 분석
• 키워드 매칭은 섹션 제목과 내용 모두에서 판단한다.
• 관련 없는 섹션은 스킵한다.

---

분석 프로세스

1. 대상 파일 결정

• workspace/projects/{PROJECT}/docs/*.md 에서 원본 파일 목록을 수집한다.
• --force 가 없으면: features/ 폴더에 이미 분석 파일이 존재하는 원본은 스킵한다.
  • 스킵 판단: features/ 파일 상단 > source: 메타데이터에 원본 파일명이 기록됨
• 분석 대상이 없으면 messages.md 의 analyze_all_done 출력 후 종료한다.

--force 실행 시 prompt-origin 보호

--force 는 기존 features/ 파일을 덮어쓸 수 있다. 그 전에 > source: prompt 태그를 Grep 으로 검색하여 prompt-origin features 가 있는지 확인하고 사용자에게 승인받는다 (1 건 이상 발견 시 경고 + y/n 질의, n 또는 미응답이면 종료). 상세 절차: references/scope-sync.md --force prompt-origin 보호 섹션.

2. 원본 파일 읽기

• 대상 파일을 Read 툴로 로드한다.

• 항상 먼저 수행 (default path, 실패 대응 아님):

  1. confluence.py fetch 출력 또는 wc -l {path} 로 파일 크기·라인 수 확인.
  2. Grep ^##+ 으로 전체 H2/H3 라인 번호 수집 (문서 구조 파악).
  3. 사용자 필터 (다운로드된 docs 의 실제 H2 키워드 2~4개를 예시로 노출 후 사용자 선택) 또는 키워드 매칭으로 관심 H2 섹션 결정.
  4. 각 관심 섹션을 targeted Read.

• 파일 크기 분기 (Read 툴 25k 토큰 한도 대응 — 실전 기획서는 표가 많아 300KB 이상 빈번):

  파일 크기	토큰 추정	권장 Read 전략
  소형 ≤ 50KB	≤ 5k	전체 1 회 Read 가능
  중형 50 ~ 150KB	5k ~ 15k	H2 목차 + 섹션 단위 Read (limit 150)
  대형 > 150KB	> 15k	섹션 단위 targeted Read (limit 80 — 표 많은 문서 보수적 기본값)

• Read rejection 발생 시 재시도 규칙: limit 을 1/3 로 축소 (1/2 는 대형 파일에서 재실패 확률 높음 — 실측). offset 유지.

• 추측 금지 원칙 유지: 읽지 않은 섹션은 features/ 생성 대상에서 제외. 전체 스캔하지 않았다면 사용자에게 범위 보고 후 확정.

• 사용자가 "전체 분석" 을 요청했는데 파일이 대형이면 H2 목차 기반으로 모든 섹션을 순회하여 빠짐없이 커버.

3. 기능 분할 및 구조화

분할 기준: H2(##) 섹션을 기능 단위로 인식. 번호 패턴(#N·N.·N)) 있으면 기능 번호로, 없으면 순차 부여.

각 기능 추출 템플릿:

# #{번호} {기능명}

> source: {원본 docs 파일명}

## 요구사항

- **조건**: 동작 전제 조건
- **트리거**: 사용자 액션 또는 시스템 이벤트
- **기대결과**: 실행 후 예상 결과 (UI·데이터 변경·알림 등)

## 상태 전환

| 전환 전 | 전환 후 | 조건 | 처리 |
| ------- | ------- | ---- | ---- |

## 비즈니스 규칙
- 검증·제약·계산 로직 목록. 원본 표는 표 형태 유지 가능.

## 예외 케이스
- 정상 흐름 외 케이스 + 조건·처리 방법.

주의사항:

• 원본 표는 의미 해석해 서술형으로 풀되 상태 전환표 같은 경우는 표 유지.
• 원본에 없는 내용 추측 금지 (한 번 추측이 들어가면 후속 prompts/·planner·generator 가 잘못된 사실 기반으로 동작).
• Figma 등 디자인 참조 유지.
• 하나의 H2 가 여러 기능 포함하면 기능별 분리.

4. 파일 저장

• 저장 경로: workspace/projects/{PROJECT}/features/
• 기능 명세 파일명: {NN}-{slug}.md
  • NN: 기능 번호 (2자리 zero-padding, 예: 12, 13)
  • slug: 기능명을 kebab-case로 변환 (한글 허용, 특수문자 제거, 최대 30자)
  • 예: 13-order-modal.md, 19-receipt-list.md
• 배치 저장 (병렬 Write) — features 파일은 서로 독립이므로, 동일 assistant turn 안에 여러 Write tool_use 를 묶어 호출한다. harness 가 병렬 실행한다. 실무상 3~5 개 단위 묶음 이 현실적 (파일당 사고 비용 > I/O 비용). 10 개 이상을 한 번에 묶으면 컨텍스트가 혼잡해지므로 분할 권장.

5. project.md 자동 갱신

features/ 생성 후 project.md 의 ## 목표 와 ## 관련 파일 을 자동 동기화한다.

도메인 결정 (5-1, 5-2 공통 전제): .agent-state.yml.domain 이 non-null 이면 그대로 사용 (이미 확정). null 이면 (a) project.md 제한사항 - domain: {x} 파싱 → (b) MANIFEST.md 도메인 분류 + 프로젝트명·features 키워드 매칭으로 후보 → (c) 사용자 질의 후 .agent-state.yml.domain 에 Edit 기록. 결정 후 workspace/context/scope/{domain}.md 를 Read. 자동 판정은 후보 제시용 만, 기록은 항상 사용자 확인 (한 번 잘못 기록되면 후속 분석 전부 오염).

5-1. ## 목표 갱신

project.md 의 ## 목표 섹션 (없으면 ## 에이전트 호출 흐름 바로 앞에 생성) 을 features/ 목록 기준으로 갱신.

• 신규 feature: - [ ] {기능명} -> [상세](features/{NN}-{slug}.md) 항목 추가.
• [x] 로 완료 처리된 항목은 변경 안 함 (이미 끝난 일을 미완료로 돌리지 않음).
• --force 재분석으로 대응 features/ 파일이 없어진 항목은 제거.
• 항목 순서는 features/ NN 순서.

5-1.5. scope/{domain}.md 자동 생성

5-2 진입 전 scope 파일 부재를 detect 하고 자동 생성한다.

트리거 조건 (둘 다 만족):

• workspace/context/scope/{domain}.md 부재 또는 빈 파일.
• MANIFEST 진입파일 (workspace/context/{domain}/index.md 또는 workspace/context/{domain}.md) 에 config.md 의 ## scope 카테고리 scope 헤더 컬럼 값과 일치하는 H2 헤더 존재.

본문 구성·idempotency·예외·A2 fallback 등 상세: references/scope-sync.md 5-1.5 섹션.

5-2. ## 관련 파일 갱신

로드한 scope/{domain}.md 의 매칭 H2 섹션 표를 추출해 project.md 의 ## 관련 파일 표를 자동 기입한다. 어떤 scope 헤더를 어떤 H3 로 기입할지는 config.md 의 ## scope 카테고리 표가 결정하고, 비어있으면 아래 default 를 사용한다.

scope 헤더	project.md 대상 H3	표 헤더
## Routes	Endpoints	엔드포인트, Method, 목적
## Models	Models	Class, DB, 목적
## Services	Services	Class, 파일, 목적

핵심 규칙 — features/ 에 명시적으로 언급된 모델·서비스·라우트는 빠뜨리지 않고 포함 (planner 영향 범위 누락 방지). scope 에 없지만 features/ 에 등장한 신규 대상은 목적 열 끝에 (from features/NN-{slug}) 주석 붙여 추가. 기존 사용자 수동 기입 행은 보존하되 중복만 제거. 빈 행(| | | |) 은 삭제.

config lookup·default fallback·프로세스 단계 상세: references/scope-sync.md 5-2 섹션.

cross-domain 의존성 detect (#09) — features/ 키워드와 scope/{domain}.md 매칭 시도 후 cover 되지 않는 외부 클래스/도메인을 MANIFEST 의 ## 외부 도메인 reference 표에서 lookup. 매칭되면 INFO [INFO] features/ 의 일부 영역이 {외부 도메인} 도메인에 의존 — \/pilot:learn {추천 경로}` 후 재분석 권장 출력. 상세: [references/scope-sync.md`](references/scope-sync.md).

Open Questions 섹션 보존 + 갱신 (#11) — 기존 ## Open Questions 섹션 보존 + cross-domain detect 결과는 ### (b) cross-domain 산출물 부재 에 행 추가 + 신규 파일은 4 카테고리 + - (없음) 포함. 4 카테고리 분류 기준: ../context/shared/open-questions.md. 상세 규칙: references/scope-sync.md.

6. prompts/ 자동 갱신

features/ 분석 결과로 prompts/{planner,generator,evaluator}.md 갱신 + .agent-state.yml.analyzed: true 게이트. 상세 (6-1 ~ 6-5): references/prompts-update.md.

7. 분석 품질 자가 검증

6-5 (doctor) 완료 후 4 항목 (커버리지·구조·정합성·추측 혐의) 자가 점검. 상세 + 출력 형식: references/self-verify.md.

8. 결과 출력

분석 완료: {원본 파일명} + 생성된 features 목록 (features/{NN}-{slug}.md — {기능명}) + 총 N개 + 갱신 파일 (project.md / prompts/*.md / .agent-state.yml) + 검증 한 줄.

---

참고

• features/ 파일은 프로젝트 에이전트(@pilot-planner, @pilot-generator)가 직접 Read하여 사용한다.
• docs/ 파일은 원본 보관용이며 /pilot:confl 커맨드를 통해서만 접근한다.
• 분석 품질이 낮으면 /pilot:analyze --force 로 재분석할 수 있다.
• TDD 모드에서는 @pilot-planner 가 Red 단계에서 features/NN-{slug}.md 를 직접 읽어 실패 테스트를 작성한다 (상세: rgr.md).