docs: align guidance with simplified agent and harness workflow

This commit is contained in:
KOKO\Mimi
2026-09-07 22:12:48 +09:00
parent d7e9629640
commit 5e2a30fce0
10 changed files with 593 additions and 1304 deletions
+19 -16
View File
@@ -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로 확대하지 않는다.
## 단계적 확장과 비목표