# FESA Solver Development Skill 구성안 ## 목적 이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 Codex skills 구성을 정의한다. Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 기술과 절차 단위다. 따라서 skill은 Agent와 1:1로 대응시키지 않고, solver 개발 과정에서 반복되는 공통 workflow를 압축해 구성한다. ## 설계 원칙 - Skill은 특정 Agent 전용 지시가 아니라 여러 Agent가 공유하는 반복 절차로 둔다. - Skill은 `SKILL.md` 기반의 project-local workflow로 시작한다. - Skill은 구현 세부사항보다 입력, 절차, 산출물, 금지사항, 검증 기준을 제공한다. - Abaqus/Nastran 실행과 reference CSV 생성은 skill 범위에 포함하지 않는다. - C++ 구현 관련 skill은 C++17, MSVC, CMake, CTest, TDD 기준을 따른다. - 모든 검증은 `python scripts/validate_workspace.py`를 기본 workspace validation 명령으로 둔다. ## Skill 구성 ### 1. `fesa-feature-definition` 요구조건 정의와 연구 질문 정리를 위한 skill이다. 사용 Agent: - Requirement Agent - Research Agent - Coordinator Agent - Release Agent 적용 개발 과정: - 1. 솔버 기능에 대한 요구조건 정의 - 2. 책, 논문 등 연구자료 조사 주요 기능: - 기능 요청을 검증 가능한 requirement baseline으로 정리한다. - `shall` 요구조건, acceptance criteria, verification matrix를 작성한다. - 필요한 연구 질문과 source gap을 정리한다. - 미확정 tolerance, 지원 범위, reference artifact 요구사항을 open issue로 남긴다. 대표 산출물: - `docs/requirements/.md` - `docs/research/-research.md` - requirement verification matrix - downstream handoff questions 금지사항: - FEM 정식화를 확정하지 않는다. - C++ 구현, Abaqus/Nastran 실행, reference CSV 생성을 하지 않는다. - 검증 불가능한 요구조건을 완료 상태로 두지 않는다. ### 2. `fesa-fem-specification` FEM 정식화, 수치 검토, 입출력 계약을 구현 가능한 specification으로 정리하기 위한 skill이다. 사용 Agent: - Formulation Agent - Numerical Review Agent - I/O Definition Agent - Implementation Planning Agent 적용 개발 과정: - 3. 코드 구현을 위한 유한요소 정식화 - 4. 솔버 입출력 데이터 정의 주요 기능: - strong form, weak form, shape function, B matrix, element equations를 정리한다. - numerical integration, Jacobian, output recovery, numerical risk를 점검한다. - Abaqus `.inp` keyword subset과 internal model mapping을 정의한다. - result CSV schema와 units, coordinate system, component naming을 정리한다. 대표 산출물: - `docs/formulations/-formulation.md` - `docs/numerical-reviews/-review.md` - `docs/io-definitions/-io.md` 금지사항: - C++ API나 파일 구조를 확정하지 않는다. - parser 구현을 하지 않는다. - reference artifact나 tolerance policy를 임의로 만들지 않는다. ### 3. `fesa-reference-validation` reference model 설계, stored Abaqus CSV 비교, physics sanity 평가를 위한 skill이다. 사용 Agent: - Reference Model Agent - Reference Verification Agent - Physics Evaluation Agent - Coordinator Agent 적용 개발 과정: - 5. TDD 방법 사용을 위한 개발 솔버와 reference solver 테스트모델 작성 - 7. reference solver 결과와 구현 solver 결과 비교 - 8. 결과 차이가 tolerance 범위 내에 들어오면 구현 완료 주요 기능: - `references///` artifact bundle 요구사항을 정의한다. - `model.inp`, `metadata.json`, `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv`를 기준 artifact로 둔다. - solver result CSV와 stored reference CSV를 schema, unit, coordinate, id matching, tolerance 기준으로 비교한다. - reference verification 통과 후 equilibrium, reaction consistency, displacement direction, stress/strain sanity, model coverage를 검토한다. 대표 산출물: - `docs/reference-models/-reference-models.md` - `docs/reference-verifications/-reference-verification.md` - `docs/physics-evaluations/-physics-evaluation.md` 금지사항: - Abaqus/Nastran 또는 reference solver를 실행하지 않는다. - reference CSV를 생성하거나 수정하지 않는다. - tolerance를 통과시키기 위해 solver output을 보정하지 않는다. - physics pass를 release readiness로 해석하지 않는다. ### 4. `fesa-cpp-msvc-tdd` C++17/MSVC/CMake/CTest 기반 TDD 구현과 build/test 실패 분석을 위한 skill이다. 사용 Agent: - Implementation Planning Agent - Implementation Agent - Build/Test Executor Agent - Correction Agent 적용 개발 과정: - 6. 코드 구현 주요 기능: - upstream specification을 TDD task와 CMake/CTest plan으로 변환한다. - `RED -> GREEN -> VERIFY` 순서로 C++ 구현을 진행한다. - C++ production 변경에는 관련 C++ test를 요구한다. - Build/Test 실패를 configure, compile, link, test, reference-comparison, harness, environment, upstream-contract로 분류한다. - implementation-owned failure만 최소 수정한다. 대표 산출물: - `docs/implementation-plans/-implementation-plan.md` - implementation report - `docs/build-test-reports/-build-test.md` - `docs/corrections/-correction.md` 기본 검증 명령: ```bash python -m unittest discover -s scripts -p "test_*.py" python scripts/validate_workspace.py ``` 기본 CMake/MSVC 경로: ```bash cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64 cmake --build build/msvc-debug --config Debug ctest --test-dir build/msvc-debug --output-on-failure -C Debug ``` 금지사항: - 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 변경하지 않는다. - Abaqus/Nastran을 실행하지 않는다. - release readiness를 승인하지 않는다. ### 5. `fesa-release-coordination` 전체 workflow gate, handoff, blocker, release readiness 정리를 위한 skill이다. 사용 Agent: - Coordinator Agent - Release Agent 적용 개발 과정: - 9. 솔버 기능 배포 주요 기능: - feature별 workflow state를 audit한다. - 다음 Agent handoff package를 작성한다. - repeated failure, blocker, user decision을 기록한다. - release checklist, known limitations, release notes draft를 작성한다. - Build/Test, Reference Verification, Physics Evaluation, Release gate evidence를 확인한다. 대표 산출물: - `docs/coordination/-coordination.md` - `docs/releases/-release.md` 상태 전이 기준: - `ready-for-implementation`: Implementation Planning report가 준비되었을 때 - `needs-reference-verification`: Build/Test report가 `pass-for-reference-verification`일 때 - `needs-physics-evaluation`: Reference Verification report가 `pass-for-physics-evaluation`일 때 - `needs-release`: Physics Evaluation report가 `pass-for-release-agent`일 때 - `completed`: Release Agent report가 `ready-for-release`이고 final workflow closure가 기록되었을 때 금지사항: - 다른 Agent가 소유한 기술 판정을 대체하지 않는다. - 실패하거나 누락된 gate evidence를 우회하지 않는다. - 사용자 명시 요청 없이 publish, deploy, package, tag, commit을 수행하지 않는다. ## 개발 과정과 Skill 매핑 | 개발 과정 | Skill | | --- | --- | | 1. 솔버 기능에 대한 요구조건 정의 | `fesa-feature-definition` | | 2. 책, 논문 등 연구자료 조사 | `fesa-feature-definition` | | 3. 코드 구현을 위한 유한요소 정식화 | `fesa-fem-specification` | | 4. 솔버 입출력 데이터 정의 | `fesa-fem-specification` | | 5. TDD 방법 사용을 위한 테스트모델 작성 | `fesa-reference-validation` | | 6. 코드 구현 | `fesa-cpp-msvc-tdd` | | 7. reference solver 결과와 구현 solver 결과 비교 | `fesa-reference-validation` | | 8. tolerance 범위 내 결과 차이 확인 | `fesa-reference-validation` | | 9. 솔버 기능 배포 | `fesa-release-coordination` | ## Agent와 Skill 관계 | Agent | 주로 사용하는 Skill | | --- | --- | | Coordinator Agent | `fesa-release-coordination`, `fesa-feature-definition`, `fesa-reference-validation` | | Requirement Agent | `fesa-feature-definition` | | Research Agent | `fesa-feature-definition` | | Formulation Agent | `fesa-fem-specification` | | Numerical Review Agent | `fesa-fem-specification` | | I/O Definition Agent | `fesa-fem-specification` | | Reference Model Agent | `fesa-reference-validation` | | Implementation Planning Agent | `fesa-fem-specification`, `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-validation` | | Physics Evaluation Agent | `fesa-reference-validation` | | Release Agent | `fesa-release-coordination`, `fesa-feature-definition` | ## v1 구현 방침 - 각 skill은 `.codex/skills//SKILL.md`에 둔다. - v1에서는 `SKILL.md`만 작성하고, 별도 scripts, references, assets, plugin packaging은 만들지 않는다. - skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 실제 반복 절차와 checklist 중심으로 작성한다. - skill description은 Codex가 자동으로 고를 수 있도록 trigger 상황을 명확히 쓴다. - 추후 반복 사용 중 절차가 안정화되면 검증 스크립트나 reference template을 skill resource로 분리한다.