FESADev/AGENTS.md

Project: FESA

기술 스택

• C++ 17 이상
• Math library : Intel OneApi MKL
• Parallel library : Intel OneApi TBB
• 해석 결과 저장 형식 : hdf5 형식 사용
• git 주소 : https://teagit.mimi1011.synology.me/baram2584/FESADev.git

아키텍처 규칙

• CRITICAL: 레퍼런스가 되는 예제들과 결과 비교를 통해 솔버의 품질을 항상 유지
• CRITICAL: docs/ARCHITECTURE.md와 docs/ADR.md의 결정 사항을 우선 준수할 것. 구조 변경이 필요하면 먼저 ADR을 추가/수정할 것
• 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장할 것
• Domain은 입력 모델 정의를 보존하고 가능한 한 불변으로 취급할 것
• 현재 step에서 활성화되는 객체는 AnalysisModel로 분리하고, 해석 중 변하는 물리량과 반복 상태는 AnalysisState에 저장할 것
• 자유도 정의, constrained/free dof mapping, equation numbering, sparse pattern 생성은 DofManager가 전담할 것. Node/Element 내부에 equation id를 분산 저장하지 말 것
• 해석 알고리즘은 Strategy + Template Method 구조를 따를 것. 선형 정적, 비선형 정적, 동적, 열전달 해석은 공통 실행 흐름을 공유하되 세부 반복/적분 알고리즘은 분리할 것
• Abaqus input keyword와 내부 객체 생성은 Factory + Registry 구조로 분리할 것. Phase 1 입력 범위는 *Node, *Element, *Nset, *Elset, *Material, *Elastic, *Shell Section, *Boundary, *Cload, *Step
• MKL, TBB, HDF5 API는 solver core에 직접 노출하지 말고 adapter/wrapper 계층 뒤에서 사용할 것
• 결과는 step/frame/field/history 모델로 관리할 것
• 대규모 모델을 목표로 sparse matrix, assembly, solver 계층은 성능 확장이 가능하게 설계할 것
• MITC4 요소 구현은 Phase 1에서 정확도와 테스트 가능성을 우선하며, reference 검증 전 과도한 최적화를 하지 말 것

Harness Workflow

• 먼저 docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md를 읽고 기획/설계 의도를 파악할 것
• 단계별 실행 계획이 필요하면 repo skill harness-workflow를 사용해 phases/ 아래 파일을 설계할 것
• 변경사항 리뷰가 필요하면 repo skill harness-review 또는 Codex의 /review를 사용할 것
• phases/{phase}/index.json은 phase 진행 상태의 단일 진실 공급원으로 취급할 것
• 각 stepN.md는 독립된 Codex 세션에서도 실행 가능하도록 자기완결적으로 작성할 것

개발 프로세스

• CRITICAL: 새 기능 구현 시 반드시 테스트를 먼저 작성하고, 테스트가 통과하는 구현을 작성할 것 (TDD)
• 커밋 메시지는 conventional commits 형식을 따를 것 (feat:, fix:, docs:, refactor:)
• scripts/execute.py는 step 완료 후 코드/메타데이터 커밋을 정리하므로, step 프롬프트 안에서 별도 커밋을 만들 필요는 없음

검증

• 기본 검증 스크립트는 python scripts/validate_workspace.py
• 기준이 되는 Reference 모델들의 해석결과와 비교로 검증 수행

명령어

• python scripts/execute.py <phase-dir>: Codex 기반 phase 순차 실행
• python scripts/execute.py <phase-dir> --push: phase 완료 후 브랜치 push
• python scripts/validate_workspace.py: 저장소 검증