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

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

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

## 설계 원칙
- 새로운 솔버 기능 요구조건 분석, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
- 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
- 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `references/`에 저장된 입력 파일과 레퍼런스 CSV 결과를 검증 기준으로 사용한다.
- 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.

## 전체 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 입력 형식을 정의한다.
- 출력 CSV 또는 result file schema를 정의한다.
- Abaqus input file과 내부 입력 모델 사이의 대응 관계를 정리한다.
- 결과 비교를 위해 레퍼런스 CSV와 구현 솔버 출력의 컬럼 규약을 맞춘다.

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

### Reference Model Agent
TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.

책임:
- 개발 대상 기능을 검증할 최소 모델, benchmark 모델, 회귀 모델을 설계한다.
- `references/`에 보관할 Abaqus input file과 Abaqus 결과 CSV 요구사항을 정의한다.
- 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다.
- 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.

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

권장 reference 구조:
```text
references/
  <feature-name>/
    model.inp
    metadata.json
    displacements.csv
    reactions.csv
    element_forces.csv
    stresses.csv
```

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

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

주요 산출물:
- 구현 계획
- 테스트 우선순위
- 변경 파일 후보
- acceptance checklist

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

책임:
- 테스트를 먼저 작성하고 실패를 확인한다.
- 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
- C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
- 불필요한 일반화나 speculative abstraction을 피한다.

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

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

책임:
- Harness validation을 실행한다.
- MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
- 실패 로그를 요약하고 Correction Agent에 전달한다.

기본 검증 명령:
```powershell
python scripts/validate_workspace.py
```

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

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

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

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

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

책임:
- 구현 솔버 결과 CSV와 `references/`의 Abaqus CSV를 비교한다.
- 절점 변위, 반력, 요소 내력, 응력의 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. TDD 테스트모델 작성 | Reference Model Agent, Implementation Planning Agent | 테스트 모델, reference artifact 요구사항 |
| 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 -- "아니오" --> O["Physics Evaluation Agent"]
  O --> 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: 테스트 준비 승인
통과 조건:
- 구현 전 실패해야 하는 테스트가 정의되어 있다.
- `references/` artifact 요구사항이 명확하다.
- 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다.

### Gate 4: 구현 검증
통과 조건:
- CMake/MSVC/CTest validation이 통과한다.
- 단위 테스트와 통합 테스트가 통과한다.
- Harness TDD guard를 만족한다.

### Gate 5: 레퍼런스 검증
통과 조건:
- 저장된 Abaqus CSV 결과와 구현 솔버 결과가 tolerance 안에 있다.
- 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다.
- 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다.

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

## Reference CSV 비교 기준

권장 비교 방식:
- 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. 1D truss 또는 bar element
3. 2D plane stress/plane strain element
4. 3D solid element
5. material model 확장
6. nonlinear 또는 dynamic analysis 확장

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

## 운영 메모

- Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건을 `metadata.json`에 기록한다.
- reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
- 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다.