docs: align guidance with simplified agent and harness workflow
This commit is contained in:
KOKO\Mimi
@@ -14,7 +14,7 @@
|
||||
|
||||
- FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다.
|
||||
- 새 기능은 입력 keyword만 인식하거나 element kernel만 존재한다고 완성된 것이 아니다. Semantic model, equation system, 해법, 결과 복구, HDF5 외부 계약과 독립 검증 evidence가 하나의 추적 가능한 기능을 이뤄야 한다.
|
||||
- 설계나 구현 전에 [PRD](docs/PRD.md)의 제품 범위, [ARCHITECTURE](docs/ARCHITECTURE.md)의 소유권과 데이터 흐름, [ADR](docs/ADR.md)의 기존 결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다.
|
||||
- 설계·구현 전에 [PRD](docs/PRD.md), [ARCHITECTURE](docs/ARCHITECTURE.md), [ADR](docs/ADR.md)에서 현재 작업에 관련된 제품 범위·소유권·데이터 흐름·결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다. 같은 문맥에서 읽은 변경 없는 자료를 다시 읽지 않는다.
|
||||
- 재사용 가능한 agent, skill과 Harness는 개발 운영 인프라다. 이를 일반화해도 이 저장소가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 승인된 수치 계약은 바뀌지 않는다.
|
||||
- FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라
|
||||
Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을
|
||||
@@ -40,24 +40,24 @@
|
||||
|
||||
## 문서 기준과 Feature 관리
|
||||
|
||||
- 공통 역할·handoff·상태 전이·재시도는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 구성과 적용 경계는 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), Feature 문서 배치와 소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 기준으로 한다. 실제 skill 실행 절차는 해당 `SKILL.md`를 읽는다.
|
||||
- [HARNESS](docs/HARNESS.md)와 [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 설치·흐름 참고 문서다. 승인·역할·상태 전이는 위 agent 계약과 현재 [harness skill](.agents/skills/harness/SKILL.md), 실행 메커니즘은 선택된 설정과 현재 `scripts/` 구현에 대조한다. 오래된 설명으로 이 계약을 덮어쓰지 않으며, 구현이 승인된 제품·수치 계약을 바꿀 권한도 없다.
|
||||
- 기능별 승인 계약과 모든 agent 보고서는 `docs/<feature-id>/`에 둔다. Coordinator가 안정적인 kebab-case Feature ID를 정하고 모든 dispatch에서 같은 폴더와 revision을 사용한다. 기존 `docs/features/<feature-id>/` 자료가 있으면 자동 이동·복제하지 않고 필요한 경로와 revision을 참조한다.
|
||||
- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크나 결정을 루트 문서에 누적하지 않는다. 프로젝트 공통 지침 수정은 별도 사용자 요청으로 승인된 범위에서만 수행한다.
|
||||
- Coordinator는 새 Feature에 아래 관리 문서를 실제 요구사항으로 초기화한다. 재개 시 기존 기록을 읽고 필요한 부분만 갱신하며, 승인되지 않은 내용을 승인으로 표시하거나 후속 stage의 빈 보고서를 미리 만들지 않는다.
|
||||
- 현행 운영 결정은 [ADR-028](docs/ADR.md#adr-028), 역할·인계·실패 처리는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 적용은 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), 문서 배치·소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 따른다. 실제 절차는 필요한 `SKILL.md`와 관련 reference만 읽는다.
|
||||
- [HARNESS](docs/HARNESS.md)는 설치·설정·CLI, [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 개발·검증 흐름을 설명한다. 실행 동작은 선택된 설정과 현재 `scripts/`에 대조하며 구현이 승인된 제품·수치 계약을 바꿀 권한은 없다.
|
||||
- 지속할 계약·evidence가 필요한 Feature는 메인이 안정적인 kebab-case ID와 `docs/<feature-id>/`를 정한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
|
||||
- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크를 누적하지 않으며 공통 지침 수정은 별도 사용자 요청 범위에서 수행한다.
|
||||
- 새 Feature를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다. 각 문서는 프로젝트 AGENTS·PRD·ADR를 상대 Markdown 링크로 참조한다.
|
||||
|
||||
| Coordinator 소유 문서 | 내용과 경계 |
|
||||
| 메인 소유 문서 | 내용과 경계 |
|
||||
| --- | --- |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 산출물 경로·owner·revision·검토 상태 목록, 현재 상태 문서 링크 |
|
||||
| `PRD.md` | 사용자 요구, 범위·제외, acceptance 요약과 requirement ID별 계약 링크. 요구사항·검증 matrix 원본은 Requirement Agent의 `requirements.md` |
|
||||
| `ADR.md` | Feature 결정 ID·상태·이유·영향, 결정 owner와 승인 근거 링크 |
|
||||
| `coordination.md` | stage·outcome·next owner·contract revision, gate evidence·retry·blocker·다음 작업의 유일한 workflow 상태 원본 |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당 owner와 문서 목록. 현재 checklist는 PRD로 연결 |
|
||||
| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본이며 복잡한 상세 계약은 필요한 경우만 분리하여 연결 |
|
||||
| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거 |
|
||||
|
||||
- 관리 문서에서 실제 프로젝트 기준 문서를 상대 Markdown 링크로 연결한다. Coordinator의 목록·참조·상태 관리는 specialist 본문을 대신 작성·수정할 권한이 아니다.
|
||||
- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 모든 dispatch와 Harness step의 필수 입력에 Feature 폴더 및 그 안의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md` 경로를 명시한다.
|
||||
- 기본 보고서는 Feature ID·owner·입력 revision, 핵심 결과, evidence, 미해결 항목·handoff만 간결하게 기록한다. 긴 유도·schema·상세 분석은 같은 폴더의 `formulation-derivation.md`, `io-schema.md` 같은 상세 문서로 분리하고 상대 링크로 연결한다. 본문과 상세 문서에 같은 내용을 중복 유지하지 않는다.
|
||||
- 상세 문서는 기본 산출물과 동일 owner·Feature ID·입력 revision을 사용하며 같은 stale 판정을 받는다. 반환 `evidence_paths`에는 기본 문서와 작성·갱신하거나 판정에 사용한 상세 문서를 포함한다. Coordinator는 실제 파일과 링크를 확인하고 목록에 등록한다.
|
||||
- 소스·테스트·Harness 제어 파일·기계 생성 로그/결과·read-only reference artifact는 각각의 지정 경로에 유지하고 보고서에서 참조한다. 필수 검증을 생략했다면 미실행 사실과 이유를 남긴다.
|
||||
- 현재 checklist는 PRD 한 곳에 둔다. `requirements.md`·검증 matrix는 분리가 필요할 때만 작성하고 PRD에는 요약·링크만 유지한다. Specialist는 할당된 전문 문서만 수정한다.
|
||||
- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 메인은 필요한 Feature context와 관련 경로·절만 인계하며 모든 문서를 매번 재독하도록 요구하지 않는다.
|
||||
- 기존 `coordination.md`, `docs/features/<feature-id>/`와 phase 자료는 이력으로 보존하고 필요한 경로·계약 revision을 참조한다. 자동 이동·복제하거나 신규 coordination 상태 파일을 만들지 않는다.
|
||||
- 보고서는 결정·결과, 적용 계약, evidence와 미해결 항목을 간결하게 기록한다. 간단한 구현·build/test·reference 결과는 한 보고서로 모으고 긴 유도·schema는 같은 폴더의 상세 문서로 분리해 연결한다.
|
||||
- 실제 계약 변경은 관련 evidence의 유효성을 다시 확인한다. 의미 변화 없는 문서 편집마다 고정 handoff·hash·gate 기록을 만들지 않는다. 미실행 검사는 이유를 남기며 승인·통과로 표시하지 않는다.
|
||||
- 소스·테스트·기계 생성 로그/결과·read-only reference artifact는 지정 경로에 유지하고 보고서에서 참조한다.
|
||||
|
||||
## FESA 개발의 핵심 원칙
|
||||
|
||||
@@ -72,9 +72,9 @@
|
||||
### 소유권과 의존성
|
||||
|
||||
- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
|
||||
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
|
||||
- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
|
||||
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
|
||||
- 동작 추가·수정은 해당 동작을 확인하는 테스트로 검증한다. 버그는 가능한 경우 실패를 재현한 뒤 최소 수정한다.
|
||||
- 기존 coverage가 충분한 rename·refactor나 문서 수정에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 작업 범위에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
|
||||
- CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다.
|
||||
- CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다.
|
||||
- Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
|
||||
@@ -95,17 +95,11 @@
|
||||
|
||||
### 개발 운영 인프라
|
||||
|
||||
- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
|
||||
- Harness runner는 [scripts/execute.py](scripts/execute.py)이며 `feat-<phase-name>` branch prefix를 사용한다. 실행 전 Git top-level이 Harness root와 같아야 하고, 선택된 phase 제어 파일 allowlist 밖의 worktree는 clean이어야 한다. 관련 없는 변경을 stage하거나 숨기지 않는다.
|
||||
- Executor는 branch, 현재 pending step 선택, transport attempt, timestamp, path-scoped staging/commit과 phase 진행을 소유한다. 구현 경로와 phase metadata를 분리해 commit하며 저장소 전체를 무조건 stage하지 않는다. Implementation Agent는 선택된 step의 코드·테스트·보고서와 result payload만 갱신하며 branch/commit/push나 다른 step·제어 metadata를 변경하지 않는다.
|
||||
- Planning은 각 Step의 승인된 정확한 상대 파일 목록을 phase index의 `owned_paths`에 기록한다. 모든 pending Step은 실행 전에 목록이 필요하고 `[]`는 구현 파일 변경 없음을 뜻한다. Executor는 신뢰된 목록으로 매 시도 후·stage 전·commit 전 경로를 검사하며 rename 양쪽 경로도 승인되어야 한다. 범위 밖 변경은 보존하고 재시도·커밋·다음 Step 진행을 중단한다. 실행 중 동시 편집까지 원자적으로 격리하는 보장은 아니다.
|
||||
- Executor의 process/session transport 시도는 실제 wrapper timeout과 결과 미보고가 확인된 경우에만 최초 포함 최대 2회이며 Coordinator의 correction budget과 별개다. 비정상 종료에서도 명시적 `error/blocked`를 보존하고, 인식된 sandbox helper 환경 실패는 종료 코드 0에서도 `blocked`로 기록한다. Executor 소유 `attempt_history`는 재시도·재개 때 보존하며 구현·상위 계약·환경·물리 실패를 transport retry로 반복하지 않는다.
|
||||
- 기본 sandbox는 `FEM_HARNESS_CODEX_SANDBOX=workspace-write`다. `danger-full-access`는 동일 명령의 native sandbox 실패 증거, 해당 실행 직전 사용자의 명시적 승인, clean linked Git worktree와 `--approve-danger-full-access`가 모두 필요하다. 환경변수 설정만으로 승인되지 않는다. `--push` 등 원격 작업도 별도 명시적 승인이 필요하다.
|
||||
- Hook 연결은 [.codex/hooks.json](.codex/hooks.json), 구현은 [scripts/hooks](scripts/hooks)와 [scripts/msvc_harness](scripts/msvc_harness)에 둔다. Hook script를 수동 실행해 등록된 hook이나 검증 evidence를 대체하지 않는다.
|
||||
- PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하고 허용된 편집 경로를 기록한다. 이는 RED 실행이나 correctness의 증거가 아니다.
|
||||
- Stop은 유효한 동일 session/turn 기록에서 기록된 편집 도구의 대상이 모두 저장소 내부 `.md`일 때 build/test를 생략한다. 기록 누락·손상 또는 비문서 변경이면 정상 검증 경로를 따른다. Shell 쓰기는 이 기록이 완전히 추적하지 못하며, 편집 기록 없는 읽기 전용 계획 요청도 자동 생략을 보장하지 않는다.
|
||||
- 생략하지 않는 Stop은 `.harness/config.json` 또는 자동 감지 결과의 backend로 build/test를 검증한다. 문서 작업에서 사용자가 실행을 제외하면 수동으로 Hook·CMake·CTest 등을 실행하지 않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작하거나 생략된 검증을 통과로 보고하지 않는다.
|
||||
- `.harness/hook-state/`와 `phases/**/step*-output.json` 같은 생성 실행 기록은 ignored 상태로 유지한다.
|
||||
- 일반 specialist의 기본 추론 강도는 `medium`, 정식화·수치·물리 검토는 `high`다. 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따르고 난해한 작업에만 필요한 범위에서 높인다.
|
||||
- [scripts/execute.py](scripts/execute.py)는 명시적 build/test 실행기다. 내부 LLM·phase 상태기계·자동 Git·재시도·파일명 TDD gate·대화 종료 hook을 사용하지 않는다.
|
||||
- 설정·preset·명령은 검토할 실행 입력이다. `shell=False`·경로 검사·timeout이 모든 side effect를 격리하는 sandbox는 아니며 실제 도구 권한과 외부 실행 승인은 별도로 따른다.
|
||||
- 관련 없는 사용자 변경은 보존한다. Commit을 요청받으면 작업 경로만 stage하고 push·tag·publish 등 원격 작업은 명시적으로 승인된 범위에서 수행한다. Runner는 이 권한을 부여하거나 Git 상태를 변경하지 않는다.
|
||||
- 기존 phase·hook 생성 기록은 이력으로 보존하며 ignored 상태를 유지한다. 현재 검증을 위해 기록을 조작하거나 삭제된 hook을 수동 실행하지 않는다.
|
||||
|
||||
## 기능을 추가할 때의 판단 기준
|
||||
|
||||
@@ -118,62 +112,60 @@
|
||||
|
||||
## 개발 프로세스
|
||||
|
||||
- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다.
|
||||
- 동작 변경을 검증하는 테스트와 가능한 버그 재현을 기본으로 하며 최소 수정 후 관련 검사를 수행한다.
|
||||
- CRITICAL: 빌드 경고를 새로 추가하지 말 것.
|
||||
- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다. 문서 수정·읽기 전용 검토를 새 solver feature 전체 workflow로 확대하지 않는다.
|
||||
- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, outcome, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID의 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- 수식·요소·재료·적분·상태 갱신 변경은 독립 numerical review와 해당 analytical/invariant 검증을 수행한다. 필요한 물리·reference 검증도 유지한다.
|
||||
- 변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 필수 reference 비교를 한 번 수행한다. 사용자 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하며 이후 변경·실패가 없으면 반복하지 않는다.
|
||||
- 문서만 수정하는 작업은 링크·소스 대조·diff 정적 검토로 확인하고 build/test를 실행하지 않는다. 미실행을 통과로 보고하지 않는다.
|
||||
- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
|
||||
|
||||
## Agent/Skill Workflow
|
||||
|
||||
Solver feature workflow에서 `coordinator-agent`만 main agent로서 상태 전이와 closure를
|
||||
소유하며 다음 eligible specialist에게 한 번에 하나의 bounded task를 dispatch한다.
|
||||
Specialist는 peer를 호출하거나 다음 gate로 진행하거나 자신의 산출물을 최종 승인하지 않는다.
|
||||
Intake/coordination은 아래 정규 stage와 별도로 관리한다.
|
||||
메인 assistant가 범위를 파악하고 필요한 전문 작업만 위임하며 계획·구현·검증·결과 확인을
|
||||
조정한다. 작은 작업은 직접 수행하고 고정된 stage 순회나 별도 coordinator를 호출하지 않는다.
|
||||
|
||||
| 단계 | 담당 sub-agent | 필수 skill | 기본 보고서 (`docs/<feature-id>/`) |
|
||||
| --- | --- | --- | --- |
|
||||
| 1. `requirements` | `requirement-agent` | `fem-requirements-baseline` | `requirements.md` |
|
||||
| 2. `research` | `research-agent` | `fem-research-evidence` | `research.md` |
|
||||
| 3. `formulation` | `formulation-agent` | `fem-formulation-spec` | `formulation.md` |
|
||||
| 4. `numerical-review` | `numerical-review-agent` | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` |
|
||||
| 5. `io-definition` | `io-definition-agent` | `fem-io-contract` | `io.md` |
|
||||
| 6. `implementation-planning` | `implementation-planning-agent` | `fem-implementation-tdd`, `harness` | `implementation-plan.md` |
|
||||
| 7. `implementation` | `implementation-agent` | `fem-implementation-tdd` | `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
|
||||
| 8. `physics-evaluation` | `physics-evaluation-agent` | `fem-physics-review` | `physics-evaluation.md` |
|
||||
| 9. `release-readiness` | `release-agent` | `fem-release-readiness` | `release.md` |
|
||||
| Specialist | 호출 조건 | Skill |
|
||||
| --- | --- | --- |
|
||||
| `requirement-agent` | 복잡하거나 상충하는 scope·acceptance 정리 | `fem-requirements-baseline` |
|
||||
| `research-agent` | 부족한 이론·benchmark·reference 근거 조사 | `fem-research-evidence` |
|
||||
| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화 | `fem-formulation-spec` |
|
||||
| `numerical-review-agent` | 정식화·주요 수치 변경·수치 불일치의 독립 검토 | `fem-numerical-review` |
|
||||
| `io-definition-agent` | 입력 의미·진단·결과 schema·비교 mapping 정의 | `fem-io-contract` |
|
||||
| `implementation-agent` | 위임할 이점이 있는 구현 묶음 | `fem-implementation-tdd` |
|
||||
| `physics-evaluation-agent` | 평형·물리 타당성·coverage 평가 | `fem-physics-review` |
|
||||
|
||||
- 위 8개 lifecycle skill은 [.codex/skills](.codex/skills)에 있다. Planning은 할당된 `phases/index.json`, `phases/<phase>/index.json`, `stepN.md`도 소유하고, Implementation은 할당된 코드·테스트·build registration을 소유한다.
|
||||
- 보조 skill은 [.agents/skills/harness](.agents/skills/harness/SKILL.md)의 phase 계획·실행, [.agents/skills/review](.agents/skills/review/SKILL.md)의 읽기 전용 diff 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)의 configured FEM wiki 근거·coverage gap 조회다. `fem-theory-query`를 모든 FEM 질문에 적용하거나 workstation vault 절대 경로를 commit하지 않는다.
|
||||
- 모든 dispatch/return은 SOLVER_AGENT_DESIGN의 공통 envelope를 사용한다. Workflow outcome은 `pass | return-upstream | retry | blocked-environment | needs-user-decision`만 사용한다. Specialist outcome은 전이 요청이며 Coordinator가 실제 산출물·owner·revision·evidence를 확인한 뒤 상태를 기록한다.
|
||||
- `return-upstream`은 정확한 계약 owner로 반환하고 영향받는 downstream evidence를 stale 처리한다. Numerical Review는 formulation과 reference-model readiness, Implementation은 TDD·전체 build/test·필수 reference comparison 증거가 모두 있어야 통과한다. Release의 `pass`는 내부 readiness일 뿐 push/tag/publish/deploy/package 권한이 아니다.
|
||||
- `correction-agent`는 정규 stage가 아닌 on-demand rework다. Coordinator는 `retry_key = feature_id|failing_gate|normalized_failure_classification|contract_revision`별 correction을 최대 한 번 허용하고 이후 Implementation rerun을 한 번 dispatch한다. 같은 key가 다시 실패하면 두 번째 correction을 금지하고 계약·환경·critical decision owner로 반환한다. 문구만 바꿔 key를 새로 만들지 않으며 `corrections.md`는 실제 correction 때만 작성한다.
|
||||
- 승인된 Feature와 할당된 dispatch 안의 일반 문서·계획 파일 작성 및 bounded local 실행에는 반복적인 사용자 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않으며 Harness 실행은 해당 작업에 실행까지 할당된 경우에만 한다.
|
||||
- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명, 보안·법률 위험 수용, destructive/remote/release 작업은 SOLVER_AGENT_DESIGN의 critical decision 절차를 따른다. 권한이 필요한 실행을 일반 자율 작업으로 확대하지 않는다.
|
||||
- Harness step은 0부터 연속 번호로 나누고 각 step 안에서 `RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY`를 완료하도록 계획한다. 정확한 입력·소유 파일·명령·제외 범위·중단 조건을 명시하며 필요한 물리·schema·tolerance·reference가 없으면 해당 owner로 반환한다.
|
||||
- Harness step 상태 `pending/completed/error/blocked`는 workflow outcome과 별개다. Implementation은 선택된 step에 `completed`와 비어 있지 않은 `summary`, `error`와 `error_message`, 또는 `blocked`와 `blocked_reason`을 반환한다. Executor가 timestamp와 phase 진행을 관리하며 실패 증거를 지우고 즉시 재실행하지 않는다.
|
||||
- 메인도 `fem-implementation-tdd`로 계획·구현·일반 실패 수정을 수행할 수 있다. 전용 planning/correction profile이나 phase 파일을 요구하지 않는다.
|
||||
- `fem-release-readiness`는 사용자가 별도 감사를 명시 요청할 때만 사용한다. Readiness 권고는 외부 release 권한이 아니다.
|
||||
- [harness](.agents/skills/harness/SKILL.md)는 구성된 build/test의 명시 실행, [review](.agents/skills/review/SKILL.md)는 요청 diff의 읽기 전용 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)는 configured FEM wiki 근거·coverage gap 조회에 사용한다. Workstation vault 절대 경로를 commit하지 않는다.
|
||||
- Dispatch는 작업·관련 경로/절·수정 파일·검증 기준, return은 결과·변경 파일·검사 결과·미해결 항목으로 충분하다. 지원되는 도구에서는 `fork_turns="none"`으로 필요한 문맥만 전달하고 연속 수정은 같은 owner에게 보낸다.
|
||||
- Specialist는 할당 범위를 지키고 peer를 재위임하거나 상위 계약을 결과에 맞춰 수정하지 않는다. 계약 문제는 owner·경로·근거와 함께 메인에 전달한다. 독립 검토를 자기 승인으로 대체하지 않는다.
|
||||
- 일반 실패는 현재 구현 owner가 수정한다. 새 근거·변경 없이 같은 명령·agent 호출을 반복하지 않으며 고정 correction/transport 예산을 두지 않는다.
|
||||
- 승인된 범위의 일반 작업과 인계에 반복 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않는다.
|
||||
- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명·비용, 중대한 보안·법률 위험, destructive/remote/release 작업은 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md)의 사용자 결정 경계를 따른다.
|
||||
|
||||
## 최소 검증 진입점
|
||||
|
||||
아래 명령은 해당 구현·검증 작업에만 사용한다. 문서만 수정하는 작업의 정적 검토를 위해
|
||||
build/test를 실행하지 않는다. 실행할 명령은 승인된 step/plan에서 확인하고,
|
||||
`.harness/config.json`, preset·project metadata와 프로젝트 지침에 대조한 뒤에만 기본값을
|
||||
사용한다. Target graph, dependency normalization과 Windows runtime staging은
|
||||
ARCHITECTURE와 실제 CMake 파일을 따른다.
|
||||
아래 명령은 해당 구현·검증 작업에만 사용한다. 현재 작업, `.harness/config.json`,
|
||||
preset·project metadata와 프로젝트 기준을 대조하여 선택한다. 문서 수정에는 실행하지 않는다.
|
||||
|
||||
### Harness Python 검증
|
||||
|
||||
Harness 구현 변경에 필요한 검사는 관련 범위부터 실행하며 전체 검사가 필요할 때는 다음을 사용한다.
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
### Phase 실행
|
||||
### 구성된 전체 build/test
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase-dir>
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
`<phase-dir>`는 할당된 phase로 대체한다. `--push`는 원격 push가 명시적으로 승인된 경우에만 추가한다.
|
||||
Phase 인자나 `--push`·`--approve-danger-full-access`를 추가하지 않는다. 이 인자들은
|
||||
usage error로 거부된다. Exit 의미·설정·이전 방식 변경 안내는 [HARNESS](docs/HARNESS.md)를
|
||||
따른다. 필요한 수치/reference 검증을 runner 성공만으로 대체하지 않는다.
|
||||
|
||||
### CMake/CTest 프로젝트
|
||||
|
||||
@@ -189,7 +181,10 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1
|
||||
ctest --preset windows-msvc-ninja-debug --output-on-failure
|
||||
```
|
||||
|
||||
Hook도 이 preset을 사용하게 구성하려면 [.harness/config.example.json](.harness/config.example.json)을
|
||||
참고해 local `.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을
|
||||
함께 맞춘다. Preset 파일이 있다는 사실만으로 Stop이 해당 preset을 선택하지는 않는다.
|
||||
FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 기준으로 한다.
|
||||
Runner에도 이 preset을 적용하려면 [HARNESS](docs/HARNESS.md)의 예시에 따라 개인
|
||||
`.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을
|
||||
함께 맞춘다. 현재 [.harness/config.example.json](.harness/config.example.json)은 최소
|
||||
CMake 설정이며 preset 필드가 없다. Preset 파일이 있다는 사실만으로 runner가 이를
|
||||
선택하지 않는다. FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를
|
||||
기준으로 한다. Target graph·dependency·Windows runtime staging은 ARCHITECTURE와 실제
|
||||
CMake 파일을 따른다.
|
||||
|
||||
+66
-4
@@ -23,8 +23,9 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한
|
||||
- 현재 선택된 toolchain, 외부 형식과 구현별 계약은 [AGENTS.md](../AGENTS.md) 및 승인된
|
||||
설정·Feature 계약을 따른다. 문서 일반화만으로 이를 교체하지 않는다.
|
||||
- 기존 결정 번호는 다른 의미로 재사용하지 않는다. 후속 결정은 마지막 번호 다음으로 추가한다.
|
||||
- ADR-024~027은 현재 agent·skill·Feature 문서 운영 계약을 기록한다. 새 해석 기능이나
|
||||
외부 실행 권한을 승인하는 결정이 아니다.
|
||||
- ADR-024~027은 당시 agent·skill·Feature 문서 운영 계약의 이력이다. 현행 운영은
|
||||
[ADR-028](#adr-028)을 따른다. 대체 안내 아래의 기존 결정 본문과 그 안의 링크는
|
||||
결정 당시 설명으로 읽으며 현행 절차를 요구하는 근거로 사용하지 않는다.
|
||||
|
||||
## 프로젝트 공통 결정
|
||||
|
||||
@@ -36,7 +37,7 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한
|
||||
**이유**: 개발 자동화의 편의가 물리적 의미, 사용자 요구와 수치 검증을 대신하지 않게 한다.
|
||||
|
||||
**트레이드오프**: Solver의 완료 evidence와 자동화 자체의 correctness를 별도로 관리해야 한다.
|
||||
현재 운영 역할과 검증 범위는 ADR-024·026에서 보완한다.
|
||||
현재 운영 역할과 검증 범위는 ADR-028을 따른다.
|
||||
|
||||
### ADR-002: 구현·검증 환경은 명시된 프로젝트 baseline으로 관리한다
|
||||
|
||||
@@ -47,7 +48,7 @@ backend를 처리할 수 있다는 사실을 FESA 제품 지원으로 간주하
|
||||
**이유**: 개발 환경의 암묵적 차이가 build와 numerical regression 판정을 흐리지 않게 한다.
|
||||
|
||||
**트레이드오프**: 새 환경은 별도의 compatibility와 실행 evidence가 필요하다. 원문의
|
||||
기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-026의 구성 경계를 따른다.
|
||||
기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-028이 유지하는 구성 경계를 따른다.
|
||||
|
||||
### ADR-003: 외부 입력은 승인된 subset의 의미로 지원한다
|
||||
|
||||
@@ -133,6 +134,9 @@ pattern·scatter와 deterministic reduction을 사용한다.
|
||||
|
||||
### ADR-012: 계획, 실행과 Hook 검증의 책임을 분리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 전용 Planning/Executor/Hook 분업은 폐기한다. 실제 검증
|
||||
> evidence와 테스트 파일 존재의 구분은 유지한다. 아래 본문은 당시 결정의 이력이다.
|
||||
|
||||
**결정**: Planning은 할당된 계획 파일, Executor는 실행 상태와 Git 처리, Hook은 등록된
|
||||
guardrail과 종료 검증을 담당한다. 테스트 파일 존재는 RED 관찰의 증거가 아니다.
|
||||
|
||||
@@ -245,6 +249,9 @@ ADR-014·020의 과거 수치 정책을 대체하지만 artifact 선택·identit
|
||||
|
||||
### ADR-024: Coordinator가 evidence 기반 workflow와 유한 correction을 소유한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 전용 Coordinator·고정 상태 전이·correction/rerun 예산을
|
||||
> 폐기한다. 승인 범위의 자율 작업, 필요한 사용자 결정과 필수 evidence는 유지한다.
|
||||
|
||||
**상태**: 현재 [agent 운영 계약](SOLVER_AGENT_DESIGN.md)의 기록.
|
||||
ADR-012의 계획·실행·검증 계층을 보완하며 specialist의 계약 소유권을 변경하지 않는다.
|
||||
|
||||
@@ -264,6 +271,9 @@ Release readiness가 외부 게시나 배포 권한을 주지는 않는다.
|
||||
|
||||
### ADR-025: 프로젝트 기준과 Feature 문서의 원본·소유권을 분리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 관리 문서 4개·coordination 상태 원본·필수 requirements
|
||||
> 분리·전체 bundle 인계를 폐기한다. 프로젝트/Feature 경계, 전문 소유권과 원본 구분은 유지한다.
|
||||
|
||||
**상태**: 현재 [Feature 문서 관리](FEATURE_DOCUMENTATION.md) 계약의 기록.
|
||||
|
||||
**결정**: 프로젝트 PRD·ARCHITECTURE·ADR에는 공통 기준만 둔다. Coordinator는
|
||||
@@ -283,6 +293,9 @@ upstream 변경의 영향과 stale evidence를 추적할 수 있다.
|
||||
|
||||
### ADR-026: Harness의 구성, Git 소유권과 검증 범위를 신뢰 경계로 관리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** Executor의 자동 Git·transport·자체 sandbox 통제와 hook
|
||||
> 검증을 폐기한다. Config/command 신뢰 경계, 사용자 변경 보존과 실제 runtime 권한은 유지한다.
|
||||
|
||||
**상태**: 현재 [Harness skill](../.agents/skills/harness/SKILL.md)과
|
||||
[프로젝트 지침](../AGENTS.md)의 실행 계약 기록. ADR-002의 구체적 실행 구성과
|
||||
ADR-012의 운영 설명을 보완한다.
|
||||
@@ -312,6 +325,9 @@ PreToolUse의 파일 존재 검사는 RED evidence가 아니다. Stop의 문서
|
||||
|
||||
### ADR-027: Harness의 Step 결과와 커밋 범위를 명시적 계약으로 검증한다
|
||||
|
||||
> **실행 계약 대체 — ADR-028:** phase Step payload·owned_paths·attempt_history·자동
|
||||
> commit·transport retry는 더 이상 사용하지 않는다. 실패 증거와 사용자 변경 보존은 유지한다.
|
||||
|
||||
**상태**: 사용자 승인된 Harness 보완 계획(실패 상태 보존, 파일 소유권 검증, 환경 오류
|
||||
분류)에 따른 결정. ADR-026의 실행 경계를 보완하며 solver·Hook·sandbox 권한을 변경하지 않는다.
|
||||
|
||||
@@ -334,6 +350,52 @@ Planning은 Step마다 정확한 상대 파일 목록 `owned_paths`를 작성한
|
||||
경로 검사는 filesystem sandbox나 동시 writer에 대한 원자적 격리가 아니다. 구현·metadata
|
||||
커밋도 단일 transaction이 아니므로 뒤쪽 커밋 실패 시 앞선 커밋을 보존하고 오류로 반환한다.
|
||||
|
||||
<a id="adr-028"></a>
|
||||
|
||||
### ADR-028: 메인이 필요한 전문 작업을 조정하고 Harness를 명시적 검증 실행기로 사용한다
|
||||
|
||||
**상태**: Accepted. 2026-09-07 사용자가 승인한
|
||||
[문서 갱신 계획](superpowers/plans/2026-09-07-agent-harness-documentation-update.md)에 따라
|
||||
Agent·Harness 경량화 결정을 공통 운영 문서에 반영한다. 솔버의 제품·물리·수치·입출력
|
||||
계약과 외부 실행 권한은 변경하지 않는다.
|
||||
|
||||
**결정**:
|
||||
|
||||
- 메인 assistant가 작업 분해, 필요한 전문 작업의 위임, 구현 조정과 완료 확인을 맡는다.
|
||||
7개 specialist는 필요한 경우에만 호출한다. 고정 stage 순회와 전용
|
||||
coordinator/planning/correction/release profile은 사용하지 않는다.
|
||||
- Harness는 `python scripts/execute.py`로 구성된 build/test를 한 번 명시 실행한다.
|
||||
내부 LLM·프롬프트 주입, phase 상태기계, 자동 Git·재시도, 파일명 TDD gate와 대화 종료
|
||||
hook은 사용하지 않는다. 기존 phase와 coordination 기록은 이력으로 보존한다.
|
||||
- 동작 변경은 의미 있는 테스트로 검증하고, 버그는 가능한 경우 재현한 뒤 최소 수정한다.
|
||||
개발 중 관련 검사를 수행하며 솔버 기능 완료 시 전체 build/test와 필수 reference 비교를
|
||||
한 번 수행한다. 이후 변경·실패가 없으면 반복하지 않는다. 수식·요소·재료·적분·상태
|
||||
갱신 변경의 독립 수치 검토와 필요한 analytical/invariant·물리 검증은 유지한다.
|
||||
- 관련 입력 경로/절, 작업·수정 범위와 검증 기준만 인계하고 결과·변경 파일·검사·미해결
|
||||
항목을 간결하게 반환한다. 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`를
|
||||
기본으로 하며 난해한 작업에만 필요한 범위에서 높인다.
|
||||
- Feature를 초기화하면 메인이 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다.
|
||||
현재 checklist와 작은 요구사항의 원본은 PRD에 둔다. 필요한 상세 계약·결과만 분리하여
|
||||
연결하고 간단한 구현·build/test·reference evidence는 하나의 보고서에 기록한다.
|
||||
Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다.
|
||||
|
||||
이 결정은 ADR-012·024~027의 위에 표시한 운영 부분을 대체한다. Config·preset·실행
|
||||
command는 검토해야 할 실행 입력이며 `shell=False`나 경로 검사가 그 side effect를
|
||||
sandbox처럼 격리하지는 않는다. 사용자 변경·reference를 보존하고 미실행·실패·stale
|
||||
evidence를 통과로 표시하지 않는 원칙, 실제 도구 권한과 외부 작업의 명시적 승인은 유지한다.
|
||||
|
||||
**이유**: 반복적인 문맥 주입, 역할 전환, 형식적 보고와 중복 검증을 줄이면서 필요한
|
||||
공학적 판단과 재현 가능한 evidence에 집중한다.
|
||||
|
||||
**트레이드오프**: 고정 상태기계나 자동 Git gate가 완료·변경 범위를 강제하지 않으므로
|
||||
메인이 할당 범위, 필요한 검증과 미해결 항목을 확인한다. 명령 실패의 원인은 현재 구현
|
||||
owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.
|
||||
|
||||
역할과 호출 조건은 [Agent 운영](SOLVER_AGENT_DESIGN.md), skill 적용은
|
||||
[Skill 설계](SOLVER_SKILL_DESIGN.md), 문서 원본과 소유권은
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md), CLI·설정과 실패 진단은
|
||||
[Harness](HARNESS.md) 및 [동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
|
||||
## 후속 ADR 작성 기준
|
||||
|
||||
프로젝트 전체의 dependency 방향, 공통 identity·수명·결과 의미, 기술 baseline,
|
||||
|
||||
+32
-40
@@ -37,13 +37,13 @@ Solver runtime
|
||||
└─ numerical backend
|
||||
|
||||
개발 운영 영역
|
||||
사용자 요구 → Coordinator → 담당 specialist → 산출물과 evidence → gate 판정
|
||||
│
|
||||
└─ 할당된 계획 / Harness / 코드·테스트·문서 변경
|
||||
사용자 요구 → 메인 assistant → 필요한 전문 작업·구현 → 검증·결과 확인
|
||||
│
|
||||
└─ 명시적 Harness / 코드·테스트·문서 변경
|
||||
```
|
||||
|
||||
첫 흐름은 해석 데이터의 전달을, 두 번째는 개발 작업과 검증의 흐름을 나타낸다.
|
||||
Agent, prompt, phase 파일과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
|
||||
Agent, skill과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
|
||||
개발 운영 영역은 저장소의 변경과 검증을 통제하며 solver가 실행 중 이를 호출하지 않는다.
|
||||
|
||||
## 공통 책임과 의존성
|
||||
@@ -193,8 +193,10 @@ Diagnostic은 실패 단계, 안정된 code와 메시지, 가능한 source locat
|
||||
## 검증과 reference 경계
|
||||
|
||||
검증 coverage와 비교량의 논리적 정의는 Numerical Review, 물리량의 저장·외부 대응은
|
||||
I/O, 실행 evidence는 Implementation, 독립 물리 판단은 Physics Evaluation이 소유한다.
|
||||
각 단계는 상위 계약을 결과에 맞춰 수정하지 않는다.
|
||||
I/O, 실행 evidence는 구현 담당자, 독립 물리 판단은 Physics Evaluation의 전문 책임이다.
|
||||
메인은 작업에 필요한 전문 판단만 배정하며 고정 stage 순회를 요구하지 않는다. 수식·요소·
|
||||
재료·적분·상태 갱신 변경에는 독립 수치 검토와 해당 analytical/invariant 검증을 수행한다.
|
||||
각 담당자는 상위 계약을 결과에 맞춰 수정하지 않는다.
|
||||
|
||||
- Source identity, location과 component 일치 여부를 수치 tolerance보다 먼저 확인한다.
|
||||
- Missing, extra, duplicate와 nonfinite required value를 숨기지 않는다.
|
||||
@@ -208,50 +210,40 @@ Architecture 문서의 그림이나 모듈명이 기능의 완료 증거를 대
|
||||
|
||||
## 개발 운영 인프라
|
||||
|
||||
공통 agent 상태 전이는 [SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill의 역할은
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실제 실행 절차는
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 agent/skill profile을 읽는다.
|
||||
현행 운영은 [ADR-028](ADR.md#adr-028), 역할·인계는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill 적용은
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실행 동작은
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 source·config에 대조한다.
|
||||
|
||||
| Owner | 책임 |
|
||||
| --- | --- |
|
||||
| Coordinator | Feature 문서 목록·상태, dispatch, evidence gate, revision·retry budget과 closure |
|
||||
| Specialist | 할당된 stage의 전문 판단, 기본·상세 산출물과 공통 handoff |
|
||||
| Planning Agent | 할당된 implementation plan과 phase/index/step 계획 파일 |
|
||||
| Executor | 현재 step 선택, branch, transport attempt, timestamp, path-scoped commit과 phase 진행 |
|
||||
| Implementation Agent | 선택된 step의 코드·테스트·보고서와 result payload |
|
||||
| Hook | 도구 호출 전 guardrail과 설정된 종료 검증; TDD 관찰이나 완전한 sandbox의 대체가 아님 |
|
||||
| 메인 assistant | 범위·작업 분해, 필요한 전문 작업 배정, 직접 계획·구현·수정, Feature context와 완료 evidence 확인 |
|
||||
| Specialist | 할당된 전문 판단·파일과 간결한 결과; 상위 계약 문제를 owner와 메인에 전달 |
|
||||
| 구현 담당자 | 메인 또는 implementation-agent로서 코드·테스트·관련 검증과 필요한 reference evidence 작성 |
|
||||
| Harness runner | 명시 호출 시 config·project·toolchain 선택, adapter 계획 실행과 결과 반환 |
|
||||
| Backend adapter/process | CMake/CTest 또는 MSBuild 명령 구성, argv/cwd·timeout·실패·결과 검사 |
|
||||
|
||||
Coordinator만 workflow를 전이한다. Specialist의 outcome은 전이 요청이고, Harness의
|
||||
step 상태는 별개의 실행 상태다. Executor transport attempt는 최대 2회이며 동일
|
||||
`retry_key`의 correction 1회와 뒤따르는 Implementation rerun은 Coordinator가 관리한다.
|
||||
두 budget을 혼용하거나 실패 문구만 바꿔 반복하지 않는다.
|
||||
Runner는 내부 LLM, phase 상태기계, 자동 Git·retry, 파일명 TDD gate나 대화 종료 hook을
|
||||
사용하지 않는다. 과거 phase/coordination 기록은 이력으로 보존한다. 일반 실패는 현재
|
||||
구현 owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.
|
||||
|
||||
승인된 scope와 할당된 작업 안의 일반 계획·문서·local 실행에는 반복 승인 gate를
|
||||
추가하지 않는다. 계획 요청만으로 실행을 시작하지 않으며 외부 solver, 원격·파괴 작업과
|
||||
sandbox 권한 확대에는 해당 명시적 권한이 필요하다.
|
||||
Project config·preset·command는 검토해야 할 실행 입력이다. Repository 경로 검사,
|
||||
`shell=False`와 timeout이 실행 파일의 side effect를 모두 격리하는 sandbox는 아니다.
|
||||
사용자 변경을 보존하고 실제 도구 권한과 외부 solver·원격·파괴 작업의 명시적 승인을 따른다.
|
||||
승인된 일반 작업에 반복 승인을 추가하지 않으며 계획 요청만으로 실행을 시작하지 않는다.
|
||||
|
||||
Project config, preset과 실행 command는 검토해야 하는 실행 입력이다. Hook 통과나
|
||||
구조화된 argument list만으로 그 side effect가 격리되었다고 간주하지 않는다.
|
||||
Executor는 시작 전 선택된 phase 제어 파일 밖의 변경을 거부하며 모든 pending Step의
|
||||
Planning 소유 `owned_paths`를 검증한다. 매 시도 후와 stage/commit 경계에서 신뢰된 목록과
|
||||
변경·staged 경로를 대조하고 구현 변경과 phase metadata를 분리한다. 범위 밖 변경은
|
||||
보존하고 재시도·커밋·다음 Step을 중단한다. 이 검사는 동시 writer의 원자적 격리나 여러
|
||||
커밋의 단일 transaction을 보장하지 않는다. 실행 중 동시 편집을 피한다.
|
||||
종료 코드와 Step 보고 상태를 함께 판정하며 명시적 실패를 transport 재시도로 덮어쓰지
|
||||
않는다. 실제 wrapper timeout이고 결과 미보고일 때만 최초 포함 최대 두 번 시도한다.
|
||||
환경·실패 진단과 원래 보고는 Executor 소유 `attempt_history`에 남기고 재개 때 보존한다.
|
||||
등록된 Hook을 수동 실행하여 검증 evidence를 대신하지 않는다.
|
||||
|
||||
문서 전용 Stop 생략은 기록된 동일 session/turn의 허용된 편집 대상이 모두 저장소 내부
|
||||
Markdown인 조건에 한정된다. 기록이 없거나 불완전한 읽기 전용 작업과 shell 쓰기까지
|
||||
안전하게 분류한다고 가정하지 않는다. 생략은 build/test 통과가 아니다.
|
||||
사용자가 실행을 제외한 문서 작업은 정적 검토와 미실행 항목을 보고한다.
|
||||
변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 계약상 필수
|
||||
reference 비교를 한 번 수행한다. 요청이나 넓은 영향으로 전체 검증이 필요한 경우에도
|
||||
실행하고 이후 변경·실패가 없으면 반복하지 않는다. 문서 작업은 정적 검토로 확인한다.
|
||||
명령·exit code·판정값과 미실행 항목을 필요한 보고서에 기록하며 Harness 성공만으로
|
||||
물리·수치 correctness나 외부 release readiness를 선언하지 않는다.
|
||||
|
||||
## 문서와 아키텍처의 변경
|
||||
|
||||
프로젝트 공통 원칙의 변경은 공통 ADR로, 구현 항목별 선택은 해당 Feature ADR로
|
||||
기록한다. Feature PRD는 범위와 acceptance 요약을, requirements·formulation·I/O는
|
||||
전문 계약의 원본을 소유한다. 관리 문서와 기본·상세 산출물은
|
||||
기록한다. Feature PRD는 범위·작은 요구사항·acceptance와 현재 checklist의 원본이다.
|
||||
복잡한 requirements·formulation·I/O는 필요한 경우에만 전문 문서로 분리하고 PRD에서
|
||||
참조하여 원본을 중복하지 않는다. 메인이 관리하는 핵심 문서 3개와 선택적 상세 산출물은
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)의 소유권과 링크 규칙을 따른다.
|
||||
|
||||
Public dependency, identity, 수명, result meaning이나 lifecycle 변경은 영향받는
|
||||
|
||||
+12
-10
@@ -4,7 +4,7 @@
|
||||
|
||||
이 문서는 FESA production 및 test C++의 코드 스타일, 객체 설계, 문서화와 검증 규칙을
|
||||
정의하는 project-local source of truth다. 새 C++를 작성하거나 기존 C++를 리팩터링하는
|
||||
사람과 Implementation Agent는 작업 전에 이 문서를 읽어야 한다.
|
||||
메인 assistant와 구현 담당자는 작업에 관련된 규칙을 확인한다.
|
||||
|
||||
[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)를 baseline으로
|
||||
사용한다. 이 문서, `AGENTS.md`, 승인된 feature contract와 architecture/ADR이 Google guide의
|
||||
@@ -217,12 +217,14 @@ contract language는 현재 외부 계약을 유지한다.
|
||||
|
||||
## Test와 변경 관리
|
||||
|
||||
- Production C++ 변경은 관련 C++ test와 같은 patch에 있어야 한다.
|
||||
- Behavior 또는 interface 변경은 `RED -> observed failure -> minimal GREEN -> VERIFY`를
|
||||
따른다.
|
||||
- Production 동작·interface 변경은 해당 의미를 확인하는 테스트를 추가·수정하여 검증한다.
|
||||
- 버그는 가능한 경우 실패를 재현한 뒤 최소 수정하고 관련 검사를 실행한다. 기존 coverage가
|
||||
충분한 rename/refactor에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
- Refactoring test는 base interface 사용, ownership/lifetime, invalid combination,
|
||||
deterministic order와 current numerical result preservation을 검증한다.
|
||||
- Focused test 뒤에 full MSVC x64 Debug build와 CTest를 실행한다.
|
||||
- 개발 중에는 관련 검사를 실행하고, 솔버 기능 완료 시 full MSVC x64 Debug build와 CTest를
|
||||
한 번 수행한다. 요청이나 넓은 변경 영향으로 필요한 경우에도 실행하며 이후 변경·실패가
|
||||
없으면 반복하지 않는다. 문서만 수정할 때는 정적 검토를 수행한다.
|
||||
- B33/MITC4 output 경계를 건드린 변경은 승인된 reference comparison을 다시 실행한다.
|
||||
- Reference artifact, input path와 tolerance를 리팩터링에 맞춰 수정하지 않는다.
|
||||
- Commit은 review 가능한 module slice로 제한하고 Conventional Commits를 사용한다.
|
||||
@@ -243,14 +245,14 @@ doxygen Doxyfile
|
||||
|
||||
Generated Doxygen HTML과 tool cache/build output은 source control에 넣지 않는다.
|
||||
|
||||
## Implementation Agent Checklist
|
||||
## 구현 담당자 Checklist
|
||||
|
||||
Implementation Agent는 C++ Step을 시작하기 전에 다음을 확인한다.
|
||||
메인 또는 구현 agent는 할당된 C++ 작업 전에 다음을 확인한다.
|
||||
|
||||
- 이 문서와 feature implementation plan을 읽었다.
|
||||
- 관련 코딩 규칙·Feature 계약과 필요한 경우의 구현 계획을 확인했다.
|
||||
- 변경할 base/concrete/module owner가 승인 설계와 일치한다.
|
||||
- 관련 test file과 RED condition이 Step에 명시되어 있다.
|
||||
- 변경 동작을 확인할 검사와 가능한 버그 재현 조건을 정했다.
|
||||
- Public API naming과 production Doxygen가 이 문서에 맞는다.
|
||||
- Vendor dependency와 ownership direction이 역전되지 않는다.
|
||||
- Stable identity, numerical order, HDF5와 reference contract가 보존된다.
|
||||
- Formatting, Doxygen, focused/full MSVC/CTest acceptance command가 계획되어 있다.
|
||||
- Formatting, Doxygen와 변경 영향에 맞는 MSVC/CTest·reference 검증 범위 및 명령을 정했다.
|
||||
|
||||
@@ -1,79 +1,82 @@
|
||||
# Feature 문서 관리
|
||||
|
||||
이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
|
||||
`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
|
||||
`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.
|
||||
지속할 요구사항·계약·검증 evidence가 필요한 solver Feature에는 `docs/<feature-id>/`를
|
||||
사용한다. 메인 assistant가 안정적인 kebab-case Feature ID를 정하고 context와 문서 목록을
|
||||
관리한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
|
||||
현재 운영은 [ADR-028](ADR.md#adr-028)과 [Agent 계약](SOLVER_AGENT_DESIGN.md)을 따른다.
|
||||
|
||||
## 시작과 참조
|
||||
|
||||
1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를
|
||||
재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다.
|
||||
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용
|
||||
기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다.
|
||||
3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고
|
||||
자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는
|
||||
`AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다.
|
||||
4. 기존 `docs/features/<feature-id>/` 자료는 이력이므로 자동 이동하거나 복제하지 않는다.
|
||||
재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다.
|
||||
1. 새 Feature 폴더를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다.
|
||||
재개 시 기존 계약과 evidence를 읽고 필요한 부분만 갱신한다.
|
||||
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 일반 Feature
|
||||
작업에서 읽기 전용 기준이다. Feature 진행 링크를 공통 문서에 누적하지 않으며 공통
|
||||
지침 변경은 별도 사용자 요청 범위에서 수행한다.
|
||||
3. Specialist는 할당 작업에 관련된 Feature 문서와 원문의 절만 읽는다.
|
||||
`FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니므로 필요한 context는
|
||||
메인이 경로·절로 전달한다. 모든 인계에서 핵심 문서 3개를 재독하도록 강제하지 않는다.
|
||||
4. 기존 `docs/features/<feature-id>/`와 `coordination.md`는 이력으로 보존한다.
|
||||
자동 이동·복제하지 않고 재개에 필요한 경로·계약 revision을 참조한다.
|
||||
`coordination.md`를 새로 생성하거나 현재 상태 기록을 위해 갱신하지 않는다.
|
||||
|
||||
이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
|
||||
기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
|
||||
Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
|
||||
계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.
|
||||
Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 실제 상위 계약 문제는
|
||||
해당 owner와 메인에 evidence를 전달하고 필요한 사용자 결정을 따른다.
|
||||
|
||||
## Coordinator 관리 문서
|
||||
## 메인이 관리하는 핵심 문서
|
||||
|
||||
| 문서 | 필요한 내용 | 참조 기준 |
|
||||
| 문서 | 필요한 내용 | 프로젝트 기준 링크 |
|
||||
| --- | --- | --- |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` |
|
||||
| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 |
|
||||
| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 |
|
||||
| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당된 owner와 유용한 문서 목록. 현재 checklist는 PRD에 연결 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본, 필요한 상세 계약 링크 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거. 실제 결정이 없으면 그 사실과 적용 공통 결정 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
|
||||
- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를
|
||||
가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다.
|
||||
현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다.
|
||||
- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에
|
||||
결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로
|
||||
표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다.
|
||||
- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다.
|
||||
Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다.
|
||||
- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를
|
||||
갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다.
|
||||
- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자
|
||||
요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.
|
||||
- 현재 checklist는 PRD 한 곳에서 관리한다. 문서 목록이나 별도 파일에 같은 상태를
|
||||
중복 기록하지 않는다.
|
||||
- 작은 요구사항·acceptance는 PRD에 직접 정의한다. 복잡하여 분리할 필요가 있을 때만
|
||||
`requirements.md`나 상세 verification matrix를 작성하고 PRD에는 요약과 링크를 둔다.
|
||||
분리된 전문 계약은 할당된 owner가 소유한다.
|
||||
- 메인은 관련 반환을 확인하여 목록·링크·checklist를 갱신한다. Specialist는 할당된
|
||||
문서만 수정하며 downstream이 upstream 계약을 결과에 맞춰 변경하지 않는다.
|
||||
- 승인되지 않은 내용이나 아직 실행하지 않은 검증을 승인·완료로 표시하지 않는다.
|
||||
일반 문서 작성·업데이트를 위해 반복적인 승인 gate를 추가하지 않는다.
|
||||
- 각 핵심 문서는 실제 프로젝트 기준을 상대 Markdown 링크로 연결한다. 필요한 운영
|
||||
설명은 `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md`를 참조한다.
|
||||
|
||||
## Agent 산출물 작성
|
||||
## 필요한 상세 문서와 evidence
|
||||
|
||||
각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
|
||||
필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.
|
||||
결과를 지지하는 다음 내용만 필요한 만큼 기록한다.
|
||||
|
||||
1. 식별: Feature ID, owner, 입력 contract revision.
|
||||
2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
|
||||
3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
|
||||
4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.
|
||||
1. 해당 Feature·작업·owner와 적용 계약 또는 관련 revision.
|
||||
2. 판단·결정, 구현·검토에 필요한 정의와 주요 발견.
|
||||
3. 출처·evidence 경로, 실제 명령·exit code·결정적 측정값과 적용 기준.
|
||||
4. 가정, 미지원 범위, 미해결 항목·제한과 다음 작업에 필요한 정보.
|
||||
|
||||
상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
|
||||
수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
|
||||
분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.
|
||||
`research.md`, `formulation.md`, `io.md`, `numerical-review.md`,
|
||||
`reference-model.md`, `implementation-report.md`, `build-test.md`,
|
||||
`reference-comparison.md`, `physics-evaluation.md`는 필요한 경우의 산출물 예시다.
|
||||
간단한 구현·build/test·reference 결과는 하나의 짧은 보고서에 모을 수 있으며 같은 결과를
|
||||
여러 기본 보고서에 반복하지 않는다. Release 보고서는 명시적으로 감사를 요청한 경우에만 작성한다.
|
||||
|
||||
긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
|
||||
`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
|
||||
`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.
|
||||
긴 유도·전체 schema·mapping·검증 matrix가 필요하면 같은 폴더의
|
||||
`formulation-derivation.md`, `io-schema.md` 같은 문서로 분리하여 관련 본문에서 연결한다.
|
||||
상세 문서는 해당 전문 owner가 소유하고 적용되는 계약과 기본 문서를 명확히 연결한다.
|
||||
반환할 때 판단에 사용한 상세 evidence 경로도 포함한다. 고정 envelope나 모든 산출물의
|
||||
hash·gate 기록은 요구하지 않는다.
|
||||
|
||||
- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
|
||||
적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
|
||||
- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
|
||||
기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
|
||||
- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
|
||||
문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
|
||||
- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
|
||||
기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
|
||||
참조한다.
|
||||
짧게 쓰기 위해 필수 수식·identity·units·schema·tolerance·acceptance 정의를 없애지 않는다.
|
||||
문서만 수정할 때 원시 로그나 의미 변화 없는 revision 기록을 추가하지 않는다. 실제 계약이
|
||||
변경되면 관련 evidence가 여전히 유효한지 확인하며 과거 결과를 현재 검증으로 소급하지 않는다.
|
||||
필수 검증을 실행하지 않았다면 미실행 사실과 이유를 남긴다.
|
||||
|
||||
## Gate 확인
|
||||
소스·테스트·기계 생성 로그/결과·read-only reference artifact는 각자의 지정 경로에 유지하고
|
||||
보고서에서 참조한다. 기존 phase 이력은 새 보고서 형식에 맞추어 변경하지 않는다.
|
||||
Reference artifact와 tolerance를 구현 결과에 맞추어 수정하지 않는다.
|
||||
|
||||
Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
|
||||
판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
|
||||
필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
|
||||
검증을 대신하지 않는다.
|
||||
## 언어와 확인
|
||||
|
||||
기본 Feature 문서는 한국어 Markdown으로 작성하고 agent/skill ID, field, requirement ID,
|
||||
경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`다.
|
||||
|
||||
메인은 실제 파일·소유권·상대 링크와 판단에 필요한 evidence를 확인한다. 필수 상세 근거가
|
||||
없거나 연결이 끊겼다면 해당 owner와 해결하고 요약만으로 검증을 대신하지 않는다.
|
||||
문서 정리는 정적 검토로 확인하며 solver build나 수치/reference 검증의 통과로 보고하지 않는다.
|
||||
|
||||
+91
-117
@@ -1,84 +1,46 @@
|
||||
# Harness 운영 가이드
|
||||
|
||||
## Requirements
|
||||
## 목적과 준비 환경
|
||||
|
||||
Windows와 Codex CLI가 필요하다. Executor는 Python 3.10 이상을 사용하며, 이 저장소의
|
||||
계약 테스트는 표준 `tomllib`을 사용하므로 검증 환경은 Python 3.11 이상으로 준비한다.
|
||||
Harness는 명시적으로 호출하는 repository build/test 실행기다.
|
||||
[Agent 운영](SOLVER_AGENT_DESIGN.md)과 [Harness skill](../.agents/skills/harness/SKILL.md)에
|
||||
따라 필요한 검증을 수행하며 내부 Codex 호출, phase 관리, 자동 Git 처리와 대화 종료
|
||||
hook을 사용하지 않는다. 현재 운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다.
|
||||
|
||||
Runner에는 Windows와 Python 3.10 이상이 필요하다. 저장소의 `tomllib` 기반 Python 검사는
|
||||
Python 3.11 이상을 사용한다. Runner 자체는 Codex CLI를 필요로 하지 않는다.
|
||||
FESA는 Visual Studio의 Desktop development with C++ 워크로드, CMake/CTest와 Ninja를
|
||||
사용한다. MSVC x64 developer 환경과 dependency 경로는 [AGENTS.md](../AGENTS.md)의
|
||||
최소 검증 진입점을 따른다.
|
||||
사용한다. MSVC x64 developer 환경에서 `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`,
|
||||
`HDF5_DIR`를 설치된 dependency 경로로 설정한다. 상세 기준은
|
||||
[프로젝트 지침](../AGENTS.md)의 최소 검증 진입점을 따른다.
|
||||
|
||||
역할·승인·상태 전이는 [Agent 계약](SOLVER_AGENT_DESIGN.md)과
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)을 따른다. 이 문서는 설치·실행 참고이며
|
||||
solver Feature의 9개 stage와 evidence gate를 대신하지 않는다.
|
||||
## 명시적 실행과 설정 선택
|
||||
|
||||
## 프로젝트 자동 감지
|
||||
|
||||
프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의
|
||||
CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는
|
||||
건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는
|
||||
오류로 처리한다.
|
||||
|
||||
설정 파일은 선택 사항이다. 기본 자동 감지와 `.harness/build` 경로를 그대로 사용할
|
||||
때는 만들지 않아도 된다. 프로젝트별 override가 필요하면 다음처럼 예시를 복사한다.
|
||||
저장소 루트에서 구성된 전체 검증을 한 번 실행한다.
|
||||
|
||||
```powershell
|
||||
Copy-Item .harness/config.example.json .harness/config.json
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
승인된 Feature와 Coordinator dispatch에 따라 Planning Agent가 할당된 phase 파일을
|
||||
작성한다. 일반 계획 파일 작성에 반복 승인을 요구하지 않는다. 실행까지 할당된 경우에만
|
||||
다음 명령을 사용하며, 계획 작성 요청만으로 Executor를 시작하지 않는다.
|
||||
개발 중 focused check는 선택된 backend의 실제 명령을 직접 실행한다. 솔버 기능 완료 시
|
||||
구성된 전체 build/test와 계약상 필수 reference 비교를 수행하고 이후 변경·실패가 없으면
|
||||
반복하지 않는다. 문서만 변경하는 작업에서는 정적 검토를 하고 build/test를 실행하지 않는다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase-name>
|
||||
```
|
||||
Runner는 자신의 script 위치를 기준으로 저장소 root를 정하고 `.harness/config.json`을
|
||||
읽는다. 설정이 없으면 기본 자동 감지를 사용한다. 선택 순서는 명시한 `projectType`,
|
||||
설정된 CMake source directory의 metadata, root의 단일 `.sln`, 단일 `.vcxproj`다.
|
||||
여러 solution/project로 선택이 모호하면 명시 설정이 필요하다. C++ source 전체를
|
||||
scan하거나 metadata 없는 C++ 파일의 존재로 별도 gate를 적용하지 않는다.
|
||||
|
||||
`--push`는 해당 원격 push를 사용자가 명시적으로 승인했을 때만 추가한다. 실행 전
|
||||
Git top-level은 Harness root와 같고 선택된 phase 제어 파일 밖의 worktree는 clean이어야
|
||||
한다. 실행 중 동시 편집과 커밋 범위의 한계는 [동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
현재 [config 예시](../.harness/config.example.json)는 `projectType=cmake`와
|
||||
`cmake.sourceDir=.`만 지정한다. 개인 설정이 필요할 때 참고하되 기존 설정을 무조건
|
||||
덮어쓰지 않는다. Preset 없는 기본 binary directory는 `.harness/build`다.
|
||||
|
||||
모든 `pending` Step에는 승인된 정확한 상대 파일 목록인 `owned_paths`가 필요하다.
|
||||
누락된 기존 phase는 Planning의 할당된 준비 작업에서 목록을 보완한 뒤 실행한다.
|
||||
`[]`는 구현 파일 변경이 없음을 뜻하며 완료 이력에는 목록을 소급 추가하지 않는다.
|
||||
Executor는 실행 후와 staging/commit 경계에서 소유권을 검사하며 범위 밖 변경은
|
||||
보존하고 중단한다. 상세 schema와 제한은 [Harness skill](../.agents/skills/harness/SKILL.md)을 따른다.
|
||||
## FESA CMake preset 설정
|
||||
|
||||
Executor가 시작하는 Codex 세션은 기본적으로 `workspace-write` sandbox를 사용한다.
|
||||
Windows native sandbox에서 MSVC compiler-id의 `cl.exe`가 정지하는 것이 재현되고 같은
|
||||
명령이 sandbox 밖에서 정상 완료되는 경우에만, 사용자 승인을 받은 격리된 clean
|
||||
linked Git worktree에서 다음처럼 해당 실행에 한정해 fallback을 지정할 수 있다.
|
||||
|
||||
```powershell
|
||||
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
|
||||
python scripts/execute.py <phase-name> --approve-danger-full-access
|
||||
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
|
||||
```
|
||||
|
||||
허용값은 `workspace-write`와 `danger-full-access`뿐이다. 후자는 Codex Step에 workspace
|
||||
밖의 파일 접근 권한도 부여하므로 일반 기본값으로 설정하지 않는다. 어느 모드에서도
|
||||
`.codex/hooks.json`의 등록된 hook을 비활성화하지 않는다. 환경변수만으로 권한이 승인되지
|
||||
않으며 Executor는 승인 flag가 없거나 primary/dirty worktree인 권한 상승 실행을 거부한다.
|
||||
|
||||
Stop은 유효한 동일 session/turn 편집 기록의 대상이 모두 저장소 내부 `.md`일 때만
|
||||
build/test를 생략한다. 기록 누락·손상 또는 비문서 편집은 정상 검증 경로를 따른다.
|
||||
Shell 쓰기나 편집 기록 없는 읽기 전용 요청도 자동 생략을 보장하지 않는다. 문서 작업에서
|
||||
사용자가 실행을 제외하면 수동으로 Hook·build/test를 실행하지 않고 미검증 사실을 보고한다.
|
||||
|
||||
## Harness Python 검증
|
||||
|
||||
이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
|
||||
다음 명령으로 실행한다.
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
## CMake preset 설정
|
||||
|
||||
`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
|
||||
`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
|
||||
지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
|
||||
FESA의 현재 [CMakePresets.json](../CMakePresets.json)을 사용하려면 다음 필드를
|
||||
`.harness/config.json`에 함께 지정한다. Preset 파일의 존재나 config 예시 복사만으로
|
||||
Runner가 preset 이름을 선택하지는 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -94,6 +56,9 @@ uv run --with pytest python -B -m pytest -v -rs
|
||||
}
|
||||
```
|
||||
|
||||
`configurePreset`, `buildPreset`, `testPreset`, `binaryDir`는 함께 지정해야 한다.
|
||||
이에 대응하는 backend 명령은 다음과 같다.
|
||||
|
||||
```powershell
|
||||
cmake --preset windows-msvc-ninja-debug
|
||||
cmake --build --preset windows-msvc-ninja-debug
|
||||
@@ -101,10 +66,8 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1
|
||||
ctest --preset windows-msvc-ninja-debug --output-on-failure
|
||||
```
|
||||
|
||||
위 예시는 현재 [CMakePresets.json](../CMakePresets.json)과
|
||||
[config 예시](../.harness/config.example.json)에 맞춘다. Preset 파일이 존재하는 것만으로
|
||||
Stop이 그 preset을 선택하지는 않는다. 아래는 preset을 쓰지 않는 adapter의 명령 형태이며,
|
||||
FESA에서는 dependency 경로와 승인된 build 구성을 함께 확인한다.
|
||||
아래는 preset 없는 CMake adapter의 기본 명령 형태다. FESA에서는 승인된 MSVC x64 Debug
|
||||
구성과 dependency 경로를 함께 확인한다.
|
||||
|
||||
```powershell
|
||||
cmake -S . -B .harness/build -A x64
|
||||
@@ -113,14 +76,14 @@ ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Runner는 configure 후 MSVC compiler metadata를 확인하고 CTest discovery가 0개이면
|
||||
실패로 처리한다. Build/test 성공이 물리·수치 correctness나 별도 필수 reference 비교의
|
||||
통과를 대신하지 않는다. Runner는 Feature 문서에서 추가 비교 명령을 추론하지 않는다.
|
||||
|
||||
## 직접 MSBuild 설정
|
||||
|
||||
다음은 재사용 가능한 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며
|
||||
이 예시로 solution-only MSBuild 검증을 대체 승인하지 않는다.
|
||||
|
||||
`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
|
||||
지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
|
||||
파일과 인수를 JSON 배열로 적는다.
|
||||
다음은 재사용 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며
|
||||
solution-only MSBuild를 승인된 대체 검증으로 간주하지 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -135,46 +98,57 @@ ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
}
|
||||
```
|
||||
|
||||
`msbuild.testCommand`는 필수 argv 배열이며 실행 파일은 repository-relative 경로로
|
||||
지정한다. 선택한 solution/project를 build한 뒤 testCommand를 한 번 실행한다.
|
||||
|
||||
## 결과와 실패 진단
|
||||
|
||||
| 상황 | Runner 결과 |
|
||||
| --- | --- |
|
||||
| 구성된 build/test와 결과 검사가 모두 성공 | exit 0, 명령·cwd·exit code와 test 출력 요약 |
|
||||
| 잘못된 config, 모호한 감지, toolchain/adapter 오류, backend 실패·timeout | exit 1 |
|
||||
| 명시한 projectType의 metadata가 없음 | exit 1 |
|
||||
| Non-MSVC compiler 또는 CTest 0개/잘못된 discovery 결과 | exit 1 |
|
||||
| 자동 감지에서 CMake/MSBuild metadata가 없음 | `not configured`, exit 2 |
|
||||
| 지원하지 않는 CLI 인자 | usage error, exit 2; 검증 미시작 |
|
||||
|
||||
Backend nonzero는 실패 진단에 원래 값으로 남지만 runner의 반환값은 1이다.
|
||||
대상 부재나 미실행을 검증 통과로 표시하지 않는다. 실패 시 stage, argv, cwd와 가능한
|
||||
출력 tail을 확인한다. 실패 후 자동 재시도나 후속 단계를 실행하지 않는다.
|
||||
|
||||
- Visual Studio 도구가 없으면 C++ workload와 설치 경로를 확인한다.
|
||||
- Solution/project 선택이 모호하면 `projectType`, `msbuild.solution`을 명시한다.
|
||||
- Compiler가 MSVC가 아니면 선택된 환경과 toolchain 설정을 확인한다.
|
||||
- CTest가 0개이면 `enable_testing()`과 테스트 등록을 확인한다.
|
||||
- MSBuild test command가 없으면 실제 테스트 실행 파일과 인수를 설정한다.
|
||||
- Timeout·실패 원인은 현재 구현 owner가 수정한다. 새 근거나 변경 없이 반복 실행하지 않는다.
|
||||
|
||||
Runner 전체 deadline은 config·discovery·toolchain 탐색을 포함해 1,800초다. 각 명령에는
|
||||
남은 전체 시간과 명령별 timeout 중 짧은 값을 적용한다. 실행·검사 경계는
|
||||
[동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
|
||||
## 이전 운영 방식에서 달라진 점
|
||||
|
||||
옛 `python scripts/execute.py <phase>` 호출과 `--push`,
|
||||
`--approve-danger-full-access` 인자는 usage error로 거부한다. Phase import나 상태
|
||||
migration은 제공하지 않으며 기존 `phases/` 기록을 읽거나 수정하지 않는다.
|
||||
|
||||
Legacy `tdd` config는 설정 로드 때 폐기 안내를 한 번 출력하고 무시한다.
|
||||
`testRoots`·`testPatterns`·`exclude`에 의한 대응 파일명 gate는 없다. 개인 config는
|
||||
자동 수정하지 않으므로 사용자가 필요할 때 해당 항목을 제거할 수 있다.
|
||||
|
||||
전용 phase executor, 자동 branch/commit/push·retry, PreToolUse/Stop과 자체 sandbox 승인
|
||||
환경변수는 사용하지 않는다. Git 상태를 변경하거나 commit할 권한은 runner 실행에서
|
||||
생기지 않는다. Config·preset·명령은 검토할 실행 입력이며 `shell=False`와 경로 검사는
|
||||
완전한 sandbox가 아니다. 실제 도구 권한과 외부 실행의 명시적 승인 경계는 유지한다.
|
||||
|
||||
## Harness Python 검증
|
||||
|
||||
Harness 구현을 변경하여 Python 검증이 필요할 때 다음 명령을 사용한다. 개발 중에는
|
||||
관련 검사만 선택하고 전체 검사가 필요한 최종 변경 후 한 번 실행한다.
|
||||
|
||||
```powershell
|
||||
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
|
||||
.\build\tests\Debug\MyProjectTests.exe
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
## TDD 확장
|
||||
|
||||
`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다
|
||||
`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은
|
||||
기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를
|
||||
대체하지 않고 추가한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"tdd": {
|
||||
"testRoots": ["tests", "integration-tests"],
|
||||
"testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
|
||||
"exclude": ["legacy/generated/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 실패 복구
|
||||
|
||||
Executor는 명시적 `error/blocked`를 비정상 종료에서도 보존하며 자동 재시도하지 않는다.
|
||||
인식된 sandbox helper 환경 오류는 종료 코드 0에서도 Step과 상위 phase를 `blocked`로
|
||||
기록한다. 실제 wrapper timeout으로 결과를 받지 못했을 때만 최초 포함 최대 두 번 시도한다.
|
||||
원인 미분류 nonzero와 `completed`/nonzero 불일치는 `error`다. 환경 차단은 종료 코드 2,
|
||||
일반 실패는 1이며 preflight 실패는 branch/state 변경 전에 반환한다.
|
||||
|
||||
- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
|
||||
- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다.
|
||||
- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
|
||||
- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다.
|
||||
- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다.
|
||||
- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리,
|
||||
종료 코드와 출력 tail을 확인한다. 실행이 할당된 범위에서만 재현 명령을 수행하며
|
||||
문서 작업의 검증 제외 지시를 덮어쓰지 않는다. Stop은 별도의 빌드 로그 파일을 만들지 않는다.
|
||||
- 실패 분류와 재시작 결정은 Coordinator가 기록한다. Planning Agent는 명시적으로 할당된
|
||||
복구 작업에서만 현재 실패 Step의 status를 `pending`으로 바꾸고, Executor가 재시작 시
|
||||
오래된 outcome 필드와 timestamp를 정리하되 `attempt_history`는 보존한다. 실패 evidence를 먼저 보존하며
|
||||
상세 절차는 [Harness skill](../.agents/skills/harness/SKILL.md)의 Recovery and handoff를 따른다.
|
||||
실제 검사 결과와 미실행 항목을 구분해 보고한다. 문서만 갱신할 때는 이 명령을 실행하지 않는다.
|
||||
|
||||
+80
-664
@@ -1,693 +1,109 @@
|
||||
# Harness Framework 동작 과정
|
||||
# Harness 동작 과정
|
||||
|
||||
이 문서는 자연어 요구사항을 받은 뒤 Harness Framework가 계획을 만들고, 독립된
|
||||
Codex 세션에서 Step을 실행하고, MSVC로 C++ 프로젝트를 검증하는 전체 과정을
|
||||
설명한다. 설치 및 설정 예시는 [Harness 운영 가이드](HARNESS.md)를 참고한다.
|
||||
## 개발 작업과 명시적 검증
|
||||
|
||||
Feature의 9개 정규 stage와 Coordinator의 gate 전이는
|
||||
[Agent 계약](SOLVER_AGENT_DESIGN.md), 역할별 절차는
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md), 문서 소유권은
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다. Harness는 그중 할당된
|
||||
구현 계획·Step 실행을 지원하며, solver workflow 전체를 대신하지 않는다.
|
||||
|
||||
## 1. 핵심 구조
|
||||
|
||||
Harness Framework는 다음 세 계층으로 구성된다.
|
||||
|
||||
1. **계획 계층**: 승인된 요구사항과 Coordinator dispatch를 실행 가능한 Step으로 변환한다.
|
||||
2. **실행 계층**: Step Executor가 Step마다 독립 Codex 세션을 실행하고 상태와 Git
|
||||
커밋을 관리한다.
|
||||
3. **검증 계층**: PreToolUse 훅이 편집 전 정책을 검사하고, Stop 훅이 종료 전 MSVC
|
||||
빌드와 테스트를 실행한다. 유효한 문서 전용 편집 기록이면 조건부로 생략한다.
|
||||
|
||||
전체 흐름은 다음과 같다.
|
||||
메인 assistant가 관련 계약과 변경 범위를 확인하고 필요한 전문 작업만 위임한다.
|
||||
현재 역할과 사용자 결정 경계는 [Agent 운영](SOLVER_AGENT_DESIGN.md),
|
||||
문서 관리는 [Feature 문서 관리](FEATURE_DOCUMENTATION.md),
|
||||
운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다.
|
||||
|
||||
```text
|
||||
사용자 요구사항
|
||||
↓
|
||||
Feature의 선행 계약·gate 확인
|
||||
↓
|
||||
Coordinator의 bounded Planning dispatch
|
||||
↓
|
||||
Planning Agent의 자기완결적 Step 작성
|
||||
↓
|
||||
phases/index.json, task index, stepN.md 생성
|
||||
↓
|
||||
실행까지 할당된 경우 Step Executor 시작
|
||||
↓
|
||||
각 Step을 독립 Codex 세션에서 실행
|
||||
├─ 도구 호출 전: PreToolUse 정책 검사
|
||||
└─ 응답 종료 전: Stop 검증 또는 문서 전용 조건부 생략
|
||||
↓
|
||||
성공: 커밋 후 다음 Step
|
||||
transport 실패: 최초 포함 최대 2회 시도
|
||||
구현 실패·차단: Coordinator로 반환
|
||||
관련 계약·현재 evidence 확인 → 변경 → 관련 test/build → 결과 확인
|
||||
│
|
||||
└─ 기능 완료 시 전체 build/test·필수 reference 비교
|
||||
```
|
||||
|
||||
자연어 요구사항이나 계획 요청만으로 Executor가 자동 시작되지는 않는다. 승인된 Feature와
|
||||
dispatch 안의 일반 계획 파일 작성·할당된 실행에 반복 승인 gate를 추가하지 않는다.
|
||||
권한 상승, 원격·파괴 작업, licensed reference solver 실행은 별도 명시적 승인이 필요하다.
|
||||
동작 변경에는 해당 의미를 확인하는 테스트를 추가·수정한다. 버그는 가능한 경우 실패를
|
||||
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적인
|
||||
새 테스트를 요구하지 않는다. 계획·소스·테스트·evidence는 할당된 범위 안에서 변경한다.
|
||||
|
||||
## 2. 요구사항 탐색과 구체화
|
||||
개발 중 focused check는 실제 configured backend 명령으로 수행한다.
|
||||
`python scripts/execute.py`는 구성된 전체 build/test를 한 번 실행한다. 사용자가 요청하거나
|
||||
넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되, 이후 변경·실패가 없으면 반복하지
|
||||
않는다. 계획 작성만 요청받은 경우에는 실행하지 않는다.
|
||||
|
||||
예를 들어 사용자가 다음 요구사항을 전달했다고 가정한다.
|
||||
## 변경 종류별 검증
|
||||
|
||||
아래 Calculator 예시는 Harness Step 구조를 설명하기 위한 것으로 FESA 제품 요구사항이나
|
||||
새 기능 구현 지시가 아니다.
|
||||
| 작업 | 수행할 작업과 확인 |
|
||||
| --- | --- |
|
||||
| 문서 수정 | 관련 문서·소스·링크·diff 정적 확인. Solver build, 새 테스트, 별도 specialist 호출을 의무화하지 않음 |
|
||||
| 일반 구현 버그 | 메인 또는 기존 구현 owner가 가능한 실패 재현 → 최소 수정 → 관련 검사. 변경 영향·기능 완료 조건에 따라 전체 검증 |
|
||||
| 새 수치 기능 | 필요한 요구·정식화·I/O 정의, 독립 numerical review → 구현·관련 테스트 → 전체 build/test와 필수 analytical/invariant·물리·reference 검증 |
|
||||
|
||||
> CMake 기반 C++20 라이브러리에 `divide()` 함수를 추가하고, 0으로 나누면 예외를
|
||||
> 발생시키며 GoogleTest 테스트를 작성한다.
|
||||
수식·요소·재료·적분·상태 갱신 변경에는 독립 numerical review를 수행한다. 물리/수치
|
||||
검증은 각 계약에 따라 수행하며 역할이나 보고서 수를 줄였다는 이유로 생략하지 않는다.
|
||||
Release-readiness 감사는 명시적으로 요청할 때만 수행한다.
|
||||
|
||||
계획을 작성하기 전에 다음 자료를 확인한다.
|
||||
## Runner의 실행 순서
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/PRD.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/ADR.md`
|
||||
- Coordinator dispatch와 `docs/<feature-id>/`의 승인된 선행 계약
|
||||
- 해당 Feature의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`
|
||||
- 관련 제품 코드와 테스트
|
||||
- `.harness/config.json`이 있으면 그 설정, 없으면 preset·metadata·프로젝트 지침과 감지 기본값
|
||||
[Runner](../scripts/execute.py)는 자신의 경로에서 저장소 root를 정한 뒤 아래를 수행한다.
|
||||
|
||||
이 탐색을 통해 다음 조건을 구체화한다.
|
||||
1. [Config](../scripts/msvc_harness/config.py)를 읽고 타입·허용 field·경로·preset 조합을 확인한다.
|
||||
2. [Discovery](../scripts/msvc_harness/discovery.py)가 명시된 projectType 또는 CMake/MSBuild metadata로 backend를 선택한다.
|
||||
3. [Toolchain](../scripts/msvc_harness/toolchain.py)이 필요한 Visual Studio/MSBuild·CMake/CTest 도구를 찾는다.
|
||||
4. 선택된 adapter가 argv·cwd·stage·timeout·결과 검사를 포함한 검증 계획을 만든다.
|
||||
5. [Process](../scripts/msvc_harness/process.py)가 명령을 순서대로 실행하고 각 결과를 검사한다.
|
||||
6. 성공 시 실행한 명령·cwd·exit code와 test 출력 요약을 반환한다. 실패 시 원인 진단과 nonzero를 반환한다.
|
||||
|
||||
- 사용하는 MSVC toolset과 C++ 표준
|
||||
- CMake 프로젝트인지 Visual Studio solution/project인지
|
||||
- 테스트 프레임워크와 테스트 실행 방법
|
||||
- public header와 implementation의 의존성 방향
|
||||
- 수정할 모듈과 범위 밖 항목
|
||||
- 실행 가능한 Acceptance Criteria 명령
|
||||
여기서 검증 계획은 backend 명령 목록이다. Feature phase/index/step 파일이나 LLM
|
||||
프롬프트가 아니다. Runner는 Git branch·HEAD·index를 관리하거나 Feature 문서를
|
||||
해석해 추가 명령을 생성하지 않는다.
|
||||
|
||||
필수 계약이 없으면 Coordinator를 통해 해당 owner로 반환한다. 예외 타입, 수치 타입,
|
||||
public API·ABI처럼 승인된 의미를 바꾸는 선택은 critical decision 기준에 따라 사용자에게
|
||||
올린다. 이미 승인된 계약 안의 파일 배치나 테스트 분해는 담당자가 결정한다.
|
||||
### Backend별 실행
|
||||
|
||||
## 3. 요구사항을 Step으로 분해
|
||||
| Backend | 실행과 결과 검사 |
|
||||
| --- | --- |
|
||||
| CMake/CTest | configure → compiler metadata의 MSVC 확인 → build → CTest JSON discovery/0개 거부 → test |
|
||||
| MSBuild | 선택된 solution/project build → 명시된 repository-relative testCommand 실행 |
|
||||
|
||||
사용자가 구현 계획 작성을 요청하면 요구사항을 작은 Step으로 나눈다. Step 설계
|
||||
규칙은 [Harness Workflow](../.agents/skills/harness/SKILL.md)에 정의되어 있다.
|
||||
FESA는 CMake/MSVC x64/Debug와 CTest를 제품 검증 기준으로 사용한다.
|
||||
MSBuild adapter가 있다는 사실이 solution-only 검증을 대체 승인하지 않는다.
|
||||
Preset 선택과 정확한 명령·설정 예시는 [Harness 운영 가이드](HARNESS.md)를 따른다.
|
||||
|
||||
각 Step은 다음 조건을 만족해야 한다.
|
||||
## 실행 경계와 실패 처리
|
||||
|
||||
- 하나의 모듈 또는 명확한 한 가지 책임만 다룬다.
|
||||
- 다른 대화 내용을 참조하지 않아도 실행할 수 있도록 자기완결적으로 작성한다.
|
||||
- 먼저 읽을 문서와 이전 Step의 관련 파일을 명시한다.
|
||||
- Feature 관리 문서와 승인된 선행 계약의 정확한 경로·revision을 명시한다.
|
||||
- 클래스와 함수 시그니처 수준으로 작업 범위를 설명한다.
|
||||
- 수정할 소스·테스트·보고서 파일과 수정하지 않을 upstream 파일을 명시한다.
|
||||
- 실제 실행 가능한 빌드·테스트 명령을 Acceptance Criteria로 사용한다.
|
||||
- 성공, 오류, 사용자 개입 필요 상태의 판정 기준을 적는다.
|
||||
- 범위 밖 기능과 기존 테스트 회귀를 명시적으로 금지한다.
|
||||
Config의 경로와 명령 cwd는 repository 범위 안인지 확인한다. MSBuild testCommand의
|
||||
실행 파일도 repository-relative 경로여야 한다. Subprocess는 argv 배열과 `shell=False`로
|
||||
실행하며 stdout/stderr를 수집한다. Config·preset·실행 파일 자체의 side effect까지 격리하는
|
||||
sandbox는 아니므로 실제 실행 입력과 도구 권한을 확인한다.
|
||||
|
||||
예시 Step은 다음과 같은 내용을 포함할 수 있다.
|
||||
전체 deadline은 시작부터 1,800초다. 각 명령의 timeout은 남은 전체 시간과 명령별 제한 중
|
||||
짧은 값이며, 실행 전 남은 시간이 없으면 실패한다. Backend nonzero, timeout, MSVC 확인
|
||||
실패나 CTest 0개 등 결과 검사 실패가 발생하면 후속 단계를 실행하지 않는다.
|
||||
|
||||
```text
|
||||
Step 0: division-api
|
||||
명령 실패 진단에는 stage·argv·cwd, 가능한 원래 exit code와 출력 tail이 포함된다.
|
||||
현재 구현 owner가 원인을 확인하고 필요한 수정 또는 환경 조치 후 관련 검사를 수행한다.
|
||||
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않으며 자동 transport retry나
|
||||
별도 correction 예산은 없다.
|
||||
|
||||
읽어야 할 파일
|
||||
- AGENTS.md
|
||||
- include/calculator.hpp
|
||||
- src/calculator.cpp
|
||||
- tests/calculator_test.cpp
|
||||
Runner는 성공 시 exit 0, config/toolchain/backend 등 실행 실패 시 exit 1을 반환한다.
|
||||
자동 감지에서 metadata가 없거나 CLI 인자가 잘못되면 exit 2다. 명시된 projectType에 필요한
|
||||
metadata가 없는 경우는 exit 1이다. Backend 원래 nonzero와 runner exit를 구분한다.
|
||||
전체 목록은 [결과와 실패 진단](HARNESS.md#결과와-실패-진단)을 참조한다.
|
||||
|
||||
작업
|
||||
- divide(double lhs, double rhs)의 실패 테스트를 먼저 추가한다.
|
||||
- rhs가 0이면 std::invalid_argument가 발생하도록 최소 구현한다.
|
||||
## 수치 evidence와 완료 확인
|
||||
|
||||
Acceptance Criteria
|
||||
- CMake/MSBuild 빌드가 성공한다.
|
||||
- 전체 테스트가 성공한다.
|
||||
- 새로운 컴파일러 경고가 없다.
|
||||
```
|
||||
Harness 성공은 build/test 실행 결과다. 필요한 reference comparison을 자동 탐색하거나
|
||||
솔버 correctness 전체를 판정하지 않는다. 메인·구현 담당자는 계약이 요구하는 다음
|
||||
검증을 별도로 확인한다.
|
||||
|
||||
### TDD와 Step 경계
|
||||
- Unit·coordinate·부호·DOF/component·source identity와 결과 위치의 일치
|
||||
- Analytical solution, invariant·equilibrium·energy·convergence 등 적용되는 검증
|
||||
- Missing·extra·duplicate·nonfinite required row를 tolerance 전에 거부하는 비교
|
||||
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature의 비교량·판정 구분
|
||||
- Trial/committed state·실패 보존·결정론과 필요한 독립 물리 판단
|
||||
|
||||
프로젝트 규칙은 실패하는 테스트를 먼저 요구하지만 Stop 훅은 Codex가 Step을 종료할
|
||||
때 전체 테스트 성공을 요구한다. 따라서 다음처럼 실패 상태를 Step 사이에 남겨둘 수
|
||||
없다.
|
||||
Reference artifact와 tolerance를 통과에 맞춰 수정하지 않는다. 명령·exit code와 결정적
|
||||
판정값은 필요한 보고서에 한 번 기록하고 원시 로그는 원본 경로로 연결한다. 실패·미실행·
|
||||
stale evidence와 미해결 항목을 명확히 남기며 검사를 생략한 사실을 통과로 보고하지 않는다.
|
||||
|
||||
```text
|
||||
Step 0: 실패하는 테스트만 추가하고 종료
|
||||
Step 1: 제품 코드를 구현해 테스트 통과
|
||||
```
|
||||
## 과거 phase·hook·Git 처리
|
||||
|
||||
실제 red-green 순서는 하나의 Codex 실행 안에서 완료되어야 한다.
|
||||
현재 runner는 내부 Codex 세션, phase 상태기계·result payload, `owned_paths`·
|
||||
`attempt_history`, 자동 branch/commit/push, PreToolUse/Stop을 사용하지 않는다.
|
||||
`coordination.md`와 기존 phase·hook 기록은 이력으로 보존하고 새 실행 입력으로 만들지 않는다.
|
||||
|
||||
```text
|
||||
테스트 작성
|
||||
→ 테스트 실패 확인
|
||||
→ 최소 제품 코드 구현
|
||||
→ 테스트 성공 확인
|
||||
→ Step 종료
|
||||
```
|
||||
|
||||
즉, 테스트가 구현보다 먼저 작성되는 순서는 지키되 각 Step은 최종적으로 green
|
||||
상태여야 한다.
|
||||
|
||||
## 4. 할당된 계획 산출물
|
||||
|
||||
Planning Agent는 Coordinator가 할당한 다음 파일을 생성한다. 기존 산출물을 재개할 때는
|
||||
덮어쓰지 않고 승인된 변경 범위만 갱신한다. Step 번호는 0부터 연속으로 둔다.
|
||||
|
||||
```text
|
||||
phases/
|
||||
├── index.json
|
||||
└── add-division/
|
||||
├── index.json
|
||||
├── step0.md
|
||||
├── step1.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 4.1 Top-level index
|
||||
|
||||
`phases/index.json`은 여러 task의 상태를 관리한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": [
|
||||
{
|
||||
"dir": "add-division",
|
||||
"status": "pending"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Task index
|
||||
|
||||
`phases/add-division/index.json`은 task 내부 Step의 상태를 관리한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "Calculator",
|
||||
"phase": "add-division",
|
||||
"steps": [
|
||||
{
|
||||
"step": 0,
|
||||
"name": "division-api",
|
||||
"status": "pending",
|
||||
"owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
상태별 기록은 다음과 같이 나뉜다.
|
||||
|
||||
`owned_paths`는 Planning이 작성하는 정확한 저장소 상대 파일 목록이다. Step 본문의 소유
|
||||
파일과 일치해야 하며 source/header/test/build/report를 필요한 만큼 명시한다. 디렉터리,
|
||||
glob, 절대 경로, 경로 이탈, Git 내부와 `phases/` 제어 경로는 허용하지 않는다. 연결된
|
||||
파일·디렉터리 경로도 지원하지 않는다. `[]`는 구현 파일 변경 없음이며 누락과 다르다.
|
||||
기존 완료 Step은 필드 없이 읽을 수 있지만 모든 pending Step은 실행 전에 목록이 필요하다.
|
||||
기존 phase를 일괄 변환하거나 Markdown에서 파일 권한을 자동 추출하지 않는다.
|
||||
|
||||
| 상태 | Codex가 기록 | Executor가 기록 |
|
||||
|---|---|---|
|
||||
| `completed` | `summary` | `completed_at` |
|
||||
| `error` | `error_message` | `failed_at` |
|
||||
| `blocked` | `blocked_reason` | `blocked_at` |
|
||||
|
||||
Executor는 task의 `created_at`과 Step의 `started_at`, `attempt_history`도 기록한다.
|
||||
History에는 단조 증가하는 `attempt`, `recorded_at`, `exit_code`(프로세스 미기동은 null),
|
||||
`reported_status`, `reported_reason`, 로컬 `classification`·판정 `reason`과 `diagnostic`을 보존한다.
|
||||
진단은 stderr 우선, 없으면 stdout의 마지막 4,000자이며 raw output 전체의 대체가 아니다.
|
||||
Implementation은 `owned_paths`·history·timestamp를 수정할 수 없다. `summary`는 다음
|
||||
독립 Codex 세션이 이전 Step의 핵심 산출물과 결정을 이해할 수 있도록 한 줄로
|
||||
작성한다.
|
||||
|
||||
### 4.3 Step 파일
|
||||
|
||||
각 `stepN.md`에는 다음 내용이 들어간다.
|
||||
|
||||
- 읽어야 할 파일
|
||||
- 작업 범위와 인터페이스
|
||||
- 핵심 동작 및 불변 조건
|
||||
- Acceptance Criteria 명령
|
||||
- 아키텍처·ADR·CRITICAL 규칙 확인 절차
|
||||
- 성공, 오류, 차단 상태 기록 방법
|
||||
- 범위 밖 변경 금지사항
|
||||
|
||||
Step은 독립 Codex 실행의 전체 작업 지시서이므로 이전 대화만 참조하는 표현을 넣지
|
||||
않는다.
|
||||
|
||||
## 5. Step Executor 시작
|
||||
|
||||
계획 파일이 준비되고 실행까지 할당된 경우 다음 명령으로 실행한다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py add-division
|
||||
```
|
||||
|
||||
완료된 브랜치의 원격 push를 사용자가 명시적으로 승인한 경우에만 `--push`를 추가한다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py add-division --push
|
||||
```
|
||||
|
||||
[Step Executor](../scripts/execute.py)는 시작할 때 다음 작업을 수행한다.
|
||||
|
||||
1. phase 경로와 top-level/phase index schema, Step 번호·이름·상태를 검사한다.
|
||||
2. 현재 첫 미완료 Step이 `error` 또는 `blocked`이면 복구 결정 전까지 중단한다.
|
||||
3. 모든 pending Step의 `owned_paths`, Implementation Agent profile, Git top-level,
|
||||
sandbox 승인 조건과 clean 상태를 검사한다.
|
||||
기본 모드는 선택된 phase 제어 파일 allowlist 밖의 변경을 허용하지 않는다.
|
||||
4. `feat-{phase-name}` 브랜치를 생성하거나 checkout한다.
|
||||
5. `AGENTS.md`와 `docs/*.md`를 guardrail로 읽는다.
|
||||
6. task/Step timestamp와 재개 상태를 정리하고 첫 번째 `pending` Step부터 순차 실행한다.
|
||||
|
||||
`AGENTS.md`와 모든 `docs/*.md` 내용은 각 Codex 프롬프트에 직접 삽입된다. 따라서
|
||||
이 문서들도 실행 입력에 포함된다. 역할·승인·상태 전이에서는 Agent 계약과 Harness skill의
|
||||
권한 경계를 따르며, 설치 예시를 Feature의 요구사항으로 사용하지 않는다. Feature 관리
|
||||
문서는 자동으로 로드되지 않으므로 dispatch와 Step의 필수 입력 경로에 명시해야 한다.
|
||||
|
||||
## 6. Step마다 독립 Codex 세션 실행
|
||||
|
||||
Executor는 각 Step을 다음 형태의 독립 프로세스로 실행한다.
|
||||
|
||||
```text
|
||||
codex exec
|
||||
--disable unified_exec
|
||||
--json
|
||||
--model <implementation-agent profile model>
|
||||
--config model_reasoning_effort="<profile effort>"
|
||||
--sandbox <workspace-write|danger-full-access>
|
||||
--dangerously-bypass-hook-trust
|
||||
--cd <repository-root>
|
||||
-
|
||||
```
|
||||
|
||||
기본값은 `workspace-write`다. `FEM_HARNESS_CODEX_SANDBOX` 환경 변수는
|
||||
`workspace-write` 또는 `danger-full-access`만 허용한다. Windows native sandbox에서
|
||||
MSVC compiler-id의 `cl.exe` 정지가 재현되고 동일 명령이 sandbox 밖에서 통과하는
|
||||
환경에서는, 해당 실행 직전 사용자 승인을 받은 clean linked Git worktree 실행에 한해서
|
||||
`danger-full-access` fallback을 사용할 수 있다. Executor의
|
||||
`--approve-danger-full-access` flag도 필요하며 환경변수만으로 승인되지 않는다.
|
||||
이 override는 등록된 hook을 비활성화하지 않는다.
|
||||
|
||||
Codex에 전달하는 프롬프트는 다음 내용의 조합이다.
|
||||
|
||||
```text
|
||||
Implementation Agent profile의 역할·수정 경계
|
||||
+ AGENTS.md와 docs 문서
|
||||
+ 이전에 완료된 Step의 summary
|
||||
+ 이전 시도의 오류(재시도인 경우)
|
||||
+ Executor 공통 작업 규칙
|
||||
+ 현재 stepN.md
|
||||
```
|
||||
|
||||
이전 Step의 전체 대화나 Codex 세션은 전달하지 않는다. task index에 기록한
|
||||
`summary`만 다음 Step에 누적한다.
|
||||
|
||||
Codex 실행 결과의 exit code, stdout, stderr는 다음 파일에 저장한다.
|
||||
|
||||
```text
|
||||
phases/{task-name}/step{N}-output.json
|
||||
```
|
||||
|
||||
## 7. 도구 호출 전 PreToolUse 검사
|
||||
|
||||
[`.codex/hooks.json`](../.codex/hooks.json)은 shell 및 파일 편집 도구에
|
||||
[PreToolUse 훅](../scripts/hooks/pre_tool_use.py)을 등록한다. Codex가 실제 명령이나
|
||||
편집을 수행하기 전에 이 훅이 요청을 검사한다.
|
||||
|
||||
### 7.1 위험 명령 차단
|
||||
|
||||
다음 유형의 명령은 요구사항과 관계없이 차단한다.
|
||||
|
||||
- `git reset --hard`
|
||||
- `git push --force` 또는 `--force-with-lease`
|
||||
- `rm -rf`
|
||||
- `Remove-Item -Recurse -Force`
|
||||
- `rmdir /s /q`
|
||||
- `DROP TABLE`
|
||||
|
||||
위험 패턴이 발견되면 훅은 차단 이유를 stderr로 출력하고 종료 코드 2를 반환한다.
|
||||
그러면 해당 도구 호출은 실행되지 않는다.
|
||||
|
||||
### 7.2 C++ TDD 검사
|
||||
|
||||
`apply_patch`, `Edit`, `MultiEdit`, `Write`로 다음 C/C++ 확장자의 파일을 편집하려
|
||||
하면 [TDD 정책](../scripts/msvc_harness/tdd_policy.py)을 검사한다.
|
||||
|
||||
```text
|
||||
.c .cc .cpp .cxx .h .hpp .hxx
|
||||
```
|
||||
|
||||
일반 제품 코드를 수정하려면 대응되는 테스트 파일이 먼저 존재해야 한다. 예를 들어
|
||||
`src/calculator.cpp`의 기본 대응 테스트 이름은 다음과 같다.
|
||||
|
||||
```text
|
||||
calculator_test.cpp
|
||||
calculator_tests.cpp
|
||||
test_calculator.cpp
|
||||
calculator.test.cpp
|
||||
```
|
||||
|
||||
테스트는 다음 위치에서 검색한다.
|
||||
|
||||
- `.harness/config.json`의 `tdd.testRoots`
|
||||
- 제품 파일과 같은 디렉터리 아래 `tests/`
|
||||
- 제품 파일과 같은 디렉터리 아래 `test/`
|
||||
|
||||
다음 파일과 디렉터리는 대응 테스트 존재 검사가 면제된다.
|
||||
|
||||
- 테스트 파일 자체
|
||||
- `main.cpp`
|
||||
- `.harness/build/**`, `build/**`, `out/**`
|
||||
- `cmake-build-*/**`
|
||||
- `third_party/**`, `external/**`, `vendor/**`
|
||||
- `generated/**`
|
||||
- `tdd.exclude`에 추가한 경로
|
||||
|
||||
`tdd.exclude`는 기본 제외 항목을 대체하지 않고 추가한다.
|
||||
|
||||
### 7.3 TDD 검사가 보장하는 범위
|
||||
|
||||
현재 TDD 훅이 직접 보장하는 것은 대응되는 이름의 테스트 파일이 존재한다는
|
||||
사실이다. 다음 항목까지 증명하지는 않는다.
|
||||
|
||||
- 테스트가 이번 요구사항을 실제로 검증하는가
|
||||
- 구현 전에 테스트가 실제로 실패했는가
|
||||
- 테스트의 assertion과 경계 조건이 충분한가
|
||||
- 기존 테스트 파일을 이번 변경과 함께 수정했는가
|
||||
|
||||
또한 shell 명령의 리다이렉션 등으로 C++ 파일을 쓰는 경우 shell 위험 패턴 검사는
|
||||
적용되지만 경로 기반 TDD 검사는 적용되지 않는다. 따라서 이 훅은 완전한 TDD
|
||||
증명기가 아니라 테스트 우선 편집을 유도하는 guardrail이다.
|
||||
|
||||
PreToolUse는 허용된 편집 도구의 대상 경로를 `.harness/hook-state/`에 기록한다.
|
||||
이 ignored 기록은 Stop의 문서 전용 판정 입력일 뿐 RED나 실제 편집 성공의 증거가 아니다.
|
||||
|
||||
## 8. Codex 종료 전 Stop 검증
|
||||
|
||||
Codex가 Step 작업을 끝내고 응답을 종료하려 하면
|
||||
[Stop 훅](../scripts/hooks/stop_validation.py)이 실행된다. 유효한 동일 session/turn 기록에서
|
||||
편집 대상이 모두 저장소 내부 `.md`이면 build/test를 생략한다. 기록 누락·손상 또는 비문서
|
||||
편집이면 정상 검증 경로에서 발견된 C/C++ 프로젝트 전체를 빌드하고 테스트한다.
|
||||
|
||||
Shell 쓰기는 완전히 추적되지 않으며, 편집 기록 없는 읽기 전용 요청도 자동 생략을
|
||||
보장하지 않는다. 사용자가 문서 작업의 실행을 제외하면 수동 Hook·build/test를 실행하지
|
||||
않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작해 생략을 만들지 않는다.
|
||||
|
||||
### 8.1 저장소 루트와 재진입 방지
|
||||
|
||||
Stop 훅은 `git rev-parse --show-toplevel`로 프로젝트 루트를 결정한다. Git 저장소를
|
||||
찾을 수 없으면 현재 디렉터리를 사용한다.
|
||||
|
||||
빌드나 테스트의 자식 프로세스에는 `CODEX_STOP_VALIDATION_ACTIVE=1`을 전달한다.
|
||||
같은 훅이 자식 프로세스에서 다시 진입하면 즉시 성공 처리하여 검증 재귀를 막는다.
|
||||
|
||||
### 8.2 설정 로드
|
||||
|
||||
[설정 로더](../scripts/msvc_harness/config.py)는 `.harness/config.json`을 읽는다.
|
||||
파일이 없으면 다음 기본값을 사용한다.
|
||||
|
||||
- `version`: 1
|
||||
- `projectType`: `auto`
|
||||
- CMake source: 저장소 루트
|
||||
- preset 미사용 시 binary directory: `.harness/build`
|
||||
- configuration: `Debug`
|
||||
- platform: `x64`
|
||||
- 테스트 루트: `tests`, `test`
|
||||
- 기본 테스트 이름 패턴 네 개
|
||||
|
||||
설정은 다음 조건을 엄격하게 검사한다.
|
||||
|
||||
- 알 수 없는 필드를 거부한다.
|
||||
- `version`은 숫자 1만 허용한다.
|
||||
- `projectType`은 `auto`, `cmake`, `msbuild`만 허용한다.
|
||||
- 저장소 상대 경로만 허용한다.
|
||||
- 저장소 밖으로 해석되는 경로를 거부한다.
|
||||
- CMake preset을 사용하면 `configurePreset`, `buildPreset`, `testPreset`,
|
||||
`binaryDir`를 모두 요구한다.
|
||||
- 모든 `tdd.testPatterns`에 `{stem}`을 요구한다.
|
||||
|
||||
### 8.3 프로젝트 자동 감지
|
||||
|
||||
[프로젝트 탐색기](../scripts/msvc_harness/discovery.py)는 다음 순서로 프로젝트를
|
||||
선택한다.
|
||||
|
||||
1. `projectType: cmake` 또는 `projectType: msbuild` 명시 설정
|
||||
2. 루트의 `CMakePresets.json`
|
||||
3. 루트의 `CMakeUserPresets.json`
|
||||
4. 루트의 `CMakeLists.txt`
|
||||
5. 루트의 단일 `.sln`
|
||||
6. 루트의 단일 `.vcxproj`
|
||||
|
||||
자동 감지 결과는 다음처럼 처리한다.
|
||||
|
||||
| 저장소 상태 | 결과 |
|
||||
|---|---|
|
||||
| CMake metadata가 있음 | CMake 프로젝트 선택 |
|
||||
| 하나의 `.sln` 또는 `.vcxproj`가 있음 | MSBuild 프로젝트 선택 |
|
||||
| 여러 solution/project가 있음 | 설정으로 하나를 지정하라는 오류 |
|
||||
| C/C++ 파일과 build metadata가 모두 없음 | 검증할 프로젝트가 없으므로 통과 |
|
||||
| C/C++ 파일은 있지만 build metadata가 없음 | orphan C++ 프로젝트 오류 |
|
||||
|
||||
### 8.4 MSVC 도구 탐색
|
||||
|
||||
[도구 탐색기](../scripts/msvc_harness/toolchain.py)는 `vswhere.exe`로 다음을
|
||||
확인한다.
|
||||
|
||||
- Visual Studio 설치 경로
|
||||
- Desktop development with C++ workload
|
||||
- `MSBuild.exe`
|
||||
|
||||
CMake 프로젝트에서는 다음 우선순위로 CMake와 CTest를 선택한다.
|
||||
|
||||
1. PATH에서 발견한 독립 `cmake.exe`와 `ctest.exe`
|
||||
2. Visual Studio에 번들된 CMake와 CTest
|
||||
|
||||
따라서 새로 설치한 CMake의 `bin` 디렉터리가 PATH에 반영되어 있으면 독립 CMake를
|
||||
우선 사용한다.
|
||||
|
||||
## 9. 빌드 시스템별 검증 계획
|
||||
|
||||
### 9.1 CMake preset 미사용
|
||||
|
||||
[CMake adapter](../scripts/msvc_harness/adapters/cmake.py)는 다음 검증 계획을 만든다.
|
||||
|
||||
```powershell
|
||||
cmake -S <source> -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
|
||||
```
|
||||
|
||||
명령 성공 외에 다음 결과도 검사한다.
|
||||
|
||||
- 생성된 CMake compiler metadata의 `CMAKE_CXX_COMPILER_ID`가 `MSVC`인가
|
||||
- CTest JSON에 한 개 이상의 테스트가 있는가
|
||||
|
||||
따라서 빌드가 성공해도 MinGW 등 다른 컴파일러를 사용했거나 CTest가 테스트를 한
|
||||
개도 발견하지 못하면 실패한다.
|
||||
|
||||
### 9.2 CMake preset 사용
|
||||
|
||||
`.harness/config.json`에 preset을 완전히 지정하면 다음 형태로 실행한다.
|
||||
|
||||
```powershell
|
||||
cmake --preset <configurePreset>
|
||||
cmake --build --preset <buildPreset>
|
||||
ctest --preset <testPreset> --show-only=json-v1
|
||||
ctest --preset <testPreset> --output-on-failure
|
||||
```
|
||||
|
||||
이 경우 모든 명령은 `cmake.sourceDir`에서 실행하고 compiler metadata 검사는 설정한
|
||||
`binaryDir`에서 수행한다.
|
||||
|
||||
### 9.3 직접 MSBuild
|
||||
|
||||
[MSBuild adapter](../scripts/msvc_harness/adapters/msbuild.py)는 다음 순서로 실행한다.
|
||||
|
||||
```powershell
|
||||
MSBuild.exe <solution-or-vcxproj> /m /nologo `
|
||||
/p:Configuration=<configuration> `
|
||||
/p:Platform=<platform>
|
||||
|
||||
<msbuild.testCommand>
|
||||
```
|
||||
|
||||
직접 MSBuild 프로젝트는 표준 테스트 탐색 명령이 없으므로
|
||||
`.harness/config.json`의 `msbuild.testCommand`가 반드시 필요하다. 이 값이 없으면
|
||||
Stop 검증이 실패한다.
|
||||
|
||||
## 10. 명령 실행 안전성과 제한시간
|
||||
|
||||
[검증 실행기](../scripts/msvc_harness/process.py)는 다음 안전 규칙을 적용한다.
|
||||
|
||||
- 명령을 shell 문자열이 아닌 argv 배열로 실행한다.
|
||||
- `shell=False`를 사용한다.
|
||||
- 각 명령의 working directory가 저장소 내부인지 검사한다.
|
||||
- 명령별 제한시간과 Stop 전체 제한시간 중 더 짧은 값을 적용한다.
|
||||
- 종료 코드가 0이 아니면 즉시 해당 stage를 실패 처리한다.
|
||||
|
||||
Stop 훅의 전체 제한시간은 저장소 탐색, toolchain 탐색, configure, build, test discovery,
|
||||
test를 모두 포함해 1,800초다. `.codex/hooks.json`의 Stop command timeout도 1,800초다.
|
||||
|
||||
실패 메시지에는 다음 진단 정보를 포함한다.
|
||||
|
||||
- 실패 stage
|
||||
- 안전하게 표현한 argv 배열
|
||||
- working directory
|
||||
- 종료 코드
|
||||
- stdout과 stderr의 마지막 8,000자
|
||||
|
||||
Harness는 별도 빌드 로그 파일을 생성하지 않는다.
|
||||
|
||||
## 11. 성공, 실패, 차단 처리
|
||||
|
||||
### 11.1 Stop 검증 성공
|
||||
|
||||
빌드와 테스트가 모두 성공하거나 문서 전용 생략 조건을 충족하면 Stop 훅은 출력 없이
|
||||
종료한다. 생략은 build/test 통과 evidence가 아니다. Codex가 정상 종료하면 Executor는
|
||||
branch/HEAD, 제어 파일과 현재 Step 외 상태의 변경 여부를 검사하고 task index를 읽는다.
|
||||
Codex 종료 코드가 0이 아니면 `completed` 기록만으로 성공 처리하지 않는다.
|
||||
|
||||
Codex가 Step을 다음처럼 기록한 경우:
|
||||
|
||||
```json
|
||||
{
|
||||
"step": 0,
|
||||
"name": "division-api",
|
||||
"status": "completed",
|
||||
"owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"],
|
||||
"summary": "divide API와 0 나누기 테스트를 추가함"
|
||||
}
|
||||
```
|
||||
|
||||
Executor는 `completed_at`을 기록하고 변경사항을 커밋한 뒤 다음 `pending` Step을
|
||||
실행한다.
|
||||
|
||||
### 11.2 Stop 검증 실패
|
||||
|
||||
Stop 훅은 Codex hook protocol에 따라 다음 형태의 응답을 출력한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": "build failed ..."
|
||||
}
|
||||
```
|
||||
|
||||
훅 자체의 종료 코드는 0이지만 `decision: block`이 종료 차단 이유를 전달한다.
|
||||
수정은 할당된 역할·Step·retry budget 안에서만 수행하며, Hook 실패가 상위 계약 변경이나
|
||||
무제한 반복 권한을 주지 않는다.
|
||||
|
||||
### 11.3 Executor 재시도
|
||||
|
||||
Executor는 branch/HEAD·제어 파일·결과 형식과 변경 경로의 소유권을 먼저 검증한 뒤
|
||||
Step 보고와 프로세스 종료 코드를 함께 판정한다.
|
||||
|
||||
| 결과 | 처리 | 자동 재시도 |
|
||||
| --- | --- | --- |
|
||||
| 인식된 sandbox helper 환경 오류(종료 코드 무관), CLI 미설치 | Step과 상위 phase `blocked`, 종료 2 | 없음 |
|
||||
| 명시적 `blocked` 또는 `error`(종료 코드 무관) | 원래 사유 보존, 각각 종료 2 또는 1 | 없음 |
|
||||
| `completed` + 종료 0 | 소유권·staged 경로 검증 후 커밋 | 없음 |
|
||||
| `completed` + nonzero | `error`, 종료 1 | 없음 |
|
||||
| 결과 미보고 + Executor wrapper의 실제 `TimeoutExpired` | transport timeout | 최초 포함 최대 2회 |
|
||||
| 결과 미보고 + 종료 0, 원인 미분류 nonzero | `error`, 종료 1 | 없음 |
|
||||
|
||||
종료 코드 124만으로 timeout을 추정하지 않는다. Wrapper가 실제 timeout을 관찰했을 때만
|
||||
raw output에 `transportFailure: "timeout"`을 기록한다. 제어·소유권 위반은 이 재시도보다
|
||||
우선하여 중단한다. 실패 결과를 `pending`으로 덮어쓰지 않고 원래 보고와 프로세스 진단을
|
||||
Executor 소유 history에 구분해 남긴다.
|
||||
|
||||
```text
|
||||
첫 번째 transport 시도 실패
|
||||
→ 오류를 다음 프롬프트에 삽입
|
||||
→ 두 번째 독립 Codex 실행
|
||||
→ 두 번째도 실패하면 error 기록 후 종료
|
||||
```
|
||||
|
||||
Coordinator의 workflow correction은 별도 budget이다. 정규화된
|
||||
`feature_id|failing_gate|failure_classification|contract_revision`별로 Correction을 최대
|
||||
한 번, 그 뒤 Implementation rerun을 한 번만 허용한다. 계약·환경·물리 실패를 transport
|
||||
재시도로 숨기거나 문구만 바꾸어 새 retry key를 만들지 않는다.
|
||||
|
||||
### 11.4 사용자 개입 필요
|
||||
|
||||
인증, API 키, 수동 설치처럼 Codex가 자동으로 해결할 수 없는 문제가 있으면 Step을
|
||||
`blocked`로 기록한다. Executor는 `blocked_at`과 top-level 상태를 갱신하고 종료 코드
|
||||
2로 중단한다.
|
||||
|
||||
재개 전 Coordinator가 원인 분류, 실패 evidence, retry key와 허용된 다음 작업을
|
||||
`coordination.md`에 보존한다. Coordinator는 phase 파일을 직접 편집하지 않는다.
|
||||
명시적으로 할당받은 Planning Agent가 Executor가 중단된 상태에서 phase index의 현재
|
||||
실패/차단 Step status만 `pending`으로 변경한다. 다른 Step, top-level 상태와 timestamp는
|
||||
변경하지 않는다. Executor가 재시작 시 오래된 outcome 필드·timestamp를 정리하되
|
||||
`attempt_history`는 유지한다. 기존 Step에 `owned_paths`가 없으면 승인 목록을 작성하는
|
||||
별도 Planning 할당이 필요하며 status 복구 권한만으로 목록을 추가·확대하지 않는다.
|
||||
이는 할당된 파일 편집 절차이며 자동 복구 명령이나 추가 correction 허용이 아니다.
|
||||
|
||||
## 12. Git 커밋과 phase 완료
|
||||
|
||||
Step이 성공하면 제품 변경과 Harness metadata를 분리해 다음 형식으로 커밋한다.
|
||||
|
||||
```text
|
||||
feat(add-division): step 0 - division-api
|
||||
chore(add-division): step 0 output
|
||||
```
|
||||
|
||||
두 번째 커밋의 `output`은 task index의 Step 상태와 summary 같은 Harness metadata를
|
||||
뜻한다. 원시 Codex 실행 기록인 `stepN-output.json`은 `.gitignore` 대상이며 커밋에
|
||||
포함되지 않는다.
|
||||
|
||||
모든 Step이 완료되면 Executor는 다음 작업을 수행한다.
|
||||
|
||||
- task의 `completed_at` 기록
|
||||
- `phases/index.json`의 task 상태를 `completed`로 변경
|
||||
- 최종 metadata 커밋
|
||||
- `--push` 사용 시 `origin/feat-{phase-name}`으로 push
|
||||
|
||||
Executor는 신뢰된 `owned_paths` snapshot으로 매 시도 후와 staging 직전의 변경 경로를
|
||||
검사한다. tracked/untracked, staged/unstaged, 생성·수정·삭제와 rename 양쪽 경로가 대상이다.
|
||||
Windows 경로 구분자·대소문자 alias를 정규화하며 디렉터리·링크 대체도 다시 검사한다.
|
||||
범위 밖 변경이 있으면 index를 정리하기 전에 중단하고 해당 경로와 사용자 파일을 보존한다.
|
||||
|
||||
검사 후 검증된 경로 snapshot에 한정해 index만 정리하고
|
||||
`git --literal-pathspecs add -A -- <선택 경로>`를 사용한다. 저장소 전체 index를 reset하지 않는다.
|
||||
Commit 직전에는 `git diff --cached --name-only --no-renames -z`의 실제 staged 경로도
|
||||
선택된 커밋 그룹과 대조한다. 구현 커밋에 phase metadata가 섞이는 것도 거부한다.
|
||||
범위 위반 시 추가 stage/commit·재시도·다음 Step을 중단하며 파일을 되돌리거나 allowlist를
|
||||
자동 확대하지 않는다. staging 후 발견한 위반은 당시 index를 남기므로 재개 전 검토가 필요하다.
|
||||
|
||||
동시 writer에 대한 원자적 격리는 보장하지 않으므로 실행 중 동시 편집을 피한다. 구현·metadata
|
||||
커밋도 단일 transaction이 아니다. 구현 커밋 후 metadata 커밋이 실패하면 기존 커밋을
|
||||
되돌리지 않고 Step을 `error`로 기록해 Coordinator에 반환한다.
|
||||
|
||||
## 13. 요구사항 종류별 동작
|
||||
|
||||
| 받은 요구사항 또는 변경 | PreToolUse 동작 | Stop 동작 |
|
||||
|---|---|---|
|
||||
| 새 C++ 제품 파일 추가 | 대응 테스트가 먼저 없으면 차단 | 전체 빌드·테스트 |
|
||||
| 기존 C++ 구현 또는 header 수정 | 대응 테스트 파일 존재 여부 검사 | 전체 빌드·테스트 |
|
||||
| 테스트 파일 추가 | TDD 차단 없이 허용 | 모든 테스트가 성공해야 종료 |
|
||||
| `main.cpp` 수정 | TDD 대응 테스트 검사 면제 | 전체 빌드·테스트 |
|
||||
| 유효한 동일 session/turn 기록의 내부 `.md` 편집만 있음 | C++ TDD 검사 없이 경로 기록 | build/test 생략, 통과 evidence 아님 |
|
||||
| JSON, Python 또는 다른 비문서 편집 | C++ TDD 검사 없음 | C++ 프로젝트가 있으면 전체 검증 |
|
||||
| 편집 기록 없음·손상 또는 shell 쓰기 | 완전한 편집 추적을 보장하지 않음 | 문서 전용 자동 생략을 보장하지 않음 |
|
||||
| 위험한 Git 또는 삭제 명령 | 즉시 차단 | 도달하지 않음 |
|
||||
| C++ 파일은 있지만 build metadata 없음 | 편집은 허용될 수 있음 | orphan 프로젝트 오류 |
|
||||
| 직접 MSBuild인데 `testCommand` 없음 | 편집은 허용될 수 있음 | 설정 오류로 종료 차단 |
|
||||
| C/C++가 전혀 없는 저장소 | 관련 편집 검사 없음 | 검증할 프로젝트가 없어 통과 |
|
||||
|
||||
## 14. 적용 전 준비사항
|
||||
|
||||
FESA는 실제 구조해석 솔버 프로젝트이며 Harness는 재사용 가능한 개발 운영 인프라다.
|
||||
일반 Feature 실행 전에 다음을 확인한다.
|
||||
|
||||
1. `AGENTS.md`, 공통 PRD·ARCHITECTURE·ADR와 승인된 Feature 범위를 읽는다.
|
||||
2. Feature 관리 문서·선행 계약·revision과 Planning/Implementation dispatch를 확인한다.
|
||||
일반 Feature 작업에서 프로젝트 공통 문서를 템플릿처럼 다시 작성하지 않는다.
|
||||
3. 기본 자동 감지로 충분하지 않을 때만 `.harness/config.example.json`을 참고해
|
||||
`.harness/config.json`을 만든다.
|
||||
4. FESA의 CMake/MSVC x64 Debug·CTest 명령과 dependency 경로를 확인한다. 다른 저장소에
|
||||
Harness를 적용할 때만 그 프로젝트의 승인된 adapter를 선택한다.
|
||||
5. phase 파일이 없다면 Planning Agent가 할당된 파일을 작성한다. 실행 권한은 별도로 확인한다.
|
||||
6. 시작 전 clean 범위와 실행 중 동시 편집 여부를 확인한다. 권한 상승은 clean linked
|
||||
worktree, native sandbox 실패 증거와 해당 실행 직전 승인·flag가 모두 필요하다.
|
||||
|
||||
특히 `AGENTS.md`와 `docs/*.md`는 각 Codex 실행에 그대로 주입된다. C++ 프로젝트에서
|
||||
TypeScript 예시나 미완성 placeholder가 남아 있으면 실제 작업 지시와 충돌할 수 있다.
|
||||
옛 phase/push/권한 상승 CLI와 legacy `tdd` 설정의 처리는
|
||||
[이전 운영 방식 안내](HARNESS.md#이전-운영-방식에서-달라진-점)를 따른다.
|
||||
사용자 config와 이력을 자동 migration하거나 실패 evidence를 지우지 않는다.
|
||||
로컬 검증은 commit·push·tag·release 또는 외부 solver 실행 권한을 부여하지 않는다.
|
||||
|
||||
+19
-16
@@ -41,15 +41,15 @@ Harness와 agent·skill은 이 목표를 달성하기 위한 개발 운영 인
|
||||
| 이 PRD | 제품 목적, 공통 요구사항, 품질 속성과 완료 기준 |
|
||||
| [ARCHITECTURE](ARCHITECTURE.md) | 공통 책임, 의존성, 수명과 확장 경계 |
|
||||
| [ADR](ADR.md) | 프로젝트 전반의 설계 결정과 변경 이력 |
|
||||
| Feature `PRD.md` | 해당 요구의 목적·범위·제외·acceptance 요약과 상세 요구사항 링크 |
|
||||
| Feature `requirements.md` | Requirement Agent가 소유하는 검증 가능한 요구사항과 verification matrix |
|
||||
| Feature `PRD.md` | 목적·범위·제외, 작은 요구사항·acceptance의 원본, 현재 checklist와 상세 계약 링크 |
|
||||
| Feature `requirements.md` | 복잡한 요구사항을 분리할 때만 작성하는 상세 요구사항과 verification matrix |
|
||||
| Feature `ADR.md` | 해당 Feature의 결정·이유·영향·owner와 승인 근거 |
|
||||
| Feature 전문 산출물 | 연구, 정식화, 수치/reference 검토, I/O, 구현·검증, 물리 검토와 release evidence |
|
||||
|
||||
Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분리는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. Feature PRD가
|
||||
`requirements.md`와 별도의 요구사항 원본을 만들거나 공통 기준을 묵시적으로 덮어쓰지 않는다.
|
||||
공통 기준 자체의 변경은 별도로 승인된 프로젝트 문서 작업으로 다룬다.
|
||||
Feature 문서의 생성·재개, 메인이 관리하는 핵심 문서 3개와 선택적 상세 문서는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 작은 요구사항은 Feature
|
||||
PRD에 정의하고, 상세 요구사항을 분리하면 PRD에는 요약과 링크만 남겨 원본을 중복하지 않는다.
|
||||
공통 기준을 묵시적으로 덮어쓰지 않으며 기준 자체의 변경은 별도로 승인된 문서 작업으로 다룬다.
|
||||
|
||||
## 공통 기능 요구사항
|
||||
|
||||
@@ -69,9 +69,9 @@ Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분
|
||||
| FESA-PRD-GEN-007 | 결과의 물리량, location, units, coordinates, component, entity와 step/frame 의미를 식별할 수 있어야 한다. | I/O·result schema 계약과 mapping 검증 |
|
||||
| FESA-PRD-GEN-008 | 실패한 candidate가 유효한 state나 최종 결과를 부분적으로 오염시키지 않도록 계약된 보존 범위를 지켜야 한다. | State commit·복구·출력 실패 검증 |
|
||||
| FESA-PRD-GEN-009 | 외부 형식과 vendor/OS API를 adapter 뒤에 격리하고 solver core에 노출하지 않아야 한다. | Public dependency와 adapter 경계 검토 |
|
||||
| FESA-PRD-GEN-010 | Production 동작 변경은 관련 테스트의 기대 실패를 관찰한 뒤 구현하고 지정된 검증 evidence를 남겨야 한다. | RED/GREEN, focused/full 검증 명령과 실제 결과 |
|
||||
| FESA-PRD-GEN-010 | Production 동작 변경은 해당 동작을 확인하는 테스트로 검증하고, 버그는 가능한 경우 실패를 재현한 뒤 최소 수정해야 한다. | 변경 영향에 맞는 검사, 가능한 버그 재현, 기능 완료 시 전체 검증 명령과 실제 결과 |
|
||||
| FESA-PRD-GEN-011 | 기능에 필요한 독립 검증과 reference 비교를 수행하고 승인된 identity·수치 정책을 유지해야 한다. | 검증 matrix, 사전검사, reference 또는 명시적 N/A와 대체 근거 |
|
||||
| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 요구사항부터 물리 검토·release readiness까지의 gate 기록 |
|
||||
| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 해당 계약을 지지하는 검증 결과, 적용 범위·제한과 미해결 항목 |
|
||||
|
||||
요구사항 단계는 acceptance intent와 필요한 물리적 관찰을 정한다. Numerical Review는
|
||||
기존 승인 정책 안에서 논리적 비교량·identity/component·판정 구분을 구체화하고, I/O는 이를
|
||||
@@ -109,19 +109,22 @@ unit, analytical/benchmark, integration, convergence, invariant 및 외부 refer
|
||||
- 실패·미실행·stale evidence를 통과로 표시하지 않는다. 과거 통과 기록을 현재 검증으로
|
||||
소급 적용하지 않는다.
|
||||
|
||||
정규 Feature workflow는 다음과 같다.
|
||||
메인 assistant가 범위를 파악하고 필요한 전문 작업을 선택하여 구현·검증·결과 확인을
|
||||
조정한다. 수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review와
|
||||
해당 analytical/invariant 검증을 수행한다. 필요한 물리 검토와 reference 비교도 유지한다.
|
||||
|
||||
`requirements → research → formulation → numerical-review → io-definition →
|
||||
implementation-planning → implementation → physics-evaluation → release-readiness`
|
||||
변경 중에는 관련 검사를 수행하고, 솔버 기능 완료 시 구성된 전체 build/test와 계약상 필수
|
||||
reference 비교를 한 번 수행한다. 요청되거나 영향이 넓어 전체 검증이 필요한 경우에도
|
||||
실행한다. 이후 변경·실패가 없으면 같은 검증을 반복하지 않는다. 기존 coverage가 충분한
|
||||
rename/refactor에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
|
||||
구현 gate는 TDD, 지정된 전체 build/test와 필수 reference evidence가 갖추어졌을 때
|
||||
통과한다. Feature closure에는 그 뒤의 독립 물리 검토와 release-readiness 감사도 필요하다.
|
||||
Release readiness는 내부 완료 권고이며 외부 publish, push, tag, deploy 또는 package 권한이 아니다.
|
||||
Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다. Readiness 권고는
|
||||
외부 publish, push, tag, deploy 또는 package 권한이 아니다. 메인은 필수 evidence와
|
||||
미해결 항목을 확인하여 완료 여부를 판단하며, 문서 수정에는 정적 검토를 적용한다.
|
||||
|
||||
Owner, 공통 handoff, outcome, stale 처리와 유한 correction은
|
||||
현재 운영 결정은 [ADR-028](ADR.md#adr-028), 역할과 인계·실패 처리는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md)을 따른다. Skill의 적용 경계는
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md), 실행 절차는 각 현재 `SKILL.md`를 따른다.
|
||||
문서만 수정하는 작업을 solver Feature 전체 workflow로 확대하지 않는다.
|
||||
|
||||
## 단계적 확장과 비목표
|
||||
|
||||
|
||||
+97
-182
@@ -1,220 +1,135 @@
|
||||
# Structural FEM Solver Agent Design
|
||||
|
||||
## 1. 목적
|
||||
## 목적
|
||||
|
||||
이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
|
||||
`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
|
||||
산출물만 소유한다. 기능별 문서는 `docs/<feature-id>/`에 보존한다.
|
||||
폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다.
|
||||
메인 assistant가 작업 분해, 필요한 specialist 선택, 구현 조정과 완료 확인을 담당한다.
|
||||
작은 문서·구현·일상 결함은 직접 처리한다. Specialist는 전문 판단이나 독립 검토가
|
||||
필요한 bounded task에 사용하며 고정 lifecycle을 순회하기 위해 호출하지 않는다.
|
||||
|
||||
이 계약의 목표는 다음과 같다.
|
||||
현재 운영 결정은 [ADR-028](ADR.md#adr-028), Feature 폴더와 산출물 관리는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 필요한 계약과 검증은
|
||||
유지하면서 문맥 재독, 형식적 인계와 같은 결과의 반복 검토를 줄인다.
|
||||
|
||||
- 수치적·물리적 책임을 명확히 분리한다.
|
||||
- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다.
|
||||
- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다.
|
||||
- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다.
|
||||
- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다.
|
||||
|
||||
## 2. 권한과 판단 기준
|
||||
## 권한과 판단 기준
|
||||
|
||||
충돌하는 정보는 다음 우선순위로 판단한다.
|
||||
|
||||
1. 사용자가 승인한 feature contract와 critical decision
|
||||
2. 지배 방정식, 수학적 일관성, 적용되는 표준과 검증된 1차 문헌
|
||||
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 verification 사례
|
||||
4. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md`와 기존 승인 계약
|
||||
1. 현재 사용자 요청의 범위·권한과 승인된 Feature contract·critical decision
|
||||
2. 지배 방정식, 수학적 일관성, 적용 표준과 검증된 1차 문헌
|
||||
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 검증 사례
|
||||
4. 프로젝트 지침, architecture, ADR, tolerance와 기존 승인 계약
|
||||
5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현
|
||||
|
||||
Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석
|
||||
절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료
|
||||
구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다.
|
||||
관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다.
|
||||
Abaqus는 외부 reference convention이다. 지원 subset의 공개 입력 의미와 승인된 비교량을
|
||||
참고하되 비공개 알고리즘·내부 상태·결과 생성 절차를 추정하거나 내부 동등성을 주장하지
|
||||
않는다. 수치 결과의 exact equality는 허용되지만 내부 동등성의 evidence가 아니다.
|
||||
의미상 무해하다고 계약된 항목만 명시적 warning/no-op으로 처리하고 그 밖의 미지원
|
||||
semantics는 fail-closed로 진단한다.
|
||||
|
||||
공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이
|
||||
입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로
|
||||
진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다.
|
||||
## 메인의 작업 조정
|
||||
|
||||
## 3. 계층과 단독 상태 전이
|
||||
메인은 관련 계약과 현재 evidence를 확인하여 작업·수정 파일·검증 기준을 정한다.
|
||||
새 Feature에 지속할 계약이나 근거가 필요하면 `docs/<feature-id>/`를 초기화하고
|
||||
`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 작은 수정에는 새 Feature 폴더나
|
||||
빈 보고서를 만들지 않는다. 현재 checklist는 PRD 한 곳에 둔다.
|
||||
|
||||
`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다.
|
||||
메인은 계획·구현·일반 실패 수정을 직접 수행하거나 필요한 구현 묶음을 위임할 수 있다.
|
||||
Specialist는 할당된 판단과 파일만 소유하며 다른 계약을 수정하거나 peer를 재위임하지
|
||||
않는다. 메인은 결과를 확인하되 독립 검토가 필요한 판단을 작성자의 자기 승인으로 대체하지
|
||||
않는다. 누락된 evidence는 통과가 아니다.
|
||||
|
||||
```text
|
||||
INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
|
||||
```
|
||||
## Specialist 선택
|
||||
|
||||
- Coordinator는 요구사항 접수 시 Feature 폴더와 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`,
|
||||
`coordination.md`를 생성하고 문서 목록과 참조를 관리한다. 프로젝트 기준 문서는 보존한다.
|
||||
- Coordinator만 `docs/<feature-id>/coordination.md`의 현재 stage, outcome과 next owner를 바꾼다.
|
||||
- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다.
|
||||
- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다.
|
||||
- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한
|
||||
후 기록한다.
|
||||
- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다.
|
||||
- 누락된 증거는 통과로 간주하지 않는다.
|
||||
현재 profile은 [`.codex/agents`](../.codex/agents)에 있다.
|
||||
|
||||
## 4. 단계와 소유권
|
||||
|
||||
| Stage | Owner | Owned outputs |
|
||||
| Specialist | 호출할 때 | 기본 추론 강도 |
|
||||
| --- | --- | --- |
|
||||
| intake / coordination | `coordinator-agent` | `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md` |
|
||||
| `requirements` | `requirement-agent` | `requirements.md` |
|
||||
| `research` | `research-agent` | `research.md` |
|
||||
| `formulation` | `formulation-agent` | `formulation.md` |
|
||||
| `numerical-review` | `numerical-review-agent` | `numerical-review.md`, `reference-model.md` |
|
||||
| `io-definition` | `io-definition-agent` | `io.md` |
|
||||
| `implementation-planning` | `implementation-planning-agent` | `implementation-plan.md`, assigned Harness phase files |
|
||||
| `implementation` | `implementation-agent` | implementation files, tests, build registration, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
|
||||
| `physics-evaluation` | `physics-evaluation-agent` | `physics-evaluation.md` |
|
||||
| `release-readiness` | `release-agent` | `release.md` |
|
||||
| `requirement-agent` | 범위·acceptance가 복잡하거나 상충하여 별도 계약 정리가 필요 | `medium` |
|
||||
| `research-agent` | 사용할 이론·benchmark·reference 근거가 부족 | `medium` |
|
||||
| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화가 필요 | `high` |
|
||||
| `numerical-review-agent` | 새 정식화·주요 수치 변경·원인 불명의 수치 불일치를 독립 검토 | `high` |
|
||||
| `io-definition-agent` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경 | `medium` |
|
||||
| `implementation-agent` | 메인이 직접 수행하기보다 위임할 이점이 있는 구현 묶음 | `medium` |
|
||||
| `physics-evaluation-agent` | 새 해석 기능이나 결과의 평형·물리적 타당성·coverage 평가가 필요 | `high` |
|
||||
|
||||
`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
|
||||
implementation-owned 파일과 `corrections.md`를 수정한다.
|
||||
수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review를 수행한다.
|
||||
역할의 조건부 호출은 해당 analytical/invariant 검증이나 계약상 필수 물리·reference
|
||||
검증을 생략할 근거가 아니다. Release-readiness 감사는 사용자 명시 요청 시에만
|
||||
`fem-release-readiness`로 수행하며 전용 release profile이나 필수 종료 stage를 두지 않는다.
|
||||
|
||||
문서 경로는 모두 `docs/<feature-id>/` 기준이다. 각 specialist는 자신의 기본 산출물에
|
||||
연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며
|
||||
specialist 본문의 편집 권한을 뜻하지 않는다.
|
||||
모델과 역할별 강도는 현재 profile을 따른다. 난해한 정식화·수렴 문제에만 필요한 범위에서
|
||||
강도를 높인다. Profile 변경만으로 이미 실행 중인 session의 설정이 갱신되었다고 가정하지
|
||||
않는다. 불필요한 진행 확인·보고서 재작성·같은 결과의 재검토를 위해 agent를 호출하지 않는다.
|
||||
|
||||
각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
|
||||
재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
|
||||
`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.
|
||||
## 작업 인계와 반환
|
||||
|
||||
## 5. 공통 handoff envelope
|
||||
Dispatch에는 다음 정보만 필요한 만큼 전달한다.
|
||||
|
||||
모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
|
||||
envelope에는 전이에 필요한 요약만 둔다.
|
||||
- 수행할 작업과 결정할 문제
|
||||
- 관련 계약·원문의 경로와 절, 필요한 Feature context
|
||||
- 수정할 정확한 파일과 제외 범위
|
||||
- 검증 기준과 완료에 필요한 evidence
|
||||
|
||||
```yaml
|
||||
feature_id: <stable feature id>
|
||||
stage: requirements | research | formulation | numerical-review | io-definition |
|
||||
implementation-planning | implementation | correction | physics-evaluation |
|
||||
release-readiness
|
||||
outcome: pass | return-upstream | retry | blocked-environment | needs-user-decision
|
||||
next_owner: <agent id or null>
|
||||
evidence_paths: [<repository-relative path>]
|
||||
evidence_digest: <commands, exit codes, decisive findings, artifact hashes when relevant>
|
||||
failure_classification: <normalized class or null>
|
||||
retry_key: <feature-id|failing-gate|classification|contract-revision or null>
|
||||
attempt: <nonnegative integer>
|
||||
escalation_class: <critical class or null>
|
||||
blocker: <actionable blocker or null>
|
||||
```
|
||||
새 agent는 도구가 지원하면 `fork_turns="none"`으로 시작하여 필요한 문맥만 전달한다.
|
||||
연속 수정은 기존 agent에 짧은 후속 작업으로 보낸다. 같은 문맥에서 읽은 변경 없는 자료를
|
||||
다시 읽거나 모든 Feature 문서를 매번 주입하지 않는다.
|
||||
|
||||
필드 규칙은 다음과 같다.
|
||||
Return은 결과·판단, 변경 파일, 실행한 명령·exit code·결정적 결과, 미해결 항목·제한을
|
||||
간결하게 전달한다. 고정 envelope, outcome enum, retry signature나 artifact hash를 모든
|
||||
작업에 요구하지 않는다. 추적에 필요한 계약 revision과 실제 evidence 경로는 남기고,
|
||||
긴 로그·유도·schema는 원본을 연결한다.
|
||||
|
||||
- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다.
|
||||
- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다.
|
||||
- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다.
|
||||
- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다.
|
||||
- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다.
|
||||
- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다.
|
||||
- Dispatch는 `docs/<feature-id>/`와 Feature 관리 문서 3개를 필수 입력으로 명시한다.
|
||||
기본·상세 산출물의 owner를 지정하고 반환된 상세 문서도 `evidence_paths`로 확인한다.
|
||||
## 구현·검증과 완료
|
||||
|
||||
## 6. Outcome과 전이 규칙
|
||||
동작 변경에는 그 동작을 확인하는 테스트를 추가·수정하고, 버그는 가능한 경우 실패를
|
||||
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor나 문서 수정에는
|
||||
형식적인 새 테스트를 요구하지 않는다.
|
||||
|
||||
| Outcome | 의미 | Coordinator action |
|
||||
| --- | --- | --- |
|
||||
| `pass` | 현재 owner의 gate evidence가 완전함 | 다음 정규 stage로 전이 |
|
||||
| `return-upstream` | 선행 계약의 수정이 필요함 | `next_owner`로 되돌리고 영향받은 downstream gate를 stale 처리 |
|
||||
| `retry` | 계약을 바꾸지 않는 bounded rerun이 가능함 | retry 정책 안에서 지정 owner를 재호출 |
|
||||
| `blocked-environment` | 도구·권한·의존성·라이선스 문제로 신뢰성 있는 진행 불가 | 상태를 보존하고 환경 수정 전까지 중단 |
|
||||
| `needs-user-decision` | 아래 critical decision이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 |
|
||||
변경 중에는 관련 검사를 실행한다. 솔버 기능 완료 시, 사용자가 요청한 경우 또는 영향이
|
||||
넓어 필요한 경우 구성된 전체 build/test를 한 번 수행한다. 기능 완료에 필요한 reference
|
||||
비교도 수행하며 이후 변경·실패가 없으면 같은 검사를 반복하지 않는다. 문서 작업은 정적
|
||||
검토로 확인하고 build/test를 실행하지 않는다.
|
||||
|
||||
`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지
|
||||
않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만
|
||||
사용한다.
|
||||
메인은 완료를 판단할 때 다음을 확인한다.
|
||||
|
||||
정규 통과 순서는 다음과 같다.
|
||||
- 해당 요구와 계약을 지지하는 실제 결과가 있고 stale/missing evidence가 아님
|
||||
- 수치 변경에 필요한 독립 검토, analytical/invariant와 물리 검증이 있음
|
||||
- Reference quantity, unit, coordinate/component와 source identity가 대응함
|
||||
- Missing, extra, duplicate와 nonfinite required value를 tolerance 전에 거부함
|
||||
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature 판정 기준을 유지함
|
||||
- 실제 명령·exit code·판정값과 가정·미지원 범위·잔여 위험을 재현 가능하게 기록함
|
||||
|
||||
```text
|
||||
requirements -> research -> formulation -> numerical-review -> io-definition
|
||||
-> implementation-planning -> implementation -> physics-evaluation
|
||||
-> release-readiness -> completed
|
||||
```
|
||||
Reference artifact와 상위 계약을 구현 결과에 맞춰 생성·보정하거나 tolerance를 완화하지
|
||||
않는다. 실패·미실행 검사를 통과로 표시하지 않으며 과거 통과를 현재 검증으로 소급하지 않는다.
|
||||
|
||||
Numerical review는 formulation correctness와 reference-model readiness가 모두 확보되어야
|
||||
`pass`할 수 있다. Implementation은 TDD evidence, 전체 build/test와 feature가 요구하는
|
||||
reference comparison이 모두 통과해야 `pass`할 수 있다. Release의 `pass`는 내부 readiness
|
||||
closure일 뿐 publish, deploy, push, tag 또는 package 권한이 아니다.
|
||||
## 실패 처리와 사용자 결정
|
||||
|
||||
## 7. 자율 진행과 사용자 escalation
|
||||
일반 구현 실패는 현재 구현 owner가 재현·수정하고 관련 검사를 수행한다. 새 근거나 변경
|
||||
없이 같은 명령·agent 호출을 반복하지 않는다. 다른 관점이 필요할 때만 원인과 관련 evidence를
|
||||
전문가에게 전달한다. 고정 correction 횟수나 transport 재시도 예산을 두지 않는다.
|
||||
|
||||
Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다.
|
||||
상위 계약 결함은 정확한 계약 owner와 경로를 메인에 알린다. Downstream이 요구사항·수식·
|
||||
schema·tolerance·reference를 바꾸어 실패를 숨기지 않는다. 실제 계약 변경은 영향받은
|
||||
evidence를 다시 확인하고, 환경 문제는 필요한 환경 변화와 재개 조건을 기록한다.
|
||||
|
||||
- 승인 계약을 구현하는 파일 배치, private API와 내부 자료구조 선택
|
||||
- 기존 규칙에 따른 테스트 분해, config-selected build/test backend 등록, 진단 문구와 오류 처리
|
||||
- 문서·계획·evidence report의 생성 및 갱신
|
||||
- 명백한 compile, link, test, parser와 implementation defect의 최소 수정
|
||||
- Numerical Review가 `docs/TOLERANCE.md`와 feature evidence에 따라 선택하는 비교 quantity,
|
||||
identity/component, metric, scale, blocking/diagnostic 구분과 수치 tolerance
|
||||
- 공식 문서와 저장소 관례가 하나의 의미를 정하는 secondary convention
|
||||
- 안전한 read-only 조사, local build/test와 저장된 reference artifact 비교
|
||||
승인된 범위 안의 되돌릴 수 있는 저장소 작업에는 반복적인 중간 승인 절차를 추가하지 않는다.
|
||||
계획 요청만으로 실행 권한을 추정하지 않으며 다음 결정이 실제로 필요할 때 사용자에게
|
||||
대안·권고·영향을 함께 제시한다.
|
||||
|
||||
다음 항목만 `needs-user-decision`으로 escalation한다.
|
||||
- 지원 physics·제품 범위·공개 호환성의 변경
|
||||
- 지배 방정식·정식화·재료 모델 등 물리적 의미의 선택
|
||||
- 합격/불합격이나 공개 정확도 약속을 바꾸는 acceptance·tolerance 선택
|
||||
- Authoritative 입력·영속 결과 schema의 비호환 변경이나 해결되지 않은 필수 계약/reference 충돌
|
||||
- 외부 solver의 라이선스·자격증명·비공개 자료·비용 또는 외부 협조
|
||||
- 중대한 보안·신뢰 경계 변경이나 해결되지 않은 보안·법률·라이선스 위험 수용
|
||||
- 파괴적 Git/파일 작업, push·tag·publish·deploy·package·release
|
||||
|
||||
- feature scope, 지원 해석 유형 또는 공개 호환성의 변경
|
||||
- 지배 방정식, 요소 정식화, 재료 모델, 접촉·동역학 등 물리적 의미의 선택
|
||||
- 합리적인 두 acceptance 기준이 동일 evidence를 pass와 fail로 나누고 그 선택이 제품
|
||||
acceptance 의미나 공개 정확도 약속을 바꾸는 경우
|
||||
- authoritative input/output schema나 영속 public contract의 비호환 변경
|
||||
- authoritative requirement와 reference evidence가 충돌하고 기술 evidence로 우선순위를
|
||||
결정할 수 없는 경우
|
||||
- 외부 solver 실행에 필요한 라이선스·자격증명·비공개 자료
|
||||
- 보안·신뢰 경계 또는 credential 처리의 중대한 변경, 해결되지 않은 보안·법률·라이선스
|
||||
위험의 수용
|
||||
- destructive Git 작업, 외부 게시, push, tag, deploy, package 또는 release
|
||||
내부 검증 또는 readiness 권고는 외부 실행 권한이 아니다. 이미 승인된 작업의 일반 문서
|
||||
작성·로컬 실행·인계마다 승인을 다시 요구하지 않는다.
|
||||
|
||||
질문은 결정 가능한 대안, downstream 영향과 권고안을 하나로 묶는다. 단순 진행 확인,
|
||||
일반 문서 승인, 계획 승인 또는 agent 간 handoff 승인을 반복해서 요청하지 않는다.
|
||||
## 언어와 기록
|
||||
|
||||
## 8. 실패 분류와 유한 correction
|
||||
|
||||
실패 분류는 최소한 다음 값을 정규화해 사용한다.
|
||||
|
||||
```text
|
||||
configure | compile | link | test | reference-comparison | harness |
|
||||
environment | upstream-contract | physics | evidence
|
||||
```
|
||||
|
||||
Coordinator는 다음 요소로 retry signature를 만든다.
|
||||
|
||||
```text
|
||||
retry_key = feature_id | failing_gate | normalized_failure_classification | contract_revision
|
||||
```
|
||||
|
||||
동일 `retry_key`에 대한 Correction loop는 한 번만 허용한다.
|
||||
|
||||
1. Implementation Agent가 실패를 분류하고 명백한 implementation-owned defect를 최소 수정·재검증한다.
|
||||
2. 반복되거나 원인이 불명확하면 Coordinator가 해당 key의 correction 사용 이력을 확인한다.
|
||||
3. 사용 이력이 없을 때만 Correction Agent를 한 번 dispatch한다.
|
||||
4. Correction Agent는 `retry`로 Implementation rerun을 요청하고 Coordinator가 rerun을 dispatch한다.
|
||||
5. 같은 key가 다시 실패하면 두 번째 correction을 금지한다. 계약 문제는 `return-upstream`,
|
||||
환경 문제는 `blocked-environment`, 실제 critical choice만 `needs-user-decision`으로 전환한다.
|
||||
|
||||
문구만 바꾸거나 동일 계약 revision을 새 key로 가장하면 안 된다. Upstream 계약이 승인된 방식으로
|
||||
변경된 경우에만 `contract_revision`을 올리고 새 signature를 만든다.
|
||||
|
||||
## 9. Evidence gate
|
||||
|
||||
Coordinator는 `pass` 전에 다음을 확인한다.
|
||||
|
||||
- 요구되는 산출물이 존재하고 owner가 명시되어 있다.
|
||||
- 선행 artifact와 revision이 일치하며 stale evidence가 아니다.
|
||||
- 실행 증거에는 실제 명령, 종료 코드, 핵심 결과가 있다.
|
||||
- 수치 비교에는 quantity, unit, coordinate/component, matching rule과 적용 tolerance가 있다.
|
||||
- reference row의 missing, extra, duplicate와 nonfinite 값은 tolerance 판정 전에 검출된다.
|
||||
- 가정, 미지원 범위와 잔여 위험이 기록되어 있다.
|
||||
- specialist owner의 결론을 Coordinator나 downstream agent가 대신 만들지 않았다.
|
||||
- Feature 문서 목록과 기본·상세 문서 링크가 유효하고 필수 상세 근거까지 검토되었다.
|
||||
|
||||
Reference input과 결과 artifact는 명시적으로 소유 agent가 아닌 한 read-only다. 저장된 외부
|
||||
reference 결과를 임의로 생성·보정하거나 통과하도록 수치를 변경해서는 안 된다.
|
||||
|
||||
## 10. 언어와 기록
|
||||
|
||||
- 기능 문서는 사용자가 다른 언어를 요청하지 않는 한 한국어 Markdown으로 작성한다.
|
||||
- Agent id, field name, outcome, failure classification, requirement id, path와 command는 English를 유지한다.
|
||||
- Requirement id 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- Placeholder artifact는 만들지 않는다. Correction이 실제 발생할 때만 `corrections.md`를 만든다.
|
||||
- 모든 stage는 자신이 변경한 경로와 변경하지 않은 upstream contract를 명확히 기록한다.
|
||||
기능 문서는 기본적으로 한국어 Markdown으로 작성한다. Agent/skill ID, field,
|
||||
requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은
|
||||
`FEM-REQ-<FEATURE>-###`이다. 보고서는 실제 결정과 evidence를 한 번만 기록하고,
|
||||
기존 phase·coordination·실패 기록은 이력으로 보존한다.
|
||||
|
||||
+68
-141
@@ -1,165 +1,92 @@
|
||||
# Structural FEM Solver Skill Design
|
||||
|
||||
## 1. 목적
|
||||
## 목적과 적용 원칙
|
||||
|
||||
Project-local skill은 범용 유한요소 구조해석 solver feature를 요구사항부터 release readiness까지
|
||||
일관되게 처리하는 재사용 절차다. Agent가 stage의 책임과 write boundary를 소유하고, skill은
|
||||
그 stage에서 필요한 판단 방법, evidence와 output contract를 제공한다.
|
||||
Project-local skill은 필요한 FEM 판단과 검증 방법을 제공한다. 고정 lifecycle의 모든
|
||||
skill을 순회하지 않는다. 메인 assistant 또는 할당된 specialist는 현재 작업에 필요한
|
||||
skill과 직접 영향받는 계약만 읽는다.
|
||||
|
||||
실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`다. 공통 workflow와
|
||||
상태 전이는 `docs/SOLVER_AGENT_DESIGN.md`, 수치 비교 정책은 `docs/TOLERANCE.md`가 소유한다.
|
||||
Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다.
|
||||
실행 지침의 원본은 각 `SKILL.md`다. 역할·인계는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), 공통 운영 결정은
|
||||
[ADR-028](ADR.md#adr-028), 수치 비교 정책은 [TOLERANCE](TOLERANCE.md)를 따른다.
|
||||
|
||||
## 2. 설계 원칙
|
||||
- 이름과 description은 실제 사용할 조건을 구분한다.
|
||||
- `SKILL.md`에는 목적·필요 입력·판단 규칙·결과·수정 경계를 둔다.
|
||||
- 긴 유도나 toolchain·해석 계열별 절차는 `references/`에서 필요할 때만 읽는다.
|
||||
- 같은 문맥에서 읽은 변경 없는 자료를 재독하거나 모든 Feature 문서를 인계에 넣지 않는다.
|
||||
- Skill은 승인된 작업 범위나 외부 실행 권한을 넓히지 않는다.
|
||||
- FESA가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 수치 계약은 유지한다.
|
||||
- 필요한 산출물만 [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 작성한다.
|
||||
빈 보고서, 고정 envelope·outcome, 자동 commit이나 workflow 상태 파일을 요구하지 않는다.
|
||||
|
||||
- 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다.
|
||||
- `SKILL.md`에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다.
|
||||
- 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 `references/`에서 필요한
|
||||
경우에만 읽는다.
|
||||
- Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다.
|
||||
- 산출물은 Coordinator가 생성·관리하는 `docs/<feature-id>/`의 공통 feature bundle에 둔다.
|
||||
- [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 핵심 결과만 본문에 두고 필요한
|
||||
상세 내용은 같은 폴더의 별도 문서로 분리해 참조한다. Feature 관리 문서에서 공통 기준과
|
||||
현재 작업을 연결하며 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 보존한다.
|
||||
- 모든 stage는 공통 handoff envelope와 다섯 outcome을 사용한다.
|
||||
- Input, result container, tabular comparison format, compiler와 build adapter는 project/feature
|
||||
contract가 선택한다. 특정 형식을 solver identity로 고정하지 않는다.
|
||||
- Read-only 조사와 reversible in-repository 판단은 자율 수행한다. Critical decision만
|
||||
`needs-user-decision`으로 반환한다.
|
||||
## FEM skill inventory
|
||||
|
||||
## 3. Workflow skill inventory
|
||||
다음 8개 skill은 [`.codex/skills`](../.codex/skills)에 있다. 대표 산출물은 필요한
|
||||
경우의 예시이며 모든 작업에 별도 파일을 생성하라는 요구가 아니다.
|
||||
|
||||
| Stage | Skill | 대표 산출물 |
|
||||
| Skill | 사용할 때와 필요한 입력 | 결과와 경계 |
|
||||
| --- | --- | --- |
|
||||
| Requirements | `fem-requirements-baseline` | `requirements.md` |
|
||||
| Research | `fem-research-evidence` | `research.md` |
|
||||
| Formulation | `fem-formulation-spec` | `formulation.md` |
|
||||
| Numerical review | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` |
|
||||
| I/O definition | `fem-io-contract` | `io.md` |
|
||||
| Planning/implementation/correction | `fem-implementation-tdd` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md`, 필요 시 `corrections.md` |
|
||||
| Physics evaluation | `fem-physics-review` | `physics-evaluation.md` |
|
||||
| Release readiness | `fem-release-readiness` | `release.md` |
|
||||
| `fem-requirements-baseline` | 지속할 scope·acceptance 계약이 필요할 때 사용자 요구와 관련 기존 계약 확인 | 검증 가능한 요구·acceptance; 복잡하면 `requirements.md`와 matrix로 분리. 수식·schema·수치 기준을 선결정하지 않음 |
|
||||
| `fem-research-evidence` | 이론·benchmark 근거가 부족할 때 구체적인 solver 질문과 관련 원문 확인 | 출처 있는 연구 근거·적용 한계·gap. 사실과 추론을 구분하고 정식화 결론을 대신하지 않음 |
|
||||
| `fem-formulation-spec` | 새 수학 모델이나 변경된 정식화가 필요할 때 관련 요구·근거 확인 | DOF/kinematics, residual/tangent, integration, state update와 recovery 계약. 구현이나 자기 승인을 하지 않음 |
|
||||
| `fem-numerical-review` | 정식화·안정성·검증 범위의 독립 검토가 필요할 때 수식과 evidence 확인 | 수치 위험·analytical/invariant 검증·reference-model 준비 판단. 비교량·identity·location·units를 정의하고 저장 layout은 I/O에 남김 |
|
||||
| `fem-io-contract` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경될 때 관련 계약 확인 | 지원 subset, fail-closed 진단, 결과 의미와 저장·비교 mapping. 공개 compatibility를 임의 확대하지 않음 |
|
||||
| `fem-implementation-tdd` | 솔버 계획·구현·수정 시 할당 작업, 영향받는 계약과 build 설정 확인 | 최소 코드·의미 있는 테스트·필요한 계획과 검증 evidence. 상위 계약·reference·tolerance를 결과에 맞추어 수정하지 않음 |
|
||||
| `fem-physics-review` | 결과의 평형·부호·대칭·energy·mode·coverage 평가가 필요할 때 결과와 승인 기준 확인 | 물리적 타당성과 적용 한계. 새 acceptance를 즉석에서 만들거나 코드·계약을 수정하지 않음 |
|
||||
| `fem-release-readiness` | 사용자가 release-readiness 감사를 명시 요청할 때 해당 Feature 계약·결과·제한 확인 | 필수 evidence와 잔여 위험에 대한 내부 권고. 필수 lifecycle stage나 외부 release 권한이 아님 |
|
||||
|
||||
위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter `name`, agent prompt와
|
||||
`agents/openai.yaml` invocation name은 항상 동일해야 한다.
|
||||
수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 해당 analytical/invariant
|
||||
검증은 유지한다. 메인은 `fem-implementation-tdd`를 직접 사용하여 계획·구현·일반 실패
|
||||
수정을 수행할 수 있다. 별도 planning/correction profile이나 Harness phase 파일이 필요하지 않다.
|
||||
|
||||
## 4. Stage별 책임 분리
|
||||
## Supporting skill
|
||||
|
||||
### Requirements
|
||||
|
||||
`fem-requirements-baseline`은 scope, observable requirement, acceptance intent와
|
||||
requirement-verification matrix를 정의한다. Formulation, tolerance 값, API와 storage schema를
|
||||
선결정하지 않는다.
|
||||
|
||||
### Research
|
||||
|
||||
`fem-research-evidence`는 governing theory, primary source, benchmark와 reference convention의
|
||||
신뢰성·적용 한계를 정리한다. 사실, 계산, 추론과 evidence gap을 구분하며 formulation 결론을
|
||||
대신 만들지 않는다.
|
||||
|
||||
### Formulation
|
||||
|
||||
`fem-formulation-spec`은 strong/weak form, variables/DOF, kinematics, constitutive update,
|
||||
residual/tangent, integration, state와 recovery를 implementation-neutral 수학 계약으로 만든다.
|
||||
선택된 linear/nonlinear/dynamic/eigen/contact/material family의 reference만 읽는다.
|
||||
|
||||
### Numerical review
|
||||
|
||||
`fem-numerical-review`는 formulation을 독립 검토하고 requirement를 falsify할 verification
|
||||
coverage를 정의한다. Logical quantity, identity, location, units와 tolerance 근거까지 소유하지만
|
||||
physical dataset/file layout은 I/O stage에 남긴다.
|
||||
|
||||
### I/O definition
|
||||
|
||||
`fem-io-contract`은 선택된 external syntax와 semantic model, versioned result schema 및
|
||||
comparison identity 사이를 mapping한다. 미지원 semantic construct, validation과 diagnostic을
|
||||
명시한다. Subset 지원을 full compatibility로 표현하지 않는다.
|
||||
|
||||
### Planning, implementation와 correction
|
||||
|
||||
`fem-implementation-tdd`는 approved upstream bundle을 작은 RED/GREEN step으로 계획하고 C++
|
||||
변경, configured build/test와 필요한 reference comparison evidence를 만든다. Implementation은
|
||||
upstream contract, tolerance 또는 reference artifact를 결과에 맞춰 고치지 않는다.
|
||||
|
||||
Executor의 process/session 재시도는 transport attempt이며 Coordinator의 normalized
|
||||
failure/correction budget과 별개다. 동일 `retry_key`의 correction은 한 번만 허용한다.
|
||||
|
||||
### Physics evaluation
|
||||
|
||||
`fem-physics-review`는 numerically passing result가 문서화된 equilibrium, sign, symmetry,
|
||||
energy, mode와 model coverage 기대를 만족하는지 독립 검토한다. 새 acceptance를 즉석에서
|
||||
만들지 않는다.
|
||||
|
||||
### Release readiness
|
||||
|
||||
`fem-release-readiness`는 동일 feature/contract revision의 traceability, gate evidence,
|
||||
limitations와 release-note draft를 감사한다. Readiness verdict는 publish, tag, deploy 또는
|
||||
external release 권한이 아니다.
|
||||
|
||||
## 5. Supporting skill
|
||||
|
||||
| Skill | 적용 조건 |
|
||||
| Skill | 적용 조건과 경계 |
|
||||
| --- | --- |
|
||||
| `fem-theory-query` | 사용자가 configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때 |
|
||||
| `harness` | implementation phase를 만들거나 bounded Executor 작업을 수행할 때 |
|
||||
| `review` | repository diff를 architecture, numerical, test와 evidence 기준으로 읽기 전용 검토할 때 |
|
||||
| `fem-theory-query` | configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때. 일반 FEM 질문 전체에 적용하지 않음 |
|
||||
| `harness` | 구성된 build/test를 명시적으로 실행할 때. `python scripts/execute.py` 사용; phase 계획·agent 호출·Git 관리 기능 없음 |
|
||||
| `review` | 요청된 diff와 영향받는 계약·correctness·검증·범위를 읽기 전용 검토할 때. 수정 요청 없이 finding을 고치지 않음 |
|
||||
|
||||
`fem-theory-query`는 일반 FEM 질문 전체를 가로채지 않는다. Vault path는 environment,
|
||||
project instruction 또는 untracked local override에서 해석하며 workstation 절대 경로를
|
||||
commit하지 않는다. External research나 vault write는 해당 요청과 권한이 있을 때만 수행한다.
|
||||
`fem-theory-query`의 vault resolution과 citation 규칙을 유지한다. Workstation 절대 경로는
|
||||
untracked local override 등에 두고 commit하지 않는다. 외부 조사나 vault 수정에는 해당
|
||||
요청과 권한이 필요하다. Harness는 수치·물리·reference 검증이나 외부 solver 권한을 대신하지
|
||||
않으며 명령과 설정은 [HARNESS](HARNESS.md)를 따른다.
|
||||
|
||||
Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은
|
||||
guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다.
|
||||
## 결과와 evidence
|
||||
|
||||
## 6. 공통 evidence
|
||||
결과에는 작업을 지지하는 판단·가정, 변경 파일, 실제 명령·exit code·결정적 판정값,
|
||||
evidence 경로와 미해결 항목·제한만 필요한 만큼 기록한다. 수치 비교는 quantity,
|
||||
identity/component, units, metric과 승인된 tolerance source를 확인한다.
|
||||
|
||||
Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다.
|
||||
실행하지 않았거나 실패한 검사, missing/stale blocking evidence를 통과로 표시하지 않는다.
|
||||
긴 로그와 이미 정의된 수식을 여러 보고서에 복사하거나 의미 변화 없는 문서 편집마다
|
||||
revision/hash·gate 기록을 새로 만들지 않는다. 실제 계약이 변경되면 영향받은 evidence의
|
||||
유효성을 다시 확인한다.
|
||||
|
||||
- `feature_id`, `stage`, `outcome`, `next_owner`
|
||||
- `evidence_paths`, current contract revision과 artifact identity/hash
|
||||
- decisive finding, command, exit code, duration과 test count
|
||||
- comparison quantity, identity, units, metric와 tolerance source
|
||||
- `failure_classification`, `retry_key`, `attempt`
|
||||
- `escalation_class`, actionable blocker와 residual risk
|
||||
동작 변경은 해당 테스트로 검증하고 버그는 가능한 경우 실패를 재현한다. 변경 중에는 관련
|
||||
검사를 실행하며 솔버 기능 완료 시 구성된 전체 build/test와 필수 reference 비교를 한 번
|
||||
수행한다. 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되 이후 변경·
|
||||
실패가 없으면 반복하지 않는다. 충분한 기존 coverage가 있는 refactor에는 형식적인 새
|
||||
테스트를 요구하지 않는다.
|
||||
|
||||
필요한 명령이 실패했거나 실행되지 않았고 blocking evidence가 stale/missing이면 `pass`를
|
||||
반환하지 않는다. Raw log 전체를 모든 skill 문서에 복사하지 않고 재현 가능한 digest와 원본
|
||||
artifact path를 남긴다.
|
||||
## Reference와 사용자 결정 경계
|
||||
|
||||
## 7. Abaqus reference policy
|
||||
Abaqus의 공개 입력 의미·출력 정의·검증 사례는 승인된 범위의 reference로 사용한다.
|
||||
비공개 내부 알고리즘·상태·결과 생성 절차의 동등성이나 full compatibility를 주장하지
|
||||
않는다. 수치적 exact equality는 내부 동등성의 evidence가 아니다.
|
||||
|
||||
Abaqus는 project가 선택한 경우 다음 공개 observable convention의 기준으로 사용한다.
|
||||
저장된 artifact의 읽기와 외부 Abaqus 실행은 다른 권한이다. Reference 생성·수정·복원은
|
||||
명시적으로 승인된 범위에서만 다루며 구현 통과를 위해 값을 보정하지 않는다. Numerical
|
||||
Review는 공통 TOLERANCE 안에서 기능별 비교량·identity·판정 구분을 정의하며 임의로
|
||||
수치 기준을 완화하지 않는다.
|
||||
|
||||
- input keyword와 option의 문서화된 syntax/semantics
|
||||
- model data와 history/step data의 구분
|
||||
- element formulation, integration과 output location 정의
|
||||
- analysis procedure와 convergence 개념
|
||||
- verification guide의 benchmark 구성과 expected physical behavior
|
||||
지원 physics·공개 호환성·authoritative schema·acceptance 변경, 해결되지 않은 필수
|
||||
계약/reference 충돌, 외부 권한이나 파괴적·원격·release 작업은 사용자 결정 경계를 따른다.
|
||||
이미 승인된 범위의 일반 작업과 skill 인계에 반복 승인을 추가하지 않는다.
|
||||
|
||||
Skill은 비공개 내부 구현을 추정하지 않고 full compatibility나 solver equivalence를 주장하지
|
||||
않는다. External Abaqus execution은 저장된 artifact를 읽는 것과 다른 권한이며 라이선스,
|
||||
자격증명, 비용과 명시된 command scope가 확보된 경우에만 수행한다.
|
||||
## Skill 변경의 확인
|
||||
|
||||
## 8. Autonomous decision boundary
|
||||
|
||||
Skill은 approved contract 안의 내부 naming/layout, test 분해, diagnostic, 문서 형식, 기술
|
||||
근거가 유일한 convention과 명백한 결함 수정을 자율적으로 처리한다. Numerical Review는
|
||||
`docs/TOLERANCE.md`와 evidence로 feature-specific metric/tolerance를 결정할 수 있다.
|
||||
|
||||
지원 physics/범위, 공개 compatibility, authoritative schema, product acceptance를 바꾸는
|
||||
tolerance, 상충하는 필수 reference evidence, 외부 권한 또는 destructive/release 작업만
|
||||
사용자 결정이 필요하다. “계속할까요?” 같은 routine approval을 stage 사이에 추가하지 않는다.
|
||||
|
||||
## 9. Validation
|
||||
|
||||
Skill 변경 후 다음을 검증한다.
|
||||
|
||||
- lifecycle skill 8개와 supporting skill의 frontmatter parse
|
||||
- 폴더명, `name`, `openai.yaml` invocation과 agent 참조 일치
|
||||
- relative reference link의 존재와 repository containment
|
||||
- canonical output path와 common outcome vocabulary
|
||||
- product-specific legacy name과 machine-specific absolute path 부재
|
||||
- realistic requests를 이용한 최소 forward-test
|
||||
|
||||
Project에 validator가 제공되면 해당 validator와 repository pytest suite를 모두 실행한다.
|
||||
Validator 부재 또는 미실행을 성공으로 간주하지 않는다.
|
||||
Skill 자체를 변경할 때 영향받는 frontmatter, 폴더명·invocation·agent 참조, 상대 링크와
|
||||
조건부 reference를 확인한다. 변경된 동작에 필요한 최소 검사를 선택하며 제공되는
|
||||
validator나 관련 repository 검사가 필요하면 실행한다. 문서 설명만 수정하는 작업에
|
||||
전체 pytest나 solver build를 강제하지 않는다. 정적 검토와 실제 실행 여부를 구분해 기록한다.
|
||||
|
||||
Reference in New Issue
Block a user