docs: align consolidated solver workflow

This commit is contained in:
KOKO\Mimi
2026-08-15 03:14:34 +09:00
parent a8efe2b738
commit 925c4851c9
71 changed files with 687 additions and 937 deletions
+28 -27
View File
@@ -15,7 +15,7 @@
- 프로젝트의 배경, 목적, 사용자, 범위는 `docs/PRD.md`에서 확인한다.
- 전체 아키텍처와 모듈별 책임은 `docs/ARCHITECTURE.md`에서 확인한다.
- 주요 아키텍처 결정과 그 이유 및 트레이드오프는 `docs/ADR.md`에서 확인한다.
- AI 에이전트는 설계나 구현 결정을 내리기 전에 PRD에서 제품 범위를, ARCHITECTURE에서 소유권과 데이터 흐름을, ADR에서 이미 결정된 트레이드오프를 먼저 확인한다. 기능별 의미는 `docs/requirements/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`의 승인 문서를 source of truth로 삼는다.
- AI 에이전트는 설계나 구현 결정을 내리기 전에 PRD에서 제품 범위를, ARCHITECTURE에서 소유권과 데이터 흐름을, ADR에서 이미 결정된 트레이드오프를 먼저 확인한다. 기능별 요구조건, 연구, 정식화, 수치/reference 검토, I/O, 구현, 검증, 물리 및 release 의미는 `docs/<feature-id>/`의 승인 문서를 source of truth로 삼는다.
- Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다. 전체 실행 흐름은 `docs/HARNESS_WORKFLOW.md`, 설치와 설정은 `docs/HARNESS.md`를 따른다.
- FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라
Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을
@@ -119,37 +119,38 @@
## 개발 프로세스
- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다.
- CRITICAL: 빌드 경고를 새로 추가하지 말 것.
- 기능 개발은 다음 gate를 순서대로 통과해야 한다.
1. 요구조건 분석
2. 연구자료 조사
3. 유한요소 정식화
4. 수치 검토
5. I/O 계약 정의
6. reference model 계약 준비
7. C++ 구현
8. build/test 검증
9. reference comparison
10. physics sanity
11. release readiness
- 기능 개발은 다음 8단계 gate를 순서대로 통과해야 한다.
1. 요구조건
2. 연구
3. 정식화
4. 수치 검토 + reference model 계약
5. I/O 정의
6. 구현 계획 + C++ 구현 + build/test + reference comparison
7. 물리 검토
8. 배포 준비
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
## Agent/Skill Workflow
AI 에이전트는 유한요소 구조해석 지식이 필요할 때 FEM wiki를 참조하기 위해 `.codex/skills/fem-theory-query` 스킬을 사용할 수 있다.
`coordinator-agent`는 유일한 main agent로서 `docs/<feature-id>/coordination.md`의 8단계
worklist, sub-agent dispatch, evidence gate와 workflow closure를 관리한다. 나머지 모든
profile은 Coordinator가 한정된 단계 작업으로 호출하는 sub-agent이며, peer agent를 직접
호출하거나 다음 gate로 진행하지 않는다. 유한요소 구조해석 지식이 필요할 때는
`.codex/skills/fem-theory-query`를 보조 skill로 사용할 수 있다.
| 개발 과정 | Agent | Skill | 산출물 |
| 단계 | 담당 sub-agent | 필수 skill | `docs/<feature-id>/` 산출물 |
| --- | --- | --- | --- |
| 요구조건 분석 | `requirement-agent` | `fesa-requirements-baseline` | `docs/requirements/<feature-id>.md` |
| 연구자료 조사 | `research-agent` | `fesa-research-evidence`, `fem-theory-query` | `docs/research/<feature-id>-research.md` |
| 유한요소 정식화 | `formulation-agent` | `fesa-formulation-spec` | `docs/formulations/<feature-id>-formulation.md` |
| 수치 검토 | `numerical-review-agent` | `fesa-numerical-review` | `docs/numerical-reviews/<feature-id>-review.md` |
| I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `docs/io-definitions/<feature-id>-io.md` |
| reference model | `reference-model-agent` | `fesa-reference-models` | `docs/reference-models/<feature-id>-reference-models.md` |
| 구현 계획/구현 | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd` | tests, source, implementation report |
| build/test | `build-test-executor-agent` | `fesa-cpp-msvc-tdd` | `docs/build-test-reports/<feature-id>.md` |
| correction | `correction-agent` | `fesa-cpp-msvc-tdd` | `docs/corrections/<feature-id>.md` |
| reference 비교 | `reference-verification-agent` | `fesa-reference-comparison` | `docs/reference-verifications/<feature-id>-reference-verification.md` |
| 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `docs/physics-evaluations/<feature-id>-physics-evaluation.md` |
| 배포 준비 | `release-agent` | `fesa-release-readiness` | `docs/releases/<feature-id>-release.md` |
| 1. 요구조건 | `requirement-agent` | `fesa-requirements-baseline` | `requirements.md` |
| 2. 연구 | `research-agent` | `fesa-research-evidence`, 필요 시 `fem-theory-query` | `research.md` |
| 3. 정식화 | `formulation-agent` | `fesa-formulation-spec` | `formulation.md` |
| 4. 수치 검토 + reference model 계약 | `numerical-review-agent` | `fesa-numerical-review` | `numerical-review.md`, `reference-model.md` |
| 5. I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `io.md` |
| 6. 구현 계획 + C++ 구현 + build/test + reference comparison | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd`, 계획 시 project-local `harness` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
| 7. 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `physics-evaluation.md` |
| 8. 배포 준비 | `release-agent` | `fesa-release-readiness` | `release.md` |
`correction-agent`는 정규 단계가 아니라 반복되거나 원인이 불명확한 구현 실패를 다루는
on-demand rework sub-agent다. Coordinator가 호출할 때만 `docs/<feature-id>/corrections.md`
원인, 수정과 재검증 결과를 기록하고 Implementation 단계로 반환한다.
Implementation Planning Agent는 구현 계획 요청에서 `.agents/skills/harness`를 반드시
사용한다. 먼저 여러 자기완결적 Step의 초안을 제시하고 사용자 승인을 받은 뒤에만