FESADev/AGENTS.md

# FESA Structural Solver

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

## 프로젝트 문서와 영역

```text
.
├── AGENTS.md                         → 작업 진입점과 핵심 규칙
├── CLAUDE.md                         → 같은 내용의 작업 진입점
├── docs/
│   ├── README.md                      → 기능별 기술 요약 색인
│   ├── solver-core/README.md          → 공통 구조·I/O·수치 기준·빌드 방법
│   └── <feature-id>/                  → 기능 요약과 formulation 원문
├── 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
├── 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/solver-core/README.md), 변경할 기능의
[기술 요약](docs/README.md)과 해당 영역의 AGENTS.md를 확인한다.
같은 문맥에서 읽고 바뀌지 않은 자료는 다시 읽지 않는다.
Public header 변경은 대응하는 src 영역의 책임과 consumer까지 확인한다.

- 범위·physics·절차 변경: 기능 요약의 채택 범위·수식·구현 한계와 formulation을 확인한다.
- 입력·결과·비교 변경: 공통 I/O·수치 기준과 해당 기능의 identity·reference mapping을 확인한다.
- C++ 구현: 공통 요약의 코딩 규약, 해당 영역 지침과 행동을 검증할 검사를 확인한다.
- 빌드 변경: 실제 preset·target graph·dependency와 명령의 side effect를 실행 전에 확인한다.
- 기능 재개: 해당 기능 요약의 현재 구현·검증·미해결 범위를 대조한다.
  과거 phase 파일은 보존된 개발 이력이며 현재 실행 지시가 아니다.

기능별 요약은 `docs/<feature-id>/README.md` 한 곳에 두고 수식은 formulation 원문을 따른다.
기존 승인된 기술 의미·수치 기준·source identity와 관련 없는 사용자 변경을 보존한다.
일반 기능 작업은 요청과 관련 없는 공통 규칙을 함께 바꾸지 않는다.
필요한 전문 작업만 선택하고 승인된 일반 작업에 반복 승인 절차를 추가하지 않는다.

## 문제 처리

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

나머지 문제는 현재 owner가 관련 범위에서 해결한다. 지금 해결할 수 없는 문제는 재현 조건,
영향, 해결하지 못하는 이유와 다음 접근을 해당 기능 요약의 미해결 항목에 기록한다.
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.

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