FESADev/AGENTS.md

# FESA Structural Solver

FESA는 개인 연구를 위해 개발하는 유한요소 구조해석 솔버이며 외부 사용자 배포를 장기
목표로 한다. C++17 이상·Windows MSVC·CMake/CTest를 사용하고 승인된 Abaqus 입력
subset에서 재현 가능한 해석과 HDF5 결과를 제공한다. 코드 존재와 기능 검증 완료는 다르다.

## 프로젝트 문서와 영역

```text
.
├── AGENTS.md                         → 작업 진입점과 핵심 규칙
├── CLAUDE.md                         → 같은 내용의 작업 진입점
├── docs/
│   ├── ARCHITECTURE.md                → 구성·데이터 흐름·소유권
│   ├── business-rules.md              → 물리 의미와 제품 범위
│   ├── security.md                    → 실행 권한과 데이터 취급
│   ├── standards.md                   → 개발·검증·변경의 공통 규칙
│   ├── engineering-notes.md           → 수치·실행에서 혼동하기 쉬운 점
│   ├── operations.md                  → 환경 준비·빌드·검사·실행
│   ├── contracts.md                   → CLI·입력·결과·비교 계약
│   ├── PRD.md                         → 기존 공통 요구사항과 승인 ID
│   ├── ADR.md                         → 기존 결정·승인·대체 이력
│   ├── TOLERANCE.md                   → 승인된 외부 비교 기준의 상세 원본
│   ├── CODINGSTYLE.md                 → 기존 C++ 규약의 상세 원본
│   ├── FEATURE_DOCUMENTATION.md       → 기능별 기록의 소유권
│   ├── SOLVER_AGENT_DESIGN.md         → 전문 역할과 사용자 결정 경계
│   ├── SOLVER_SKILL_DESIGN.md          → 전문 skill의 적용 범위
│   ├── HARNESS.md                     → 기존 검증 실행기 상세 사용법
│   ├── HARNESS_WORKFLOW.md            → 검증 실행기의 책임과 실패 처리
│   ├── <feature-id>/                  → 해당 기능의 요구·결정·수식·I/O·evidence
│   └── tracking/
│       ├── status.md                  → 구현·검증 상태와 남은 범위
│       ├── findings.md                → 미해결 문제와 영향
│       └── decisions/
│           ├── index.md               → 유지하는 선택 목록
│           ├── 0001-independent-solver.md       → 외부 subset과 내부 독립성
│           ├── 0002-build-and-backends.md       → 검증 환경과 vendor 격리
│           ├── 0003-model-and-equations.md      → 모델·view·equation 소유권
│           ├── 0004-ordered-assembly.md         → local 계산과 결정적 누적
│           ├── 0005-state-and-output.md         → candidate와 최종 결과 보존
│           ├── 0006-procedure-lifecycle.md      → 절차별 상태와 full residual
│           ├── 0007-reference-evidence.md       → 원본과 수치 비교 정책
│           ├── 0008-layered-verification.md     → 독립 수치·물리 검증
│           ├── 0009-explicit-development.md     → 필요한 전문 작업과 명시 실행
│           ├── 0010-feature-contract-ownership.md → 기능별 계약 소유권
│           ├── 0011-eigen-first-implementation.md → 고유치 첫 구현의 경계
│           ├── 0012-hht-kinetic-mass.md          → 동역학 질량 선택
│           └── 0013-thermal-staged-scope.md      → 초기 열해석 범위
├── include/fesa/
│   └── AGENTS.md                     → 공개 API와 수명·의존성
├── src/fesa/
│   ├── AGENTS.md                     → production target과 구현 경계
│   ├── app/AGENTS.md                 → 경로·lease·실행 조합
│   ├── core/AGENTS.md                → source identity·진단
│   ├── model/AGENTS.md               → Domain·target·geometry
│   ├── properties/AGENTS.md          → section·material 연결
│   ├── materials/AGENTS.md           → 물성 capability와 구성 관계
│   ├── elements/AGENTS.md            → local 수식·회전·관성
│   ├── loads/AGENTS.md               → 하중 의미와 contribution
│   ├── fem/AGENTS.md                 → DOF·equation·pattern
│   ├── constraints/AGENTS.md         → 지정값·partition
│   ├── assembly/AGENTS.md            → deterministic reduction
│   ├── analysis/AGENTS.md            → procedure·trial·commit
│   ├── math/AGENTS.md                → storage·private 수치 adapter
│   ├── solvers/
│   │   ├── linear/AGENTS.md          → factorization·solve
│   │   └── eigen/AGENTS.md           → FEAST·count·검증 경계
│   ├── results/AGENTS.md             → 복구량·identity·candidate
│   └── io/
│       ├── abaqus/AGENTS.md          → 문법·의미 mapping
│       └── hdf5/AGENTS.md            → schema·readback·finalize
├── scripts/
│   ├── AGENTS.md                     → 명시 실행 진입점
│   ├── msvc_harness/AGENTS.md         → config·toolchain·명령 실행
│   └── verification/AGENTS.md        → 원본 reference 비교
├── tests/
│   └── AGENTS.md                     → 계층별 검사·실패·비교 evidence
└── cmake/
    └── AGENTS.md                     → dependency·runtime 연결
```

## 핵심 규칙

1. 승인된 물리·입력·결과·수치 기준을 구현 편의로 바꾸지 않는다. 모호한 의미를 silent
   default·clamp·평균으로 숨기지 않는다.
2. Source identity와 내부 index를 구분하고 병렬 실행에서도 구조·누적·결과·진단 순서를
   결정적으로 유지한다.
3. 모델 정의·equation·state·local 계산·adapter의 소유권을 지킨다. Vendor 타입을 public
   core에 노출하지 않고 실패한 candidate가 유효한 state나 최종 HDF5를 오염시키지 않게 한다.
4. Reference 원본과 관련 없는 사용자 변경을 보존한다. 생성·수정·복원, 외부 solver·비용,
   원격·파괴·release 작업은 명시적으로 승인된 범위에 한정한다.
5. 실행 성공을 correctness로 대체하지 않는다. 수식 변경에는 독립 검토와 필요한 물리
   검증을 수행하고 실패·미실행·과거 evidence를 현재 통과로 보고하지 않는다.

## 작업 전 확인

기본적으로 [개발 규칙](docs/standards.md), [주의점](docs/engineering-notes.md)과
변경할 영역의 AGENTS.md를 확인한다. 같은 문맥에서 읽고 바뀌지 않은 자료는 다시 읽지 않는다.
Public header 변경은 대응하는 src 영역의 책임과 consumer까지 확인한다.

- 범위·physics·절차 변경: [제품 요구](docs/PRD.md), [구조](docs/ARCHITECTURE.md),
  [기존 결정](docs/ADR.md)과 해당 Feature의 PRD·ADR·정식화·독립 검토.
- 입력·결과·비교 변경: [외부 계약](docs/contracts.md), [수치 기준](docs/TOLERANCE.md),
  해당 Feature의 I/O·reference mapping. 공통 요약이 승인된 상세 계약을 덮어쓰지 않는다.
- C++ 구현: [코딩 규약](docs/CODINGSTYLE.md), 해당 영역 지침과 행동을 검증할 검사.
- 실행기·빌드 변경: [실행 방법](docs/operations.md), 실제 config·preset·target graph.
  Config와 명령의 side effect는 실행 전에 확인한다.
- 기능 재개: [전체 현황](docs/tracking/status.md)과 Feature PRD의 실제 checklist.
  폐기된 phase·hook·고정 stage 순회를 복원하지 않는다.

[기능 기록](docs/FEATURE_DOCUMENTATION.md)의 FEATURED_AGENTS·PRD·ADR과 기존
요구사항 ID·승인 이력은 보존한다. 공통 지침을 바꾸는 별도 요청 없이 일반 Feature 작업에서
프로젝트 PRD·ADR·지침을 수정하지 않는다. 현재 checklist는 Feature PRD 한 곳에 둔다.

메인이 필요한 전문 작업만 배정한다. 역할은 [전문 작업 운영](docs/SOLVER_AGENT_DESIGN.md),
적용 범위는 [Skill 사용](docs/SOLVER_SKILL_DESIGN.md)을 따른다. 구현 계획·수정에는
fem-implementation-tdd, 명시 build/test에는 [harness](.agents/skills/harness/SKILL.md),
요청 diff 검토에는 [review](.agents/skills/review/SKILL.md)를 사용한다. Release-readiness는
별도 명시 요청에만 수행한다. 승인된 일반 작업에 반복 승인 gate를 추가하지 않는다.

## 문제 처리

승인된 physics·acceptance·영속 schema를 바꿔야 하는 경우, 필수 reference와 계약이
충돌한 경우, 기존 최종 결과 손상·원본 reference 변경이 발견된 경우에는 즉시 사용자에게
근거와 영향을 알린다. 자동으로 tolerance를 완화하거나 데이터를 복구·보정하지 않는다.

나머지 문제는 현재 owner가 관련 범위에서 해결한다. 지금 해결할 수 없는 문제는 재현 조건,
영향, 해결하지 못하는 이유와 다음 접근을 [미해결 문제](docs/tracking/findings.md)에 기록한다.
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.

문서만 변경하면 정적 검토를 하고 build/test를 실행하지 않는다. 동작 변경은 관련 검사부터,
솔버 기능 완료 시에는 구성된 전체 MSVC x64 Debug build/CTest와 필수 reference 비교를 수행한다.