spec-scanner

spec-scanner

기획서/명세서 디렉토리를 스캔하여 구조를 파악하고, 불명확·누락·미결정 항목을 탐지한 뒤, 정해진 중간 포맷으로 분석 결과를 출력한다.

입력

사용자에게 아래 항목을 확인한다:

항목	필수	기본값	설명
docs_path	Y	-	기획서 디렉토리 경로
scope	N	"전체"	스캔 범위 (전체 / 특정 도메인 이름)
output_path	N	{docs_path}/../meeting-prep/	분석 결과 저장 경로

처리 단계

1. 구조 파악 (적응형)

특정 기획서 구조를 가정하지 않고 아래 순서로 적응적으로 파악한다:

1. 디렉토리 트리 스캔: 전체 파일/폴더 목록 획득
2. 파일 유형 식별: .md, .txt, .docx, .pdf 등 문서 파일 필터링
3. 인덱스/목차 파일 탐지: "인덱스", "index", "목차", "README", "00_" 등의 패턴으로 목차 파일 식별
4. 도메인/카테고리 추론: 폴더명, 파일명 prefix, 인덱스 파일 내용으로 도메인 구분
5. 문서 간 참조 관계 파악: 문서 내 링크([text](path), → 파일명) 추출하여 참조 그래프 구축

2. 문서 내용 분석

각 문서를 읽고 아래 불명확 항목을 탐지한다:

유형	탐지 패턴	설명
미정	"미정", "TBD", "TODO", "미확정", "추후", "별도 정의 예정"	명시적 미결 표시
미구현	취소선(~~), "미구현", "백로그", "개발 필요"	보류/미구현 항목
일정미확정	"정식 출시 이후", "Phase N 이후", "추후 개발", "미배정"	일정 비확정
결정필요	"결정 필요", "확인 필요", "논의 필요", "검토 필요"	명시적 결정 요청
빈값	테이블 셀이 비어있음, "없음", "미작성"	정보 누락
참조깨짐	참조된 파일/섹션이 실제로 존재하지 않음	문서 간 정합성
모호한정의	"~ 필요"로 끝나는 한 줄 요구사항	구체 방안 없음

추가 분석:

• 각 불명확 항목의 영향 범위 추정 (해당 항목을 참조하는 다른 문서/기능)
• 최근 변경 사항 (git log 가능 시 활용)

3. scope 필터링

scope가 "전체"가 아닌 경우:

• 해당 도메인/키워드와 관련된 문서만 상세 분석
• 단, 참조 관계에 의해 연결된 다른 도메인 문서도 간략히 포함

출력 포맷 (중간 포맷)

반드시 아래 구조를 준수한다. meeting-doc-gen이 이 포맷을 파싱하여 사용한다.

{output_path}/spec-analysis.md에 저장:

# 기획서 분석 결과

> 분석일: {YYYY-MM-DD}
> 스캔 범위: {전체 | 도메인명}
> 스캔 경로: {docs 경로}
> 총 문서 수: {N}개

---

## 구조 요약

### 도메인 목록
| 도메인 | 문서 수 | 핵심 기능 | 인덱스 파일 |
|--------|---------|----------|------------|

### 문서 간 참조 관계
- {소스 파일} → {대상 파일}: {참조 내용 요약}

---

## 불명확 항목

### [SPEC-001] [{도메인}] {항목 제목}
- **파일**: `{파일 경로}` (L{시작행}~L{끝행})
- **현황**: {현재 기술 내용 요약}
- **유형**: {미정 | 미구현 | 참조깨짐 | 결정필요 | 빈값 | 모호한정의 | 일정미확정}
- **상세**: {왜 불명확한지, 어떤 정보가 빠져있는지}
- **영향 범위**: {이 항목이 영향 미치는 다른 기능/문서 목록}

---

## 문서 정합성 이슈

### 깨진 참조
| 소스 파일 | 참조 대상 | 유형 |
|----------|----------|------|

### 모순 사항
| 문서 A | 문서 B | 내용 |
|--------|--------|------|

---

## 최근 변경 사항
- {날짜}: {파일명} — {변경 요약}

주의사항

1. 컨텍스트 윈도우 관리: 기획서가 수십 개일 경우, 모든 파일을 한번에 읽지 말고 인덱스 파일을 먼저 읽은 뒤 필요한 파일만 상세 분석
2. 오탐 최소화: "필요"라는 단어가 모두 불명확 항목은 아님. 문맥을 고려하여 실제로 결정/구체화가 필요한 항목만 탐지
3. 출처 정확성: 파일 경로와 행 번호는 반드시 실제 확인된 것이어야 함
4. 범용성: 한국어/영어 기획서 모두 처리 가능해야 함
5. 증분 분석: scope가 특정 도메인인 경우에도, 전체 구조 요약은 간략히 포함하여 맥락 제공