diff --git a/.harness/events/planning.jsonl b/.harness/events/planning.jsonl new file mode 100644 index 0000000..d6785e0 --- /dev/null +++ b/.harness/events/planning.jsonl @@ -0,0 +1,2 @@ +{"step":"planning-context","result":"success","message":"README 개편 요청을 Task proposal로 만들 planning context를 생성했습니다.","next_action":"외부 decomposer 명령이 없어 inline fallback으로 proposal을 작성합니다.","technical":{"run_id":"plan-20260708-164729-fdf4d8","context":".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/context.json"}} +{"step":"decomposition","result":"success","message":"README 사용자 친화 개편을 독립 검증 가능한 단일 문서 Task로 제안했습니다.","next_action":"proposal 검증 후 tasks/index.json에 반영합니다.","technical":{"run_id":"plan-20260708-164729-fdf4d8","proposal":".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json","report":".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md"}} diff --git a/.harness/shared/planning/latest.json b/.harness/shared/planning/latest.json index 6d5667e..1cc4e32 100644 --- a/.harness/shared/planning/latest.json +++ b/.harness/shared/planning/latest.json @@ -1,7 +1,7 @@ { - "run_id": "plan-20260708-155019-c28b5b", - "updated_at": "2026-07-08T15:50:19+09:00", - "context": ".harness/shared/planning/runs/plan-20260708-155019-c28b5b/context.json", - "proposal": ".harness/shared/planning/runs/plan-20260708-155019-c28b5b/proposed-tasks.json", - "report": ".harness/shared/planning/runs/plan-20260708-155019-c28b5b/decomposition-report.md" + "run_id": "plan-20260708-164729-fdf4d8", + "updated_at": "2026-07-08T16:47:29+09:00", + "context": ".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/context.json", + "proposal": ".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json", + "report": ".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md" } diff --git a/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/context.json b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/context.json new file mode 100644 index 0000000..8bc4b8b --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/context.json @@ -0,0 +1,283 @@ +{ + "run_id": "plan-20260708-164729-fdf4d8", + "created_at": "2026-07-08T16:47:29+09:00", + "request": "README.md를 비개발자도 따라가기 쉬운 안내서로 개편한다. 첫 화면, Quick Start, Codex CLI Setup, 작업별 workflow 메뉴, Troubleshooting을 사용자 행동 순서 중심으로 정리한다.", + "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 검증", + "status": "done", + "section": "Week 2 — 템플릿 dogfooding (루틴 관리 SaaS로 실전 테스트, 커밋 제외)" + }, + { + "id": "3.1", + "title": "GitHub 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 상태 변경 보호 검토 기록 (H2)", + "status": "done", + "section": "Week 3 — 감사 빈틈 개선 (기준 문서: docs/specs/2026-07-04-template-audit.md)" + }, + { + "id": "3.5", + "title": "Depends 검증 경로 정리 (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": "세분화 기준 표현 정확도 개선 (L1)", + "status": "done", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.2", + "title": "test-agent pretest 오탐 스택 감지 수정 (L2)", + "status": "done", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.3", + "title": "CONTEXT_INDEX.md 미존재 파일 인덱스 정리 (L3)", + "status": "done", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.4", + "title": "rm 위험 패턴 매칭 범위 확대 (L4)", + "status": "done", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.5", + "title": "grill-me 산출 경로 인자 지원 (L5)", + "status": "done", + "section": "Week 4 — 백로그 정리 (기준 문서: docs/specs/2026-07-04-template-audit.md L1~L5)" + }, + { + "id": "4.6", + "title": "grill-me 비대화형 실행 호환 모드 (L5)", + "status": "done", + "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 호환 환경 구성" + }, + { + "id": "4.10", + "title": "Claude/Codex 공용 Quality Gate 문서화", + "status": "done", + "section": "Week 4 — Codex 호환 환경 구성" + }, + { + "id": "4.11", + "title": "rescue-from-main workflow helper 추가", + "status": "done", + "section": "Week 4 — Codex 호환 환경 구성" + }, + { + "id": "4.12", + "title": "Task별 .harness 맥락 디렉토리 도입", + "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-164729-fdf4d8", + "proposal": ".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json", + "report": ".harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md" + }, + "technical": { + "schema_version": 1, + "proposal_dir": ".harness/shared/planning" + } +} diff --git a/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md new file mode 100644 index 0000000..5fb32ce --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/decomposition-report.md @@ -0,0 +1,27 @@ +# Decomposition Report — README 사용자 친화 개편 + +## 완료 기준 + +README를 처음 보는 사용자가 순서대로 읽으며 다음 결정을 할 수 있어야 한다. + +- Claude Code만 쓸지, Codex도 함께 쓸지 먼저 고른다. +- 템플릿을 새 프로젝트에 복사하는 Quick Start를 바로 실행할 수 있다. +- Codex 사용자는 별도 CLI Setup 섹션에서 진입점과 필수 규칙을 확인할 수 있다. +- 기획, 구현, 리뷰, Git 작업별 workflow 메뉴에서 필요한 절차로 이동할 수 있다. +- 흔한 실패 상황은 Troubleshooting에서 먼저 확인할 수 있다. + +## 확인 방법 + +Acceptance는 README에 위 핵심 섹션 제목이 모두 존재하는지 확인한다. 문서 Task이므로 +기계 검증은 핵심 구조 존재를 확인하고, 내용 품질은 리뷰에서 문맥과 링크 기준으로 +확인한다. + +## 먼저 끝나야 할 작업 + +없다. 현재 repo checkout 안의 `README.md`만 주요 산출물이며, 기존 완료 Task의 +산출물을 전제로 읽기 쉽게 재배치하는 문서 변경이다. + +## 세분화 판단 + +한 파일의 외부 사용자 안내 구조를 바꾸는 단일 문서 산출물이다. 코드, CI, +런타임 동작, GitHub 설정 변경을 함께 묶지 않으므로 1 PR 이내 Task로 유지한다. diff --git a/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json new file mode 100644 index 0000000..b89c46c --- /dev/null +++ b/.harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json @@ -0,0 +1,14 @@ +{ + "tasks": [ + { + "id": "4.13", + "title": "README 사용자 친화 개편", + "dod": "README.md가 첫 화면, Quick Start, Codex CLI Setup, 작업별 workflow 메뉴, Troubleshooting을 사용자 행동 순서로 설명함", + "acceptance": "grep -q '## 먼저 고를 것' README.md && grep -q '## Quick Start' README.md && grep -q '## Codex CLI Setup' README.md && grep -q '## 작업별 Workflow' README.md && grep -q '## Troubleshooting' README.md", + "depends": [], + "status": "todo", + "gh": "-", + "section": "Week 4 — Codex 호환 환경 구성" + } + ] +} diff --git a/.harness/tasks/readme-user-friendly/LOG.md b/.harness/tasks/readme-user-friendly/LOG.md index b8e1244..93374ee 100644 --- a/.harness/tasks/readme-user-friendly/LOG.md +++ b/.harness/tasks/readme-user-friendly/LOG.md @@ -6,3 +6,12 @@ 해당 작업은 별도 Task 없이 시작된 뒤 중단됐다. - 이번 `4.12`에서는 해당 문구를 루트 템플릿에서 제거하고 이 Task별 디렉토리로 이관했다. - README 개편은 후속 Task로 남긴다. + +## 2026-07-08 + +- `4.13` README 사용자 친화 개편 Task를 planning proposal로 추가했다. +- proposal 검증, 적용, `tasks/index.json`/`Plans.md` sync 검증을 통과했다. +- `4.13` 상태를 `wip`로 전환하고 README 편집을 시작한다. +- README 앞부분에 `먼저 고를 것`, `Quick Start`, `Codex CLI Setup`, `작업별 Workflow`를 추가하고 기존 중복 Quick Start를 제거했다. +- 기존 `Troubleshooting`에 Codex command/quality-gate 관련 항목을 보강했다. +- Acceptance는 통과했고, 감지된 프로젝트 테스트 스위트는 없어 skip했다. diff --git a/.harness/tasks/readme-user-friendly/STATE.md b/.harness/tasks/readme-user-friendly/STATE.md index 07c30bb..a9a92b0 100644 --- a/.harness/tasks/readme-user-friendly/STATE.md +++ b/.harness/tasks/readme-user-friendly/STATE.md @@ -6,17 +6,22 @@ ## 진행 중인 Task -- 현재 `tasks/index.json`에는 이 README 개편 전용 Task가 없다. -- 상태: 후순위로 미룸 -- 이번 `4.12`에서는 README 개편 자체를 구현하지 않는다. +- Task: `4.13` README 사용자 친화 개편 +- 상태: `done` +- 세분화 게이트: 통과. 단일 문서 산출물이며 Acceptance가 주요 README 섹션 존재를 확인한다. +- scope/YAGNI 게이트: 통과. `README.md`와 Task 상태 문서/계획 산출물만 변경한다. ## 마지막 검증 결과 -- 없음. 작업 착수 직후 중단된 상태다. +- `python3 scripts/validate_task_proposal.py --proposal .harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json` 통과 +- `python3 scripts/apply_task_proposal.py --proposal .harness/shared/planning/runs/plan-20260708-164729-fdf4d8/proposed-tasks.json` 통과 +- `python3 scripts/validate_tasks.py && python3 scripts/sync_plans.py --check` 통과 +- Acceptance 통과: `grep -q '## 먼저 고를 것' README.md && grep -q '## Quick Start' README.md && grep -q '## Codex CLI Setup' README.md && grep -q '## 작업별 Workflow' README.md && grep -q '## Troubleshooting' README.md` +- 프로젝트 테스트 스위트: 감지된 스택 없음, skip ## 차단 요소 -- 별도 Task가 필요하다. +- 없음 ## 마지막 커밋 @@ -24,4 +29,4 @@ ## 최종 갱신 -- 2026-07-08 15:50 KST +- 2026-07-08 17:05 KST diff --git a/.harness/tasks/readme-user-friendly/TASKS.md b/.harness/tasks/readme-user-friendly/TASKS.md index de02f46..3c6e254 100644 --- a/.harness/tasks/readme-user-friendly/TASKS.md +++ b/.harness/tasks/readme-user-friendly/TASKS.md @@ -1,6 +1,6 @@ # TASKS.md — README 사용자 친화 개편 내부 체크리스트 -- [ ] README 개편 전용 Task 추가 -- [ ] 현재 README 구조 재확인 -- [ ] 사용자 행동 순서 기준으로 섹션 재배치 -- [ ] 문서 링크와 파일 존재 여부 검증 +- [x] README 개편 전용 Task 추가 +- [x] 현재 README 구조 재확인 +- [x] 사용자 행동 순서 기준으로 섹션 재배치 +- [x] 문서 링크와 파일 존재 여부 검증 diff --git a/Plans.md b/Plans.md index 5a00e97..8342fa1 100644 --- a/Plans.md +++ b/Plans.md @@ -84,6 +84,7 @@ | 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:완료 | - | | 4.11 | rescue-from-main workflow helper 추가 | Claude custom command와 Codex skill로 rescue-from-main 절차가 제공되고 AGENTS·README·BLUEPRINT·init 복사 경로에 등록됨 | test -f .agents/skills/rescue-from-main/SKILL.md && test -f .claude/commands/rescue-from-main.md && grep -q 'rescue-from-main' AGENTS.md && grep -q 'rescue-from-main' README.md && grep -q 'rescue-from-main' BLUEPRINT.md | 4.9, 4.10 | cc:완료 | - | | 4.12 | Task별 .harness 맥락 디렉토리 도입 | .harness/tasks// 구조와 루트 템플릿 역할이 문서·skeleton·최근 이관 예시로 정리됨 | test -d .harness/tasks/4.11-rescue-from-main && test -d .harness/tasks/readme-user-friendly && test -f .harness/tasks/readme-user-friendly/tasks.index.snapshot.json && test -f templates/skeleton/.harness/tasks/.gitkeep && grep -q '템플릿' .harness/STATE.md && grep -q '.harness/tasks' CLAUDE.md && grep -q '.harness/tasks' AGENTS.md && grep -q '.harness/tasks' .agents/skills/harness-work/SKILL.md && python3 scripts/validate_tasks.py && python3 scripts/sync_plans.py --check | 4.11 | cc:완료 | - | +| 4.13 | README 사용자 친화 개편 | README.md가 첫 화면, Quick Start, Codex CLI Setup, 작업별 workflow 메뉴, Troubleshooting을 사용자 행동 순서로 설명함 | grep -q '## 먼저 고를 것' README.md && grep -q '## Quick Start' README.md && grep -q '## Codex CLI Setup' README.md && grep -q '## 작업별 Workflow' README.md && grep -q '## Troubleshooting' README.md | - | cc:완료 | - | --- diff --git a/README.md b/README.md index dd5d4f5..8ac1c8f 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,85 @@ --- +## 먼저 고를 것 + +이 템플릿은 두 실행 환경을 모두 지원한다. 처음에는 아래 중 하나만 고르면 된다. + +| 내가 쓰는 도구 | 먼저 할 일 | 핵심 진입점 | +|---|---|---| +| Claude Code | [Claude Code Setup](#claude-code-setup)으로 플러그인 설치 후 `claude` 실행 | `CLAUDE.md`, `/harness-*`, `/grill-me` | +| Codex | [Codex CLI Setup](#codex-cli-setup) 확인 후 `codex` 실행 | `AGENTS.md`, `.agents/skills/*`, `$harness-*` | +| 둘 다 | Claude Code 플러그인을 설치하고 Codex는 repo 규칙을 직접 실행 | `CLAUDE.md`를 기준으로 `AGENTS.md`가 호환 절차 제공 | + +새 프로젝트에 바로 적용하려면 아래 Quick Start부터 실행한다. 이미 코드와 README가 +있는 프로젝트라면 [기존 프로젝트에 적용](#기존-프로젝트에-적용)으로 건너뛴다. + +## Quick Start + +```bash +# 1. 템플릿 클론 +git clone https://github.com/devRonPark/cc-harness-template /tmp/harness-tpl + +# 2. 내 프로젝트에 적용 +/tmp/harness-tpl/init.sh /path/to/my-project + +# 3. 프로젝트로 이동 +cd /path/to/my-project +``` + +이후 사용할 도구를 실행한다. + +```bash +claude # Claude Code +codex # Codex +``` + +복사 직후엔 `harness.toml`·`CLAUDE.md`가 플레이스홀더 상태다. +[커스터마이징 체크리스트](#step-2--커스터마이징-체크리스트)를 먼저 채워야 +AI가 엉뚱한 컨텍스트로 동작하지 않는다. + +## Codex CLI Setup + +Codex는 Claude Code 플러그인 hook을 자동 실행하지 않는다. 대신 이 저장소의 +루트 `AGENTS.md`와 `.agents/skills/`가 같은 절차를 Codex 방식으로 제공한다. + +Codex에서 새 세션을 열면 아래 순서로 시작한다. + +```text +AGENTS.md를 읽어줘. +tasks/index.json과 Plans.md 기준으로 현재 상태를 확인해줘. +$harness-progress로 진행 상황을 요약해줘. +``` + +작업을 실행할 때는 Claude Code slash command 대신 Codex skill 이름을 쓴다. + +| 목적 | Codex에서 호출 | 하는 일 | +|---|---|---| +| 기획 인터뷰 | `$grill-me` | PRD 초안과 Open Questions 정리 | +| Task 추가 | `$harness-plan` | planning context → proposal → 검증 → `tasks/index.json` 반영 | +| Task 구현 | `$harness-work` | 세분화/scope 게이트 → 구현 → Acceptance/test → 리뷰 | +| 진행 확인 | `$harness-progress` | `tasks/index.json` 기준 읽기 전용 요약 | +| Plans sync | `$harness-sync` | `tasks/index.json` 검증과 `Plans.md` 재생성 | +| Git 작업 | `$branch-checkout`, `$git-push`, `$pr-create`, `$rescue-from-main` | 브랜치, push, PR, main 작업 구조 | + +Codex 작업도 항상 `agents/quality-gates.md`를 따른다. ponytail/caveman plugin +자동 hook이 없으므로 YAGNI, scope check, findings-first 리뷰는 Codex 세션이 직접 +적용한다. + +## 작업별 Workflow + +| 하고 싶은 일 | 시작 명령 | 완료 전 확인 | +|---|---|---| +| 새 기능 기획 | Claude: `/grill-me` / Codex: `$grill-me` | `docs/PRD.md`와 Open Questions가 남았는지 확인 | +| Task 추가 | Claude: `/harness-plan` / Codex: `$harness-plan` | `validate_task_proposal.py`, `validate_tasks.py`, `sync_plans.py --check` 통과 | +| Task 구현 | Claude: `/harness-work` / Codex: `$harness-work` | Task Acceptance 명령과 관련 테스트 통과 | +| 현재 diff 리뷰 | Claude: `/harness-review` / Codex: `$harness-review` | findings-first 리뷰에서 blocker 없음 | +| 진행률 확인 | Claude: `/harness-progress` / Codex: `$harness-progress` | `tasks/index.json` 기준으로 `wip`/`todo` 확인 | +| 작업 브랜치 만들기 | Claude: `/branch-checkout` / Codex: `$branch-checkout` | `git status`가 깨끗한지 확인 후 전환 | +| PR 준비 | Claude: `/git-push`, `/pr-create` / Codex: `$git-push`, `$pr-create` | Acceptance evidence와 리뷰 결과를 PR 본문에 반영 | + +--- + ## 이 템플릿이 해결하는 문제 (Why) Claude Code로 새 프로젝트를 시작할 때마다 반복되는 일이 있다. @@ -58,28 +137,6 @@ Codex용 `AGENTS.md` 진입점 + `.harness/` 상태 문서** 조합으로 해결 --- -## Quick Start - -```bash -# 1. 템플릿 클론 -git clone https://github.com/devRonPark/cc-harness-template /tmp/harness-tpl - -# 2. 내 프로젝트에 적용 (harness.toml·CLAUDE.md·tasks/index.json·Plans.md·.harness/ 등 전부 복사) -/tmp/harness-tpl/init.sh /path/to/my-project - -# 3-a. Claude Code 실행 -cd /path/to/my-project -claude - -# 3-b. 또는 Codex 실행 -codex -``` - -플러그인 설치가 아직 안 됐다면 아래 [Claude Code Setup](#claude-code-setup)을 먼저 본다. -복사 직후엔 `harness.toml`·`CLAUDE.md`가 플레이스홀더 상태 — [커스터마이징 체크리스트](#커스터마이징-체크리스트)를 채워야 AI가 엉뚱한 컨텍스트로 동작하지 않는다. - ---- - ## 구성 요소 한눈에 보기 이 템플릿은 **필수 Plugin 3개** + **선택 Plugin 1개** + **5개 에이전트 규칙** + @@ -731,6 +788,17 @@ cc-harness-template/ 로컬 명령이 아니라 플러그인 제공 명령이다. `claude plugin install claude-code-harness@claude-code-harness-marketplace` 재실행 후 `harness doctor`로 확인한다. +### Codex에서 `/harness-work`가 안 먹힘 + +Codex에서는 Claude Code slash command가 아니라 repo-scoped skill을 쓴다. +`/harness-work` 대신 `$harness-work`처럼 호출하고, 먼저 `AGENTS.md`를 읽게 한다. + +### Codex가 ponytail/caveman처럼 동작하지 않음 + +Codex에는 Claude Code plugin hook이 자동 적용되지 않는다. +`agents/quality-gates.md`가 Codex용 공통 기준이므로 scope/YAGNI, findings-first 리뷰, +짧은 검증 중심 보고를 세션에서 직접 적용한다. + ### hooks가 실행되지 않음 이 템플릿엔 애초에 hooks가 설정돼 있지 않다 — [Hooks](#claude-code-hooks) 섹션 참고, diff --git a/tasks/index.json b/tasks/index.json index 8b12851..9ea5acf 100644 --- a/tasks/index.json +++ b/tasks/index.json @@ -437,6 +437,16 @@ "status": "done", "gh": "-", "section": "Week 4 — Codex 호환 환경 구성" + }, + { + "id": "4.13", + "title": "README 사용자 친화 개편", + "dod": "README.md가 첫 화면, Quick Start, Codex CLI Setup, 작업별 workflow 메뉴, Troubleshooting을 사용자 행동 순서로 설명함", + "acceptance": "grep -q '## 먼저 고를 것' README.md && grep -q '## Quick Start' README.md && grep -q '## Codex CLI Setup' README.md && grep -q '## 작업별 Workflow' README.md && grep -q '## Troubleshooting' README.md", + "depends": [], + "status": "done", + "gh": "-", + "section": "Week 4 — Codex 호환 환경 구성" } ] }