baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
FESADev/docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md
T
KOKO\Mimi 31b1ebb25d docs: define consolidated agent workflow
2026-08-15 01:08:55 +09:00

13 KiB
Raw Permalink Blame History

FESA Agent/Skill 개발 프로세스 통합 설계

Metadata

  • date: 2026-08-15
  • status: approved-design
  • scope: FESA 개발 workflow, custom agent, project-local skill, agent 산출물 배치

목표

FESA 기능 개발 workflow를 요구사항 단위로 단순화한다. 중복된 agent와 skill을 실제로 병합하고, coordinator-agent를 유일한 main agent로 두며, 모든 단계별 산출물을 docs/<feature-id>/에 모은다.

이 변경은 개발 운영 계약만 바꾼다. Solver C++ 구현, CMake/CTest target, Harness executor, hook 동작, Abaqus reference artifact와 승인된 FEM 기능 계약은 변경하지 않는다.

핵심 결정

  1. 기존 reference model 계약 준비 단계는 Numerical Review 단계에 병합한다.
  2. 기존 Build/Test와 Reference Comparison 단계는 C++ Implementation 단계에 병합한다.
  3. 병합된 단계의 agent와 skill도 각각 하나로 병합한다.
  4. Agent 수를 줄이되 build/test와 reference comparison 증거 문서는 별도로 유지한다.
  5. 모든 agent 산출물은 docs/<feature-id>/ 아래에 둔다.
  6. coordinator-agent는 main agent이고 나머지 agent는 Coordinator가 호출하는 sub-agent다.
  7. correction-agent는 정규 단계가 아니라 반복되거나 원인이 불명확한 실패를 다루는 재작업 sub-agent로 유지한다.

단순화된 개발 프로세스

단계 담당 sub-agent 필수 skill 산출물
1. 요구조건 requirement-agent fesa-requirements-baseline requirements.md
2. 연구 research-agent fesa-research-evidence, 필요 시 fem-theory-query research.md
3. 정식화 formulation-agent fesa-formulation-spec formulation.md
4. 수치 검토 + reference model 계약 numerical-review-agent 확장된 fesa-numerical-review numerical-review.md, reference-model.md
5. I/O 정의 io-definition-agent fesa-io-contract io.md
6. 구현 계획 + C++ 구현 + build/test + reference comparison implementation-planning-agent, implementation-agent 확장된 fesa-cpp-msvc-tdd와 계획 시 project-local harness implementation-plan.md, implementation-report.md, build-test.md, reference-comparison.md
7. 물리 검토 physics-evaluation-agent fesa-physics-sanity physics-evaluation.md
8. 배포 준비 release-agent fesa-release-readiness release.md

coordinator-agent는 위 단계 밖에서 전체 workflow와 handoff를 관리하고 coordination.md를 소유한다. correction-agent는 Coordinator가 재작업을 요청할 때만 corrections.md에 원인, 수정, 재검증 결과를 추가한다.

Agent 통합

Numerical Review 통합

reference-model-agent의 책임을 numerical-review-agent에 흡수하고 .codex/agents/reference-model-agent.toml을 제거한다.

병합된 Numerical Review Agent는 다음 두 판단을 함께 소유한다.

  • 정식화의 차원, 부호, 좌표 변환, Jacobian, 적분, locking, rigid-body mode와 검증 준비도
  • 기존 reference input/CSV의 존재, 비교량, blocking/warning 정책, source identity/component, row precheck와 승인된 tolerance

기존 Reference Model Agent가 I/O 문서를 입력으로 요구하던 순환 의존성은 제거한다. reference-model.md는 exact input/CSV, 비교량, source identity/component와 tolerance를 확정한다. 다음 I/O 단계가 이를 소비해 io.md에서 최종 HDF5 dataset projection과 CSV column mapping을 정의한다.

Implementation 통합

build-test-executor-agent와 reference-verification-agent의 책임을 implementation-agent에 흡수하고 다음 파일을 제거한다.

  • .codex/agents/build-test-executor-agent.toml
  • .codex/agents/reference-verification-agent.toml

병합된 Implementation Agent는 한 단계 안에서 다음 순서를 완료한다.

RED -> observed failure -> minimal GREEN -> focused VERIFY
    -> full MSVC x64 Debug build/CTest -> reference artifact check
    -> blocking/warning reference comparison -> report

하나의 agent가 수행하더라도 증거는 다음 세 문서로 분리한다.

  • implementation-report.md: 구현 범위, RED/GREEN/VERIFY, 코드 변경과 traceability
  • build-test.md: 환경, 명령, exit code, 실패 분류와 CTest 결과
  • reference-comparison.md: artifact inventory, row identity, tolerance와 quantity별 결과

Implementation 단계의 최종 성공 상태는 pass-for-physics-evaluation이다. Compile, link, ordinary test 또는 명확한 implementation-owned mismatch는 Implementation Agent가 먼저 수정한다. 같은 failure classification이 반복되거나 원인이 불명확하면 Coordinator가 correction-agent를 호출한다.

Skill 통합

Numerical Review skill

fesa-reference-models의 reference inventory, comparison scope, identity, row precheck, tolerance와 handoff 계약을 fesa-numerical-review에 흡수한다. 다음 디렉터리를 제거한다.

  • .codex/skills/fesa-reference-models/

확장된 fesa-numerical-review는 numerical-review.md와 reference-model.md를 모두 산출하고 I/O Definition Agent에 두 문서를 handoff한다.

C++ TDD skill

fesa-reference-comparison의 ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT, deterministic row matching, nonfinite/누락/추가/중복 row rejection과 tolerance 적용 계약을 fesa-cpp-msvc-tdd에 흡수한다. 다음 디렉터리를 제거한다.

  • .codex/skills/fesa-reference-comparison/

확장된 fesa-cpp-msvc-tdd는 구현 계획, TDD 구현, MSVC build/CTest, failure correction과 reference comparison을 하나의 구현 단계 절차로 정의한다. Project-local harness의 계획 승인, phase materialization, executor와 hook 계약은 변경하지 않는다.

통합 후 FESA workflow skill은 다음 8개다.

  • fesa-requirements-baseline
  • fesa-research-evidence
  • fesa-formulation-spec
  • fesa-numerical-review
  • fesa-io-contract
  • fesa-cpp-msvc-tdd
  • fesa-physics-sanity
  • fesa-release-readiness

fem-theory-query와 project-local harness, review는 별도 보조 skill로 유지한다.

Agent 계층과 Coordinator Orchestration

통합 후 .codex/agents/에는 main agent 1개와 sub-agent 10개가 남는다.

  • main: coordinator-agent
  • sub-agents: requirement-agent, research-agent, formulation-agent, numerical-review-agent, io-definition-agent, implementation-planning-agent, implementation-agent, correction-agent, physics-evaluation-agent, release-agent

Coordinator는 다음 순서로 동작한다.

INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT

Coordinator는 한 번에 다음 유효 단계의 owner만 호출한다. Sub-agent는 전달받은 단계와 산출물만 처리하고 peer agent를 직접 호출하거나 다음 단계로 진행하지 않는다. 완료 후 산출물 경로, status, 핵심 evidence, blocker를 Coordinator에 반환한다.

docs/<feature-id>/coordination.md는 다음 정보를 중심으로 작성한다.

  • feature scope와 현재 목표
  • 8단계 worklist
  • 단계별 owner, 상태, 산출물 경로와 완료 evidence
  • 현재 실행 중인 sub-agent와 다음 handoff
  • blocker, 사용자 결정과 failure classification
  • correction attempt count와 반복 실패 stop condition
  • gate transition decision log와 최종 workflow closure

Worklist 항목 상태는 pending | in-progress | passed | needs-rework | blocked만 사용한다. 동일 failure classification이 두 번 반복되면 자동 재작업을 중단하고 전체 workflow를 needs-user-decision 또는 blocked로 전환한다.

Gate 계약

  1. Requirements gate: requirements.md가 승인된 범위, acceptance criteria, 검증량과 tolerance를 가진다.
  2. Research gate: research.md가 필요한 이론과 검증 evidence를 제공한다.
  3. Formulation gate: formulation.md가 구현 가능한 수치 계약을 제공한다.
  4. Numerical/reference gate: numerical-review.md와 reference-model.md가 모두 통과한다.
  5. I/O gate: io.md가 reference identity를 authoritative HDF5 dataset과 연결한다.
  6. Implementation gate: 구현 계획, RED/GREEN evidence, MSVC build/CTest와 blocking reference comparison이 모두 통과한다.
  7. Physics gate: physics-evaluation.md가 pass-for-release-agent다.
  8. Release gate: release.md가 ready-for-release이고 Coordinator가 closure를 기록한다.

요구사항 단위 산출물 구조

docs/<feature-id>/
├── coordination.md
├── requirements.md
├── research.md
├── formulation.md
├── numerical-review.md
├── reference-model.md
├── io.md
├── implementation-plan.md
├── implementation-report.md
├── build-test.md
├── reference-comparison.md
├── corrections.md
├── physics-evaluation.md
└── release.md

산출물이 필요하지 않았거나 기존 workflow에서 생성되지 않은 경우 빈 placeholder 문서를 만들지 않는다. corrections.md는 실제 correction이 발생할 때만 생성한다.

기존 문서 마이그레이션

현재 agent별 폴더의 기능 문서를 다음 두 요구사항 폴더로 이동한다.

  • docs/linear-static-3d-euler-beam/
  • docs/linear-static-mitc4-shell/

파일 내용과 당시 owner_agent, status, numerical verdict는 역사적 evidence이므로 바꾸지 않는다. 내부 문서 경로만 새 위치로 갱신한다. 삭제된 agent 이름이 기존 evidence의 소유자로 기록된 경우도 그대로 보존한다.

기존 docs/requirements/, docs/research/, docs/formulations/, docs/numerical-reviews/, docs/io-definitions/, docs/reference-models/, docs/implementation-plans/, docs/build-test-reports/, docs/corrections/, docs/reference-verifications/, docs/physics-evaluations/, docs/releases/, docs/coordination/의 기능 문서와 필요한 내부 링크를 옮긴 뒤 agent별 README는 제거한다. 공통 운영 계약은 AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, docs/SOLVER_SKILL_DESIGN.md에 통합한다.

기존 두 기능은 ready-for-release evidence를 가지고 있으므로 새 coordination.md에서 completed로 inventory한다. 누락된 과거 산출물을 새 문서로 꾸미거나 새 workflow를 소급 실행하지 않는다.

다음 항목은 이동하거나 변경하지 않는다.

  • docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md
  • docs/reference-papers/와 기타 공통 기술 문서
  • reference/ 아래의 Abaqus input/CSV artifact
  • phases/의 실행 상태와 Harness 실행 결과 본문. 이동된 문서를 가리키는 path reference만 기계적으로 갱신할 수 있다.
  • Solver C++ source, tests, CMake/CTest configuration

문서와 참조 갱신

현재 실행 계약에서는 제거된 agent/skill과 기존 agent별 산출물 경로를 사용하지 않는다. 다음 파일군을 새 workflow와 docs/<feature-id>/ 경로로 갱신한다.

  • AGENTS.md
  • .codex/agents/*.toml
  • .codex/skills/*/SKILL.md와 대상 agents/openai.yaml
  • docs/SOLVER_AGENT_DESIGN.md
  • docs/SOLVER_SKILL_DESIGN.md
  • 이동한 기능 문서의 내부 링크
  • 기존 경로를 입력으로 사용하는 관련 계획, spec, phase 문서

역사적 산출물 본문에 기록된 과거 agent 이름과 status는 stale reference 검사 대상에서 제외하지만, 새 입력 경로를 가리키는 링크는 유효해야 한다.

검증 전략

tests/test_agent_skill_workflow_contract.py를 추가해 다음 정적 계약을 검증한다.

  • 남은 agent 파일 집합이 main 1개와 sub-agent 10개인지 확인
  • 제거 대상 agent 3개와 skill 2개가 존재하지 않는지 확인
  • Coordinator가 main 역할과 docs/<feature-id>/coordination.md worklist를 정의하는지 확인
  • 모든 다른 agent가 sub-agent 역할과 Coordinator handoff를 정의하는지 확인
  • 병합 대상 skill의 핵심 workflow와 output contract가 destination skill에 존재하는지 확인
  • 현재 실행 계약에 제거된 agent/skill 이름이나 기존 agent별 출력 경로가 없는지 확인
  • 모든 TOML이 parse되고 각 skill의 frontmatter와 UI metadata가 유효한지 확인

검증 명령은 다음과 같다.

uv run --with pytest python -m pytest -v -rs
python <skill-creator>/scripts/quick_validate.py .codex/skills/<remaining-skill>
git diff --check

quick_validate.py는 남아 있는 project-local skill 각각에 실행한다. 이번 변경은 C++ production과 CMake/CTest를 수정하지 않으므로 MSVC build와 CTest는 필수 검증 범위가 아니다.

완료 기준

  • 8단계 workflow가 AGENTS.md, agent config와 설계 문서에서 동일하다.
  • 삭제 대상 agent와 skill이 제거되고 모든 책임과 quality gate가 destination에 보존된다.
  • coordinator-agent가 main agent로서 sub-agent dispatch와 worklist 갱신을 소유한다.
  • 모든 새 산출물 경로가 docs/<feature-id>/ 규칙을 따른다.
  • 기존 기능 문서가 새 폴더에 모이고 역사적 verdict가 보존된다.
  • 자동 계약 테스트, 전체 Python pytest, skill validation과 git diff --check가 통과한다.
Reference in New Issue View Git Blame Copy Permalink