FESADev/CLAUDE.md

# FESA Structural Solver

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

## 프로젝트 문서와 영역

```text
.
├── AGENTS.md                         → 작업 진입점과 핵심 규칙
├── CLAUDE.md                         → 같은 내용의 작업 진입점
├── docs/
│   ├── README.md                      → 기능별 기술 요약 색인
│   ├── architecture.md                → 구성 요소·의존 방향·실행 흐름
│   ├── business-rules.md              → 물리량·상태 전이·수치 판정 규칙
│   ├── security.md                    → 로컬 실행·파일 보호·권한 경계
│   ├── standards.md                   → 개발·의존성·검증의 필수 기준
│   ├── engineering-notes.md           → 재현된 함정과 대응 방법
│   ├── operations.md                  → 환경 준비·빌드·실행·검사 절차
│   ├── contracts.md                   → CLI·입력·결과·실패의 외부 계약
│   ├── tracking/
│   │   ├── status.md                  → 구현과 실제 검증 상태
│   │   ├── decisions/                → 대안·선택 이유·영향
│   │   │   ├── index.md              → 결정 기록 목록
│   │   │   ├── 0001-input-subset.md   → 입력 표기와 알고리즘 구분
│   │   │   ├── 0002-typed-ownership.md → 정의와 실행 상태 소유권
│   │   │   ├── 0003-ordered-reduction.md → 병렬 누적 순서
│   │   │   ├── 0004-candidate-output.md → 검증 뒤 최종 파일 공개
│   │   │   ├── 0005-eigen-comparison.md → 한정된 고유치 비교 예외
│   │   │   ├── 0006-thermal-diagnostic.md → NT11 진단 분류
│   │   │   ├── 0007-local-build-paths.md → 두 빌드 경로와 로컬 의존성
│   │   │   ├── 0008-shell-inertia.md  → Shell 질량 영공간
│   │   │   ├── 0009-hex8-numerics.md  → Hex8 강성·질량·정밀도
│   │   │   └── 0010-thermal-discretization.md → 두께 온도와 시간적분
│   │   └── findings.md               → 재현 조건과 해결하지 못한 문제
│   ├── development-context.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 연결
├── msvc/
│   └── AGENTS.md                     → 직접 MSBuild·source 등록·runtime 연결
└── scripts/
    └── AGENTS.md                     → 읽기 전용 결과 비교 도구
```

## 핵심 규칙

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/README.md), 변경할 기능의 README와 해당 영역의 AGENTS.md를 확인한다.
공통 개발 기준은 [standards](docs/standards.md), 재현된 함정은
[engineering-notes](docs/engineering-notes.md)에서 확인한다.
[솔버 공통 요약](docs/solver-core/README.md)은 아래 변경 성격에 해당하는 절을 읽는다.
색인의 다른 기능·연구 이력·대형 이관 자료를 일괄 필독으로 확장하지 않는다.
같은 문맥에서 읽고 바뀌지 않은 자료는 다시 읽지 않는다.
Public header 변경은 대응하는 src 영역의 책임과 consumer까지 확인한다.

- 범위·physics·절차 변경: 기능 요약의 채택 범위·구현 한계와 관련 formulation 절의
  유도·가정·검증 요구를 함께 확인한다.
- 입력·결과·비교 변경: 공통 I/O·수치 기준과 해당 기능의 identity·reference mapping을 확인한다.
  외부 호출·schema 변경은 contracts, 로컬 파일 권한·공유 변경은 security도 확인한다.
- C++ 구현: 공통 요약의 코딩 규약, 해당 영역 지침과 행동을 검증할 검사를 확인한다.
- 빌드 변경: 실제 preset·target graph·dependency와 명령의 side effect를 실행 전에 확인한다.
- 기능 재개: 해당 기능 요약의 현재 구현·검증·미해결 범위를 대조한다.
  과거 단계별 개발 계획은 Git 이력에서 확인하며 현재 실행 지시로 사용하지 않는다.

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

## 문제 처리

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

나머지 문제는 현재 owner가 관련 범위에서 해결한다. 지금 해결할 수 없는 문제는 재현 조건,
영향, 해결하지 못하는 이유와 다음 접근을 docs/tracking/findings.md에 기록한다.
기능별 요약의 기존 기술적 한계도 함께 일치시킨다.
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.

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

직접 MSBuild가 주 개발 빌드이며 CMake/Ninja는 같은 제품·검사 source를 사용하는 보조 경로다.
실제 명령·환경·`.build/native/Debug` 및 `.build/cmake-debug` 출력은 solver-core를 따른다.
두 경로의 전체 검사 등록과 실제 실행 범위를 구분하고 별도 Python·reference 결과를 기록한다.
과거 작업의 한정 실행으로 이후 일반 솔버 기능의 전체 검증 의무를 대체하지 않는다.
`reference/temp`는 검증에 사용하지 않는다. 정식 자료 누락은 미완료로 기록하고 통과로 바꾸지 않는다.