From 235d10f0926b1b7b3ee0692b7e7d470b9f0599d0 Mon Sep 17 00:00:00 2001 From: devRonPark Date: Wed, 8 Jul 2026 13:39:14 +0900 Subject: [PATCH 1/2] task 4.10: add Claude/Codex quality gates --- .agents/skills/branch-checkout/SKILL.md | 22 ++ .agents/skills/git-push/SKILL.md | 22 ++ .agents/skills/grill-me/SKILL.md | 24 ++ .agents/skills/harness-plan/SKILL.md | 26 ++ .agents/skills/harness-progress/SKILL.md | 20 ++ .agents/skills/harness-review/SKILL.md | 24 ++ .agents/skills/harness-sync/SKILL.md | 20 ++ .agents/skills/harness-work/SKILL.md | 28 ++ .agents/skills/pr-create/SKILL.md | 24 ++ .claude/commands/branch-checkout.md | 24 ++ .claude/commands/git-push.md | 24 ++ .claude/commands/pr-create.md | 25 ++ .harness/CONTEXT_INDEX.md | 5 + .harness/LESSONS.md | 7 + .harness/LOG.md | 45 +++ .harness/STATE.md | 26 +- .harness/shared/planning/latest.json | 7 + .../plan-20260708-quality-gates/context.json | 265 ++++++++++++++++++ .../decomposition-report.md | 22 ++ .../proposed-tasks.json | 16 ++ AGENTS.md | 98 +++++++ BLUEPRINT.md | 40 ++- CLAUDE.md | 6 + Plans.md | 11 + README.md | 107 +++++-- agents/quality-gates.md | 73 +++++ docs/setup-guide.md | 16 ++ .../2026-07-08-codex-claude-quality-gates.md | 79 ++++++ init.sh | 12 +- tasks/index.json | 46 +++ templates/skeleton/.harness/CONTEXT_INDEX.md | 4 + templates/skeleton/Plans.md | 2 +- templates/skeleton/tasks/index.json | 4 +- 33 files changed, 1140 insertions(+), 34 deletions(-) create mode 100644 .agents/skills/branch-checkout/SKILL.md create mode 100644 .agents/skills/git-push/SKILL.md create mode 100644 .agents/skills/grill-me/SKILL.md create mode 100644 .agents/skills/harness-plan/SKILL.md create mode 100644 .agents/skills/harness-progress/SKILL.md create mode 100644 .agents/skills/harness-review/SKILL.md create mode 100644 .agents/skills/harness-sync/SKILL.md create mode 100644 .agents/skills/harness-work/SKILL.md create mode 100644 .agents/skills/pr-create/SKILL.md create mode 100644 .claude/commands/branch-checkout.md create mode 100644 .claude/commands/git-push.md create mode 100644 .claude/commands/pr-create.md create mode 100644 .harness/shared/planning/latest.json create mode 100644 .harness/shared/planning/runs/plan-20260708-quality-gates/context.json create mode 100644 .harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md create mode 100644 .harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json create mode 100644 AGENTS.md create mode 100644 agents/quality-gates.md create mode 100644 docs/specs/2026-07-08-codex-claude-quality-gates.md diff --git a/.agents/skills/branch-checkout/SKILL.md b/.agents/skills/branch-checkout/SKILL.md new file mode 100644 index 0000000..80b6415 --- /dev/null +++ b/.agents/skills/branch-checkout/SKILL.md @@ -0,0 +1,22 @@ +--- +name: branch-checkout +description: 작업 전용 Git 브랜치를 만들거나 전환한다. 별도 브랜치 체크아웃, task 브랜치 생성, 브랜치 전환 요청 시 사용. +--- + +# branch-checkout + +별도 작업 브랜치를 안전하게 만들거나 전환한다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`를 확인한다. +2. 변경분이 있으면 요약하고, 전환해도 되는지 판단한다. 사용자 변경은 되돌리지 않는다. +3. 필요하면 `git fetch origin`으로 원격 기준을 최신화한다. +4. 기존 브랜치면 `git switch {branch}`를 실행한다. +5. 새 브랜치면 `task/{task-id}-{short-slug}` 형식을 선호해 `git switch -c {branch}`를 실행한다. +6. 전환 후 현재 브랜치와 남은 변경분을 보고한다. + +## 제한 + +- `git reset --hard`, `git checkout --`, 강제 push는 실행하지 않는다. +- 브랜치명이 불명확하면 Task ID나 사용자 목적에서 짧은 이름을 제안한다. diff --git a/.agents/skills/git-push/SKILL.md b/.agents/skills/git-push/SKILL.md new file mode 100644 index 0000000..1c8ebd4 --- /dev/null +++ b/.agents/skills/git-push/SKILL.md @@ -0,0 +1,22 @@ +--- +name: git-push +description: 현재 Git 브랜치를 안전하게 원격에 push한다. git push, upstream 설정, 작업 브랜치 게시 요청 시 사용. +--- + +# git-push + +현재 브랜치를 원격에 push한다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`를 확인한다. +2. 현재 브랜치가 `main`/`master`면 push하지 말고 사용자 확인을 받는다. +3. 커밋되지 않은 변경분이 있으면 push 대상이 아니므로 중단하고 보고한다. +4. upstream이 있으면 `git push`를 실행한다. +5. upstream이 없으면 `git push -u origin {current-branch}`를 실행한다. +6. push 결과와 PR 작성 가능 여부를 보고한다. + +## 제한 + +- `--force`, `--force-with-lease`는 사용하지 않는다. +- 인증/권한/remote 오류는 원문을 요약하고 멈춘다. diff --git a/.agents/skills/grill-me/SKILL.md b/.agents/skills/grill-me/SKILL.md new file mode 100644 index 0000000..0f5c988 --- /dev/null +++ b/.agents/skills/grill-me/SKILL.md @@ -0,0 +1,24 @@ +--- +name: grill-me +description: 아이디어·기능 요청을 한 번에 한 질문씩 인터뷰해서 docs/PRD.md 초안까지 작성한다. 새 프로젝트/기능 착수, PRD 작성, "grill me" 요청 시 사용. +--- + +# grill-me + +Codex용 PRD 인터뷰 스킬이다. `CLAUDE.md` 기획 규칙과 `.claude/skills/grill-me/SKILL.md` +의 기존 의도를 따른다. 인터뷰만 하고 끝내지 말고 `docs/PRD.md` 작성까지 완료한다. + +## 절차 + +1. 먼저 `AGENTS.md`, `CLAUDE.md`, 기존 `docs/PRD.md`, `docs/templates/PRD.md`를 읽는다. +2. 코드베이스나 기존 문서로 답할 수 있는 내용은 직접 확인한다. +3. 사용자에게 질문은 한 번에 하나만 한다. +4. 모든 질문에는 권장 답과 이유를 함께 제시한다. +5. 목적, 대상 사용자, 핵심 기능 3±2개, Non-goals, 측정 가능한 성공 기준이 나오면 질문을 멈춘다. +6. `docs/templates/PRD.md`를 기준으로 `docs/PRD.md`를 작성하고, 미확정 항목은 Open Questions에 남긴다. +7. 승인 후 UserFlow·DESIGN·Architecture 보완과 `$harness-plan` 실행을 안내한다. + +## 기본값 + +- 산출 경로 기본값은 현재 프로젝트의 `docs/`다. +- 사용자가 응답하지 않거나 headless 환경이면, 이미 확정된 내용과 권장 답을 기준으로 초안을 쓰고 미확정 항목을 Open Questions에 남긴다. diff --git a/.agents/skills/harness-plan/SKILL.md b/.agents/skills/harness-plan/SKILL.md new file mode 100644 index 0000000..d889ab3 --- /dev/null +++ b/.agents/skills/harness-plan/SKILL.md @@ -0,0 +1,26 @@ +--- +name: harness-plan +description: PRD·기획 문서를 실행 가능한 Task proposal로 분해하고 검증 후 tasks/index.json에 반영한다. Task 추가·변경이나 계획 수립 요청 시 사용. +--- + +# harness-plan + +Codex에서 Claude Code `/harness-plan`에 해당하는 절차를 직접 수행한다. `Plans.md`를 +직접 편집하지 않는다. + +## 절차 + +1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `tasks/index.json`, `Plans.md`, 필요한 기획 문서를 읽는다. +2. `python3 scripts/build_planning_context.py`로 planning context를 만든다. +3. `harness.toml [plan].decomposer_command`가 있으면 그 명령으로 proposal을 만든다. +4. 명령이 없거나 실패하고 `allow_inline_fallback = true`이면, 현재 Codex 세션이 `agents/task-decomposer.md` 기준으로 같은 proposal 파일 계약을 채운다. +5. `python3 scripts/validate_task_proposal.py ...`로 proposal을 검증한다. +6. 통과한 경우에만 `python3 scripts/apply_task_proposal.py ...`로 `tasks/index.json`에 반영한다. +7. `python3 scripts/sync_plans.py`로 `Plans.md`를 재생성하고 `python3 scripts/validate_tasks.py`로 확인한다. + +## 규칙 + +- proposal은 확정본이 아니다. 검증 전에는 `tasks/index.json`을 수정하지 않는다. +- `.harness/events/planning.jsonl`의 사용자-facing 메시지는 쉬운 문장으로 남긴다. +- 새 Task는 `agents/task-decomposer.md`의 INVEST·DoD·Acceptance 기준과 + `agents/quality-gates.md`의 scope/YAGNI 기준을 만족해야 한다. diff --git a/.agents/skills/harness-progress/SKILL.md b/.agents/skills/harness-progress/SKILL.md new file mode 100644 index 0000000..dd0eafe --- /dev/null +++ b/.agents/skills/harness-progress/SKILL.md @@ -0,0 +1,20 @@ +--- +name: harness-progress +description: tasks/index.json 기준으로 진행 상황을 읽기 전용 요약한다. 상태 확인, 진행률, 다음 작업 추천 요청 시 사용. +--- + +# harness-progress + +`tasks/index.json`을 단일 출처로 진행 상황을 요약한다. 기본적으로 상태를 변경하지 않는다. + +## 절차 + +1. `AGENTS.md`, `CLAUDE.md`, `tasks/index.json`을 읽는다. +2. 필요하면 `python3 scripts/report_tasks.py`를 실행한다. +3. `todo`, `wip`, `blocked`, `done` 수와 다음에 착수 가능한 Task를 요약한다. +4. `Plans.md`가 stale일 가능성이 있으면 `python3 scripts/sync_plans.py --check` 결과를 보고한다. + +## 규칙 + +- 사용자가 명시적으로 요청하지 않으면 `Plans.md`를 재생성하지 않는다. +- Task 상태를 바꾸지 않는다. diff --git a/.agents/skills/harness-review/SKILL.md b/.agents/skills/harness-review/SKILL.md new file mode 100644 index 0000000..60b0e07 --- /dev/null +++ b/.agents/skills/harness-review/SKILL.md @@ -0,0 +1,24 @@ +--- +name: harness-review +description: 현재 diff를 Task, CLAUDE.md 규칙, Acceptance evidence 기준으로 코드 리뷰한다. 리뷰 요청이나 PR 전 점검 시 사용. +--- + +# harness-review + +Codex에서 Claude Code `/harness-review`에 해당하는 리뷰 절차를 수행한다. + +## 절차 + +1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, 대상 Task, Acceptance evidence, 현재 diff를 읽는다. +2. 코드 리뷰 관점으로 버그, 회귀 위험, 누락된 테스트, 규칙 위반, `agents/quality-gates.md` 위반을 우선 찾는다. +3. findings를 심각도순으로 먼저 보고하고, 각 항목은 파일·라인 근거를 포함한다. +4. 문제가 없으면 "발견 없음"을 명확히 말하고 남은 테스트 gap이나 잔여 위험만 짧게 남긴다. + +## 판정 + +- `APPROVE`: blocker 없음, Acceptance evidence가 충분함. +- `REQUEST_CHANGES`: 동작 버그, 규칙 위반, Acceptance 미실행/실패, 테스트 누락이 Task 완료를 막음. + +리뷰 중 직접 수정하지 않는다. 수정이 필요하면 findings를 근거로 구현 단계로 되돌린다. +findings는 `agents/quality-gates.md`의 review/reporting gate처럼 먼저 보고하고, +문제가 없으면 테스트 gap과 잔여 위험만 짧게 남긴다. diff --git a/.agents/skills/harness-sync/SKILL.md b/.agents/skills/harness-sync/SKILL.md new file mode 100644 index 0000000..75ed547 --- /dev/null +++ b/.agents/skills/harness-sync/SKILL.md @@ -0,0 +1,20 @@ +--- +name: harness-sync +description: tasks/index.json을 검증하고 Plans.md snapshot을 재생성한다. 계획 동기화, snapshot 갱신 요청 시 사용. +--- + +# harness-sync + +`tasks/index.json`을 검증하고 `Plans.md` 읽기용 snapshot을 최신화한다. + +## 절차 + +1. `AGENTS.md`, `CLAUDE.md`, `tasks/index.json`, `Plans.md`를 읽는다. +2. `python3 scripts/validate_tasks.py`를 실행한다. +3. 검증이 통과하면 `python3 scripts/sync_plans.py`를 실행한다. +4. 다시 `python3 scripts/sync_plans.py --check`로 동기화 여부를 확인한다. + +## 규칙 + +- `Plans.md`는 생성물이다. 직접 편집하지 않는다. +- 검증 실패 시 `Plans.md`를 갱신하지 말고 실패 원인과 수정 필요 지점을 보고한다. diff --git a/.agents/skills/harness-work/SKILL.md b/.agents/skills/harness-work/SKILL.md new file mode 100644 index 0000000..9e97749 --- /dev/null +++ b/.agents/skills/harness-work/SKILL.md @@ -0,0 +1,28 @@ +--- +name: harness-work +description: todo Task 하나를 선택해 세분화 게이트를 확인하고 구현, Acceptance, 테스트, 리뷰까지 진행한다. Task 구현 요청 시 사용. +--- + +# harness-work + +Codex에서 Claude Code `/harness-work`에 해당하는 절차를 직접 수행한다. + +## 절차 + +1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `.harness/STATE.md`, 최근 `.harness/LESSONS.md`, `tasks/index.json`, `Plans.md`를 읽는다. +2. 수행할 `todo` Task 하나를 고른다. 사용자가 지정한 Task가 있으면 그 Task를 우선한다. +3. 구현 전 `agents/task-decomposer.md`의 세분화 기준과 `agents/quality-gates.md`의 scope/YAGNI 체크를 확인한다. +4. 기준 미달이면 구현하지 말고 `$harness-plan` 절차로 하위 Task proposal을 만든다. +5. 기준 통과 시 `.harness/STATE.md`를 갱신하고 구현한다. +6. 작업 중 범위가 커지면 중단하고 `agents/quality-gates.md`의 split 조건과 task-decomposer 기준으로 재분해한다. +7. 구현 후 `agents/test-agent.md` 절차대로 해당 Task Acceptance 명령과 관련 테스트 스위트를 실행한다. +8. 검증 실패 시 수정 후 재실행한다. +9. 검증 통과 후 `$harness-review` 절차로 현재 diff를 리뷰한다. + +## 완료 기준 + +- Acceptance와 관련 테스트가 통과해야 한다. +- GitHub 모드에서는 PR 안에서 Task를 `done`으로 바꾸지 않는다. merge 후 `plans-complete.yml`이 전환한다. +- 새 파일이나 역할 변경은 `.harness/CONTEXT_INDEX.md`에 반영한다. +- ponytail/caveman Codex plugin 자동 동작을 가정하지 않는다. Codex에서는 + `agents/quality-gates.md`를 직접 적용한다. diff --git a/.agents/skills/pr-create/SKILL.md b/.agents/skills/pr-create/SKILL.md new file mode 100644 index 0000000..3c03706 --- /dev/null +++ b/.agents/skills/pr-create/SKILL.md @@ -0,0 +1,24 @@ +--- +name: pr-create +description: 현재 작업 브랜치에서 GitHub PR을 작성한다. PR 생성, draft PR 작성, Task 기반 PR 본문 작성 요청 시 사용. +--- + +# pr-create + +현재 작업 브랜치에서 GitHub PR을 작성한다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`를 확인한다. +2. 현재 브랜치가 `main`/`master`면 PR을 만들지 않는다. +3. 커밋되지 않은 변경분이 있으면 커밋이 필요하다고 보고하고 중단한다. +4. 대상 Task를 `tasks/index.json`에서 확인한다. +5. PR 본문에 변경 요약, 검증 결과, DoD/Acceptance evidence, 남은 위험을 포함한다. +6. Task의 `gh` 값이 `#N`이면 `Closes #N`을 포함한다. +7. 기본은 `gh pr create --draft`다. 사용자가 ready PR을 명시하면 draft를 생략할 수 있다. +8. 생성 후 PR URL과 남은 merge gate를 보고한다. + +## 제한 + +- Acceptance evidence가 없거나 리뷰가 `REQUEST_CHANGES`면 PR 생성 전 중단한다. +- GitHub 모드에서는 PR 안에서 Task를 `done`으로 바꾸지 않는다. diff --git a/.claude/commands/branch-checkout.md b/.claude/commands/branch-checkout.md new file mode 100644 index 0000000..ac2f81f --- /dev/null +++ b/.claude/commands/branch-checkout.md @@ -0,0 +1,24 @@ +--- +description: Create or switch to a dedicated task branch after checking repository state. +allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git switch:*), Bash(git fetch:*), Read +--- + +# /branch-checkout + +별도 작업 브랜치를 만들거나 체크아웃한다. 사용자가 지정한 브랜치명이 있으면 사용하고, +없으면 대상 Task ID와 제목을 바탕으로 `task/{task-id}-{short-slug}` 형식을 제안한다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`로 현재 상태를 확인한다. +2. 변경분이 있으면 사용자 변경을 덮지 않도록 요약하고, 그대로 브랜치를 전환해도 되는지 확인한다. +3. 필요하면 `git fetch origin`으로 원격 기준을 최신화한다. +4. 기존 브랜치면 `git switch {branch}`를 실행한다. +5. 새 브랜치면 기본 브랜치 기준을 확인한 뒤 `git switch -c {branch}`를 실행한다. +6. 전환 후 현재 브랜치와 남은 변경분을 보고한다. + +## 주의 + +- `git checkout --`, `git reset --hard`, 강제 push는 실행하지 않는다. +- Task 브랜치는 `CLAUDE.md`의 GitHub 플로우에 맞춰 `task/{task-id}-{짧은-설명}`을 선호한다. +- 인자: `$ARGUMENTS` diff --git a/.claude/commands/git-push.md b/.claude/commands/git-push.md new file mode 100644 index 0000000..eadd745 --- /dev/null +++ b/.claude/commands/git-push.md @@ -0,0 +1,24 @@ +--- +description: Push the current branch safely after checking status, branch, and upstream. +allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git remote:*), Bash(git push:*), Read +--- + +# /git-push + +현재 브랜치를 원격에 push한다. push 전에 브랜치, 변경분, upstream을 확인하고 +강제 push는 하지 않는다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`를 확인한다. +2. 현재 브랜치가 `main`/`master`면 push하지 말고 사용자에게 확인을 요청한다. +3. 커밋되지 않은 변경분이 있으면 push 대상이 아님을 알리고 중단한다. +4. upstream이 있으면 `git push`를 실행한다. +5. upstream이 없으면 `git push -u origin {current-branch}`를 실행한다. +6. push 결과와 다음 단계(PR 작성 여부)를 보고한다. + +## 주의 + +- `--force`, `--force-with-lease`는 사용하지 않는다. +- 인증 실패나 remote 없음은 원문 에러를 보고하고 멈춘다. +- 인자: `$ARGUMENTS` diff --git a/.claude/commands/pr-create.md b/.claude/commands/pr-create.md new file mode 100644 index 0000000..2dece5d --- /dev/null +++ b/.claude/commands/pr-create.md @@ -0,0 +1,25 @@ +--- +description: Create a GitHub pull request from the current task branch with task and acceptance context. +allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*), Bash(gh pr create:*), Bash(gh pr view:*), Read +--- + +# /pr-create + +현재 작업 브랜치에서 GitHub PR을 작성한다. PR 본문에는 Task, DoD, Acceptance evidence, +리뷰 상태, 이슈 연결 정보를 포함한다. + +## 절차 + +1. `git status --short`와 `git branch --show-current`를 확인한다. +2. 현재 브랜치가 `main`/`master`면 PR을 만들지 않는다. +3. 커밋되지 않은 변경분이 있으면 PR 생성 전에 커밋 필요 여부를 보고하고 중단한다. +4. 대상 Task를 `tasks/index.json`에서 확인하고, `gh`가 `#N`이면 PR 본문에 `Closes #N`을 넣는다. +5. Acceptance와 관련 테스트 실행 증거를 PR 본문에 요약한다. +6. `gh pr create --draft`를 기본으로 사용한다. 사용자가 ready PR을 명시하면 draft를 생략할 수 있다. +7. 생성 후 PR URL과 남은 merge gate를 보고한다. + +## 주의 + +- `REQUEST_CHANGES` 상태이거나 Acceptance evidence가 없으면 PR 생성 전 중단한다. +- GitHub 모드에서는 PR 안에서 Task를 `done`으로 바꾸지 않는다. +- 인자: `$ARGUMENTS` diff --git a/.harness/CONTEXT_INDEX.md b/.harness/CONTEXT_INDEX.md index 2002ee6..eaa60ce 100644 --- a/.harness/CONTEXT_INDEX.md +++ b/.harness/CONTEXT_INDEX.md @@ -23,9 +23,13 @@ | `.harness/shared/planning/latest.json` | 최신 planning run의 context/proposal/report 위치 | 최신 task-decomposer proposal 확인 시 | | `.harness/shared/planning/runs/` | run별 context.json·proposed-tasks.json·decomposition-report.md 작업대 | 특정 planning run 감사 시 | | `CLAUDE.md` | 프로젝트 규칙 (기획·구현·테스트·리뷰·상태 문서) | 규칙 확인 시 | +| `AGENTS.md` | Codex 진입점. CLAUDE.md 규칙을 Codex 세션에서 동일 절차로 실행하기 위한 호환 지침 | Codex 환경 구성·규칙 확인 시 | +| `.agents/skills/` | Codex repo-scoped skills (`$grill-me`, `$harness-plan`, `$harness-work`, `$harness-review`, `$harness-progress`, `$harness-sync`, `$branch-checkout`, `$git-push`, `$pr-create`) | Codex skill 호출 UX·절차 수정 시 | +| `.claude/commands/` | Claude Code local custom commands (`/branch-checkout`, `/git-push`, `/pr-create`) | Claude command 호출 UX·절차 수정 시 | | `harness.toml` | harness 플러그인 설정 ([plan]·[test]·[review]) | 설정 변경 시 | | `BLUEPRINT.md` | 시스템 전체 아키텍처 설명 (읽기용) | 구조 이해 필요 시 | | `README.md` | 템플릿 사용법 (외부 사용자용) | 문서 갱신 시 | +| `agents/quality-gates.md` | Claude/Codex 공통 scope·YAGNI·review·reporting 게이트. ponytail/caveman 원칙을 repo 규칙으로 적용 | 구현·리뷰·Codex skill 절차 수정 시 | | `agents/task-decomposer.md` | Task 세분화 기준·게이트 정의 | 계획/게이트 실행 시 | | `agents/test-agent.md` | 런타임 검증 절차 정의 | worker 완료 후 | | `.github/workflows/plans-guard.yml` | header-check·WIP 확인·diff 보호·depends 검증·Acceptance Oracle·세분화 CI (6잡) | CI 수정 시 | @@ -37,6 +41,7 @@ | `docs/templates/` | 기획 문서 골격 4종 (PRD·UserFlow·DESIGN·Architecture) | 새 기획 착수 시 | | `docs/github-integration.md` | GitHub 연동 상세 가이드 (branch protection·CI 잡 6종·plans-complete 동작) | GitHub 연동 설정 시 | | `docs/specs/2026-07-04-template-audit.md` | 템플릿 빈틈 감사 보고서 (H1~H5·M1~M8·L1~L5), Week 3 Task 매핑 근거 (L1~L5는 Plans.md Week 4 Task 4.1~4.6로 전환됨) | 감사 배경 확인 시 | +| `docs/specs/2026-07-08-codex-claude-quality-gates.md` | ponytail/caveman Claude-only enhancement와 Codex quality-gates 적용 경계 기록 | 품질 게이트 설계 배경 확인 시 | | `docs/claude-code-hooks.md` | hooks 미설정 현황 + 권장 hooks 예시, harness.toml [safety.permissions]와 역할 분담 | hooks 추가 검토 시 | | `docs/session-recovery.md` | `.harness/` 재개 절차 심화 (파일별 역할·읽는 순서·실제 형식·다중 프로젝트 시나리오) | 세션 복구 절차 상세 확인 시 | | `docs/error-memory.md` | `LOG.md`/`LESSONS.md` 작성 규칙·실제 형식·CLAUDE.md 승격 기준 | 에러 기록 규칙 확인 시 | diff --git a/.harness/LESSONS.md b/.harness/LESSONS.md index 84c259e..e53ea3e 100644 --- a/.harness/LESSONS.md +++ b/.harness/LESSONS.md @@ -90,3 +90,10 @@ - **교훈**: 모니터/훅이 주는 상태 요약은 참고만 하고, 실제 상태는 Plans.md와 `git status`로 직접 확인한 뒤 판단한다. - **CLAUDE.md 반영**: 불필요 (일회성 판단 습관). +## 2026-07-08 — Task status 변경은 Task ID context와 함께 패치할 것 + +- `tasks/index.json`에는 `"status": "todo"` 같은 반복 문자열이 많다. 상태를 바꿀 때 + 단일 status 줄만 패치하면 다른 Task가 변경될 수 있다. +- 예방 규칙: status 패치는 반드시 `"id": "{task-id}"`와 title/acceptance 일부를 + 포함한 context hunk로 적용하고, 직후 `grep -n '"id": "{task-id}"' -A8`로 대상 + Task 상태를 확인한다. diff --git a/.harness/LOG.md b/.harness/LOG.md index 79a722b..a51a2de 100644 --- a/.harness/LOG.md +++ b/.harness/LOG.md @@ -105,3 +105,48 @@ - 검증: `python3 -m unittest tests.test_tasks tests.test_planning -v` PASS(18), `python3 scripts/validate_tasks.py` PASS, `python3 scripts/sync_plans.py --check` PASS, `init.sh` smoke test PASS. + +## 2026-07-08 — Codex repo-scoped harness skills + +- 사용자 제공 계획에 따라 `.agents/skills/` 아래 Codex skill 6종 추가: + `grill-me`, `harness-plan`, `harness-work`, `harness-review`, + `harness-progress`, `harness-sync`. +- `AGENTS.md`, `README.md`, `BLUEPRINT.md`를 `$grill-me`/`$harness-*` 호출 + 방식으로 갱신하고, `init.sh`가 `.agents/skills`와 planning proposal scripts를 + 새 프로젝트에 복사하도록 수정. +- `.agents/skills` 디렉터리가 샌드박스에서 read-only로 잡혀 최초 `mkdir -p`가 + `Read-only file system`으로 실패. 승인된 escalated command로 디렉터리를 생성한 + 뒤 `apply_patch`로 파일을 추가해 해결. +- 검증: skill 6개 존재 확인, frontmatter 확인, `python3 scripts/validate_tasks.py` + PASS, `python3 scripts/validate_tasks.py --root templates/skeleton` PASS, + `python3 scripts/sync_plans.py --check` PASS, skeleton sync check PASS, + `init.sh /tmp/cc-harness-skill-test.iB2C65` smoke test PASS, + `python3 -m unittest tests.test_tasks tests.test_planning -v` PASS(18). + +## 2026-07-08 — Git workflow helper command/skill + +- Claude Code local custom command 3종 추가: + `.claude/commands/branch-checkout.md`, `.claude/commands/git-push.md`, + `.claude/commands/pr-create.md`. +- Codex repo-scoped skill 3종 추가: + `.agents/skills/branch-checkout/SKILL.md`, `.agents/skills/git-push/SKILL.md`, + `.agents/skills/pr-create/SKILL.md`. +- 각 절차는 `git status`와 현재 브랜치를 먼저 확인하고, local changes discard와 + force push를 금지하도록 작성. +- `init.sh`, `README.md`, `BLUEPRINT.md`, `AGENTS.md`, `docs/setup-guide.md`, + context index, `tasks/index.json`, `Plans.md` 갱신. +- 검증: skill frontmatter PASS, command 파일 존재 확인 PASS, + `python3 scripts/validate_tasks.py` PASS, skeleton validate PASS, + `python3 scripts/sync_plans.py --check` PASS, skeleton sync check PASS, + `python3 -m unittest tests.test_tasks tests.test_planning -v` PASS(18), + `init.sh /tmp/cc-harness-git-helper-test.9j00Yd` smoke test PASS. +## 2026-07-08 12:20 KST — Task status patch target mistake + +- 상황: Task `4.10`을 완료 처리하려고 `"status": "todo"` 단일 패턴을 패치했더니 + 첫 번째 TODO였던 `4.1`이 잘못 `done`으로 변경됐다. +- 원인: `apply_patch` context가 Task ID를 포함하지 않아 동일한 status 문자열 중 + 첫 매칭에 적용됐다. +- 조치: `grep -n '"id": "4\.' -A7 tasks/index.json`으로 상태를 확인했고, + `4.1`은 `todo`로 복구, `4.10`만 `done`으로 전환했다. +- 검증: `python3 scripts/sync_plans.py`, `python3 scripts/validate_tasks.py`, + `python3 scripts/sync_plans.py --check`, 전체 unittest 재실행 모두 PASS. diff --git a/.harness/STATE.md b/.harness/STATE.md index 8dec0a5..70c7da4 100644 --- a/.harness/STATE.md +++ b/.harness/STATE.md @@ -6,20 +6,32 @@ ## 현재 목표 -Planning observability v1 적용: 독립 task-decomposer proposal 기본 흐름, -비개발자 친화 planning JSONL 로그, proposal 검증/적용 스크립트, 문서 규약 반영. +Claude/Codex 공용 Quality Gate 정리 완료: ponytail/caveman의 핵심 원칙을 +`agents/quality-gates.md`로 흡수하고, Codex skill·Claude/Codex 문서·init +골격·Task snapshot에 같은 기준을 연결한다. ## 진행 중인 Task -- 사용자 요청 기반 직접 작업. `tasks/index.json`의 기존 Week 4 TODO 상태는 변경하지 않음. +- Task `4.10` 완료. GitHub 미연동 모드 기준으로 `tasks/index.json` status를 `done`으로 전환하고 `Plans.md` 재생성 완료. ## 마지막 검증 결과 +- Task `4.10` Acceptance **PASS**: + `test -f docs/specs/2026-07-08-codex-claude-quality-gates.md && test -f agents/quality-gates.md && grep -q 'YAGNI' agents/quality-gates.md && grep -q 'caveman' README.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-work/SKILL.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-review/SKILL.md` - `python3 -m unittest tests.test_tasks tests.test_planning -v` **PASS** (18 tests) - `python3 scripts/validate_tasks.py` **PASS** (`tasks/index.json valid`) +- `python3 scripts/validate_tasks.py --root templates/skeleton` **PASS** (`tasks/index.json valid`) - `python3 scripts/sync_plans.py --check` **PASS** (`Plans.md in sync`) -- `init.sh` smoke test **PASS**: `/tmp/harness-init-test.cZ7eqd`에 새 `.harness/shared/planning/runs/` - 및 `.harness/events/` 골격 복사 확인 +- `python3 scripts/sync_plans.py --root templates/skeleton --check` **PASS** (`Plans.md in sync`) +- init smoke test **PASS**: `/tmp/cc-harness-quality-gate-test.G576HW`에 + `agents/quality-gates.md`, `.agents/skills/{harness-work,harness-review}/SKILL.md`, + `AGENTS.md`, `CLAUDE.md` 복사 확인 +- `.agents/skills` frontmatter check **PASS** (9개 `SKILL.md`) +- Claude command existence check **PASS** (`branch-checkout`, `git-push`, `pr-create`) +- Codex Git skill existence check **PASS** (`branch-checkout`, `git-push`, `pr-create`) +- `init.sh` smoke test **PASS**: `/tmp/cc-harness-git-helper-test.9j00Yd`에 + `.claude/commands/*`, `.agents/skills/{branch-checkout,git-push,pr-create}/SKILL.md`, + `AGENTS.md`, `CLAUDE.md` 복사 확인 ## 차단 요소 @@ -32,8 +44,8 @@ Planning observability v1 적용: 독립 task-decomposer proposal 기본 흐름, `603fcc0`(3.6) → `0c8ea99`(3.4) → `03d185f`(3.5) → `2594119`(3.7) → `2dd1d8b`(3.8) → `11aa504`(3.9) → `d5117bc`(3.10) → `2b9a6d8`(3.11) → `6667307`(3.12) -- 현재 planning observability 변경분은 **아직 커밋 안 됨**. +- 현재 planning observability, Codex skill, Git helper command/skill 변경분은 **아직 커밋 안 됨**. ## 최종 갱신 -- 2026-07-08, planning observability v1 구현 및 검증 완료 +- 2026-07-08 12:22 KST, Quality Gate 작업 구현·검증·리뷰 완료 diff --git a/.harness/shared/planning/latest.json b/.harness/shared/planning/latest.json new file mode 100644 index 0000000..5e5c36d --- /dev/null +++ b/.harness/shared/planning/latest.json @@ -0,0 +1,7 @@ +{ + "run_id": "plan-20260708-quality-gates", + "updated_at": "2026-07-08T13:12:44+09:00", + "context": ".harness/shared/planning/runs/plan-20260708-quality-gates/context.json", + "proposal": ".harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json", + "report": ".harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md" +} diff --git a/.harness/shared/planning/runs/plan-20260708-quality-gates/context.json b/.harness/shared/planning/runs/plan-20260708-quality-gates/context.json new file mode 100644 index 0000000..2ac9827 --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-quality-gates/context.json @@ -0,0 +1,265 @@ +{ + "run_id": "plan-20260708-quality-gates", + "created_at": "2026-07-08T13:12:44+09:00", + "request": "Claude/Codex 공용 Quality Gate 정리: 계획 문서 작성, agents/quality-gates.md 추가, Codex harness skills와 README/BLUEPRINT/AGENTS.md/init skeleton 연결, tasks/Plans 반영", + "documents": [ + { + "label": "PRD", + "path": "docs/PRD.md", + "exists": false + }, + { + "label": "User Flow", + "path": "docs/UserFlow.md", + "exists": false + }, + { + "label": "Design", + "path": "docs/DESIGN.md", + "exists": false + }, + { + "label": "Architecture", + "path": "docs/Architecture.md", + "exists": false + } + ], + "existing_tasks": [ + { + "id": "0.1", + "title": "PRD 작성 (`/grill-me` 인터뷰)", + "status": "done", + "section": "완료된 작업" + }, + { + "id": "0.2", + "title": "기획 보완 문서", + "status": "done", + "section": "완료된 작업" + }, + { + "id": "0.3", + "title": "Harness 초기화", + "status": "done", + "section": "완료된 작업" + }, + { + "id": "0.4", + "title": "Plugin 설정", + "status": "done", + "section": "완료된 작업" + }, + { + "id": "1.0", + "title": "Plans.md 템플릿 개선", + "status": "done", + "section": "Week 1 — 템플릿 개선" + }, + { + "id": "1.1", + "title": "test agent 추가", + "status": "done", + "section": "Week 1 — 템플릿 개선" + }, + { + "id": "1.2", + "title": "기획 파이프라인 추가", + "status": "done", + "section": "Week 1 — 템플릿 개선" + }, + { + "id": "1.3", + "title": "task-decomposer + 세분화 게이트 추가", + "status": "done", + "section": "Week 1 — 템플릿 개선" + }, + { + "id": "1.4", + "title": ".harness/ 상태 문서 체계 추가", + "status": "done", + "section": "Week 1 — 템플릿 개선" + }, + { + "id": "2.1", + "title": "테스트 프로젝트 골격 생성", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.2", + "title": "기획 파이프라인 테스트 (grill-me 인터뷰)", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.3", + "title": "보완 문서 테스트 (UserFlow·Architecture 골격 적용)", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.4", + "title": "계획 파이프라인 테스트 (task-decomposer → Plans.md)", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.5", + "title": "템플릿 결함 기록", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.6", + "title": "DESIGN.md 기획 산출물 추가", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "2.7", + "title": "GitHub 연동 E2E 검증 + plans-complete 워크플로", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "3.1", + "title": "plans-complete branch protection 호환 (H1)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.2", + "title": "clean 골격 세트 분리 (H5)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.3", + "title": "init.sh 초기화 스크립트 (H5)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.4", + "title": "plans-guard diff 보호 잡 (H2)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.5", + "title": "plans-guard depends-check 잡 (H3)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.6", + "title": "Plans.md 헤더 검증 선행 파싱 (M1·M7)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.7", + "title": "완료 전환 서술 통일 (M3)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.8", + "title": "harness.toml 죽은 설정 정리 (M4)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.9", + "title": "Plans.md anti-pattern 예시 교정 (M2)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.10", + "title": "agents 문서 수행 주체 명시 (M5)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.11", + "title": "ci.yml 이름 고정 요약 잡 (M6)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.12", + "title": "플러그인 SHA 기록 절차 (M8)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "4.1", + "title": "granularity 오탐지 정규식 정확도 개선 (L1)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.2", + "title": "test-agent pretest 오탐 스택 감지 수정 (L2)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.3", + "title": "CONTEXT_INDEX.md 미존재 파일 인덱스 정리 (L3)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.4", + "title": "rm 위험 패턴 매칭 범위 확대 (L4)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.5", + "title": "grill-me 산출 경로 인자 지원 (L5)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.6", + "title": "grill-me 비대화형 실행 호환 모드 (L5)", + "status": "todo", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.7", + "title": "Codex 호환 진입점 추가", + "status": "done", + "section": "Week 4 — Codex 호환 환경 구성" + }, + { + "id": "4.8", + "title": "Codex harness skills 추가", + "status": "done", + "section": "Week 4 — Codex 호환 환경 구성" + }, + { + "id": "4.9", + "title": "Git workflow helper command/skill 추가", + "status": "done", + "section": "Week 4 — Codex 호환 환경 구성" + } + ], + "rules": { + "task_decomposer": "agents/task-decomposer.md", + "task_state_source": "tasks/index.json", + "readable_plan": "Plans.md" + }, + "outputs": { + "run_dir": ".harness/shared/planning/runs/plan-20260708-quality-gates", + "proposal": ".harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json", + "report": ".harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md" + }, + "technical": { + "schema_version": 1, + "proposal_dir": ".harness/shared/planning" + } +} diff --git a/.harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md b/.harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md new file mode 100644 index 0000000..9e4323e --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-quality-gates/decomposition-report.md @@ -0,0 +1,22 @@ +# Quality Gate Task Proposal + +## 완료 기준 + +- Claude-only plugin enhancement인 ponytail/caveman과 Codex 공통 품질 규칙의 경계를 문서화한다. +- `agents/quality-gates.md`를 공통 절차 문서로 추가한다. +- Codex harness skills가 구현 전 scope/YAGNI 체크와 리뷰 findings 기준을 같은 문서에서 참조한다. +- README, BLUEPRINT, AGENTS, init skeleton, context index가 새 품질 게이트의 역할을 설명한다. + +## 확인 방법 + +- proposal의 Acceptance 명령은 계획 문서와 품질 게이트 파일 존재를 확인한다. +- `YAGNI`, `caveman`, `agents/quality-gates.md` 핵심 연결 문구를 grep으로 확인한다. +- 전체 Task 검증과 Plans sync check는 구현 후 별도로 실행한다. + +## 먼저 끝나야 할 작업 + +- Codex skill 골격이 있어야 연결할 수 있으므로 `4.8`을 Depends로 둔다. + +## 분해 판단 + +이 작업은 문서와 절차 연결만 다루며 런타임 기능 변경을 포함하지 않는다. 산출물이 하나의 품질 게이트 기준으로 묶여 있고 독립 acceptance가 있으므로 추가 분해하지 않는다. diff --git a/.harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json b/.harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json new file mode 100644 index 0000000..2376e47 --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-quality-gates/proposed-tasks.json @@ -0,0 +1,16 @@ +{ + "tasks": [ + { + "id": "4.10", + "title": "Claude/Codex 공용 Quality Gate 문서화", + "dod": "docs/specs/2026-07-08-codex-claude-quality-gates.md와 agents/quality-gates.md가 존재하고 Codex skill, README, BLUEPRINT, AGENTS, init skeleton이 quality gate 기준을 참조함", + "acceptance": "test -f docs/specs/2026-07-08-codex-claude-quality-gates.md && test -f agents/quality-gates.md && grep -q 'YAGNI' agents/quality-gates.md && grep -q 'caveman' README.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-work/SKILL.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-review/SKILL.md", + "depends": [ + "4.8" + ], + "status": "todo", + "gh": "-", + "section": "Week 4 — Codex 호환 환경 구성" + } + ] +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..381f436 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,98 @@ +# [PROJECT_NAME] — AGENTS.md + +Codex entrypoint for this harness template. Codex must operate from the same +project rules, task sources, and verification gates that Claude Code uses. + +## Read Order + +At the start of a session, read these files before planning or editing: + +1. `CLAUDE.md` +2. `harness.toml` +3. `tasks/index.json` +4. `Plans.md` +5. `BLUEPRINT.md` when architecture or command provenance matters + +On resumed work, follow the recovery order in `CLAUDE.md`: + +1. `.harness/STATE.md` +2. latest entries in `.harness/LESSONS.md` +3. `tasks/index.json` +4. `Plans.md` +5. only the extra files listed in `.harness/CONTEXT_INDEX.md` that are needed + +## Source Of Truth + +- `CLAUDE.md` is the canonical harness rulebook for planning, implementation, + testing, review, GitHub flow, and `.harness/` state documents. +- `tasks/index.json` is the task status source of truth. +- `Plans.md` is a generated human-readable snapshot. Do not edit it directly; + run `python3 scripts/sync_plans.py` after task JSON changes. +- `harness.toml` `[github]`, `[review]`, `[test]`, and `[plan]` sections are + summary indexes for the `CLAUDE.md` rules, not independently parsed runtime + configuration. +- `agents/quality-gates.md` is the shared scope, YAGNI, review, and reporting + gate. Claude Code may get ponytail/caveman as plugin enhancements, but Codex + must apply the same principles from this repo file directly. + +## Codex Compatibility Rules + +Claude Code slash commands and plugins may not exist in Codex. When a +`CLAUDE.md` workflow names a slash command, perform the equivalent repository +procedure directly: + +| Claude Code workflow | Codex equivalent | +|---|---| +| `/grill-me` | Use `$grill-me` from `.agents/skills/grill-me/SKILL.md` for the interview and PRD procedure. | +| `/harness-plan` | Use `$harness-plan` from `.agents/skills/harness-plan/SKILL.md` to build planning context, produce/validate a proposal, then apply it. | +| `/harness-work` | Use `$harness-work` from `.agents/skills/harness-work/SKILL.md` to select a `todo` task, enforce the task-decomposer gate, implement, verify, and review. | +| `/harness-review` | Use `$harness-review` from `.agents/skills/harness-review/SKILL.md` to review the diff against `CLAUDE.md`, the target task, and acceptance evidence. | +| `/harness-progress` | Use `$harness-progress` from `.agents/skills/harness-progress/SKILL.md` for read-only progress summaries. | +| `/harness-sync` | Use `$harness-sync` from `.agents/skills/harness-sync/SKILL.md` to validate `tasks/index.json` and regenerate `Plans.md`. | + +Do not assume the Claude Code plugin has performed any gate automatically. +Codex must execute the same gates explicitly. + +Do not assume ponytail or caveman plugins run in Codex. When a Claude workflow +relies on those plugins for scope control or terse reporting, use +`agents/quality-gates.md` instead. + +## Git Workflow Helpers + +| Claude Code command | Codex skill | +|---|---| +| `/branch-checkout` | `$branch-checkout` from `.agents/skills/branch-checkout/SKILL.md` | +| `/git-push` | `$git-push` from `.agents/skills/git-push/SKILL.md` | +| `/pr-create` | `$pr-create` from `.agents/skills/pr-create/SKILL.md` | + +These helpers must inspect `git status` and the current branch before changing +branches, pushing, or creating PRs. Never force push or discard local changes. + +## Mandatory Gates + +- Before adding or changing task rows, use the planning proposal contract in + `CLAUDE.md` and the scripts: + `build_planning_context.py`, `validate_task_proposal.py`, + `apply_task_proposal.py`, and `sync_plans.py`. +- Before implementation, confirm the selected task passes + `agents/task-decomposer.md` granularity criteria and + `agents/quality-gates.md` scope/YAGNI criteria. +- After implementation and before review, follow `agents/test-agent.md`: run + the task Acceptance command and the relevant project test suite. +- During review, apply `agents/quality-gates.md`: findings first, verification + evidence first, and only useful residual risk after approval. +- Do not mark a task `done` unless the Acceptance evidence has passed. In + GitHub mode, leave WIP-to-done conversion to `plans-complete.yml` after merge. + +## State Documents + +- Update `.harness/STATE.md` before risky work and after meaningful work units. +- Append errors and fixes to `.harness/LOG.md`; add durable prevention rules to + `.harness/LESSONS.md`. +- Update `.harness/CONTEXT_INDEX.md` when creating a file or changing a file's + role. + +## Response Language + +Use Korean for user-facing responses, unless the user requests otherwise. +Keep code, commands, filenames, and proper nouns unchanged. diff --git a/BLUEPRINT.md b/BLUEPRINT.md index 54a7fea..c941aad 100644 --- a/BLUEPRINT.md +++ b/BLUEPRINT.md @@ -1,4 +1,4 @@ -# BLUEPRINT.md — Claude Code Harness 시스템 구조 +# BLUEPRINT.md — Claude Code / Codex Harness 시스템 구조 > 이 문서는 설치된 harness 시스템이 어떻게 동작하는지 한눈에 파악하기 위한 설계도다. > 코드가 아니라 "각 레이어가 무슨 역할을 하고, 언제 발동되며, 어떻게 맞물리는가"를 설명한다. @@ -22,6 +22,13 @@ 세션이 시작되거나 프롬프트가 제출될 때 자동으로 동작하는 네 개의 플러그인. Claude Code가 관리하며, 이 프로젝트에만 한정되지 않고 모든 세션에 적용된다. +Codex에서는 이 플러그인 레이어가 자동 적용되지 않는다. 대신 루트 `AGENTS.md`가 +Codex 진입점으로 동작하며, `CLAUDE.md` 규약과 `agents/*.md` 절차, `scripts/` +검증 도구를 직접 실행해 동일한 planning/test/review/state 흐름을 맞춘다. +ponytail/caveman의 durable 원칙은 `agents/quality-gates.md`에 흡수한다. +Claude Code에서는 plugin enhancement가 이를 자동 보강할 수 있고, Codex에서는 +`.agents/skills/*`가 같은 파일을 직접 참조한다. + ### 1-1. claude-code-harness v4 (핵심 엔진) Harness 전체를 구동하는 엔진. `harness` 명령어로 직접 호출하거나, @@ -153,7 +160,8 @@ harness가 요청을 처리할 때 spawning하는 세 종류의 플러그인 에 agents/ ← 플러그인이 모르는 프로젝트 전용 절차 문서 ├── task-decomposer.md ← 계획 단계 세분화 + 구현 단계 게이트 (공용) -└── test-agent.md ← worker 완료 후 런타임 검증 +├── test-agent.md ← worker 완료 후 런타임 검증 +└── quality-gates.md ← scope/YAGNI + review/reporting 공통 기준 ``` > **M5 갱신 (2026-07-08) — `agents/*.md` 자체는 호출 가능한 Claude 서브에이전트가 아니다.** @@ -177,24 +185,28 @@ agents/ ← 플러그인이 모르는 프 | **caveman** (토큰 압축) | **lite** | OFF | OFF | | **VFF v2** (진단 구조) | 검증·코드 규율만 | **전체** | **전체** | | **VFF Hook** (드리프트 방지) | 전역 발동 | 전역 발동 | 전역 발동 | +| **quality-gates.md** (repo 기준) | scope/YAGNI | findings/reporting | scope/YAGNI | ### worker 구현 담당. `tasks/index.json`의 Task를 실제로 코드로 만드는 역할. - **caveman lite**: filler 제거, 문장 구조는 유지 → 간결하되 읽을 수 있는 응답 - **ponytail 전체**: 코드 작성 전 7단계 사다리 → MVP 범위 외 구현 금지 - **VFF 검증·코드 규율만**: 완료 선언 전 검증 의무 + 요청 범위 외 수정 금지 +- **quality-gates.md**: Codex에서도 같은 scope/YAGNI/split 조건을 직접 적용 ### reviewer 완료된 구현을 검토하는 역할. - **caveman OFF**: 판단 근거와 리뷰 내용은 압축하지 않는다 - **ponytail 전체**: 과도한 추상화·오버엔지니어링 지적 기준으로 활용 - **VFF v2 전체**: 단서 우선 진단, 확신도 표시, 핵심 변수 1~2개로 추천 +- **quality-gates.md**: findings-first, verification-first, 테스트 gap 보고 기준 ### advisor 방침과 설계 방향을 결정하는 역할. - **caveman OFF**: 설계 근거는 압축 없이 명확하게 - **ponytail 전체**: YAGNI 원칙 우선 적용 - **VFF v2 전체**: 의사결정 조언 시 핵심 변수 먼저, 일반론 나열 금지 +- **quality-gates.md**: 현재 Task 경계 안에서 가장 작은 실행 경로를 우선 --- @@ -207,8 +219,12 @@ harness 자체의 동작을 정의하는 파일들. ├── harness.toml ← 프로젝트명·버전·안전 규칙 정의 ├── .claude/ │ ├── settings.local.json ← 프로젝트 스코프 권한 설정 +│ ├── commands/ ← Git helper local commands (/branch-checkout 등) │ └── agent-memory/ ← 각 Agent MEMORY.md +├── .agents/ +│ └── skills/ ← Codex repo-scoped skills ($grill-me, $harness-work 등) ├── CLAUDE.md ← 프로젝트 전역 규칙 (기술 스택, 응답 포맷 등) +├── AGENTS.md ← Codex 진입점 (CLAUDE.md 규약을 Codex 절차로 실행) ├── tasks/index.json ← Task 상태 단일 출처 └── Plans.md ← 사람이 읽는 Task 로드맵 (JSON에서 생성) ``` @@ -331,9 +347,10 @@ GitHub → Settings → Branches → main: ### harness-work 실행 시 (`/harness-work`) — 구현 단계 ``` 6. harness가 `tasks/index.json`에서 `todo` Task 선택 -6-a. 세분화 게이트: 선택된 Task가 task-decomposer 기준 미달이면(DoD·Acceptance - 미기재, 뭉뚱그린 표현, 관심사 혼재 등) worker에게 넘기지 않고 task-decomposer를 - 다시 호출해 하위 Task(`{task-id}.N`)로 쪼갠 뒤에만 진행 +6-a. 세분화 + 품질 게이트: 선택된 Task가 task-decomposer 기준 또는 + `agents/quality-gates.md`의 scope/YAGNI 기준 미달이면(DoD·Acceptance + 미기재, 뭉뚱그린 표현, 관심사 혼재, 과잉 추상화 필요 등) worker에게 넘기지 + 않고 task-decomposer를 다시 호출해 하위 Task(`{task-id}.N`)로 쪼갠 뒤에만 진행 7. advisor에게 방침 요청 (caveman OFF + VFF v2) 8. worker에게 구현 위임 (caveman lite + ponytail + VFF 검증) └─ SubagentStart 훅 → ponytail이 worker에 자동 주입 @@ -366,6 +383,16 @@ GitHub → Settings → Branches → main: | `/caveman [lite\|full\|ultra]` | caveman 강도 수동 조절 | | `/itsvff` | VFF 세션 모드 수동 활성화 | | `/ponytail-review` | 현재 diff ponytail 기준 리뷰 | +| `/branch-checkout` | 별도 작업 브랜치 생성·전환 (로컬 custom command) | +| `/git-push` | 현재 브랜치 안전 push (로컬 custom command) | +| `/pr-create` | 현재 브랜치에서 draft PR 작성 (로컬 custom command) | + +Codex에서는 `/grill-me`와 `/harness-*` top-level slash command 대신 +`.agents/skills/`의 `$grill-me`, `$harness-plan`, `$harness-work`, +`$harness-review`, `$harness-progress`, `$harness-sync`를 사용한다. Git helper는 +`$branch-checkout`, `$git-push`, `$pr-create`를 사용한다. +Codex용 별도 `$ponytail`/`$caveman` skill은 제공하지 않는다. 해당 원칙은 +`agents/quality-gates.md`에서 공통 gate로 적용한다. --- @@ -386,4 +413,7 @@ VFF Hook ─────────────────────── harness ───────────────────────────────────────────▶ 전체 조율 `tasks/index.json`/Plans.md 기반으로 위 세 Agent를 오케스트레이션 + +quality-gates.md ─────────────────────────────────▶ Claude/Codex 공통 절차 + plugin 자동 동작이 없는 환경에서도 scope/YAGNI/review/reporting 기준 유지 ``` diff --git a/CLAUDE.md b/CLAUDE.md index bbb0d95..6cfb87e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -114,6 +114,10 @@ ## 구현 규칙 (세분화 게이트) +- **구현 전 `agents/quality-gates.md`를 scope/YAGNI 게이트로 함께 적용한다.** + ponytail이 설치된 Claude Code 세션에서는 plugin enhancement가 같은 원칙을 + 보강할 수 있지만, 저장소 기준은 이 파일이다. Codex는 ponytail/caveman 자동 + hook을 가정하지 않고 `AGENTS.md`와 `.agents/skills/*`에서 이 문서를 직접 참조한다. - **`/harness-work` 실행 전, `tasks/index.json`의 대상 `todo` Task가 전부 `agents/task-decomposer.md`의 세분화 기준을 통과했는지 먼저 확인한다.** 하나라도 미달(DoD·Acceptance 미기재, "전체/모든/및"으로 뭉뚱그린 표현, @@ -144,6 +148,8 @@ ## 리뷰 규칙 - **worker 완료 후 PR 오픈 전에 반드시 `/harness-review`를 실행한다.** +- 리뷰는 `agents/quality-gates.md`의 review/reporting gate를 따른다. findings를 + 먼저 보고하고, Acceptance·테스트 evidence와 잔여 risk를 짧게 남긴다. - `harness.toml`의 `[review] require_before_pr = true` 설정 시 harness가 자동 강제. - `/harness-work` 사용 시 step 9(자동 리뷰 스테이지)가 내장 실행됨 — 별도 호출 불필요. - `/harness-work` 없이 직접 구현한 경우: 커밋 후 PR 오픈 전 `/harness-review` 수동 실행. diff --git a/Plans.md b/Plans.md index 4f47744..61c6fe2 100644 --- a/Plans.md +++ b/Plans.md @@ -74,6 +74,17 @@ --- +## Week 4 — Codex 호환 환경 구성 + +| Task | 내용 | DoD | Acceptance | Depends | Status | GH | +|------|------|-----|------------|---------|--------|----| +| 4.7 | Codex 호환 진입점 추가 | AGENTS.md가 Codex 진입점으로 존재하고 init.sh가 새 프로젝트에 복사하며 README·BLUEPRINT에 Codex 동작 경로가 명시됨 | test -f AGENTS.md && grep -q 'AGENTS.md' init.sh && grep -q 'Recommended Codex Workflow' README.md | - | cc:완료 | - | +| 4.8 | Codex harness skills 추가 | .agents/skills 아래 harness 흐름 6종 SKILL.md가 존재하고 init.sh가 새 프로젝트에 복사함 | test -f .agents/skills/grill-me/SKILL.md && test -f .agents/skills/harness-plan/SKILL.md && test -f .agents/skills/harness-work/SKILL.md && test -f .agents/skills/harness-review/SKILL.md && test -f .agents/skills/harness-progress/SKILL.md && test -f .agents/skills/harness-sync/SKILL.md && grep -q '.agents/skills' init.sh | 4.7 | cc:완료 | - | +| 4.9 | Git workflow helper command/skill 추가 | Claude custom command와 Codex skill로 branch-checkout·git-push·pr-create 절차가 제공되고 init.sh가 복사함 | test $(find .claude/commands -name '*.md' \| wc -l) -ge 3 && test -f .agents/skills/branch-checkout/SKILL.md && test -f .agents/skills/git-push/SKILL.md && test -f .agents/skills/pr-create/SKILL.md && grep -q '.claude/commands' init.sh | 4.8 | cc:완료 | - | +| 4.10 | Claude/Codex 공용 Quality Gate 문서화 | docs/specs/2026-07-08-codex-claude-quality-gates.md와 agents/quality-gates.md가 존재하고 Codex skill, README, BLUEPRINT, AGENTS, init skeleton이 quality gate 기준을 참조함 | test -f docs/specs/2026-07-08-codex-claude-quality-gates.md && test -f agents/quality-gates.md && grep -q 'YAGNI' agents/quality-gates.md && grep -q 'caveman' README.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-work/SKILL.md && grep -q 'agents/quality-gates.md' .agents/skills/harness-review/SKILL.md | 4.8 | cc:완료 | - | + +--- +