baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add skills

Browse Source
This commit is contained in:
김경종
2026-06-04 15:03:03 +09:00
parent 1daf68afb9
commit 9b31adfd15
42 changed files with 1401 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/SOLVER_SKILL_DESIGN.md
+131 -182
View File
@@ -1,232 +1,181 @@
# FESA Solver Development Skill 구성안
# FESA Solver Skill Rebuild Plan
## 목적
이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 Codex skills 구성을 정의한다.
이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 project-local Codex skill 구성을 정의한다.
Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 기술과 절차 단위다. 따라서 skill은 Agent와 1:1로 대응시키지 않고, solver 개발 과정에서 반복되는 공통 workflow를 압축해 구성한다.
Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 절차와 검증 도구 단위다. 따라서 skill은 Agent와 1:1로 대응하지 않는다. 대신 요구조건, 연구, 정식화, I/O 계약, reference model, C++ TDD 구현, reference 비교, 물리 검토, release readiness처럼 솔버 개발 과정에서 반복되는 작업 흐름을 기준으로 구성한다.
## 설계 원칙
- 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은 `.codex/skills/<skill-name>/SKILL.md`에 둔다.
- 각 skill은 필수 frontmatter `name`, `description`과 UI metadata `agents/openai.yaml`을 가진다.
- Skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 입력, 절차, 산출물, 금지사항, 품질 gate, handoff를 정의한다.
- Skill은 `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.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 구성
### 1. `fesa-feature-definition`
| 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` |
요구조건 정의와 연구 질문 정리를 위한 skill이다.
## 개발 과정별 사용 예
사용 Agent:
- Requirement Agent
- Research Agent
- Coordinator Agent
- Release Agent
예시 기능: `linear-truss-1d`
적용 개발 과정:
- 1. 솔버 기능에 대한 요구조건 정의
- 2. 책, 논문 등 연구자료 조사
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 CSV와 저장된 reference CSV를 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를 작성한다.
주요 기능:
- 기능 요청을 검증 가능한 requirement baseline으로 정리한다.
- `shall` 요구조건, acceptance criteria, verification matrix를 작성한다.
- 필요한 연구 질문과 source gap을 정리한다.
- 미확정 tolerance, 지원 범위, reference artifact 요구사항을 open issue로 남긴다.
## Skill별 핵심 계약
대표 산출물:
- `docs/requirements/<feature-id>.md`
- `docs/research/<feature-id>-research.md`
- requirement verification matrix
- downstream handoff questions
### `fesa-requirements-baseline`
금지사항:
- FEM 정식화를 확정하지 않는다.
- C++ 구현, Abaqus/Nastran 실행, reference CSV 생성을 하지 않는다.
- 검증 불가능한 요구조건을 완료 상태로 두지 않는다.
- 기능 요청을 검증 가능한 요구조건 baseline으로 만든다.
- `shall` 문장과 `FESA-REQ-<FEATURE>-###` id를 사용한다.
- 모든 `must` 요구조건은 verification method와 acceptance criteria를 가져야 한다.
- FEM 정식화, C++ 구현, reference CSV 생성, release readiness 판단은 하지 않는다.
### 2. `fesa-fem-specification`
### `fesa-research-evidence`
FEM 정식화, 수치 검토, 입출력 계약을 구현 가능한 specification으로 정리하기 위한 skill이다.
- 연구 질문, source inventory, source reliability tier, benchmark 후보를 정리한다.
- 검증된 사실과 추론을 분리한다.
- source gap은 open issue로 남긴다.
- FEM 정식화 확정이나 reference value 생성을 하지 않는다.
사용 Agent:
- Formulation Agent
- Numerical Review Agent
- I/O Definition Agent
- Implementation Planning Agent
### `fesa-formulation-spec`
적용 개발 과정:
- 3. 코드 구현을 위한 유한요소 정식화
- 4. 솔버 입출력 데이터 정의
- 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 검토 전 최종 승인 상태로 두지 않는다.
주요 기능:
- 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을 정리한다.
### `fesa-numerical-review`
대표 산출물:
- `docs/formulations/<feature-id>-formulation.md`
- `docs/numerical-reviews/<feature-id>-review.md`
- `docs/io-definitions/<feature-id>-io.md`
- 정식화를 수치 알고리즘 계약으로 독립 검토한다.
- dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다.
- `pass-for-implementation-planning`은 구현 계획 가능 상태만 의미한다.
- 정식화 문서를 직접 수정하지 않는다.
금지사항:
- C++ API나 파일 구조를 확정하지 않는다.
- parser 구현을 하지 않는다.
- reference artifact나 tolerance policy를 임의로 만들지 않는다.
### `fesa-io-contract`
### 3. `fesa-reference-validation`
- FESA solver input이 지원할 Abaqus `.inp` subset을 정의한다.
- model data와 history data를 구분한다.
- 내부 semantic model 계약과 output/CSV schema를 정의한다.
- parser 구현이나 full Abaqus compatibility claim은 하지 않는다.
reference model 설계, stored Abaqus CSV 비교, physics sanity 평가를 위한 skill이다.
### `fesa-reference-models`
사용 Agent:
- Reference Model Agent
- Reference Verification Agent
- Physics Evaluation Agent
- Coordinator Agent
적용 개발 과정:
- 5. TDD 방법 사용을 위한 개발 솔버와 reference solver 테스트모델 작성
- 7. reference solver 결과와 구현 solver 결과 비교
- 8. 결과 차이가 tolerance 범위 내에 들어오면 구현 완료
주요 기능:
- `references/<feature-id>/<model-id>/` artifact bundle 요구사항을 정의한다.
- 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로 둔다.
- solver result CSV와 stored reference CSV를 schema, unit, coordinate, id matching, tolerance 기준으로 비교한다.
- reference verification 통과 후 equilibrium, reaction consistency, displacement direction, stress/strain sanity, model coverage를 검토한다.
- Reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts`로 둔다.
대표 산출물:
- `docs/reference-models/<feature-id>-reference-models.md`
- `docs/reference-verifications/<feature-id>-reference-verification.md`
- `docs/physics-evaluations/<feature-id>-physics-evaluation.md`
### `fesa-cpp-msvc-tdd`
금지사항:
- Abaqus/Nastran 또는 reference solver를 실행하지 않는다.
- reference CSV를 생성하거나 수정하지 않는다.
- tolerance를 통과시키기 위해 solver output을 보정하지 않는다.
- physics pass를 release readiness로 해석하지 않는다.
- C++ 구현을 `RED -> GREEN -> VERIFY` 순서로 수행한다.
- C++ production 변경에는 관련 C++ test file이 있어야 한다.
- 기본 검증 명령:
### 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/<feature-id>-implementation-plan.md`
- implementation report
- `docs/build-test-reports/<feature-id>-build-test.md`
- `docs/corrections/<feature-id>-correction.md`
기본 검증 명령:
```bash
```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
ctest -C Debug -R <feature-or-label>
```
기본 CMake/MSVC 경로:
- 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다.
- 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다.
```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
```
### `fesa-reference-comparison`
금지사항:
- 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 변경하지 않는다.
- Abaqus/Nastran을 실행하지 않는다.
- release readiness를 승인하지 않는다.
- `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를 의미하지 않는다.
### 5. `fesa-release-coordination`
### `fesa-physics-sanity`
전체 workflow gate, handoff, blocker, release readiness 정리를 위한 skill이다.
- 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 검토 가능 상태만 의미한다.
사용 Agent:
- Coordinator Agent
- Release Agent
### `fesa-release-readiness`
적용 개발 과정:
- 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/<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` |
- `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-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` |
| 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-validation` |
| Physics Evaluation Agent | `fesa-reference-validation` |
| Release Agent | `fesa-release-coordination`, `fesa-feature-definition` |
| Reference Verification Agent | `fesa-reference-comparison`, `fesa-io-contract` |
| Physics Evaluation Agent | `fesa-physics-sanity` |
| Release Agent | `fesa-release-readiness` |
## 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로 분리한다.
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/SOLVER_AGENT_DESIGN.md` 참조
- skill-specific 핵심 문구와 산출물 경로
- `agents/openai.yaml` UI metadata
- 이 문서가 아니라 실제 skill 파일이 기준이 되도록 `docs/SOLVER_SKILL_DESIGN.md`에 대한 skill 본문 참조 금지
검증 명령:
```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```
Skill 구조 검증:
```powershell
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`이다.