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는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다.
• 새 기능은 입력 keyword만 인식하거나 element kernel만 존재한다고 완성된 것이 아니다. Semantic model, equation system, 해법, 결과 복구, HDF5 외부 계약과 독립 검증 evidence가 하나의 추적 가능한 기능을 이뤄야 한다.
• 설계나 구현 전에 PRD의 제품 범위, ARCHITECTURE의 소유권과 데이터 흐름, ADR의 기존 결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 CODINGSTYLE을 따른다.
• 재사용 가능한 agent, skill과 Harness는 개발 운영 인프라다. 이를 일반화해도 이 저장소가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 승인된 수치 계약은 바뀌지 않는다.
• FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라 Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을 주장하거나 목표로 삼지 않는다. 수치 결과의 exact equality는 허용되지만 내부 동작 동등성의 evidence가 아니다.
• 기능별로 승인된 Abaqus keyword subset만 입력 형식으로 지원한다. Abaqus 결과는 승인된 비교량의 외부 수치 reference일 뿐 FESA 내부 알고리즘 계약이 아니다.
• 공식 solver output은 입력 경로의 lexical sibling인 HDF5 <stem>_results.h5이다. 파일명과 저장 계약은 PRD와 ARCHITECTURE를 따른다.
• reference 결과는 FESA와 같은 Abaqus .inp 모델을 Abaqus로 해석해 생성한 CSV 파일이다.
• reference case는 기능 문서가 지정한 기존 .inp와 실제 비교에 필요한 Abaqus CSV 경로를 그대로 사용한다. canonical 이름, legacy-alias 승인, bundle README.md, metadata.json, Abaqus version/provenance 또는 중복 unit/coordinate/step-frame/schema 기록은 readiness 조건이 아니다.
• 비교기는 필요한 source row identity와 component를 결정적으로 대응시키고 누락, 추가, 중복, nonfinite 값을 tolerance 전에 거부한다. Reference artifact는 rename, rewrite 또는 보정하지 않는다.
• 모든 외부 reference comparison의 scale, near-zero/relative/RMS 판정, zero-scale 처리와 보고서는 TOLERANCE의 승인된 공통 정책을 따른다. Numerical Review는 이 정책 안에서 기능별 비교량, identity/component와 blocking/diagnostic 구분을 정의하며 고정된 수치 기준을 임의로 선택·완화하지 않는다. 정책 변경은 해당 문서의 사용자 승인과 ADR 절차를 따른다.
• B33 section-resultant reference는 (instance, element label, endpoint node label, component)로 HDF5 element endpoint와 직접 대응한다. Node-station collapse 또는 평균을 사용하지 않는다. MITC4 U1/U2/U3는 blocking, UR1/UR2/UR3는 warning-only 분류를 유지하면서 같은 공통 수치 정책을 사용한다.
• CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다.

문서 기준과 Feature 관리

• 공통 역할·handoff·상태 전이·재시도는 SOLVER_AGENT_DESIGN, skill 구성과 적용 경계는 SOLVER_SKILL_DESIGN, Feature 문서 배치와 소유권은 FEATURE_DOCUMENTATION을 기준으로 한다. 실제 skill 실행 절차는 해당 SKILL.md를 읽는다.
• HARNESS와 HARNESS_WORKFLOW는 설치·흐름 참고 문서다. 승인·역할·상태 전이는 위 agent 계약과 현재 harness skill, 실행 메커니즘은 선택된 설정과 현재 scripts/ 구현에 대조한다. 오래된 설명으로 이 계약을 덮어쓰지 않으며, 구현이 승인된 제품·수치 계약을 바꿀 권한도 없다.
• 기능별 승인 계약과 모든 agent 보고서는 docs/<feature-id>/에 둔다. Coordinator가 안정적인 kebab-case Feature ID를 정하고 모든 dispatch에서 같은 폴더와 revision을 사용한다. 기존 docs/features/<feature-id>/ 자료가 있으면 자동 이동·복제하지 않고 필요한 경로와 revision을 참조한다.
• 일반 Feature 작업에서 프로젝트 AGENTS.md, docs/PRD.md, docs/ADR.md는 읽기 전용 기준이다. 현재 작업의 진행 링크나 결정을 루트 문서에 누적하지 않는다. 프로젝트 공통 지침 수정은 별도 사용자 요청으로 승인된 범위에서만 수행한다.
• Coordinator는 새 Feature에 아래 관리 문서를 실제 요구사항으로 초기화한다. 재개 시 기존 기록을 읽고 필요한 부분만 갱신하며, 승인되지 않은 내용을 승인으로 표시하거나 후속 stage의 빈 보고서를 미리 만들지 않는다.

Coordinator 소유 문서	내용과 경계
FEATURED_AGENTS.md	Feature ID·목적·지역 지침, 산출물 경로·owner·revision·검토 상태 목록, 현재 상태 문서 링크
PRD.md	사용자 요구, 범위·제외, acceptance 요약과 requirement ID별 계약 링크. 요구사항·검증 matrix 원본은 Requirement Agent의 requirements.md
ADR.md	Feature 결정 ID·상태·이유·영향, 결정 owner와 승인 근거 링크
coordination.md	stage·outcome·next owner·contract revision, gate evidence·retry·blocker·다음 작업의 유일한 workflow 상태 원본

• 관리 문서에서 실제 프로젝트 기준 문서를 상대 Markdown 링크로 연결한다. Coordinator의 목록·참조·상태 관리는 specialist 본문을 대신 작성·수정할 권한이 아니다.
• FEATURED_AGENTS.md는 자동 로드되는 AGENTS.md가 아니다. 모든 dispatch와 Harness step의 필수 입력에 Feature 폴더 및 그 안의 FEATURED_AGENTS.md, PRD.md, ADR.md 경로를 명시한다.
• 기본 보고서는 Feature ID·owner·입력 revision, 핵심 결과, evidence, 미해결 항목·handoff만 간결하게 기록한다. 긴 유도·schema·상세 분석은 같은 폴더의 formulation-derivation.md, io-schema.md 같은 상세 문서로 분리하고 상대 링크로 연결한다. 본문과 상세 문서에 같은 내용을 중복 유지하지 않는다.
• 상세 문서는 기본 산출물과 동일 owner·Feature ID·입력 revision을 사용하며 같은 stale 판정을 받는다. 반환 evidence_paths에는 기본 문서와 작성·갱신하거나 판정에 사용한 상세 문서를 포함한다. Coordinator는 실제 파일과 링크를 확인하고 목록에 등록한다.
• 소스·테스트·Harness 제어 파일·기계 생성 로그/결과·read-only reference artifact는 각각의 지정 경로에 유지하고 보고서에서 참조한다. 필수 검증을 생략했다면 미실행 사실과 이유를 남긴다.

FESA 개발의 핵심 원칙

물리와 수치 계약

• CRITICAL: 구현보다 요구조건, 정식화, 부호, 단위, 좌표계, row identity와 tolerance 계약을 먼저 고정한다. 구현 편의를 위해 승인된 의미를 조용히 바꾸지 않는다.
• CRITICAL: 해석 결과가 유한하고 선형계가 풀렸다는 사실만으로 correctness를 주장하지 않는다. Equilibrium, reaction, rigid-body mode, energy, symmetry와 reference identity를 기능에 맞게 검증한다.
• Source label/instance identity와 internal index/equation index를 구분한다. Stable source identity는 진단, 결과, reference mapping 전 구간에서 보존한다.
• 병렬 실행 여부와 관계없이 같은 입력은 같은 sparse structure, reduction order, result row order와 diagnostic order를 만들어야 한다.
• Scale-aware validation은 formulation과 I/O 계약의 기준을 사용한다. 임의의 max(1, ...), zero clamp, 누락 row 무시 또는 불일치 평균으로 오류를 숨기지 않는다.

소유권과 의존성

• CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
• CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
• CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
• CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
• CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다.
• CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다.
• Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
• AnalysisModel은 현재 step에서 활성화된 elements, loads, boundary conditions, properties/materials의 non-owning view를 제공하며 Domain을 복사하지 않는다. 따라서 Domain은 AnalysisModel보다 오래 살아야 한다.
• DofManager는 node별 자유도 정의, constrained/free mapping, equation numbering, sparse pattern ownership을 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.
• AnalysisState는 해당 procedure가 실제로 사용하는 mutable solution과 recovery row만 소유한다. 구체적인 state는 승인된 procedure 계약과 ARCHITECTURE를 따르며 미래 state를 미리 할당하지 않는다.
• MKL, TBB, HDF5, Win32 API와 vendor type은 public solver core에 노출하지 않는다. LinearSolver, ParallelFor, ResultsWriter, Vector, Matrix, SparseMatrix 경계 뒤에 둔다.
• 해석 단계는 실패할 수 있는 candidate를 완성하고 검증한 뒤 소유 state/output에 반영한다. 실패 시 기존 state와 기존 최종 HDF5를 가능한 계약 범위에서 보존한다.

선형 정적 해석 불변식

• 해석 실행의 공통 책임은 docs/ARCHITECTURE.md를 따른다. LinearStaticAnalysis::Run()의 구체적인 단계와 객체별 책임은 해당 기능의 승인된 계약과 구현을 대조한다.
• Full stiffness를 stable free/constrained 순서로 Kff/Kfc/Kcf/Kcc에 분할하고, Kff factorization을 load assembly보다 먼저 수행한다.
• Effective RHS는 Ff - Kfc * dc이며 substitution 뒤 full displacement를 복구한다. 모든 DOF가 constrained인 유효한 모델의 0 x 0 Kff를 singular error로 바꾸지 않는다.
• Reaction과 free-equilibrium evidence는 조립된 full residual K*d - F에서 구한다. Constrained 성분은 physical reaction이고 free 성분은 residual evidence다.
• Sparse assembly는 element-local contribution과 stable COO ordering, 고정된 reduction을 사용한다. 병렬 worker가 global CSR storage를 직접 갱신하지 않는다.
• Element end action, positive-local-x section resultant, Gauss generalized result와 section-point stress는 서로 다른 identity와 부호 계약을 가진다. Station mismatch를 평균으로 합치지 않는다.

개발 운영 인프라

• Codex custom agent의 model_reasoning_effort는 xhigh이며, 모델과 역할별 설정은 .codex/agents의 현재 profile을 따른다.
• Harness runner는 scripts/execute.py이며 feat-<phase-name> branch prefix를 사용한다. 실행 전 Git top-level이 Harness root와 같아야 하고, 선택된 phase 제어 파일 allowlist 밖의 worktree는 clean이어야 한다. 관련 없는 변경을 stage하거나 숨기지 않는다.
• Executor는 branch, 현재 pending step 선택, transport attempt, timestamp, path-scoped staging/commit과 phase 진행을 소유한다. 구현 경로와 phase metadata를 분리해 commit하며 저장소 전체를 무조건 stage하지 않는다. Implementation Agent는 선택된 step의 코드·테스트·보고서와 result payload만 갱신하며 branch/commit/push나 다른 step·제어 metadata를 변경하지 않는다.
• Planning은 각 Step의 승인된 정확한 상대 파일 목록을 phase index의 owned_paths에 기록한다. 모든 pending Step은 실행 전에 목록이 필요하고 []는 구현 파일 변경 없음을 뜻한다. Executor는 신뢰된 목록으로 매 시도 후·stage 전·commit 전 경로를 검사하며 rename 양쪽 경로도 승인되어야 한다. 범위 밖 변경은 보존하고 재시도·커밋·다음 Step 진행을 중단한다. 실행 중 동시 편집까지 원자적으로 격리하는 보장은 아니다.
• Executor의 process/session transport 시도는 실제 wrapper timeout과 결과 미보고가 확인된 경우에만 최초 포함 최대 2회이며 Coordinator의 correction budget과 별개다. 비정상 종료에서도 명시적 error/blocked를 보존하고, 인식된 sandbox helper 환경 실패는 종료 코드 0에서도 blocked로 기록한다. Executor 소유 attempt_history는 재시도·재개 때 보존하며 구현·상위 계약·환경·물리 실패를 transport retry로 반복하지 않는다.
• 기본 sandbox는 FEM_HARNESS_CODEX_SANDBOX=workspace-write다. danger-full-access는 동일 명령의 native sandbox 실패 증거, 해당 실행 직전 사용자의 명시적 승인, clean linked Git worktree와 --approve-danger-full-access가 모두 필요하다. 환경변수 설정만으로 승인되지 않는다. --push 등 원격 작업도 별도 명시적 승인이 필요하다.
• Hook 연결은 .codex/hooks.json, 구현은 scripts/hooks와 scripts/msvc_harness에 둔다. Hook script를 수동 실행해 등록된 hook이나 검증 evidence를 대체하지 않는다.
• PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하고 허용된 편집 경로를 기록한다. 이는 RED 실행이나 correctness의 증거가 아니다.
• Stop은 유효한 동일 session/turn 기록에서 기록된 편집 도구의 대상이 모두 저장소 내부 .md일 때 build/test를 생략한다. 기록 누락·손상 또는 비문서 변경이면 정상 검증 경로를 따른다. Shell 쓰기는 이 기록이 완전히 추적하지 못하며, 편집 기록 없는 읽기 전용 계획 요청도 자동 생략을 보장하지 않는다.
• 생략하지 않는 Stop은 .harness/config.json 또는 자동 감지 결과의 backend로 build/test를 검증한다. 문서 작업에서 사용자가 실행을 제외하면 수동으로 Hook·CMake·CTest 등을 실행하지 않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작하거나 생략된 검증을 통과로 보고하지 않는다.
• .harness/hook-state/와 phases/**/step*-output.json 같은 생성 실행 기록은 ignored 상태로 유지한다.

기능을 추가할 때의 판단 기준

• 새 element는 요구조건과 formulation을 승인한 뒤 semantic mapping, property/material 연결, DOF/scatter, local kernel, deterministic assembly, recovery, HDF5 row identity, reference/physics evidence를 함께 설계한다.
• 새 load 또는 constraint는 parser 인식만 추가하지 않는다. Source target resolution, stable application order, full-space assembly, partition/effective RHS, diagnostic과 결과 의미까지 연결한다.
• 새 analysis procedure는 기존 선형 정적 lifecycle에 조건문을 누적하지 않는다. 필요한 state, equation, solver lifecycle과 recovery contract를 별도 요구조건·ADR·formulation으로 정의한다.
• 새 backend는 기존 public interface를 유지하고 vendor lifecycle, integer/index conversion, runtime dependency와 failure translation을 adapter 내부에 격리한다.
• 새 output quantity는 계산식뿐 아니라 units, coordinate system, source/internal identity, HDF5 schema, mandatory 여부, reference projection과 tolerance를 동시에 정의한다.
• Element API에 kernel이 존재하는 것과 Abaqus keyword/CLI에서 그 기능을 노출하는 것은 별도 계약이다. 예를 들어 V0의 line-load kernel은 *DLOAD 지원을 뜻하지 않는다.

개발 프로세스

• TDD를 기본으로 한다. 구현은 RED -> GREEN -> VERIFY 순서를 따른다.
• CRITICAL: 빌드 경고를 새로 추가하지 말 것.
• 기능 개발은 아래 Agent/Skill Workflow의 9개 정규 stage를 순서대로 통과한다. 문서 수정·읽기 전용 검토를 새 solver feature 전체 workflow로 확대하지 않는다.
• 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, outcome, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID의 기본 형식은 FEM-REQ-<FEATURE>-###이다.
• 커밋 메시지는 conventional commits 형식을 따른다: feat:, fix:, docs:, refactor:, test:, chore:.

Agent/Skill Workflow

Solver feature workflow에서 coordinator-agent만 main agent로서 상태 전이와 closure를 소유하며 다음 eligible specialist에게 한 번에 하나의 bounded task를 dispatch한다. Specialist는 peer를 호출하거나 다음 gate로 진행하거나 자신의 산출물을 최종 승인하지 않는다. Intake/coordination은 아래 정규 stage와 별도로 관리한다.

단계	담당 sub-agent	필수 skill	기본 보고서 (docs/<feature-id>/)
1. requirements	requirement-agent	fem-requirements-baseline	requirements.md
2. research	research-agent	fem-research-evidence	research.md
3. formulation	formulation-agent	fem-formulation-spec	formulation.md
4. numerical-review	numerical-review-agent	fem-numerical-review	numerical-review.md, reference-model.md
5. io-definition	io-definition-agent	fem-io-contract	io.md
6. implementation-planning	implementation-planning-agent	fem-implementation-tdd, harness	implementation-plan.md
7. implementation	implementation-agent	fem-implementation-tdd	implementation-report.md, build-test.md, reference-comparison.md
8. physics-evaluation	physics-evaluation-agent	fem-physics-review	physics-evaluation.md
9. release-readiness	release-agent	fem-release-readiness	release.md

• 위 8개 lifecycle skill은 .codex/skills에 있다. Planning은 할당된 phases/index.json, phases/<phase>/index.json, stepN.md도 소유하고, Implementation은 할당된 코드·테스트·build registration을 소유한다.
• 보조 skill은 .agents/skills/harness의 phase 계획·실행, .agents/skills/review의 읽기 전용 diff 검토, fem-theory-query의 configured FEM wiki 근거·coverage gap 조회다. fem-theory-query를 모든 FEM 질문에 적용하거나 workstation vault 절대 경로를 commit하지 않는다.
• 모든 dispatch/return은 SOLVER_AGENT_DESIGN의 공통 envelope를 사용한다. Workflow outcome은 pass | return-upstream | retry | blocked-environment | needs-user-decision만 사용한다. Specialist outcome은 전이 요청이며 Coordinator가 실제 산출물·owner·revision·evidence를 확인한 뒤 상태를 기록한다.
• return-upstream은 정확한 계약 owner로 반환하고 영향받는 downstream evidence를 stale 처리한다. Numerical Review는 formulation과 reference-model readiness, Implementation은 TDD·전체 build/test·필수 reference comparison 증거가 모두 있어야 통과한다. Release의 pass는 내부 readiness일 뿐 push/tag/publish/deploy/package 권한이 아니다.
• correction-agent는 정규 stage가 아닌 on-demand rework다. Coordinator는 retry_key = feature_id|failing_gate|normalized_failure_classification|contract_revision별 correction을 최대 한 번 허용하고 이후 Implementation rerun을 한 번 dispatch한다. 같은 key가 다시 실패하면 두 번째 correction을 금지하고 계약·환경·critical decision owner로 반환한다. 문구만 바꿔 key를 새로 만들지 않으며 corrections.md는 실제 correction 때만 작성한다.
• 승인된 Feature와 할당된 dispatch 안의 일반 문서·계획 파일 작성 및 bounded local 실행에는 반복적인 사용자 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않으며 Harness 실행은 해당 작업에 실행까지 할당된 경우에만 한다.
• Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명, 보안·법률 위험 수용, destructive/remote/release 작업은 SOLVER_AGENT_DESIGN의 critical decision 절차를 따른다. 권한이 필요한 실행을 일반 자율 작업으로 확대하지 않는다.
• Harness step은 0부터 연속 번호로 나누고 각 step 안에서 RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY를 완료하도록 계획한다. 정확한 입력·소유 파일·명령·제외 범위·중단 조건을 명시하며 필요한 물리·schema·tolerance·reference가 없으면 해당 owner로 반환한다.
• Harness step 상태 pending/completed/error/blocked는 workflow outcome과 별개다. Implementation은 선택된 step에 completed와 비어 있지 않은 summary, error와 error_message, 또는 blocked와 blocked_reason을 반환한다. Executor가 timestamp와 phase 진행을 관리하며 실패 증거를 지우고 즉시 재실행하지 않는다.

최소 검증 진입점

아래 명령은 해당 구현·검증 작업에만 사용한다. 문서만 수정하는 작업의 정적 검토를 위해 build/test를 실행하지 않는다. 실행할 명령은 승인된 step/plan에서 확인하고, .harness/config.json, preset·project metadata와 프로젝트 지침에 대조한 뒤에만 기본값을 사용한다. Target graph, dependency normalization과 Windows runtime staging은 ARCHITECTURE와 실제 CMake 파일을 따른다.

Harness Python 검증

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

Phase 실행

python scripts/execute.py <phase-dir>

<phase-dir>는 할당된 phase로 대체한다. --push는 원격 push가 명시적으로 승인된 경우에만 추가한다.

CMake/CTest 프로젝트

현재 CMakePresets.json의 MSVC x64 Debug preset 사용 예시다. MSVC x64 developer 환경에서 FESA_GTEST_SOURCE_DIR, MKL_DIR, TBB_DIR, HDF5_DIR 환경변수를 설치된 dependency 경로로 설정한다. FESA_GTEST_SOURCE_DIR는 승인된 local GoogleTest source checkout, 나머지는 각 package의 CMake config directory를 가리킨다. (FESA_GTEST_SOURCE_DIR 예시: C:\git\googletest)

cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug --show-only=json-v1
ctest --preset windows-msvc-ninja-debug --output-on-failure

Hook도 이 preset을 사용하게 구성하려면 .harness/config.example.json을 참고해 local .harness/config.json의 binaryDir, configurePreset, buildPreset, testPreset을 함께 맞춘다. Preset 파일이 있다는 사실만으로 Stop이 해당 preset을 선택하지는 않는다. FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 기준으로 한다.