FESADev/docs/project-plan/SOLVER_SKILL_DESIGN.md

FESA Solver Skill Rebuild Plan

목적

이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 project-local Codex skill 구성을 정의한다.

Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 절차와 검증 도구 단위다. 따라서 skill은 Agent와 1:1로 대응하지 않는다. 대신 요구조건, 연구, 정식화, I/O 계약, reference model, C++ TDD 구현, reference 비교, 물리 검토, release readiness처럼 솔버 개발 과정에서 반복되는 작업 흐름을 기준으로 구성한다.

설계 원칙

• Skill은 .codex/skills/<skill-name>/SKILL.md에 둔다.
• 각 skill은 필수 frontmatter name, description과 UI metadata agents/openai.yaml을 가진다.
• Skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 입력, 절차, 산출물, 금지사항, 품질 gate, handoff를 정의한다.
• Skill은 AGENTS.md와 docs/AGENT_RULES.md를 공통 상위 기준으로 읽는다.
• Abaqus, Nastran 또는 reference solver 실행은 skill 범위에 포함하지 않는다.
• Reference CSV 생성 또는 수정은 skill 범위에 포함하지 않는다.
• C++ 구현 관련 skill은 C++17 이상, MSVC, CMake, CTest, TDD 원칙을 따른다.
• 기본 workspace validation 명령은 python scripts/validate_workspace.py이다.

Skill 구성

Skill	적용 개발 과정	주요 사용자 Agent	대표 산출물
fesa-requirements-baseline	1. 새로운 솔버 기능 요구조건 분석	Requirement Agent, Coordinator Agent	docs/requirements/<feature-id>.md
fesa-research-evidence	2. 책, 논문 등 연구자료 조사	Research Agent, Formulation Agent	docs/research/<feature-id>-research.md
fesa-formulation-spec	3. 코드 구현을 위한 유한요소 정식화	Formulation Agent, Implementation Planning Agent	docs/formulations/<feature-id>-formulation.md
fesa-numerical-review	3. 정식화 독립 수치 검토	Numerical Review Agent, Coordinator Agent	docs/numerical-reviews/<feature-id>-review.md
fesa-io-contract	4. 솔버 입출력 데이터 정의	I/O Definition Agent, Reference Verification Agent	docs/io-definitions/<feature-id>-io.md
fesa-reference-models	5. TDD/reference 테스트모델 작성	Reference Model Agent, Implementation Planning Agent	docs/reference-models/<feature-id>-reference-models.md
fesa-cpp-msvc-tdd	6. 코드 구현 및 build/test correction	Implementation Planning Agent, Implementation Agent, Build/Test Executor Agent, Correction Agent	implementation plan/report, build/test report, correction report
fesa-reference-comparison	7. reference solver 결과와 구현 solver 결과 비교	Reference Verification Agent	docs/reference-verifications/<feature-id>-reference-verification.md
fesa-physics-sanity	8. tolerance 통과 후 물리 타당성 검토	Physics Evaluation Agent	docs/physics-evaluations/<feature-id>-physics-evaluation.md
fesa-release-readiness	9. 솔버 기능 배포 준비	Release Agent, Coordinator Agent	docs/releases/<feature-id>-release.md

개발 과정별 사용 예

예시 기능: linear-truss-1d

1. Requirement Agent는 fesa-requirements-baseline을 사용해 새로운 솔버 기능의 범위, 제외 범위, 입력, 출력, 검증 물리량, tolerance, Requirement Verification Matrix를 분석하고 작성한다.
2. Research Agent는 fesa-research-evidence를 사용해 truss/bar element 이론, benchmark 후보, source reliability, applicability limits를 정리한다.
3. Formulation Agent는 fesa-formulation-spec을 사용해 strong form, weak form, shape functions, B matrix, element stiffness, output recovery를 정리한다.
4. Numerical Review Agent는 fesa-numerical-review를 사용해 rigid body modes, patch test, stiffness symmetry, Jacobian, locking 위험을 검토하고 pass-for-implementation-planning 여부를 판단한다.
5. I/O Definition Agent는 fesa-io-contract를 사용해 지원할 Abaqus .inp keyword subset과 displacements.csv, reactions.csv, element_forces.csv, stresses.csv schema를 정의한다.
6. Reference Model Agent는 fesa-reference-models를 사용해 references/linear-truss-1d/<model-id>/ artifact bundle 계약과 coverage matrix를 작성한다.
7. Implementation Planning Agent와 Implementation Agent는 fesa-cpp-msvc-tdd를 사용해 테스트 작성, 실패 확인, 최소 구현, CMake/CTest 등록, validation을 수행한다.
8. Reference Verification Agent는 fesa-reference-comparison을 사용해 구현 solver HDF5 결과와 저장된 reference HDF5 artifact를 tolerance 기준으로 비교한다.
9. Physics Evaluation Agent는 fesa-physics-sanity를 사용해 global equilibrium, reaction consistency, displacement direction, symmetry, model coverage를 검토한다.
10. Release Agent는 fesa-release-readiness를 사용해 gate evidence, acceptance traceability, known limitations, release notes draft를 작성한다.

Skill별 핵심 계약

fesa-requirements-baseline

• 새로운 솔버 기능 요청을 검증 가능한 요구조건 분석 baseline으로 만든다.
• shall 문장과 FESA-REQ-<FEATURE>-### id를 사용한다.
• 모든 must 요구조건은 verification method와 acceptance criteria를 가져야 한다.
• FEM 정식화, C++ 구현, reference HDF5 artifact 또는 reference CSV 생성, release readiness 판단은 하지 않는다.

fesa-research-evidence

• 연구 질문, source inventory, source reliability tier, benchmark 후보를 정리한다.
• 검증된 사실과 추론을 분리한다.
• source gap은 open issue로 남긴다.
• FEM 정식화 확정이나 reference value 생성을 하지 않는다.

fesa-formulation-spec

• strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분해 작성한다.
• Jacobian, derivative transform, numerical integration, output recovery, numerical risks를 명시한다.
• C++ API, parser, file ownership은 설계하지 않는다.
• Numerical Review Agent 검토 전 최종 승인 상태로 두지 않는다.

fesa-numerical-review

• 정식화를 수치 알고리즘 계약으로 독립 검토한다.
• dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다.
• pass-for-implementation-planning은 구현 계획 가능 상태만 의미한다.
• 정식화 문서를 직접 수정하지 않는다.

fesa-io-contract

• FESA solver input이 지원할 Abaqus .inp subset을 정의한다.
• model data와 history data를 구분한다.
• 내부 semantic model 계약과 HDF5 output schema 및 명시적으로 요구된 optional CSV schema를 정의한다.
• parser 구현이나 full Abaqus compatibility claim은 하지 않는다.

fesa-reference-models

• smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다.
• references/<feature-id>/<model-id>/ artifact bundle 계약을 정의한다.
• model.inp, metadata.json, displacements.csv, reactions.csv, element_forces.csv, stresses.csv를 기준 artifact로 둔다.
• Reference CSV가 없으면 완료 상태가 아니라 needs-reference-artifacts로 둔다.

fesa-cpp-msvc-tdd

• C++ 구현을 RED -> GREEN -> VERIFY 순서로 수행한다.
• C++ production 변경에는 관련 C++ test file이 있어야 한다.
• 기본 검증 명령:

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
ctest -C Debug -R <feature-or-label>

• 실패는 configure | compile | link | test | reference-comparison | harness | environment | upstream-contract로 분류한다.
• 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다.

fesa-reference-comparison

• ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT 순서로 수행한다.
• metadata.json, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다.
• max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다.
• Reference pass는 physics validation이나 release readiness를 의미하지 않는다.

fesa-physics-sanity

• Reference comparison 통과 후 물리 타당성을 검토한다.
• global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, model coverage를 확인한다.
• 문서화된 물리 기대값이 없으면 pass를 선언하지 않는다.
• pass-for-release-agent는 Release Agent 검토 가능 상태만 의미한다.

fesa-release-readiness

• GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT 순서로 수행한다.
• pass-for-reference-verification, pass-for-physics-evaluation, pass-for-release-agent evidence를 요구한다.
• Known Limitations와 Release Notes Draft를 작성한다.
• 사용자 명시 요청 없이 publish, deploy, package, tag, commit, external release를 수행하지 않는다.

Agent와 Skill 관계

Agent	주로 사용하는 Skill
Coordinator Agent	fesa-requirements-baseline, fesa-reference-models, fesa-release-readiness
Requirement Agent	fesa-requirements-baseline
Research Agent	fesa-research-evidence
Formulation Agent	fesa-formulation-spec
Numerical Review Agent	fesa-numerical-review
I/O Definition Agent	fesa-io-contract
Reference Model Agent	fesa-reference-models
Implementation Planning Agent	fesa-formulation-spec, fesa-reference-models, fesa-cpp-msvc-tdd
Implementation Agent	fesa-cpp-msvc-tdd
Build/Test Executor Agent	fesa-cpp-msvc-tdd
Correction Agent	fesa-cpp-msvc-tdd
Reference Verification Agent	fesa-reference-comparison, fesa-io-contract
Physics Evaluation Agent	fesa-physics-sanity
Release Agent	fesa-release-readiness

검증 기준

Skill 구성 검증은 scripts/test_fesa_solver_skills.py가 담당한다.

검증 항목:

• 10개 solver skill의 SKILL.md 존재 여부
• YAML frontmatter의 name, description
• 공통 섹션: Inputs, Workflow, Output Contract, Boundaries, Quality Gate, Handoff
• AGENTS.md와 docs/AGENT_RULES.md 참조
• skill-specific 핵심 문구와 산출물 경로
• agents/openai.yaml UI metadata
• 이 문서가 아니라 실제 skill 파일이 기준이 되도록 docs/project-plan/SOLVER_SKILL_DESIGN.md에 대한 skill 본문 참조 금지

검증 명령:

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py

Skill 구조 검증:

python C:\Users\user\.codex\skills\.system\skill-creator\scripts\quick_validate.py .codex\skills\<skill-name>

v1 범위

• v1은 SKILL.md와 agents/openai.yaml만 포함한다.
• 별도 scripts/, references/, assets/는 만들지 않는다.
• 반복 사용 중 절차가 안정화되면 deterministic comparison script, reference artifact template, report template 같은 resource를 별도 후속 작업으로 분리한다.
• 이 문서는 skill 구성을 설명하는 계획 문서이며, 실제 실행 지침의 source of truth는 각 .codex/skills/<skill-name>/SKILL.md이다.