# 구조해석 솔버 개발 Agent 구성안

## 목적
이 문서는 Abaqus, Nastran과 같은 유한요소법 기반 구조해석 솔버를 개발하기 위한 AI Agent 운영 구성을 정의한다.

이번 구성안은 ALL-FEM 논문의 구조를 확장하거나 재사용하는 계획이 아니다. 논문은 Agent 설계를 위한 참고 자료로만 사용하며, 본 프로젝트는 C++/MSVC 기반 독립 솔버 개발 워크플로우를 따른다.

## 설계 원칙
- 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
- 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
- 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. 기능이 선언한 기존 `.inp`와 실제
  비교에 필요한 Abaqus CSV만 read-only 검증 기준으로 사용한다. Canonical naming,
  README, metadata, version 또는 provenance는 기본 readiness 조건이 아니다.
- FESA는 Abaqus와 독립적인 solver다. Agent는 Abaqus 내부 formulation, integration,
  stabilization 또는 recovery equivalence를 요구하거나 추론하지 않는다.
- 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
- Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.

## Harness Step 실행 계약

계획과 구현 Agent는 작업 전 `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.
Implementation Planning Agent는 multi-Step 초안을 사용자에게 승인받은 뒤 planning files만
materialize하며 Step을 선택하거나 실행하지 않는다. Executor는 별도의 명시적 사용자 요청으로
`scripts/execute.py`를 실행할 때 branch, pending Step 선택, retry, timestamps, commits, Step
advancement와 phase status를 소유한다.

Implementation Agent는 approved plan, materialized phase files, Executor-selected current
`stepN.md`만 사용해 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`를 완료하고
다음 Step을 시작하지 않는다. Agent가 쓸 수 있는 Harness metadata는 current Step의 `status`와
`summary`, `error_message`, `blocked_reason` payload뿐이다. `.codex/hooks.json`이 PreToolUse
interception과 Stop whole-project validation을 자동 실행하므로 hook entry point를 수동 실행해
대체하지 않는다. 세부 schema와 recovery 절차는 `docs/HARNESS_WORKFLOW.md`를 따른다.

## 전체 Agent 구성

### Coordinator Agent
전체 개발 흐름을 관리하는 상위 조정 Agent이다.

책임:
- 기능 개발 요청을 단계별 작업으로 분해한다.
- 각 Agent의 산출물을 연결하고 누락된 결정을 추적한다.
- 요구조건, 정식화, 테스트, 구현, 검증, 배포 단계의 진행 상태를 관리한다.
- 실패 시 어떤 Agent로 되돌릴지 결정한다.

주요 산출물:
- 기능별 개발 계획
- 단계별 승인 상태
- 실패 원인과 재작업 지시

### Requirement Agent
솔버 기능 요구조건을 정의하는 Agent이다.

책임:
- 해석 기능의 범위, 입력, 출력, 제약조건을 정의한다.
- 대상 요소, 재료 모델, 경계조건, 하중 조건, 해석 타입을 명확히 한다.
- 검증해야 할 물리량과 tolerance 기준을 정한다.

주요 산출물:
- 기능 요구조건 문서
- acceptance criteria
- 검증 물리량 목록

예시 검증 물리량:
- 절점 변위
- 반력
- 요소 내력
- 응력
- 변형률
- 에너지 또는 잔차 기준

### Research Agent
책, 논문, 매뉴얼, 공개 benchmark를 조사하는 Agent이다.

책임:
- 유한요소 정식화에 필요한 이론 자료를 수집한다.
- 요소별 benchmark와 patch test 사례를 찾는다.
- Abaqus/Nastran 결과와 비교할 수 있는 공개 예제 또는 문헌 해를 조사한다.
- 자료의 신뢰도와 적용 범위를 평가한다.

주요 산출물:
- 연구자료 요약
- 공식, 가정, 한계 정리
- benchmark 후보 목록

### Formulation Agent
코드 구현을 위한 유한요소 정식화를 작성하는 Agent이다.

책임:
- 약형, 형상함수, B matrix, constitutive matrix, 수치적분, 요소 강성 행렬을 정의한다.
- 자유도 배치, 좌표계, 단위계, 부호 규약을 명확히 한다.
- 선형/비선형, 정적/동적, small/large deformation 여부를 구분한다.
- 구현 가능한 알고리즘 형태로 정식화를 정리한다.

주요 산출물:
- 요소별 정식화 문서
- 알고리즘 의사코드
- 수치적분 규칙
- edge case와 singular case 목록

### Numerical Review Agent
정식화와 수치 알고리즘을 독립 검토하는 Agent이다.

책임:
- 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
- rigid body mode, patch test, symmetry, positive definiteness 등 기본 수치 조건을 확인한다.
- locking, hourglass mode, ill-conditioning 같은 위험을 식별한다.
- 구현 전 정식화 오류를 줄인다.

주요 산출물:
- 정식화 리뷰 결과
- 수치 위험 목록
- 추가 테스트 요구사항

### I/O Definition Agent
솔버 입력과 출력 데이터 구조를 정의하는 Agent이다.

책임:
- mesh, node, element, material, section, boundary condition, load, step 입력 형식을 정의한다.
- authoritative HDF5 result schema와 reference CSV comparison row schema를 정의한다.
- Abaqus input file과 내부 입력 모델 사이의 대응 관계를 정리한다.
- 결과 비교를 위해 FESA HDF5 dataset과 Abaqus reference CSV row의 ID/컴포넌트 규약을 맞춘다.

주요 산출물:
- 입력 데이터 schema
- 출력 데이터 schema
- HDF5 result schema
- 결과 비교용 deterministic CSV view schema
- 단위와 좌표계 규약

### Reference Model Agent
TDD와 검증에 사용할 기존 reference case를 inventory하는 Agent이다.

책임:
- 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다.
- 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와
  tolerance를 inventory한다.
- FESA HDF5 quantity와 source ID/component matching을 명시한다.
- 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.

중요 제약:
- Agent는 Abaqus를 직접 실행하지 않는다.
- Abaqus 해석 결과 CSV는 사람이 생성하거나 별도 승인된 절차로 생성해 `reference/<model-id>/`에 저장한다.
- Agent는 저장된 reference artifact만 사용해 비교한다.

최소 reference case 구조:
```text
reference/
  <case-dir>/
    <declared-input>.inp
    <declared-required-quantity>.csv
```

Directory와 filename은 제공된 값을 그대로 사용한다. Reference Model Agent는 canonical
이름, README, metadata, provenance 또는 비교하지 않는 quantity CSV를 요구하지 않는다.

### Implementation Planning Agent
코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다.

책임:
- 요구조건과 정식화를 C++ 구현 작업으로 분해한다.
- 먼저 작성할 단위 테스트, 통합 테스트, 레퍼런스 비교 테스트를 정의한다.
- 기존 architecture와 ownership boundary에 맞춰 변경 파일을 제한한다.
- 구현 Agent가 따라야 할 acceptance criteria를 제공한다.

주요 산출물:
- 구현 계획
- 테스트 우선순위
- 변경 파일 후보
- acceptance checklist
- 사용자 승인 전 multi-Step Harness 초안
- 승인 후 `phases/index.json`, `phases/<task-name>/index.json`, 자기완결적 `stepN.md`

필수 절차:
- 구현 계획 요청에서 project-local `$harness` skill을 사용한다.
- `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽고 multi-Step 초안만 사용자에게
  제시한다.
- 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD
  RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다.
- Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다.
- 승인 후에는 planning files만 materialize하고 Step 선택/실행은 하지 않는다. Harness executor
  실행은 별도 사용자 요청이 있을 때만 수행한다.

### Implementation Agent
C++ 코드를 구현하는 Agent이다.

책임:
- `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, materialized phase files와
  Executor-selected current `stepN.md`를 읽고 현재 Step만 수행한다.
- 테스트를 먼저 작성하고 실패를 확인한다.
- 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
- C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
- 불필요한 일반화나 speculative abstraction을 피한다.
- current Step의 `status`와 `summary`, `error_message`, `blocked_reason`만 기록한다.
  branch, retry, timestamp, commit, advancement는 Executor에 맡긴다.
- `.codex/hooks.json`으로 자동 등록된 PreToolUse와 Stop을 사용하며 hook script를 수동
  검증 대체물로 실행하지 않는다.

주요 산출물:
- C++ source/header 변경
- 테스트 코드
- CMake/CTest 변경

### Build/Test Executor Agent
빌드와 테스트를 실행하는 Agent이다.

책임:
- `.harness/config.json` 또는 자동 감지 결과에 맞는 MSVC build/test 명령을 실행한다.
- MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
- 실패 로그를 요약하고 Correction Agent에 전달한다.

기본 CMake 검증 명령:
```powershell
cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 선언된 명령을 따른다.

검증 대상:
- CMake configure
- MSVC Debug build
- CTest
- Harness self-test

### Correction Agent
빌드, 테스트, 런타임 실패를 수정하는 Agent이다.

책임:
- 실패 로그를 원인별로 분류한다.
- 컴파일 오류, 링크 오류, 테스트 실패, 결과 비교 실패를 구분한다.
- 최소 수정으로 실패를 해결한다.
- 같은 실패가 반복되면 Coordinator Agent에 차단 상태를 보고한다.

주요 산출물:
- 수정 패치
- 실패 원인 요약
- 재검증 요청

### Reference Verification Agent
구현 솔버 결과와 저장된 레퍼런스 결과를 비교하는 Agent이다.

책임:
- 구현 솔버 `results.h5`의 rows와 `reference/<model-id>/`의 Abaqus reference CSV rows를 비교하고, FESA debug CSV views는 row identity 검토와 report evidence로만 사용한다.
- 절점 변위, 반력, 요소 내력, 응력의 tolerance 만족 여부를 평가한다.
- absolute tolerance, relative tolerance, norm-based tolerance를 구분해 적용한다.
- 결과 차이가 tolerance 밖이면 원인 후보를 분류한다.

주요 산출물:
- reference comparison report
- 실패한 물리량과 위치
- 최대 오차, 평균 오차, norm 오차

### Physics Evaluation Agent
수치 결과가 물리적으로 타당한지 검토하는 Agent이다.

책임:
- 레퍼런스와 수치적으로 비슷해도 물리적으로 이상한 결과가 있는지 확인한다.
- 변위 방향, 반력 평형, 응력 집중, 대칭 조건, rigid body mode를 검토한다.
- 테스트 모델이 기능을 충분히 검증하지 못하면 추가 모델을 요구한다.

주요 산출물:
- 물리 검토 결과
- 추가 검증 모델 요구사항
- release 가능 여부 의견

### Release Agent
기능 배포 준비를 담당하는 Agent이다.

책임:
- 요구조건, 테스트, 레퍼런스 비교, 물리 검토가 모두 통과했는지 확인한다.
- 기능 문서와 release note를 정리한다.
- 알려진 제한사항과 tolerance 기준을 기록한다.

주요 산출물:
- release checklist
- 기능 문서
- known limitations

## 개발 프로세스 매핑

| 개발 과정 | 담당 Agent | 필수 산출물 |
| --- | --- | --- |
| 1. 솔버 기능 요구조건 정의 | Requirement Agent | 요구조건, acceptance criteria |
| 2. 연구자료 조사 | Research Agent | 자료 요약, benchmark 후보 |
| 3. 유한요소 정식화 | Formulation Agent, Numerical Review Agent | 정식화 문서, 리뷰 결과 |
| 4. 입출력 데이터 정의 | I/O Definition Agent | 입력/출력 schema |
| 5. Reference case 준비 | Reference Model Agent, Implementation Planning Agent | 기존 input/required CSV inventory, 비교 mapping, tolerance |
| 6. 코드 구현 | Implementation Agent | C++ 코드, 테스트 |
| 7. 레퍼런스 결과 비교 검증 | Reference Verification Agent, Physics Evaluation Agent | 비교 리포트, 물리 검토 |
| 8. tolerance 만족 시 완료 | Coordinator Agent | 기능 완료 승인 |
| 9. 기능 배포 | Release Agent | release checklist, 문서 |

## 표준 작업 흐름

```mermaid
flowchart TD
  A["기능 요청"] --> B["Requirement Agent"]
  B --> C["Research Agent"]
  C --> D["Formulation Agent"]
  D --> E["Numerical Review Agent"]
  E --> F["I/O Definition Agent"]
  F --> G["Reference Model Agent"]
  G --> H["Implementation Planning Agent"]
  H --> I["Implementation Agent"]
  I --> J["Build/Test Executor Agent"]
  J --> K{"빌드/테스트 통과?"}
  K -- "아니오" --> L["Correction Agent"]
  L --> I
  K -- "예" --> M["Reference Verification Agent"]
  M --> N{"tolerance 만족?"}
  N -- "아니오" --> L
  N -- "예" --> P["Physics Evaluation Agent"]
  P --> Q{"물리 검토 통과?"}
  Q -- "아니오" --> L
  Q -- "예" --> R["Release Agent"]
```

## 검증 Gate

### Gate 1: 요구조건 승인
통과 조건:
- 대상 기능과 제외 범위가 명확하다.
- 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
- 레퍼런스 비교 방식이 정해져 있다.

### Gate 2: 정식화 승인
통과 조건:
- 요소 정식화와 수치적분 규칙이 문서화되어 있다.
- 좌표계, 자유도, 부호 규약이 명확하다.
- Numerical Review Agent가 주요 수치 위험을 검토했다.

### Gate 3: 테스트 준비 승인
통과 조건:
- 구현 전 실패해야 하는 테스트가 정의되어 있다.
- 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다.
- 필요한 source ID/component matching과 tolerance가 정의되어 있다.

### Gate 4: 구현 검증
통과 조건:
- CMake/MSVC/CTest validation이 통과한다.
- 단위 테스트와 통합 테스트가 통과한다.
- 관련 C++ test file이 있고 같은 구현 Step 안에 RED 실패와 후속 GREEN 성공 증거가 있다.
- Stop의 전체 MSVC build/test 검증이 통과한다.

### Gate 5: 레퍼런스 검증
통과 조건:
- 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가
  tolerance 안에 있다.
- Warning-only quantity는 결과와 경고가 리포트에 남고 pass/fail을 바꾸지 않는다.
- Required source row/component의 누락, 추가, 중복 또는 nonfinite 값이 없다.

### Gate 6: 배포 승인
통과 조건:
- 요구조건의 acceptance criteria가 모두 만족된다.
- 문서와 release note가 준비되어 있다.
- 남은 제한사항이 명확히 기록되어 있다.

## FESA HDF5 / Abaqus Reference CSV 비교 기준

권장 비교 방식:
- authoritative 비교는 FESA `results.h5` rows와 Abaqus reference CSV rows 기준으로 수행한다.
- FESA HDF5에서 추출한 deterministic CSV view는 debugging/review 보조 artifact로만 사용한다.
- scalar 값: absolute tolerance와 relative tolerance를 함께 적용한다.
- vector 값: component-wise 비교와 norm 비교를 함께 기록한다.
- stress tensor: component-wise 비교를 기본으로 하고, 필요한 경우 principal stress 또는 von Mises stress를 추가 비교한다.
- 반력: 전체 하중 평형과 개별 구속 자유도 반력을 모두 확인한다.

권장 리포트 항목:
- model name
- compared quantity
- number of compared rows
- maximum absolute error
- maximum relative error
- RMS error
- worst node or element id
- pass/fail

## 반복 실패 처리

반복 실패가 발생하면 Correction Agent가 무한 수정 루프를 계속하지 않는다. 다음 중 하나로 분류해 Coordinator Agent에 보고한다.

- 요구조건 불명확
- 정식화 오류 가능성
- reference artifact 오류 가능성
- I/O schema 불일치
- 구현 결함
- tolerance 기준 부적절
- 테스트 모델이 기능을 과도하게 또는 불충분하게 검증함

Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Definition, Reference Model, Implementation Agent 중 적절한 단계로 되돌린다.

## 초기 적용 우선순위

1. 선형 정적 해석의 최소 골격
2. Isoparametric 3D Euler beam element
3. 1D truss 또는 bar element
4. 2D plane stress/plane strain element
5. 3D solid element
6. material model 확장
7. nonlinear 또는 dynamic analysis 확장

각 단계는 요구조건, 정식화, 테스트모델, 구현, 레퍼런스 비교, 배포 Gate를 독립적으로 통과해야 한다.

## 운영 메모

- Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
- 사람이 제공한 Abaqus reference artifact는 현재 path/name 그대로 read-only로 사용한다.
  별도 provenance, README 또는 metadata가 없다는 이유로 gate를 차단하지 않는다.
- reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
- 기능 구현 완료 판정은 build/test와 기능별 blocking reference validation 통과를 기준으로
  한다. Physics evaluation과 release readiness는 별도 후속 배포 gate다.
