# 요구조건 문서 작성 가이드

이 디렉터리는 Requirement Agent가 작성하거나 제안한 기능별 요구조건 문서를 보관하는 위치다.

기본 파일명은 `docs/requirements/<feature-id>.md` 형식을 사용한다. 각 문서는 구현 전에 작성되며, Formulation Agent, I/O Definition Agent, Reference Model Agent, Implementation Planning Agent가 이어받을 수 있는 검증 가능한 baseline이어야 한다.

## Requirement Agent 역할

Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 바꾼다.

수행한다:
- 기능 범위, 제외 범위, 입력, 출력, 제약조건을 정의한다.
- 해석 타입, 대상 요소, 자유도, 재료 모델, 경계조건, 하중 조건을 명확히 한다.
- 절점 변위, 반력, 요소 내력, 응력 등 검증 물리량을 정한다.
- tolerance와 reference artifact 요구사항을 기록한다.
- Requirement Verification Matrix를 작성한다.

수행하지 않는다:
- C++ 코드를 구현하지 않는다.
- 유한요소 정식화를 확정하지 않는다.
- C++ API나 파일 구조를 설계하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- reference HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
- 기능 완료 여부를 승인하지 않는다.

## 문서 템플릿

```markdown
# <feature title> Requirements

## Metadata
- feature_id: <feature-id>
- title: <title>
- status: draft | needs-user-decision | approved
- owner_agent: requirement-agent
- date: <YYYY-MM-DD>

## Purpose
<기능 목적과 사용자/개발자 관점의 기대 동작>

## In Scope
- <포함 범위>

## Out Of Scope
- <제외 범위>

## Analysis Definition
- analysis_type: linear static | nonlinear static | modal | other
- elements: <대상 요소>
- dofs: <자유도>
- material_model: <재료 모델>
- boundary_conditions: <경계조건>
- loads: <하중 조건>
- coordinate_system: <좌표계>
- units: <단위계>

## Input Requirements
- <입력 요구조건>

## Output Requirements
- <출력 요구조건>

## Verification Quantities
- nodal_displacement: required | not-applicable
- reaction: required | not-applicable
- element_internal_force: required | not-applicable
- stress: required | not-applicable
- strain: required | not-applicable
- energy_or_residual: required | not-applicable

## Tolerance Policy
- absolute_tolerance: <value or TBD>
- relative_tolerance: <value or TBD>
- norm_based_tolerance: <value or TBD>

## Reference Artifact Requirements
Expected location: `references/<feature-id>/`

- `model.inp`: required | not-applicable
- `metadata.json`: required
- `reference.h5`: required | not-applicable
- `csv/displacements.csv`: required | not-applicable
- `csv/reactions.csv`: required | not-applicable
- `csv/element_forces.csv`: required | not-applicable
- `csv/stresses.csv`: required | not-applicable

## Requirement Verification Matrix

| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| FESA-REQ-<FEATURE>-001 | The FESA solver shall ... | functional | ... | user | must | reference-comparison | ... | ... | Reference Model Agent; Implementation Planning Agent | draft |

## Open Questions
- <미확정 값 또는 사용자 결정 필요 사항>

## Downstream Handoff

### Research Agent
- <조사할 이론, 논문, benchmark, 표준>

### Formulation Agent
- <정식화 단계에 넘길 해석 타입, 요소, 재료, 자유도, 출력 물리량 계약>

### I/O Definition Agent
- <입력/출력 schema 요구조건>

### Reference Model Agent
- <필요한 references/<feature-id>/ artifact 목록>

### Implementation Planning Agent
- <먼저 작성할 테스트와 acceptance criteria>
```

## 품질 기준

- 모든 `must` 요구조건은 검증 방법과 acceptance criteria를 가져야 한다.
- 모든 수치 요구조건은 단위, 좌표계, tolerance 또는 `TBD with owner`를 가져야 한다.
- reference 비교가 필요한 요구조건은 필요한 CSV artifact를 명시해야 한다.
- "빠르게", "정확하게", "Abaqus처럼" 같은 문장은 검증 가능한 기준으로 바꾸거나 open question으로 남겨야 한다.
- 구현 방법, 정식화 세부식, C++ API는 이 문서에서 확정하지 않는다.