add agents

2026-06-02 12:28:37 +09:00
parent e54ba13d3b
commit dd50f8c093
9 changed files with 833 additions and 0 deletions
@@ -0,0 +1,148 @@
+# 정식화 문서 작성 가이드
+
+이 디렉터리는 Formulation Agent가 작성하거나 제안한 기능별 유한요소 정식화 문서를 보관하는 위치다.
+
+기본 파일명은 `docs/formulations/<feature-id>-formulation.md` 형식을 사용한다. 각 문서는 Requirement Agent의 요구조건과 Research Agent의 연구 브리프를 입력으로 받아 Implementation Planning Agent와 Implementation Agent가 사용할 수 있는 수학/알고리즘 계약을 제공해야 한다.
+
+## Formulation Agent 역할
+
+Formulation Agent는 구현 가능한 FEM 정식화 문서를 작성한다.
+
+수행한다:
+- strong form, weak form, discretization을 정리한다.
+- shape functions, `B` matrix 또는 kinematic operator를 정의한다.
+- constitutive contract, element residual/internal force, stiffness/tangent matrix를 정리한다.
+- numerical integration, mapping, Jacobian 규칙을 명시한다.
+- output recovery, algorithm pseudocode, edge case, numerical risk를 정리한다.
+- Numerical Review Agent가 검토할 handoff 항목을 남긴다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- release readiness를 승인하지 않는다.
+- Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Formulation
+
+## Metadata
+- feature_id: <feature-id>
+- source_requirement: docs/requirements/<feature-id>.md
+- source_research: docs/research/<feature-id>-research.md
+- status: draft | needs-research | ready-for-numerical-review
+- owner_agent: formulation-agent
+- date: <YYYY-MM-DD>
+
+## Scope and Assumptions
+- analysis_type: linear static | nonlinear static | modal | dynamic | other
+- element_type: <target element>
+- deformation: small | large | TBD
+- linearity: linear | nonlinear | TBD
+- material_model_boundary: <scope>
+- coordinate_system: <global/local coordinates>
+- units: <unit system>
+
+## Primary Variables and DOFs
+- nodal_variables: <variables>
+- dof_ordering: <ordering>
+- sign_convention: <convention>
+- constrained_free_dof_assumptions: <assumptions>
+
+## Strong Form and Boundary Conditions
+- governing_equation: <equation>
+- dirichlet_boundary: <essential BC>
+- neumann_boundary: <natural BC>
+- natural_boundary_terms: <terms>
+
+## Weak or Variational Form
+- test_functions: <definition>
+- integration_by_parts: <steps>
+- internal_virtual_work: <expression>
+- external_virtual_work: <expression>
+
+## Discretization
+- interpolation: <field interpolation>
+- shape_functions: <shape functions>
+- partition_of_unity_check: <expected check>
+- kronecker_delta_check: <expected check>
+- nodal_layout: <layout>
+
+## Kinematics
+- strain_displacement_relation: <relation>
+- B_matrix_or_kinematic_operator: <definition>
+- deformation_gradient: <definition or N/A>
+- strain_measure: <definition or N/A>
+
+## Constitutive Contract
+- elasticity_matrix_or_stress_update: <contract>
+- material_state_variables: <variables or N/A>
+- assumptions_and_constraints: <assumptions>
+
+## Element Equations
+- internal_force_or_residual: <expression>
+- external_force: <expression>
+- stiffness_or_tangent_matrix: <expression>
+- mass_or_damping: <required expression or N/A>
+- vector_matrix_dimensions: <dimensions>
+
+## Mapping and Numerical Integration
+- reference_coordinates: <coordinates>
+- isoparametric_mapping: <mapping>
+- jacobian: <definition>
+- determinant_checks: <validity checks>
+- gauss_points_and_weights: <rule>
+- integration_policy: full | reduced | selective | analytical | TBD
+
+## Output Recovery
+- displacement: <location and convention>
+- reaction: <calculation>
+- element_force: <calculation>
+- strain: <location and recovery>
+- stress: <location and recovery>
+- nodal_extrapolation: <policy or N/A>
+
+## Algorithm Pseudocode
+```text
+math-level element routine and assembly flow only
+no C++ signatures, class names, or file paths
+```
+
+## Numerical Risks
+- rigid_body_modes: <risk/check>
+- patch_test: <expected test>
+- symmetry: <expected property>
+- positive_definiteness: <expected property>
+- hourglass: <risk or N/A>
+- shear_locking: <risk or N/A>
+- volumetric_locking: <risk or N/A>
+- distortion: <risk/check>
+- singular_jacobian: <risk/check>
+
+## Open Issues and Downstream Handoff
+
+### Numerical Review Agent
+- <derivations, assumptions, numerical risks, open issues>
+
+### I/O Definition Agent
+- <required inputs, outputs, units, coordinate conventions, output locations>
+
+### Reference Model Agent
+- <benchmarkable quantities, patch test needs, expected invariants, edge cases>
+
+### Implementation Planning Agent
+- <math-level pseudocode, acceptance-relevant quantities, tests to write first>
+```
+
+## 품질 기준
+
+- 요구조건과 연구 브리프에 없는 값을 임의로 확정하지 않는다.
+- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분한다.
+- shape functions는 가능한 경우 partition of unity와 Kronecker delta 검사를 포함한다.
+- numerical integration은 integration point, weight, 적분 대상, full/reduced/selective 정책을 포함한다.
+- mapping은 reference coordinates, Jacobian, determinant validity check를 포함한다.
+- output recovery는 nodal, element-level, integration-point 위치를 구분한다.
+- numerical risk는 rigid body modes, patch test, hourglass, locking, Jacobian 문제를 명시한다.
@@ -0,0 +1,119 @@
+# 요구조건 문서 작성 가이드
+
+이 디렉터리는 Requirement Agent가 작성하거나 제안한 기능별 요구조건 문서를 보관하는 위치다.
+
+기본 파일명은 `docs/requirements/<feature-id>.md` 형식을 사용한다. 각 문서는 구현 전에 작성되며, Formulation Agent, I/O Definition Agent, Reference Model Agent, Implementation Planning Agent가 이어받을 수 있는 검증 가능한 baseline이어야 한다.
+
+## Requirement Agent 역할
+
+Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 바꾼다.
+
+수행한다:
+- 기능 범위, 제외 범위, 입력, 출력, 제약조건을 정의한다.
+- 해석 타입, 대상 요소, 자유도, 재료 모델, 경계조건, 하중 조건을 명확히 한다.
+- 절점 변위, 반력, 요소 내력, 응력 등 검증 물리량을 정한다.
+- tolerance와 reference artifact 요구사항을 기록한다.
+- Requirement Verification Matrix를 작성한다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- 유한요소 정식화를 확정하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- 기능 완료 여부를 승인하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Requirements
+
+## Metadata
+- feature_id: <feature-id>
+- title: <title>
+- status: draft | needs-user-decision | approved
+- owner_agent: requirement-agent
+- date: <YYYY-MM-DD>
+
+## Purpose
+<기능 목적과 사용자/개발자 관점의 기대 동작>
+
+## In Scope
+- <포함 범위>
+
+## Out Of Scope
+- <제외 범위>
+
+## Analysis Definition
+- analysis_type: linear static | nonlinear static | modal | other
+- elements: <대상 요소>
+- dofs: <자유도>
+- material_model: <재료 모델>
+- boundary_conditions: <경계조건>
+- loads: <하중 조건>
+- coordinate_system: <좌표계>
+- units: <단위계>
+
+## Input Requirements
+- <입력 요구조건>
+
+## Output Requirements
+- <출력 요구조건>
+
+## Verification Quantities
+- nodal_displacement: required | not-applicable
+- reaction: required | not-applicable
+- element_internal_force: required | not-applicable
+- stress: required | not-applicable
+- strain: required | not-applicable
+- energy_or_residual: required | not-applicable
+
+## Tolerance Policy
+- absolute_tolerance: <value or TBD>
+- relative_tolerance: <value or TBD>
+- norm_based_tolerance: <value or TBD>
+
+## Reference Artifact Requirements
+Expected location: `references/<feature-id>/`
+
+- `model.inp`: required | not-applicable
+- `metadata.json`: required
+- `displacements.csv`: required | not-applicable
+- `reactions.csv`: required | not-applicable
+- `element_forces.csv`: required | not-applicable
+- `stresses.csv`: required | not-applicable
+
+## Requirement Verification Matrix
+
+| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| FESA-REQ-<FEATURE>-001 | The FESA solver shall ... | functional | ... | user | must | reference-comparison | ... | ... | Reference Model Agent; Implementation Planning Agent | draft |
+
+## Open Questions
+- <미확정 값 또는 사용자 결정 필요 사항>
+
+## Downstream Handoff
+
+### Research Agent
+- <조사할 이론, 논문, benchmark, 표준>
+
+### Formulation Agent
+- <정식화 단계에 넘길 해석 타입, 요소, 재료, 자유도, 출력 물리량 계약>
+
+### I/O Definition Agent
+- <입력/출력 schema 요구조건>
+
+### Reference Model Agent
+- <필요한 references/<feature-id>/ artifact 목록>
+
+### Implementation Planning Agent
+- <먼저 작성할 테스트와 acceptance criteria>
+```
+
+## 품질 기준
+
+- 모든 `must` 요구조건은 검증 방법과 acceptance criteria를 가져야 한다.
+- 모든 수치 요구조건은 단위, 좌표계, tolerance 또는 `TBD with owner`를 가져야 한다.
+- reference 비교가 필요한 요구조건은 필요한 CSV artifact를 명시해야 한다.
+- "빠르게", "정확하게", "Abaqus처럼" 같은 문장은 검증 가능한 기준으로 바꾸거나 open question으로 남겨야 한다.
+- 구현 방법, 정식화 세부식, C++ API는 이 문서에서 확정하지 않는다.
@@ -0,0 +1,108 @@
+# 연구 브리프 작성 가이드
+
+이 디렉터리는 Research Agent가 작성하거나 제안한 기능별 연구 브리프를 보관하는 위치다.
+
+기본 파일명은 `docs/research/<feature-id>-research.md` 형식을 사용한다. 각 브리프는 Requirement Agent의 요구조건을 입력으로 받아 Formulation Agent, Numerical Review Agent, Reference Model Agent, Implementation Planning Agent가 사용할 수 있는 근거 자료를 제공해야 한다.
+
+## Research Agent 역할
+
+Research Agent는 FEM 이론, benchmark, verification reference, solver manual, 논문 자료를 조사한다.
+
+수행한다:
+- 기능 요구조건과 관련된 이론 자료를 조사한다.
+- 요소별 benchmark, patch test, MMS, MES, convergence study 후보를 찾는다.
+- Abaqus/Nastran 결과와 비교 가능한 공개 benchmark 또는 문헌 해를 정리한다.
+- 자료의 신뢰도, 적용 범위, 한계, 상충 여부를 평가한다.
+- downstream agent가 사용할 수 있도록 출처와 근거를 추적 가능하게 남긴다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- 유한요소 정식화를 확정하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- 기능 완료 여부를 승인하지 않는다.
+
+## Source Reliability Tier
+
+| tier | source type | examples | use |
+| --- | --- | --- | --- |
+| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, official solver manuals | 우선 근거 |
+| Tier 2 | peer-reviewed paper, reproducible arXiv preprint, textbook | MMS/MES 논문, finite element textbook | 이론/검증 후보 |
+| Tier 3 | vendor example, university course note, technical blog | 공개 강의노트, 기술 블로그 | 보조 근거 |
+| Reject | forum answer, LLM summary, unsourced page, illegal PDF mirror, citation 없는 wiki성 문서 | forum, mirror PDF, 출처 없는 요약 | primary evidence로 사용 금지 |
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Research Brief
+
+## Metadata
+- feature_id: <feature-id>
+- source_requirement: docs/requirements/<feature-id>.md
+- status: draft | needs-user-decision | ready-for-formulation
+- owner_agent: research-agent
+- date: <YYYY-MM-DD>
+
+## Research Questions
+- <Requirement Agent 또는 사용자가 넘긴 조사 질문>
+
+## Source Inventory
+
+| source_type | title | author_or_org | URL_or_DOI | access_date | reliability_tier | notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| standard | ASME V&V 10 | ASME | <URL> | <YYYY-MM-DD> | Tier 1 | VVUQ framework |
+
+## Extracted Facts
+- <정식화에 필요한 사실, benchmark 조건, 검증 물리량, 재료/좌표/단위 가정>
+
+## Candidate Benchmarks
+
+| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability |
+| --- | --- | --- | --- | --- | --- | --- |
+| <id> | <source title> | analytical \| NAFEMS \| Abaqus Verification/Benchmark \| NASA/FEMCI \| paper-derived | <physics> | <targets> | <needed artifacts> | <limits> |
+
+## Verification Relevance
+- code_verification: <관련성>
+- solution_verification: <관련성>
+- validation: <관련성>
+- reference_comparison: <관련성>
+
+## Applicability Limits
+- linear_or_nonlinear: <scope>
+- deformation: small | large | TBD
+- element_type: <scope>
+- material_model: <scope>
+- geometry: <scope>
+- boundary_conditions: <scope>
+- loads: <scope>
+- coordinate_system: <scope>
+- units: <scope>
+
+## Open Issues
+- <근거 부족, 상충 자료, 유료/비공개 자료, 사용자 결정 필요 사항>
+
+## Downstream Handoff
+
+### Formulation Agent
+- <이론 사실, governing assumptions, candidate equations, unresolved formulation questions>
+
+### Numerical Review Agent
+- <수치 위험, convergence expectations, patch test/MMS/MES evidence, source disagreements>
+
+### Reference Model Agent
+- <benchmark candidates, required reference artifacts, target quantities, source limitations>
+
+### Implementation Planning Agent
+- <verification scenarios and testable acceptance evidence>
+```
+
+## 품질 기준
+
+- 모든 외부 근거는 source metadata와 reliability tier를 가져야 한다.
+- verified fact와 inference를 구분해야 한다.
+- benchmark 후보는 target quantity와 applicability limit을 가져야 한다.
+- Abaqus Benchmarks Guide와 Abaqus Verification Guide의 용도를 구분해야 한다.
+- NAFEMS benchmark는 independent standard test와 target value 후보로 기록해야 한다.
+- MMS/MES 자료는 code verification 후보로 기록하되 정식화 확정으로 취급하지 않는다.
+- 사용 불가능하거나 유료/비공개인 자료는 Open Issues에 남겨야 한다.