FESADev/docs/FEATURE_DOCUMENTATION.md

# Feature 문서 관리

지속할 요구사항·계약·검증 evidence가 필요한 solver Feature에는 `docs/<feature-id>/`를
사용한다. 메인 assistant가 안정적인 kebab-case Feature ID를 정하고 context와 문서 목록을
관리한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
현재 운영은 [ADR-028](ADR.md#adr-028)과 [Agent 계약](SOLVER_AGENT_DESIGN.md)을 따른다.

## 시작과 참조

1. 새 Feature 폴더를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다.
   재개 시 기존 계약과 evidence를 읽고 필요한 부분만 갱신한다.
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 일반 Feature
   작업에서 읽기 전용 기준이다. Feature 진행 링크를 공통 문서에 누적하지 않으며 공통
   지침 변경은 별도 사용자 요청 범위에서 수행한다.
3. Specialist는 할당 작업에 관련된 Feature 문서와 원문의 절만 읽는다.
   `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니므로 필요한 context는
   메인이 경로·절로 전달한다. 모든 인계에서 핵심 문서 3개를 재독하도록 강제하지 않는다.
4. 과거 단계별 계획·coordination은 현재 작업 입력이 아니다. 별도 문서 정리 요청에서는
   유효한 결정·승인·실패·검증 근거를 현재 기능 문서에 통합하고 반복 진행 기록을 제거할 수 있다.
   요구사항·ADR ID와 당시 판정은 보존하며, 이동·삭제 시 저장소의 파일·절 참조를 갱신한다.
   `coordination.md`를 새로 생성하거나 현재 상태 기록을 위해 갱신하지 않는다.

Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 실제 상위 계약 문제는
해당 owner와 메인에 evidence를 전달하고 필요한 사용자 결정을 따른다.

## 메인이 관리하는 핵심 문서

| 문서 | 필요한 내용 | 프로젝트 기준 링크 |
| --- | --- | --- |
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당된 owner와 유용한 문서 목록. 현재 checklist는 PRD에 연결 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본, 필요한 상세 계약 링크 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거. 실제 결정이 없으면 그 사실과 적용 공통 결정 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |

- 현재 checklist는 PRD 한 곳에서 관리한다. 문서 목록이나 별도 파일에 같은 상태를
  중복 기록하지 않는다.
- 작은 요구사항·acceptance는 PRD에 직접 정의한다. 복잡하여 분리할 필요가 있을 때만
  `requirements.md`나 상세 verification matrix를 작성하고 PRD에는 요약과 링크를 둔다.
  분리된 전문 계약은 할당된 owner가 소유한다.
- 메인은 관련 반환을 확인하여 목록·링크·checklist를 갱신한다. Specialist는 할당된
  문서만 수정하며 downstream이 upstream 계약을 결과에 맞춰 변경하지 않는다.
- 승인되지 않은 내용이나 아직 실행하지 않은 검증을 승인·완료로 표시하지 않는다.
  일반 문서 작성·업데이트를 위해 반복적인 승인 gate를 추가하지 않는다.
- 각 핵심 문서는 실제 프로젝트 기준을 상대 Markdown 링크로 연결한다. 필요한 운영
  설명은 `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md`를 참조한다.

## 필요한 상세 문서와 evidence

결과를 지지하는 다음 내용만 필요한 만큼 기록한다.

1. 해당 Feature·작업·owner와 적용 계약 또는 관련 revision.
2. 판단·결정, 구현·검토에 필요한 정의와 주요 발견.
3. 출처·evidence 경로, 실제 명령·exit code·결정적 측정값과 적용 기준.
4. 가정, 미지원 범위, 미해결 항목·제한과 다음 작업에 필요한 정보.

`research.md`, `formulation.md`, `io.md`, `numerical-review.md`,
`reference-model.md`, `implementation-report.md`, `build-test.md`,
`reference-comparison.md`, `physics-evaluation.md`는 필요한 경우의 산출물 예시다.
간단한 구현·build/test·reference 결과는 하나의 짧은 보고서에 모을 수 있으며 같은 결과를
여러 기본 보고서에 반복하지 않는다. Release 보고서는 명시적으로 감사를 요청한 경우에만 작성한다.

긴 유도·전체 schema·mapping·검증 matrix가 필요하면 같은 폴더의
`formulation-derivation.md`, `io-schema.md` 같은 문서로 분리하여 관련 본문에서 연결한다.
상세 문서는 해당 전문 owner가 소유하고 적용되는 계약과 기본 문서를 명확히 연결한다.
반환할 때 판단에 사용한 상세 evidence 경로도 포함한다. 고정 envelope나 모든 산출물의
hash·gate 기록은 요구하지 않는다.

짧게 쓰기 위해 필수 수식·identity·units·schema·tolerance·acceptance 정의를 없애지 않는다.
문서만 수정할 때 원시 로그나 의미 변화 없는 revision 기록을 추가하지 않는다. 실제 계약이
변경되면 관련 evidence가 여전히 유효한지 확인하며 과거 결과를 현재 검증으로 소급하지 않는다.
필수 검증을 실행하지 않았다면 미실행 사실과 이유를 남긴다.

소스·테스트·기계 생성 로그/결과·read-only reference artifact는 각자의 지정 경로에 유지하고
보고서에서 참조한다. 기존 phase 이력은 새 보고서 형식에 맞추어 변경하지 않는다.
Reference artifact와 tolerance를 구현 결과에 맞추어 수정하지 않는다.

## 기능 문서 정리 기준

기능별 [README](README.md#기능별-진입점)는 목적·현재 범위와 필요한 문서의 진입점이다.
파일 수를 고정하지 않으며 짧은 결과 보고서는 `verification.md`, 중요한 수정은
`lessons.md` 등으로 통합할 수 있다. 기존 PRD·ADR·정식화·I/O의 유효한 의미를 유지한다.

- 최종 수식·가정·단위·부호·좌표·source identity·적용 한계와 공개 I/O를 보존한다.
- 재사용 책임·수명과 재사용하면 안 되는 조건을 Handoff에 명시한다.
- 채택 이유·중요한 대안·승인 이력을 유지하고 오래된 실패 원인을 해결 상태와 함께 기록한다.
- 구현/검증 완료, PASS/FAIL/SKIP/미실행과 보류를 구분하고 과거 readiness를 승계하지 않는다.
- 실행 revision·환경·명령·native exit·주요 metric·reference identity와 evidence 위치를 유지한다.
- 최신 날짜나 링크 부재만으로 삭제하지 않는다. 중복은 한 원본으로 통합하고 참조를 수정한다.
- 삭제한 파일의 과거 원문은 Git revision과 원래 경로로 조회할 수 있게 연결한다.

원시 로그·논문·reference 데이터는 별도 역할이다. 존재하지 않는 개인 artifact를 유효한
파일 링크로 표시하거나 문서 정리를 이유로 원본을 생성·보정하지 않는다.

## 언어와 확인

기본 Feature 문서는 한국어 Markdown으로 작성하고 agent/skill ID, field, requirement ID,
경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`다.

메인은 실제 파일·소유권·상대 링크와 판단에 필요한 evidence를 확인한다. 필수 상세 근거가
없거나 연결이 끊겼다면 해당 owner와 해결하고 요약만으로 검증을 대신하지 않는다.
문서 정리는 정적 검토로 확인하며 solver build나 수치/reference 검증의 통과로 보고하지 않는다.