Extract Features Json

# Extract Features JSON

프로젝트의 요구사항 문서를 분석하여 `specs/features.json`을 생성합니다.
각 항목은 end-to-end 사용자 시나리오 단위로 추출하며,
Ralph Loop 기반 Coding Agent가 읽고 순차적으로 구현할 수 있는 형식으로 작성합니다.

---

## 필수 선행 독해

**이 커맨드를 실행하기 전에 반드시 아래 문서를 읽어야 합니다.**

`.claude/external_knowledges/ralph_longterm_combined.md` 섹션 5.1 (`specs/features.json` 설계)을 읽습니다.

특히 아래 두 원칙을 반드시 숙지하십시오:
- **기능은 end-to-end 사용자 시나리오 단위**로 세분화합니다. 기술적 구현 단위(함수, 클래스, 모듈)가 아닙니다.
- **`passes` 필드 외 내용은 생성 후 절대 수정 금지**입니다. Anthropic의 표현대로: *"It is unacceptable to remove or edit tests."*

---

## 전제 조건

`specs/features.json`이 이미 존재하는 경우:
- 기존 항목을 수정하거나 삭제하지 않습니다.
- 새로 추출된 기능 중 기존 파일에 없는 항목만 추가합니다.
- 중복 여부는 `description`의 의미 유사도로 판단합니다.

---

## Steps

### Step 1 — 요구사항 문서 수집

아래 파일들 중 존재하는 것을 모두 읽어 요구사항을 파악합니다.
우선순위 순으로 읽습니다.

1. `CLAUDE.md` — 프로젝트 목적, 아키텍처, 주요 기능 기술
2. `README.md` 또는 `README.ko.md` — 사용자 대상 기능 설명
3. `docs/PRD.md`, `docs/requirements.md`, `docs/spec.md` 또는 유사한 문서
4. `.claude/plans/PLAN.md` — 구현 계획에 기술된 기능 목록
5. `docs/` 또는 `spec/` 디렉토리 하위의 모든 마크다운 파일
6. 위 파일이 없으면 프로젝트 루트의 마크다운 파일 전체를 탐색

읽은 문서 목록을 메모합니다.
요구사항이 명시적으로 없거나 매우 추상적인 경우, 코드베이스의 디렉토리 구조와 기존 파일을 탐색하여 의도된 기능을 추론합니다.

---

### Step 2 — 기능 추출 원칙 적용

수집한 요구사항에서 기능을 추출할 때 아래 원칙을 반드시 준수합니다.

#### 올바른 기능 단위 (추출 대상 ✅)

기능은 **"사용자가 X를 할 수 있다"** 형식의 end-to-end 시나리오입니다.

✅ "사용자가 새 채팅을 시작하면 입력창이 열린다" ✅ "사용자가 Init 버튼을 클릭하면 에이전트가 .claude/ 디렉토리를 생성한다" ✅ "Extension이 VSCode 워크스페이스 열기 시 오류 없이 활성화된다"

#### 잘못된 기능 단위 (추출 금지 ❌)

❌ "FileManager 클래스를 구현한다" → 기술 구현 단위, 사용자 시나리오 아님 ❌ "src/service/ 디렉토리를 생성한다" → 프로젝트 설정 작업 ❌ "IAgentRunner 인터페이스를 정의한다" → 내부 설계 단위

단, 인프라성 요구사항(빌드, 배포, 타입 검사 통과 등)은 `"infrastructure"` 카테고리로 포함합니다.

#### 카테고리 분류

| category | 기준 |
|----------|------|
| `functional` | 사용자가 직접 인식하고 상호작용하는 기능 |
| `infrastructure` | 빌드, 배포, 타입 검사, 패키징, 테스트 환경 등 기반 요소 |

#### 우선순위(priority) 부여

숫자가 낮을수록 높은 우선순위입니다.

- `1`: 시스템이 동작하기 위한 최소 전제 조건 (핵심 진입점, 기본 초기화 등)
- `2`: 핵심 사용자 흐름 (메인 기능 경로)
- `3`: 보조 기능, 설정, 커스터마이징
- `4`: 엣지 케이스, 에러 처리, 경고 메시지
- `5`: 성능, 접근성, 문서화 등 품질 개선 항목

---

### Step 3 — features.json 항목 작성

각 기능을 아래 JSON 스키마에 맞춰 작성합니다.

```json
{
  "id": "F-001",
  "category": "functional",
  "priority": 1,
  "description": "사용자가 [행동]하면 [결과]가 된다",
  "steps": [
    "전제 조건 또는 탐색 시작점을 설정한다",
    "사용자 행동을 실행한다 (클릭, 입력, 명령 실행 등)",
    "예상 결과가 나타나는지 확인한다",
    "부수 효과(파일 생성, 상태 변경 등)가 있으면 함께 확인한다"
  ],
  "passes": false,
  "implemented_in_commit": null,
  "notes": ""
}

필드 작성 규칙

필드	규칙
id	F- 접두사 + 3자리 숫자. 기존 파일이 있으면 마지막 id 이후 번호부터 시작.
category	"functional" 또는 "infrastructure" 중 하나만 사용.
priority	1~5 정수. 동일 우선순위 허용.
description	"사용자가 ~할 수 있다" 또는 "~가 ~한다" 형식. 기술 용어보다 사용자 언어 우선.
steps	검증자(QA 또는 에이전트)가 따라할 수 있는 구체적인 단계. 최소 3개, 최대 8개. 각 단계는 동사로 시작.
passes	항상 false로 초기화. 절대 true로 설정하지 말 것.
implemented_in_commit	항상 null로 초기화.
notes	항상 ""로 초기화.

steps 작성 패턴

steps는 E2E 검증 절차입니다. 아래 패턴을 참고합니다.

"[탐색/진입] ~로 이동한다 / ~를 연다 / ~를 실행한다"
"[행동]       ~를 클릭한다 / ~를 입력한다 / ~를 선택한다"
"[확인]       ~가 표시되는지 확인한다 / ~가 생성되는지 확인한다"
"[부수 효과]  ~파일이 존재하는지 확인한다 / ~상태가 변경되었는지 확인한다"
"[에러 없음]  오류 메시지가 없는지 확인한다 / 콘솔에 에러가 없는지 확인한다"

---

Step 4 — specs/features.json 파일 저장

1. specs/ 디렉토리가 없으면 생성합니다.
2. specs/features.json이 없으면 추출한 전체 배열을 새로 씁니다.
3. specs/features.json이 이미 있으면: a. 기존 파일을 읽어 현재 id 목록을 파악합니다. b. 새로 추출한 기능 중 description이 기존 항목과 의미상 중복되지 않는 항목만 선별합니다. c. 선별된 새 항목을 기존 배열 뒤에 추가합니다. id는 기존 최대값 이후 번호를 부여합니다. d. 기존 항목은 어떤 필드도 변경하지 않습니다.
4. 최종 JSON이 유효한지 확인합니다 (배열 형식, 필드 누락 없음).

---

Step 5 — 결과 보고

파일 저장이 완료되면 다음 항목을 보고합니다:

1. 참조한 요구사항 문서 목록: 어떤 파일을 읽었는지
2. 추출된 기능 수: 신규 추가 X개 / 기존 유지 Y개 / 전체 Z개
3. 카테고리별 분포: functional X개, infrastructure Y개
4. priority별 분포: 각 우선순위 항목 수
5. 주의 필요 항목: 요구사항이 모호하여 추론으로 작성된 항목 목록 (있을 경우)
6. 다음 단계: /configure_loop을 실행하여 루프 환경을 설정하세요.

---

생성 후 불변 규칙

specs/features.json이 생성된 이후에는 아래 규칙이 영구적으로 적용됩니다.

passes 필드만 수정 가능합니다. id, category, priority, description, steps는 어떠한 이유로도 수정하거나 삭제할 수 없습니다. 요구사항이 변경된 경우에는 기존 항목을 수정하는 대신 새 항목을 추가합니다. 이 규칙은 ralph_longterm_combined.md의 핵심 원칙에서 도출됩니다: "It is unacceptable to remove or edit tests."