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: 레퍼런스가 되는 예제들과 결과 비교를 통해 솔버의 품질을 항상 유지. 저장 위치는 references/이며, 기본 reference artifact는 Abaqus *.inp 입력 파일과 *_displacements.csv 같은 Abaqus 결과 CSV 파일이다
• CRITICAL: 모든 새 작업 세션은 먼저 PROGRESS.md와 PLAN.md를 읽고 현재 진행 상황, 다음 작업, blocker를 파악할 것
• CRITICAL: 구현 또는 phase 계획 전 docs/README.md의 문서 우선순위와 Phase 1 hard invariants를 확인할 것
• CRITICAL: docs/ARCHITECTURE.md와 docs/ADR.md의 결정 사항을 우선 준수할 것. 구조 변경이 필요하면 먼저 ADR을 추가/수정할 것
• CRITICAL: 수치 규약은 docs/NUMERICAL_CONVENTIONS.md를 우선 준수할 것. DOF, 좌표계, 단위, 부호, precision, reaction recovery 규약을 임의로 바꾸지 말 것
• 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장할 것
• 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 입력 범위와 미지원 기능은 docs/ABAQUS_INPUT_SUBSET.md를 따를 것
• MKL, TBB, HDF5 API는 solver core에 직접 노출하지 말고 adapter/wrapper 계층 뒤에서 사용할 것
• 결과는 docs/RESULTS_SCHEMA.md의 step/frame/field/history 모델로 관리할 것
• 대규모 모델을 목표로 sparse matrix, assembly, solver 계층은 성능 확장이 가능하게 설계하고, id/index/equation 번호는 int64 기반으로 둘 것
• MITC4 요소 구현은 Phase 1에서 docs/MITC4_FORMULATION.md의 baseline formulation과 reference benchmark 통과를 우선하며, reference 검증 전 과도한 최적화를 하지 말 것
• Mesh quality 진단은 Phase 1 범위에서 제외하되, singular system 진단은 필수로 구현할 것
• Abaqus 실행을 로컬/CI 검증 요구사항으로 두지 말 것. 검증은 references/에 저장된 *.inp와 *_displacements.csv 등 reference artifact와 비교할 것
• Reference input이 Phase 1 parser subset 밖의 Abaqus 기능(S4R, Part/Assembly/Instance, NLGEOM=YES 등)을 포함할 수 있다. 이런 파일은 저장 reference로 보존하되, 지원 범위를 조용히 확장하지 말고 docs/ABAQUS_INPUT_SUBSET.md와 docs/VERIFICATION_PLAN.md에 compatibility note를 남길 것
• Phase 1 implementation plan을 만들기 전 docs/README.md의 Implementation Readiness Checklist 미결 항목을 명시할 것

작업 상태 관리

• PLAN.md는 앞으로 해야 할 일, 우선순위, task ownership, open question의 단일 진실 공급원으로 취급할 것
• PROGRESS.md는 완료된 일, 검증 결과, blocker, 알려진 위험의 단일 진실 공급원으로 취급할 것
• 작업을 시작할 때 PROGRESS.md에서 최근 완료 내역과 blocker를 확인하고, PLAN.md에서 현재 objective와 다음 task를 확인할 것
• 의미 있는 문서/코드/계획 변경을 완료하면 PROGRESS.md에 날짜, 변경 파일, 검증, 후속 작업을 기록할 것
• 앞으로 해야 할 일이 새로 생기거나 우선순위가 바뀌면 PLAN.md를 갱신할 것
• 완료된 task는 PLAN.md에 방치하지 말고 PROGRESS.md에 완료 기록을 남긴 뒤 PLAN.md에서는 제거하거나 상태를 갱신할 것
• 여러 에이전트가 동시에 작업할 수 있으므로, 파일 수정 전 PLAN.md의 owner/scope를 확인하고 서로의 작업 범위를 침범하지 말 것
• phases/{phase}/index.json은 phase 실행 상태의 단일 진실 공급원이지만, phase 밖의 전체 프로젝트 진행 상태는 PLAN.md와 PROGRESS.md에서 관리할 것

Harness Engineering

• FESA의 장기 작업은 기본적으로 Planner -> Generator -> Evaluator 구조로 수행할 것
• Planner는 구현 전에 sprint contract 또는 phases/{phase}/stepN.md를 작성한다. 구현 세부를 과도하게 고정하지 말고, 산출물/검증/금지 범위를 명확히 할 것
• Generator는 승인된 contract 하나만 구현한다. 여러 layer를 한 번에 묶어 구현하지 말고, 테스트를 먼저 작성한 뒤 contract의 acceptance criteria를 만족시키는 최소 변경을 수행할 것
• Evaluator는 Generator와 분리된 관점으로 검토한다. 자기 작업을 스스로 승인하지 말고, architecture drift, 수치 규약 위반, reference 비교 누락, 테스트 누락, unsupported Abaqus feature의 조용한 확장을 실패로 판정할 것
• 각 sprint contract는 최소한 다음 항목을 포함해야 한다: objective, scope, allowed files, explicit non-goals, required reading, tests to write first, reference artifacts, acceptance commands, evaluator checklist, handoff requirements
• Sprint 시작 전 contract가 testable하지 않으면 구현하지 말고 contract를 먼저 보강할 것
• Sprint 실패 시 Evaluator는 실패 이유와 재현 방법을 feedback artifact로 남기고, Generator는 그 feedback만을 대상으로 다음 반복을 수행할 것
• 장기 실행 중 context가 커지면 PROGRESS.md, PLAN.md, phase step 파일, review feedback을 handoff artifact로 사용해 새 세션이 이어받을 수 있게 할 것
• Harness 복잡도는 필요한 만큼만 유지한다. 단순 문서 변경은 단일 agent로 처리할 수 있지만, solver 구현/수치 검증/reference 비교가 포함되면 Planner/Generator/Evaluator 분리를 적용할 것
• Harness contract와 평가 기준은 docs/HARNESS_ENGINEERING.md를 따를 것

Harness Workflow

• 먼저 PROGRESS.md, PLAN.md, docs/README.md, docs/HARNESS_ENGINEERING.md, docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md, docs/NUMERICAL_CONVENTIONS.md, docs/ABAQUS_INPUT_SUBSET.md, docs/VERIFICATION_PLAN.md, docs/RESULTS_SCHEMA.md, docs/MITC4_FORMULATION.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 모델들의 해석결과와 비교로 검증 수행
• Abaqus는 실행하지 않는 전제이다. 사용자가 references/ 아래에 정리한 입력/결과 artifact를 기준으로 비교할 것
• Reference displacement CSV는 Abaqus export column Node Label, U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3를 FESA U field의 UX, UY, UZ, RX, RY, RZ와 비교하는 기본 형식으로 취급할 것
• Reference 비교는 absolute tolerance와 relative tolerance를 함께 사용할 것

명령어

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