FESADev/docs/FEATURE_DOCUMENTATION.md

# Feature 문서 관리

이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.

## 시작과 참조

1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를
   재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다.
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용
   기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다.
3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고
   자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는
   `AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다.
4. 기존 `docs/features/<feature-id>/` 자료는 이력이므로 자동 이동하거나 복제하지 않는다.
   재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다.

이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.

## Coordinator 관리 문서

| 문서 | 필요한 내용 | 참조 기준 |
| --- | --- | --- |
| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` |
| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 |
| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 |
| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 |

- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를
  가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다.
  현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다.
- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에
  결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로
  표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다.
- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다.
  Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다.
- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를
  갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다.
- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자
  요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.

## Agent 산출물 작성

각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.

1. 식별: Feature ID, owner, 입력 contract revision.
2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.

상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.

긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.

- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
  적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
  기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
  문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
  기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
  참조한다.

## Gate 확인

Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
검증을 대신하지 않는다.