FESADev/AGENTS.md

Project: FESA Structural Solver

기술 스택

• C++17 이상
• MSVC on Windows
• CMake + CTest
• Python 3 Harness scripts
• Intel oneAPI MKL, Intel oneAPI TBB
• HDF5 result storage
• Abaqus .inp keyword subset input

프로젝트 정체성

• FESA는 유한요소법 기반 구조해석 솔버 개발 프로젝트이다.
• 프로젝트의 배경, 목적, 사용자, 범위는 docs/PRD.md에서 확인한다.
• 전체 아키텍처와 모듈별 책임은 docs/ARCHITECTURE.md에서 확인한다.
• 주요 아키텍처 결정과 그 이유 및 트레이드오프는 docs/ADR.md에서 확인한다.
• AI 에이전트는 설계나 구현 결정을 내리기 전에 위 문서 중 작업과 관련된 내용을 참조한다.
• Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다. 전체 실행 흐름은 docs/HARNESS_WORKFLOW.md, 설치와 설정은 docs/HARNESS.md를 따른다.
• 문서와 구현은 full Abaqus compatibility를 주장하지 않는다. 기능별로 승인된 Abaqus keyword subset만 지원한다.
• 공식 solver output은 HDF5 results.h5이다.
• reference 결과는 FESA와 같은 Abaqus .inp 모델을 Abaqus로 해석해 생성한 CSV 파일이다.
• reference comparison은 FESA results.h5의 변위, 반력, 내력, 응력 dataset을 reference/<model-id>/<model-id>_*.csv 파일과 비교한다.
• CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다.

아키텍처 규칙

• CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
• CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
• CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
• CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다.
• CRITICAL: public header와 implementation 의존성 방향을 역전하지 말 것
• CRITICAL: 사람 개발자가 검토하기 쉽도록 코드를 작성할것. 그리고 주석도 필수로 작성할 것.
• Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
• AnalysisModel은 현재 step에서 활성화된 elements, loads, boundary conditions, properties/materials의 view를 제공하며 Domain을 복사하지 않는다.
• DofManager는 node별 자유도 정의, constrained/free mapping, equation numbering, sparse pattern ownership을 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.
• AnalysisState는 displacement, velocity, acceleration, temperature, external/internal force, residual, time/increment/iteration, element state를 소유한다.
• MKL, TBB, HDF5 API는 solver core에 직접 노출하지 않는다. LinearSolver, ParallelFor, ResultsWriter, Vector, Matrix, SparseMatrix adapter 경계 뒤에 둔다.
• Codex custom agent의 model_reasoning_effort 기본값은 extra high로 둔다.
• Harness runner는 scripts/execute.py에 둔다.
• scripts/execute.py는 feat-<phase-name> branch prefix를 사용한다.
• runner는 git add -A로 변경사항을 stage하므로 실행 전 clean worktree 또는 별도 Git worktree를 사용한다.
• Hook 연결은 .codex/hooks.json, 구현은 scripts/hooks/와 scripts/msvc_harness/에 둔다.
• PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하는 guardrail이며 RED 실행을 증명하지 않는다.
• Stop은 .harness/config.json 또는 자동 감지 결과에 따라 MSVC build와 test를 모두 검증한다.
• Generated phase execution outputs remain ignored under phases/**/step*-output.json.

개발 프로세스

• TDD를 기본으로 한다. 구현은 RED -> GREEN -> VERIFY 순서를 따른다.
• CRITICAL: 빌드 경고를 새로 추가하지 말 것.
• 기능 개발은 다음 gate를 순서대로 통과해야 한다.
  1. 요구조건 분석
  2. 연구자료 조사
  3. 유한요소 정식화
  4. 수치 검토
  5. I/O 계약 정의
  6. reference model 계약 준비
  7. C++ 구현
  8. build/test 검증
  9. reference comparison
  10. physics sanity
  11. release readiness
• 커밋 메시지는 conventional commits 형식을 따른다: feat:, fix:, docs:, refactor:, test:, chore:.

Agent/Skill Workflow

AI 에이전트는 유한요소 구조해석 지식이 필요할 때 FEM wiki를 참조하기 위해 .codex/skills/fem-theory-query 스킬을 사용할 수 있다.

개발 과정	Agent	Skill	산출물
요구조건 분석	requirement-agent	fesa-requirements-baseline	docs/requirements/<feature-id>.md
연구자료 조사	research-agent	fesa-research-evidence, fem-theory-query	docs/research/<feature-id>-research.md
유한요소 정식화	formulation-agent	fesa-formulation-spec	docs/formulations/<feature-id>-formulation.md
수치 검토	numerical-review-agent	fesa-numerical-review	docs/numerical-reviews/<feature-id>-review.md
I/O 정의	io-definition-agent	fesa-io-contract	docs/io-definitions/<feature-id>-io.md
reference model	reference-model-agent	fesa-reference-models	docs/reference-models/<feature-id>-reference-models.md
구현 계획/구현	implementation-planning-agent, implementation-agent	fesa-cpp-msvc-tdd	tests, source, implementation report
build/test	build-test-executor-agent	fesa-cpp-msvc-tdd	docs/build-test-reports/<feature-id>.md
correction	correction-agent	fesa-cpp-msvc-tdd	docs/corrections/<feature-id>.md
reference 비교	reference-verification-agent	fesa-reference-comparison	docs/reference-verifications/<feature-id>-reference-verification.md
물리 검토	physics-evaluation-agent	fesa-physics-sanity	docs/physics-evaluations/<feature-id>-physics-evaluation.md
배포 준비	release-agent	fesa-release-readiness	docs/releases/<feature-id>-release.md

명령어

Harness Python 검증

uv run --with pytest python -m pytest -v -rs

Phase 실행

python scripts/execute.py <phase-name>
python scripts/execute.py <phase-name> --push

CMake/CTest 프로젝트

cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

Visual Studio solution 프로젝트

MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
.\build\tests\Debug\MyProjectTests.exe

실제 solution, preset, 테스트 명령은 .harness/config.json과 프로젝트 문서를 우선한다.