baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1daf68afb9c018819fb127cf49d7df436b14c4e1
FESADev/docs/SOLVER_SKILL_DESIGN.md
T
김경종 535a680197 add agents
2026-06-02 16:33:25 +09:00

9.5 KiB
Raw Blame History

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. 솔버 기능에 대한 요구조건 정의
    1. 책, 논문 등 연구자료 조사

주요 기능:

  • 기능 요청을 검증 가능한 requirement baseline으로 정리한다.
  • shall 요구조건, acceptance criteria, verification matrix를 작성한다.
  • 필요한 연구 질문과 source gap을 정리한다.
  • 미확정 tolerance, 지원 범위, reference artifact 요구사항을 open issue로 남긴다.

대표 산출물:

  • docs/requirements/<feature-id>.md
  • docs/research/<feature-id>-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

적용 개발 과정:

    1. 코드 구현을 위한 유한요소 정식화
    1. 솔버 입출력 데이터 정의

주요 기능:

  • 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/<feature-id>-formulation.md
  • docs/numerical-reviews/<feature-id>-review.md
  • docs/io-definitions/<feature-id>-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

적용 개발 과정:

    1. TDD 방법 사용을 위한 개발 솔버와 reference solver 테스트모델 작성
    1. reference solver 결과와 구현 solver 결과 비교
    1. 결과 차이가 tolerance 범위 내에 들어오면 구현 완료

주요 기능:

  • references/<feature-id>/<model-id>/ 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/<feature-id>-reference-models.md
  • docs/reference-verifications/<feature-id>-reference-verification.md
  • docs/physics-evaluations/<feature-id>-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

적용 개발 과정:

    1. 코드 구현

주요 기능:

  • 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/<feature-id>-implementation-plan.md
  • implementation report
  • docs/build-test-reports/<feature-id>-build-test.md
  • docs/corrections/<feature-id>-correction.md

기본 검증 명령:

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

기본 CMake/MSVC 경로:

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

적용 개발 과정:

    1. 솔버 기능 배포

주요 기능:

  • 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/<feature-id>-coordination.md
  • docs/releases/<feature-id>-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-name>/SKILL.md에 둔다.
  • v1에서는 SKILL.md만 작성하고, 별도 scripts, references, assets, plugin packaging은 만들지 않는다.
  • skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 실제 반복 절차와 checklist 중심으로 작성한다.
  • skill description은 Codex가 자동으로 고를 수 있도록 trigger 상황을 명확히 쓴다.
  • 추후 반복 사용 중 절차가 안정화되면 검증 스크립트나 reference template을 skill resource로 분리한다.
Reference in New Issue View Git Blame Copy Permalink