baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify documents

Browse Source
This commit is contained in:
KOKO\Mimi
2026-09-05 15:14:21 +09:00
parent 31dac85192
commit 97e4d7a971
79 changed files with 4570 additions and 2787 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/harness/SKILL.md
+98 -150
View File
@@ -1,198 +1,146 @@
---
name: harness
description: Use when planning agentic implementation phases, creating phases/index.json and self-contained step files, or running the Harness step executor.
description: Plan, materialize, or execute bounded agentic implementation phases with test-first steps, validated state, safe Git ownership, and configured C++ verification.
---
# Harness Workflow
이 프로젝트는 Harness 프레임워크를 사용한다. 아래 워크플로에 따라 작업한다.
Use Harness for multi-step repository implementation. Read `AGENTS.md`, `docs/HARNESS.md`, and
`docs/HARNESS_WORKFLOW.md` before creating phases or executing them. Read the approved upstream feature
bundle and `docs/TOLERANCE.md` when numerical comparison is in scope.
For feature work, read [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md) and the
dispatched feature's `FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`; keep agent reports in that feature folder.
## 필수 읽기와 실행 소유권
## Authorization boundary
계획, phase 파일 생성, 또는 Executor 실행 전 `AGENTS.md`,
`docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`를 읽는다. Step을 구현할 때는
`.codex/hooks.json`, phase index, Executor가 선택한 현재 `stepN.md`도 읽는다.
A Coordinator dispatch based on an approved feature bundle authorizes routine planning-file creation and
bounded local execution with the default `workspace-write` sandbox. Do not add a separate “approve this
plan” or “start implementation?” gate.
| 책임 | 소유자 |
|---|---|
| branch, pending Step 선택, retry, timestamps, commits, advancement, top-level phase status | Executor (`scripts/execute.py`) |
| Executor-selected current Step의 작업과 해당 Step의 `status` 및 `summary` / `error_message` / `blocked_reason` payload | Implementation Agent |
| PreToolUse interception과 Stop whole-project validation | `.codex/hooks.json`으로 등록된 hooks |
Separate explicit user authorization is still required immediately before:
Hook은 자동으로 작동한다. `scripts/hooks/pre_tool_use.py` 또는
`scripts/hooks/stop_validation.py`를 수동 실행해 등록된 hook의 대체물로 사용하지 않는다.
계획 승인은 Executor 실행 권한이 아니다. `scripts/execute.py`는 별도의 명시적 사용자
요청에서만 실행한다.
- `danger-full-access`
- `--push`, tag, publish, deploy, package, or release
- destructive Git/history or filesystem operations
- licensed external solver execution, credentials, cost, or non-repository side effects
## A. 탐색
## Ownership
`AGENTS.md`와 `docs/` 하위 문서(PRD, ARCHITECTURE, ADR 등)를 읽고 프로젝트의 기획,
아키텍처, 설계 의도를 파악한다. 병렬 탐색이 실제로 유용하고 현재 세션에서 허용될
때만 Codex subagent를 선택적으로 사용한다.
| Owner | Responsibility |
| --- | --- |
| Coordinator | feature state, normalized `retry_key`, correction budget, dispatch and closure |
| Planning Agent | assigned phase/index/step files and `implementation-plan.md` |
| Executor | branch, current pending Step, transport attempts, timestamps, path-scoped commits and phase advancement |
| Implementation Agent | only the Executor-selected Step, its code/tests/reports, and Step result payload |
| Hooks | pre-edit command/TDD guard and configured whole-project Stop validation |
## B. 논의
The Executor owns at most two process/session transport attempts. They do not consume or reset the
Coordinator's one-correction workflow budget. An implementation, upstream-contract, environment, or
physics failure is returned for Coordinator classification rather than automatically looped.
구현을 위해 구체화하거나 기술적으로 결정해야 할 사항이 있으면 사용자에게 한 번에
하나씩 제시하고 논의한다.
## Plan materialization
## C. Step 설계
Create only the files assigned by Coordinator:
사용자가 구현 계획 작성을 지시하면 여러 step으로 나뉜 초안을 작성해 피드백을
요청한다.
설계 원칙:
1. **Scope 최소화** — 하나의 step에서 하나의 레이어 또는 모듈만 다룬다. 여러
모듈을 동시에 수정해야 하면 step을 쪼갠다.
2. **자기완결성** — 각 step 파일은 독립된 Codex 실행에서 사용된다. 외부 대화
참조를 금지하고 필요한 정보를 모두 파일 안에 적는다.
3. **사전 준비 강제** — 관련 문서와 이전 step에서 생성하거나 수정한 파일 경로를
명시한다.
4. **시그니처 수준 지시** — 함수와 클래스의 인터페이스를 제시하고 내부 구현은
Codex 재량에 맡긴다. 멱등성, 보안, 데이터 무결성 같은 핵심 규칙은 명시한다.
5. **AC는 실행 가능한 command** — 추상적 조건 대신 실제 빌드와 테스트 command를
포함한다.
6. **주의사항은 구체적으로** — "X를 하지 마라. 이유: Y" 형식으로 적는다.
7. **네이밍** — step name은 핵심 작업을 표현하는 kebab-case slug로 정한다.
## D. 파일 생성
사용자가 초안을 승인한 후에만 다음 파일을 생성한다.
Planning Agent는 초안을 만들고 승인받아 planning files만 materialize한다. planning
Agent는 Step을 선택하거나 실행하지 않는다.
### D-1. `phases/index.json`
여러 task를 관리하는 top-level 인덱스다. 이미 존재하면 `phases` 배열에 새 항목을
추가한다.
```json
{
"phases": [
{
"dir": "0-mvp",
"status": "pending"
}
]
}
```text
phases/index.json
phases/<phase>/index.json
phases/<phase>/step0.md
phases/<phase>/step1.md
...
```
- `dir`: task 디렉터리명
- `status`: `pending` | `completed` | `error` | `blocked`
- timestamp는 executor가 상태를 바꿀 때 기록하므로 생성 시 넣지 않는다.
The top-level entry is:
### D-2. `phases/{task-name}/index.json`
```json
{"dir": "<phase>", "status": "pending"}
```
The phase index is:
```json
{
"project": "<프로젝트명>",
"phase": "<task-name>",
"project": "<project>",
"phase": "<phase>",
"steps": [
{ "step": 0, "name": "project-setup", "status": "pending" },
{ "step": 1, "name": "core-types", "status": "pending" },
{ "step": 2, "name": "api-layer", "status": "pending" }
{"step": 0, "name": "<kebab-case-name>", "status": "pending"}
]
}
```
필드 규칙:
Use contiguous Step numbers from zero. A Step must be small enough to complete
`RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY` in one Codex session; do
not leave a red-only Step for a later Step.
- `project`: `AGENTS.md`에 정의된 프로젝트명
- `phase`: task 이름이며 디렉터리명과 일치
- `steps[].step`: 0부터 시작하는 순번
- `steps[].name`: kebab-case slug
- `steps[].status`: 초기값 `pending`
Each `stepN.md` is self-contained and contains:
상태와 기록 주체:
- files and upstream contracts to read, including the exact feature folder and its
`FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`
- exact owned files, symbols and behavior
- the expected RED failure and minimal GREEN scope
- executable focused/full acceptance commands resolved from project configuration
- architecture, numerical and reference invariants
- explicit out-of-scope items and stopping conditions
| 전이 | 기록 필드 | 기록 주체 |
|------|-----------|-----------|
| `completed` | `summary`, `completed_at` | Codex가 summary, executor가 timestamp |
| `error` | `error_message`, `failed_at` | Codex가 message, executor가 timestamp |
| `blocked` | `blocked_reason`, `blocked_at` | Codex가 reason, executor가 timestamp |
Do not invent missing physics, tolerance, schema, toolchain, or reference data in a Step. Return the
issue to its owner through Coordinator.
`summary`에는 다음 step에 유용한 생성 파일과 핵심 결정을 한 줄로 적는다.
task `created_at`과 step `started_at`은 executor가 기록하므로 생성 시 넣지 않는다.
## Local execution
### D-3. `phases/{task-name}/step{N}.md`
````markdown
# Step {N}: {이름}
## 읽어야 할 파일
먼저 아래 파일을 읽고 프로젝트의 아키텍처와 설계 의도를 파악하라:
- `/AGENTS.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- 이전 step에서 생성하거나 수정한 파일 경로
이전 step의 코드를 꼼꼼히 읽고 설계 의도를 이해한 뒤 작업하라.
## 작업
구체적인 구현 지시를 파일 경로, 클래스와 함수 시그니처, 로직 설명과 함께 적는다.
구현체는 Codex에 맡기되 설계 의도에서 벗어나면 안 되는 핵심 규칙은 명시한다.
## Acceptance Criteria
프로젝트 형식에 맞는 명령을 사용한다. `.harness/config.json`이 있으면 해당 preset,
solution, configuration, platform, test command를 우선한다.
Normal execution is:
```powershell
# CMake
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --output-on-failure
# 직접 MSBuild
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
.\build\tests\Debug\MyProjectTests.exe
python scripts/execute.py <phase>
```
## 검증 절차
The Executor requires a valid top-level/phase schema and a worktree clean outside the selected phase
control-file allowlist before branch checkout. It also requires the Git top-level to equal the Harness
root and validates the Implementation Agent profile before changing branch or state. It injects the role,
project guardrails, completed Step summaries and the current Step. It rejects nonzero Codex exits even if
a Step claimed completion.
1. Acceptance Criteria command를 실행한다.
2. ARCHITECTURE 디렉터리 구조를 따르는지 확인한다.
3. ADR 기술 스택과 `AGENTS.md` CRITICAL 규칙을 확인한다.
4. 결과에 따라 task index의 Executor-selected current Step만 갱신한다.
- 성공: `status`를 `completed`로 바꾸고 한 줄 `summary` 기록
- 실행을 계속할 수 없는 오류: `status`를 `error`로 바꾸고 `error_message` 기록
- 사용자 개입 필요: `status`를 `blocked`로 바꾸고 `blocked_reason` 기록 후 중단
- retry, timestamp, commit, 다음 Step 선택과 advancement는 Executor가 기록한다.
The Implementation Agent updates only the current Step:
## 금지사항
- `completed` plus a non-empty `summary`
- `error` plus `error_message`
- `blocked` plus `blocked_reason`
- 이 step의 범위 밖 기능을 추가하지 마라. 이유: step의 독립성을 깨뜨린다.
- 기존 테스트를 깨뜨리지 마라. 이유: 이전 동작을 회귀시킨다.
````
The Executor adds timestamps. It commits implementation paths and phase metadata separately, ignores raw
`stepN-output.json`, normalizes the index before path-scoped staging, and never stages changes outside the
declared ownership boundary. Top/phase control metadata and non-current Steps are immutable during a
session; a violation is restored to the trusted snapshot and recorded as an error.
The implementation session may not run commit, push, branch, tag, merge/rebase, or history-changing Git
commands. Executor verifies symbolic branch and HEAD around every attempt. Control reads reject links and
scope escape; control/output writes use atomic replacement so a substituted link target is not overwritten.
## E. 실행
Do not run hook scripts manually as substitutes for registered hooks. A PreToolUse pass proves neither
RED nor correctness; a Stop pass proves only the configured build/test gate.
별도의 명시적 사용자 요청이 있고 approved planning files가 materialize된 경우에만
Executor를 시작한다. Implementation Agent는 Executor가 선택한 current `stepN.md` 하나만
`RED -> observed failure -> minimal GREEN -> focused/full VERIFY` 순서로 수행하고 다음
Step을 시작하지 않는다.
## Elevated and remote execution
```bash
python scripts/execute.py {task-name}
python scripts/execute.py {task-name} --push
Use `danger-full-access` only after the user has authorized that exact run, the same command was shown to
fail because of the native sandbox, and execution is in a clean linked Git worktree:
```powershell
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
python scripts/execute.py <phase> --approve-danger-full-access
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
```
환경에서 Python 3 실행 명령이 `python3`이면 그 명령을 대신 사용한다.
The environment value alone is insufficient. The Executor rejects a primary or dirty worktree.
executor가 처리하는 작업:
Use `--push` only when the user explicitly authorized pushing the completed feature branch:
- `feat-{task-name}` 브랜치 생성 또는 checkout
- `AGENTS.md`와 `docs/*.md` guardrail 주입
- 완료 step의 summary를 다음 prompt에 누적
- 실패 시 최대 3회 재시도하며 이전 오류를 prompt에 전달
- 코드 변경과 metadata를 분리해 commit
- `started_at`, `completed_at`, `failed_at`, `blocked_at` 기록
```powershell
python scripts/execute.py <phase> --push
```
에러 복구:
## Recovery and handoff
- `error`: 해당 status를 `pending`으로 바꾸고 `error_message`를 삭제한 뒤 재실행
- `blocked`: 원인을 해결하고 status를 `pending`으로 바꾸고 `blocked_reason`을 삭제한
뒤 재실행
Do not manually erase failure evidence and immediately rerun. Return the exact command/exit, classification,
artifact paths and `retry_key` to Coordinator. After the owning upstream/environment/user decision is
resolved, Coordinator may reset the current Step to `pending`; stale summary/failure/block timestamps are
cleared by the Executor.
Report the final phase state, commits created, commands and exit codes, test counts, ignored/untracked raw
output, unexecuted checks and residual risks. Never call a phase complete when any Step is non-completed.
.agents/skills/review/SKILL.md
+40 -26
View File
@@ -1,41 +1,55 @@
---
name: review
description: Use when reviewing repository changes against AGENTS.md, architecture decisions, tests, and build requirements.
description: Review repository changes for structural FEM correctness, architecture boundaries, safety, tests, and evidence without modifying them.
---
# Repository Review
먼저 다음 문서를 읽는다.
Review the requested diff, or the current working-tree changes when no range is given. This skill is
read-only: do not fix findings unless the user separately asks for implementation.
- `/AGENTS.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
## Required context
사용자가 범위를 지정하지 않으면 현재 작업 트리의 변경을 리뷰한다. 관련 diff를
확인하고 가능한 빌드와 테스트 command를 실제로 실행한다.
Read `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, and the feature contracts directly affected by
the diff. Read `docs/TOLERANCE.md` for numerical or comparison changes. Use repository configuration to
discover actual build/test commands; do not assume a solver target exists.
## 체크리스트
## Review order
1. MSVC toolset와 C++ 표준이 AGENTS.md/ADR과 일치하는가?
2. CMake 또는 MSBuild Debug/x64 빌드가 통과하는가?
3. CTest 또는 `.harness/config.json`의 명시적 test command가 통과하는가?
4. 새 C/C++ 소스와 헤더에 대응 테스트가 있는가?
5. CRITICAL 아키텍처 규칙과 public header 경계를 지키는가?
1. Identify changed public behavior, physics meaning, I/O/result identity, state ownership, and
architecture boundaries.
2. Check that every production C++ change has a test and that behavior changes show meaningful RED/GREEN
evidence.
3. For numerical code, verify units, coordinates, sign, DOF/component ordering, residual/tangent
consistency, integration, trial/commit state, determinism, and tolerance ownership.
4. For Abaqus-facing code, review only the declared observable subset and reject undocumented internal
equivalence claims or silent handling of unsupported semantics.
5. Run the smallest relevant checks, then the configured full build/test when available. Record exact
commands and exit codes. An unavailable or skipped check is `not verified`, never `pass`.
6. Check that reference inputs/results and tolerance artifacts were not changed to fit implementation
output, and that unrelated working-tree files are untouched.
## 출력 형식
## Findings
실제 결함을 심각도순으로 먼저 제시한다. 각 finding에 파일과 줄 번호, 영향,
재현 또는 근거, 구체적인 수정 방안을 포함한다.
Report actionable defects first, ordered `critical`, `high`, `medium`, `low`. Each finding must contain:
그 뒤 다음 표를 제공한다.
- file and line
- violated contract or observable risk
- concrete evidence or reproduction
- smallest credible correction
| 항목 | 결과 | 비고 |
|------|------|------|
| 아키텍처 준수 | ✅/❌/미검증 | 상세 |
| 기술 스택 준수 | ✅/❌/미검증 | 상세 |
| 테스트 존재 | ✅/❌/미검증 | 상세 |
| CRITICAL 규칙 | ✅/❌/미검증 | 상세 |
| 빌드 가능 | ✅/❌/미검증 | 상세 |
Do not report style preferences without a project rule or meaningful maintenance risk. Do not infer a
defect solely because an external solver uses a different private implementation.
실행할 수 없는 검사는 성공으로 추정하지 말고 `미검증`과 이유를 적는다. finding이
없으면 발견된 문제가 없다고 명시하고 남아 있는 검증 공백을 설명한다.
After findings, summarize:
| Gate | Result | Evidence or gap |
| --- | --- | --- |
| Requirements/architecture | pass/fail/not verified | details |
| Numerical and physical contract | pass/fail/not applicable/not verified | details |
| Tests and TDD evidence | pass/fail/not verified | details |
| Build/toolchain | pass/fail/not available/not verified | details |
| Reference/tolerance integrity | pass/fail/not applicable/not verified | details |
| Scope and repository safety | pass/fail/not verified | details |
If no defect is found, say so explicitly and list residual risks or checks that could not be executed.