From 73da7065b02fd0fa24b0ff6c29e0c3bfb1705861 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 00:02:33 +0900 Subject: [PATCH] =?UTF-8?q?feat(template):=20=EC=83=88=20=ED=94=84?= =?UTF-8?q?=EB=A1=9C=EC=A0=9D=ED=8A=B8=20=EB=BC=88=EB=8C=80=EC=99=80=20new?= =?UTF-8?q?-project.sh=EB=A5=BC=20=EB=8D=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 새 프로젝트마다 루트 지침, Claude Code 설정, 검증 진입점, 비전· 문제 정의 양식, 장부를 손으로 다시 만든다. 플러그인으로는 루트 문서와 권한 deny를 나눠 줄 수 없다(플러그인 CLAUDE.md·권한은 읽히지 않는다). 고른 방법: 공통 동작은 플러그인, 프로젝트 파일은 template/ 복사로 나눈다(결정 Q15). scripts/new-project.sh가 template/을 빈 폴더에 복사하고 이름·설명·마켓 주소를 바꾼 뒤 git init까지 한다. 커밋은 하지 않는다. - AGENTS.md 양식(40줄 이하, 결정 Q2)과 CLAUDE.md(@AGENTS.md) - .claude/settings.json: .env deny, 마켓과 harness 플러그인 켜기. Agent deny는 넣지 않는다(결정 Q5) - scripts/verify.sh: 단계(docs·unit·pr·app) 뼈대와 --on <호스트> 운반부. 작업 트리를 패치로 옮겨 기준 커밋의 새 worktree에 적용하고 트리 해시를 맞춘 뒤 잠금 아래에서 돌린다. push하지 않는다(설계 6.1절) - 빈 양식: docs/vision.md, docs/problem-statement.md, docs/adr/0000-template.md - docs/ledger/: 빈 장부와 형식 설명, .gitattributes merge=union(결정 Q11) repo 자신의 AGENTS.md·README·docs/README.md(설계와 다르게 정한 것)와 scripts/check.sh도 같이 둔다. 버린 대안: 템플릿만(공통 훅 수정이 모든 repo 손작업), 플러그인만(루트 문서·deny를 못 준다). 위험: verify.sh의 원격 운반부는 가짜 ssh(같은 기계)로만 시험했다. 실제 desktop에서는 아직 돌리지 않았다. unit·pr·app 단계 본문은 비어 있다 (종료 코드 3). 검증: scripts/check.sh 통과(플러그인 17, 템플릿 10, validate --strict). 템플릿 시험은 이름 바꾸기, 남은 {{…}} 없음, AGENTS.md 40줄 이하, settings의 플러그인·deny, 빈 폴더가 아니면 멈춤, verify docs, 가짜 ssh로 패치 적용·트리 해시·worktree 정리와 원격 실패(종료 코드 4)를 본다. scratchpad에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다. --- .gitattributes | 1 + .gitignore | 2 + AGENTS.md | 29 +++++ CLAUDE.md | 5 + README.md | 71 ++++++++++++ docs/README.md | 20 ++++ docs/ledger/README.md | 49 +++++++++ docs/ledger/estimates.jsonl | 0 scripts/check.sh | 18 ++++ scripts/new-project.sh | 87 +++++++++++++++ template/.claude/settings.json | 26 +++++ template/.gitattributes | 1 + template/.gitignore | 8 ++ template/AGENTS.md | 36 +++++++ template/CLAUDE.md | 7 ++ template/docs/adr/0000-template.md | 35 ++++++ template/docs/ledger/README.md | 49 +++++++++ template/docs/ledger/estimates.jsonl | 0 template/docs/problem-statement.md | 34 ++++++ template/docs/vision.md | 10 ++ template/scripts/verify.sh | 128 ++++++++++++++++++++++ tests/test_template.py | 156 +++++++++++++++++++++++++++ 22 files changed, 772 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/README.md create mode 100644 docs/ledger/README.md create mode 100644 docs/ledger/estimates.jsonl create mode 100755 scripts/check.sh create mode 100755 scripts/new-project.sh create mode 100644 template/.claude/settings.json create mode 100644 template/.gitattributes create mode 100644 template/.gitignore create mode 100644 template/AGENTS.md create mode 100644 template/CLAUDE.md create mode 100644 template/docs/adr/0000-template.md create mode 100644 template/docs/ledger/README.md create mode 100644 template/docs/ledger/estimates.jsonl create mode 100644 template/docs/problem-statement.md create mode 100644 template/docs/vision.md create mode 100755 template/scripts/verify.sh create mode 100644 tests/test_template.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e977fa6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/ledger/estimates.jsonl merge=union diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6658aed --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +__pycache__/ +.claude/settings.local.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8a366cd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# AGENTS.md — claude-harness의 정본 + +새 프로젝트에 바로 쓰는 Claude Code 작업 환경이다. 공통 동작(훅·스킬·스크립트)은 플러그인 `harness`로, 프로젝트 파일(루트 지침·설정·검증 뼈대·빈 양식)은 `template/` 복사로 나눠 준다. 공개 repo다. 비밀 값·개인 경로·사내 주소를 넣지 않는다. + +## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다 + +1. `scripts/check.sh` 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다. +2. 플러그인 동작을 바꾸고 `plugins/harness/.claude-plugin/plugin.json`의 `version`을 올리지 않는다(받는 쪽은 버전이 바뀌어야 갱신된다). +3. `plugins/harness/scripts/guard_bash.py`의 셸 파서·H12 절을 바꾸고 소유자 기계 전역 훅(`~/.claude/hooks/guard_bash.py`)의 같은 절을 같이 바꾸지 않는다. 소유자 기계의 전역 훅 시험이 두 사본을 비교한다. +4. 훅이 출력을 늘린다. 장부 훅은 아무것도 출력하지 않고, 넛지는 5줄 이하다(출력은 모든 세션의 컨텍스트에 들어간다). +5. 훅이 표준 라이브러리 밖의 것을 쓰거나, 실패할 때 작업을 막는다(막는 것은 H12의 종료 코드 2뿐이다). + +## 지도 + +- `.claude-plugin/marketplace.json`: 이 repo가 곧 플러그인 마켓이다. 플러그인은 `plugins/harness/` 하나다. +- `plugins/harness/`: `hooks/hooks.json`(연결), `scripts/`(훅 본체·장부·techdebt), `skills/`(estimate·retro·techdebt), `tests/`. +- `template/`: 새 프로젝트에 복사하는 뼈대. `scripts/new-project.sh`가 복사하고 이름을 바꾼다. +- `docs/`: 이 repo에서 정한 것(`docs/README.md`)과 이 repo의 예측·실측 장부(`docs/ledger/`). 설계 정본은 design-docs `harness/01-harness-design.md`다. + +## 검증 + +- `scripts/check.sh`: 플러그인 시험, 템플릿 시험, `claude plugin validate --strict`(claude가 있을 때). +- 훅을 고쳤으면 고장 낸 사본에서도 시험이 실패하는지 본다(조건 하나를 끌 때마다 시험 하나 이상이 실패해야 한다). + +## 일하는 방식 + +- 착수할 때 예측을, 끝날 때 실측을 `docs/ledger/estimates.jsonl`에 남긴다(`estimate` 스킬). +- 커밋 메시지는 `type(scope): 한국어 현재형 설명`이고 본문은 문제 → 고른 방법과 버린 대안 → 위험 → 검증이다. AI 꼬리말을 넣지 않는다. +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6ac281c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +@AGENTS.md + +## Claude Code에서만 + +- 이 repo를 고치는 세션에도 하네스 플러그인을 켤 수 있다: `claude plugin marketplace add ./` 뒤 `claude plugin install harness@claude-harness`. 플러그인 파일을 고친 뒤에는 `claude plugin marketplace update claude-harness`와 새 세션이 있어야 바뀐 훅이 돈다. diff --git a/README.md b/README.md new file mode 100644 index 0000000..aaa8a53 --- /dev/null +++ b/README.md @@ -0,0 +1,71 @@ +# claude-harness + +새 프로젝트에 바로 쓰는 Claude Code 작업 환경(하네스)이다. 프로젝트와 상관없는 공통 동작은 **플러그인**으로 받아 버전으로 갱신하고, 프로젝트마다 다른 파일은 **뼈대 복사**로 시작한다. 이 repo가 곧 플러그인 마켓이다. + +```text +claude-harness ─┬─ 플러그인 harness ──(claude plugin install)──> 모든 세션의 훅·스킬 + └─ template/ ──(scripts/new-project.sh)──> 새 repo의 AGENTS.md·설정·verify.sh·빈 양식 +``` + +## 무엇이 들었나 + +| 폴더 | 하는 일 | 먼저 읽을 곳 | +|---|---|---| +| `plugins/harness/` | 공통 플러그인: 훅 넷과 스킬 셋 | 아래 「플러그인」 | +| `template/` | 새 프로젝트에 복사하는 뼈대 | 아래 「새 프로젝트」 | +| `scripts/` | `new-project.sh`(뼈대 복사), `check.sh`(이 repo 검증) | 각 파일 머리 주석 | +| `docs/` | 이 repo에서 정한 것, 이 repo의 예측·실측 장부 | `docs/README.md` | +| `tests/` | 템플릿·new-project·verify 운반부·매니페스트 시험 | | + +## 플러그인 `harness` + +| 장치 | 때 | 하는 일 | +|---|---|---| +| H12 차단 | Bash 실행 직전 | 되돌릴 수 없는 명령을 막는다: 호스팅 원격으로 force push·`--mirror`·보호 브랜치 지우기, 작업 폴더·/tmp 밖이나 너무 넓은 `rm -r`, DB·볼륨·migration 삭제(DROP·TRUNCATE, flyway clean, `-p` 없는 `compose down -v`, `volume rm`, `kubectl delete pvc·ns`). `ssh '…'` 안도 본다 | +| N4 알림 | 파일을 쓴 직후 | 비밀 값처럼 보이는 것(개인 키, 토큰, 값이 있는 password 등)을 몇 줄로 알린다. 막지 않는다 | +| 장부 기록 | 세션 시작·턴 끝 | 세션 id와 기록 경로를 `~/.claude/harness/sessions.jsonl`에, 누적 실측(시간·호출·토큰)을 `~/.claude/harness/usage/<세션>.json`에 쓴다. 출력이 없어 컨텍스트 비용이 0이다 | +| `estimate` 스킬 | 착수할 때·끝날 때 | 착수 보고와 p30·p50·p80 예측, 끝의 실측을 repo 장부 `docs/ledger/estimates.jsonl`에 | +| `retro` 스킬 | 회고 | 틀린 예측의 이유를 나누고 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나 | +| `techdebt` 스킬 | 세션 끝 | 이번 diff가 더한 TODO·skip·검사 끄기, 남은 파일·worktree·브랜치 | + +- 훅은 Python 3 표준 라이브러리만 쓴다. 차단은 H12 하나이고, 나머지는 실패해도 작업을 막지 않는다. +- H12의 판정은 소유자 기계의 전역 훅과 같다. 사용자 전역 `~/.claude/settings.json`에 `guard_bash.py … H12`가 이미 등록돼 있으면 플러그인 H12는 아무것도 하지 않는다(두 번 막지 않는다). +- 권한 deny(예: `.env` 읽기 금지)는 플러그인으로 나눠 줄 수 없다. 그래서 `template/.claude/settings.json`에 둔다. + +### 받기 + +```bash +claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git +``` + +```bash +claude plugin install harness@claude-harness +``` + +새 세션부터 훅과 스킬이 돈다. 갱신은 `plugin.json`의 `version`이 오른 뒤 `claude plugin marketplace update claude-harness`와 `claude plugin update harness@claude-harness`다. 템플릿으로 만든 프로젝트는 `.claude/settings.json`이 마켓과 플러그인을 이미 적어 두어서, 그 폴더를 처음 열 때 Claude Code가 설치를 묻는다. + +## 새 프로젝트 + +```bash +scripts/new-project.sh ~/workspace/order-service --description "주문을 받는 서비스다." +``` + +복사되는 것: `AGENTS.md`(루트 지침 양식, 40줄 이하), `CLAUDE.md`(`@AGENTS.md`와 Claude 전용 줄), `.claude/settings.json`(`.env` deny, 하네스 플러그인 켜기), `scripts/verify.sh`(검증 진입점 뼈대와 원격 운반부), `docs/vision.md`·`docs/problem-statement.md`·`docs/adr/0000-template.md`(빈 양식), `docs/ledger/`(빈 장부와 형식 설명), `.gitattributes`·`.gitignore`. 이름을 바꾸고 `git init`까지 하며 커밋은 하지 않는다. + +### 있는 프로젝트에 붙이기 + +1. 플러그인만 켜려면 `template/.claude/settings.json`의 `extraKnownMarketplaces`·`enabledPlugins`를 그 repo의 `.claude/settings.json`에 합친다. +2. 장부를 쓰려면 `template/docs/ledger/`와 `.gitattributes` 한 줄을 복사한다. +3. 루트 지침은 `template/AGENTS.md`의 절 순서를 참고해 그 repo의 것을 줄인다(덮어쓰지 않는다). + +## 검증 + +```bash +scripts/check.sh +``` + +플러그인 시험(H12·N4·장부·techdebt), 템플릿 시험(new-project 결과, `verify.sh docs`, 가짜 ssh로 원격 운반부), `claude plugin validate --strict`를 돈다. + +## 규칙과 기여 + +규칙은 `AGENTS.md`다. 플러그인 동작을 바꾸면 `version`을 올린다. 설계 근거는 design-docs `harness/01-harness-design.md`(11·13절)이고, 이 repo에서 따로 정한 것은 `docs/README.md`다. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5d7eec2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# 이 repo에서 정한 것 + +설계 정본은 design-docs `harness/01-harness-design.md`다(11절 하네스 템플릿 repo, 13절 소유자 결정 2026-11-07). 이 문서는 만들면서 설계와 다르게 정했거나 설계에 없던 것만 적는다. + +| # | 정한 것 | 설계와 다른 점 | 근거 | +|---|---|---|---| +| 1 | H12는 force push, 범위 밖 `rm -r`, DB·볼륨·migration 삭제만 막는다 | 설계 5.1절의 `git reset --hard`·`git clean -fdx`·`git checkout -- .` 줄은 넣지 않았다 | 소유자 기계 세션 기록의 Bash 명령 43,078개에서 정당하게 쓴 경우가 각 61·32·31건이었다. 막으면 거짓 양성이 크다. 자기 작업 폴더 안에서만 효과가 있고, auto mode 분류기가 따로 본다 | +| 2 | 다른 기계 작업 사본 경로(`host:/abs/path`)로 보내는 force push는 통과(보호 브랜치를 덮거나 ref가 없으면 막음) | 설계는 force push를 모두 막는다 | 같은 기록의 force push 25건이 모두 desktop 작업 사본으로 시험 브랜치를 옮기는 운반이었다. 공유 원격(Gitea)으로 보낸 것은 0건 | +| 3 | `-p <이름>`을 준 `compose down -v`는 통과 | 설계는 `down -v`를 모두 막는다 | 시험 lane은 고유 `-p`로 띄우고 같은 `-p`로 볼륨까지 지우는 것이 정해진 절차다(백엔드 `scripts/run-compose-runtime-smoke.sh`). 막을 것은 `-p` 없는 기본 프로젝트(개발 데이터)다 | +| 4 | `kubectl delete`는 pvc·pv·namespace만 | 설계는 `kubectl delete` 전부 | pod 지우기는 컨트롤러가 다시 만든다(되돌릴 수 있다). 기록에 정당한 pod 재시작이 있었다 | +| 5 | `rm -r`은 /tmp 아래를 허용, `/tmp/claude-` 자체는 막음 | 설계는 scratchpad와 `/tmp/claude-`만 | 빌드 도구가 /tmp에 만든 임시 폴더를 지우는 정당한 경우가 있었다. /tmp는 원래 버려도 되는 곳이다 | +| 6 | 원격(`ssh '…'`) `rm -r`은 너무 넓은 대상만 막는다(`~`, `~/workspace/<이름>` 통째, `/`와 그 바로 아래) | 설계에 없음 | 원격 작업 폴더를 알 수 없다. desktop 작업 폴더 통째 지우기 2건은 막힘으로 남긴다(`git worktree remove`가 맞는 길) | +| 7 | 플러그인 H12는 사용자 전역 설정에 `guard_bash.py … H12`가 있으면 건너뛴다 | 설계 Q13 (c)의 「두 번 돌지 않게」를 구체화 | 소유자 기계는 전역 훅이, 다른 기계·파생 서비스는 플러그인이 막는다. 판정 코드는 두 곳이 같고 소유자 기계의 전역 훅 시험이 비교한다 | +| 8 | 장부 훅은 `~/.claude/harness/`에 쓰고, repo 장부(`docs/ledger/estimates.jsonl`)에는 스킬만 쓴다 | 설계 10.2절과 같음. 13절 Q11대로 repo마다 장부 | 훅이 repo 파일을 고치면 모든 세션의 작업 트리가 더러워진다 | +| 9 | `template/.claude/settings.json`에 Agent deny를 넣지 않는다 | 설계 11.2절 그림에는 있다 | 13절 Q5(Agent 금지 해제) | + +## 확인한 것과 못 한 것 + +- 이 repo 첫 작업의 시험·설치 결과는 `docs/ledger/estimates.jsonl` 첫 줄과 design-docs 공유 노트 `h2-harness-repo.md`에 있다. +- 클라우드 세션에서 Gitea 마켓을 받는지는 보지 않았다(소유자는 데스크톱 앱 로컬 세션만 쓴다). diff --git a/docs/ledger/README.md b/docs/ledger/README.md new file mode 100644 index 0000000..9890e66 --- /dev/null +++ b/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다. + +```text +착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 +끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 +회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계 +``` + +- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. +- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. +- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. +- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다. +- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`append`). 손으로 써도 형식은 같다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | + +`estimate`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `started_at` | ISO 8601 | 세션 첫 기록 시각 | +| `base` | 문자열 | 기준 커밋 | +| `task_kind`, `size` | 문자열 | 일의 종류, 작음·중간·큼(`small`·`medium`·`large`) | +| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 | +| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 결정 수, 검증 대기 | + +`actual`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간) | +| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | +| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | +| `result`, `commits` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 | +| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 | + +`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서). diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/scripts/check.sh b/scripts/check.sh new file mode 100755 index 0000000..08b5305 --- /dev/null +++ b/scripts/check.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# 이 repo의 검증 묶음. 바꾼 뒤 커밋 전에 돌린다. +# scripts/check.sh +set -euo pipefail +cd "$(dirname "$0")/.." + +echo "== 플러그인 시험" +python3 -m unittest discover -s plugins/harness/tests +echo "== 템플릿 시험" +python3 -m unittest discover -s tests +if command -v claude >/dev/null 2>&1; then + echo "== 매니페스트 검사" + claude plugin validate --strict . + claude plugin validate --strict plugins/harness +else + echo "== 매니페스트 검사 건너뜀: claude 명령이 없다" >&2 +fi +echo "check: 통과" diff --git a/scripts/new-project.sh b/scripts/new-project.sh new file mode 100755 index 0000000..b479edc --- /dev/null +++ b/scripts/new-project.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# template/을 새 프로젝트 폴더로 복사하고 이름을 바꾼다. +# +# scripts/new-project.sh <새 폴더> [--name <이름>] [--description "<한 문장>"] [--no-git] +# +# 1. 새 폴더가 없거나 비어 있는지 본다(아니면 멈춘다. 있는 프로젝트를 덮지 않는다). +# 2. template/을 숨김 파일까지 복사한다. +# 3. {{PROJECT_NAME}}·{{PROJECT_DESCRIPTION}}·{{HARNESS_GIT_URL}}을 바꾸고, 남은 {{…}}가 있으면 멈춘다. +# 4. git init -b main(--no-git이면 건너뛴다). 커밋은 하지 않는다. +# 하네스 마켓 주소는 $HARNESS_GIT_URL, 없으면 이 repo의 origin, 그것도 없으면 아래 기본값이다. +# 있는 프로젝트에 붙일 때는 이 스크립트 대신 README 「있는 프로젝트에 붙이기」를 따른다. +set -euo pipefail + +HERE=$(cd "$(dirname "$0")/.." && pwd) +DEFAULT_URL=https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git + +usage() { + sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 2 +} + +target="" name="" description="" git_init=1 +while [ $# -gt 0 ]; do + case "$1" in + --name) name=${2:?--name 뒤에 이름}; shift 2 ;; + --description) description=${2:?--description 뒤에 한 문장}; shift 2 ;; + --no-git) git_init=0; shift ;; + -h | --help) usage ;; + -*) usage ;; + *) [ -z "$target" ] || usage; target=$1; shift ;; + esac +done +[ -n "$target" ] || usage + +if [ -e "$target" ] && [ -n "$(ls -A "$target" 2>/dev/null)" ]; then + echo "new-project: $target가 비어 있지 않다. 있는 프로젝트를 덮지 않는다." >&2 + exit 1 +fi +mkdir -p "$target" +target=$(cd "$target" && pwd) +name=${name:-$(basename "$target")} +description=${description:-"(채울 것: 이 프로젝트가 무엇이고 누가 쓰는지 한 문장)"} +url=${HARNESS_GIT_URL:-$(git -C "$HERE" remote get-url origin 2>/dev/null || true)} +case "$url" in https://*) ;; *) url=$DEFAULT_URL ;; esac + +cp -R "$HERE/template/." "$target/" + +python3 - "$target" "$name" "$description" "$url" <<'EOF' +import os, sys +root, name, description, url = sys.argv[1:] +values = {"{{PROJECT_NAME}}": name, "{{PROJECT_DESCRIPTION}}": description, "{{HARNESS_GIT_URL}}": url} +left = [] +for folder, _, files in os.walk(root): + if os.sep + ".git" in folder: + continue + for f in files: + path = os.path.join(folder, f) + try: + text = open(path, encoding="utf-8").read() + except UnicodeDecodeError: + continue + new = text + for key, value in values.items(): + new = new.replace(key, value) + if new != text: + open(path, "w", encoding="utf-8").write(new) + if "{{" in new and "}}" in new: + left.append(os.path.relpath(path, root)) +if left: + sys.exit("new-project: 바꾸지 못한 {{…}}가 남았다: " + ", ".join(sorted(left))) +EOF + +chmod +x "$target/scripts/verify.sh" +if [ "$git_init" = 1 ] && [ ! -d "$target/.git" ]; then + git -C "$target" init -q -b main +fi + +cat <`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다. +- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다). + +## 헷갈리는 곳 + +- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다) + +## 일하는 방식 + +- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬). +- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. +- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로) diff --git a/template/CLAUDE.md b/template/CLAUDE.md new file mode 100644 index 0000000..cbbd698 --- /dev/null +++ b/template/CLAUDE.md @@ -0,0 +1,7 @@ +@AGENTS.md + +## Claude Code에서만 + +- 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다). +- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다. +- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다. diff --git a/template/docs/adr/0000-template.md b/template/docs/adr/0000-template.md new file mode 100644 index 0000000..6fb7fb9 --- /dev/null +++ b/template/docs/adr/0000-template.md @@ -0,0 +1,35 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 제안 +- 작성일: YYYY-MM-DD +- 요약: 무엇을 정했는지 한국어 한 문장 +- 현재 정본: 지금 동작을 설명하는 살아 있는 문서의 경로. 없으면 「없음 — 이유」 + + +# NNNN. (결정 제목: 무엇을 정했나) + +## 맥락 + +무엇이 문제였고, 무엇이 결정을 강요했나. 숫자와 사건으로 쓴다. + +## 결정 + +정한 것을 한두 문장으로. 누가 정했는지(소유자·팀·에이전트 판단)를 밝힌다. + +## 고른 이유와 버린 대안 + +| 안 | 장점 | 단점 | 고름 | +|---|---|---|---| +| A | | | 예 | +| B | | | 아니요 — 이유 | + +## 결과 + +- 좋아지는 것: +- 치르는 값: +- 다시 볼 때: (어떤 숫자나 사건이 생기면 이 결정을 다시 보나) + +## 틀렸다면 어디서 드러나나 + +이 결정의 가정이 틀렸다면 무엇을 보면 알 수 있나. 잴 수 있게 쓴다. diff --git a/template/docs/ledger/README.md b/template/docs/ledger/README.md new file mode 100644 index 0000000..9890e66 --- /dev/null +++ b/template/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다. + +```text +착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 +끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 +회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계 +``` + +- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. +- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. +- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. +- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다. +- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`append`). 손으로 써도 형식은 같다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | + +`estimate`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `started_at` | ISO 8601 | 세션 첫 기록 시각 | +| `base` | 문자열 | 기준 커밋 | +| `task_kind`, `size` | 문자열 | 일의 종류, 작음·중간·큼(`small`·`medium`·`large`) | +| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 | +| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 결정 수, 검증 대기 | + +`actual`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간) | +| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | +| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | +| `result`, `commits` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 | +| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 | + +`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서). diff --git a/template/docs/ledger/estimates.jsonl b/template/docs/ledger/estimates.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/template/docs/problem-statement.md b/template/docs/problem-statement.md new file mode 100644 index 0000000..e2e929c --- /dev/null +++ b/template/docs/problem-statement.md @@ -0,0 +1,34 @@ +# 문제 정의 — {{PROJECT_NAME}} + +> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다. +> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다. + +## 고객의 말 그대로 + +- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다) + +## 지금은 어떻게 버티나 + +- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용) + +## 하지 않는 것 + +- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능) + +## 성공 기준 + +| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 | +|---|---|---|---|---| +| (채울 것) | | | | | + +## 세 관점 점검 + +| 관점 | 묻는 것 | 답 | +|---|---|---| +| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) | +| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) | +| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) | + +## 되돌릴 수 없는 결정 + +- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다) diff --git a/template/docs/vision.md b/template/docs/vision.md new file mode 100644 index 0000000..12fd1ed --- /dev/null +++ b/template/docs/vision.md @@ -0,0 +1,10 @@ +# 비전 — {{PROJECT_NAME}} + +> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다. +> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다. + +1. 누구의 어떤 문제를 푸는가: (채울 것) +2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것) +3. 속도보다 먼저 지킬 것: (채울 것) + +점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다. diff --git a/template/scripts/verify.sh b/template/scripts/verify.sh new file mode 100755 index 0000000..3297275 --- /dev/null +++ b/template/scripts/verify.sh @@ -0,0 +1,128 @@ +#!/usr/bin/env bash +# 검증 진입점. 사람·CI·에이전트가 같은 명령을 쓴다. +# +# scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>] +# +# 단계 무엇 채우는 곳 +# docs 루트 지침·장부 검사 run_docs(뼈대에 기본 검사가 있다) +# unit 빠른 단위 시험 run_unit +# pr PR 전에 통과해야 하는 게이트 묶음 run_pr +# app 앱을 띄워 health와 기본 기능을 직접 확인 run_app +# +# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를 +# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다. +# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳). +# 환경 변수: VERIFY_HOST(--on 기본값, 없으면 here), VERIFY_REMOTE_REPO(원격 checkout, 기본 ~/workspace/), +# VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), VERIFY_SSH(기본 ssh). +# 종료 코드: 단계의 종료 코드. 2 = 사용법, 3 = 아직 채우지 않은 단계, 4 = 원격 준비 실패. +set -euo pipefail + +ROOT=$(git rev-parse --show-toplevel) +cd "$ROOT" +TMP_FILES=() +trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다 + +usage() { + sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 2 +} + +todo() { + echo "verify: '$1' 단계는 아직 정하지 않았다. scripts/verify.sh의 run_$1을 채운다." >&2 + return 3 +} + +# ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다) + +run_docs() { + local rc=0 lines + lines=$(wc -l < AGENTS.md) + if [ "$lines" -gt 40 ]; then + echo "AGENTS.md가 ${lines}줄이다(40줄 이하). 나머지는 하위 폴더 AGENTS.md·.claude/rules·스킬로 옮긴다." >&2 + rc=1 + fi + if grep -rn --include='*.md' '(채울 것' AGENTS.md docs >&2; then + echo "verify docs: 위 자리를 아직 채우지 않았다(실패로 치지 않는다)." >&2 + fi + if [ -s docs/ledger/estimates.jsonl ] && ! python3 -c ' +import json, sys +for n, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1): + if line.strip(): + json.loads(line) +' docs/ledger/estimates.jsonl; then + echo "docs/ledger/estimates.jsonl에 JSON이 아닌 줄이 있다." >&2 + rc=1 + fi + return "$rc" +} + +run_unit() { todo unit; } + +run_pr() { run_docs && run_unit && todo pr; } + +run_app() { todo app; } + +# ---------------------------------------------------------------- 실행 위치 + +run_here() { + case "$1" in + docs | unit | pr | app) "run_$1" ;; + *) usage ;; + esac +} + +run_remote() { + local stage=$1 host=$2 log=$3 ssh=${VERIFY_SSH:-ssh} + local name base tree tmp_index patch id remote_repo lock + name=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")") + remote_repo=${VERIFY_REMOTE_REPO:-"~/workspace/$name"} + lock=${VERIFY_LOCK:-/tmp/claude-gates/heavy.lock} + base=$(git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}") + tmp_index=$(mktemp) + patch=$(mktemp) + TMP_FILES+=("$tmp_index" "$patch") + cp "$(git rev-parse --git-path index)" "$tmp_index" + GIT_INDEX_FILE=$tmp_index git add -A + tree=$(GIT_INDEX_FILE=$tmp_index git write-tree) + git diff --binary "$base" "$tree" > "$patch" + id="verify-$(date +%s)-$$" + echo "verify: $host에서 '$stage' (기준 ${base:0:12}, 트리 ${tree:0:12}, 로그 ~/$log-logs/$stage.log)" >&2 + $ssh "$host" "cat > /tmp/$id.patch" < "$patch" + $ssh "$host" bash -s <&2; exit 4; fi +mkdir -p "\$(dirname $lock)" ~/$log-logs +flock $lock ./scripts/verify.sh $stage --on here 2>&1 | tee ~/$log-logs/$stage.log +exit \${PIPESTATUS[0]} +EOF +} + +main() { + local stage=${1:-} on=${VERIFY_HOST:-here} log="" + [ -n "$stage" ] || usage + shift + while [ $# -gt 0 ]; do + case "$1" in + --on) on=${2:?--on 뒤에 호스트}; shift 2 ;; + --log) log=${2:?--log 뒤에 이름}; shift 2 ;; + *) usage ;; + esac + done + if [ "$on" = here ]; then + run_here "$stage" + else + log=${log:-$(git branch --show-current | tr '/' '-')} + run_remote "$stage" "$on" "${log:-detached}" + fi +} + +main "$@" diff --git a/tests/test_template.py b/tests/test_template.py new file mode 100644 index 0000000..ce5a091 --- /dev/null +++ b/tests/test_template.py @@ -0,0 +1,156 @@ +"""템플릿·new-project.sh·verify.sh·매니페스트 시험. 표준 라이브러리와 git·bash·flock만 쓴다. + + python3 -m unittest discover -s tests +""" +import json +import os +import subprocess +import tempfile +import unittest + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +NEW_PROJECT = os.path.join(REPO, "scripts", "new-project.sh") +URL = "https://git.example.com/team/claude-harness.git" +GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com", "GIT_COMMITTER_NAME": "t", + "GIT_COMMITTER_EMAIL": "t@example.com", "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath", + "GIT_CONFIG_VALUE_0": "/dev/null"} + + +def sh(args, cwd=None, env=None, check=True): + full = {**os.environ, **GIT_ENV, **(env or {})} + r = subprocess.run(args, cwd=cwd, env=full, capture_output=True, text=True, timeout=60) + if check and r.returncode != 0: + raise AssertionError("%s → %d\n%s\n%s" % (args, r.returncode, r.stdout, r.stderr)) + return r + + +def read(path): + with open(path, encoding="utf-8") as f: + return f.read() + + +class NewProjectTest(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.target = os.path.join(self.tmp.name, "order-service") + sh([NEW_PROJECT, self.target, "--description", "주문을 받는 서비스다."], env={"HARNESS_GIT_URL": URL}) + + def tearDown(self): + self.tmp.cleanup() + + def path(self, *parts): + return os.path.join(self.target, *parts) + + def test_names_are_filled_and_nothing_is_left(self): + agents = read(self.path("AGENTS.md")) + self.assertTrue(agents.startswith("# AGENTS.md — order-service의 정본")) + self.assertIn("주문을 받는 서비스다.", agents) + self.assertIn("# 비전 — order-service", read(self.path("docs", "vision.md"))) + for folder, _, files in os.walk(self.target): + if ".git" in folder.split(os.sep): + continue + for f in files: + self.assertNotIn("{{", read(os.path.join(folder, f)), os.path.join(folder, f)) + + def test_root_instructions_stay_short(self): + self.assertLessEqual(len(read(self.path("AGENTS.md")).splitlines()), 40) + self.assertTrue(read(self.path("CLAUDE.md")).startswith("@AGENTS.md\n")) + + def test_settings_enable_plugin_and_deny_env_without_agent_deny(self): + settings = json.loads(read(self.path(".claude", "settings.json"))) + self.assertIs(settings["enabledPlugins"]["harness@claude-harness"], True) + source = settings["extraKnownMarketplaces"]["claude-harness"]["source"] + self.assertEqual((source["source"], source["url"]), ("git", URL)) + deny = settings["permissions"]["deny"] + self.assertIn("Read(**/.env)", deny) + self.assertIn("Edit(**/.env)", deny) + self.assertFalse([d for d in deny if d.startswith("Agent")], "Agent 금지는 넣지 않는다(결정 Q5)") + self.assertFalse([d for d in deny if "example" in d]) + + def test_ledger_and_git_are_ready(self): + self.assertEqual(read(self.path("docs", "ledger", "estimates.jsonl")), "") + self.assertIn("estimates.jsonl merge=union", read(self.path(".gitattributes"))) + self.assertTrue(os.path.isdir(self.path(".git"))) + self.assertTrue(os.access(self.path("scripts", "verify.sh"), os.X_OK)) + + def test_verify_docs_passes_on_fresh_project_and_fails_on_long_agents(self): + r = sh([self.path("scripts", "verify.sh"), "docs"], cwd=self.target) + self.assertIn("(채울 것", r.stderr) + with open(self.path("AGENTS.md"), "a", encoding="utf-8") as f: + f.write("줄\n" * 10) + r = sh([self.path("scripts", "verify.sh"), "docs"], cwd=self.target, check=False) + self.assertEqual(r.returncode, 1) + r = sh([self.path("scripts", "verify.sh"), "unit"], cwd=self.target, check=False) + self.assertEqual(r.returncode, 3) + + def test_refuses_non_empty_target(self): + r = sh([NEW_PROJECT, self.target], check=False) + self.assertEqual(r.returncode, 1) + self.assertIn("덮지 않는다", r.stderr) + + +class VerifyRemoteTest(unittest.TestCase): + """--on <호스트> 운반부를 가짜 ssh(호스트를 무시하고 이 기계에서 실행)로 시험한다.""" + + def test_patch_is_applied_in_a_fresh_worktree_and_cleaned_up(self): + with tempfile.TemporaryDirectory() as d: + project, bare, remote = (os.path.join(d, n) for n in ("project", "origin.git", "remote")) + home = os.path.join(d, "home") + os.makedirs(home) + sh([NEW_PROJECT, project], env={"HARNESS_GIT_URL": URL}) + sh(["git", "add", "-A"], cwd=project) + sh(["git", "commit", "-q", "-m", "init"], cwd=project) + sh(["git", "clone", "-q", "--bare", project, bare]) + sh(["git", "remote", "add", "origin", bare], cwd=project) + sh(["git", "fetch", "-q", "origin"], cwd=project) + sh(["git", "clone", "-q", bare, remote]) + with open(os.path.join(project, "docs", "notes.md"), "w", encoding="utf-8") as f: + f.write("커밋 안 한 새 파일\n") + with open(os.path.join(project, "AGENTS.md"), "a", encoding="utf-8") as f: + f.write("고친 줄\n") + fake_ssh = os.path.join(d, "fake-ssh") + with open(fake_ssh, "w") as f: + f.write('#!/bin/sh\nshift\nexec bash -c "$*"\n') + os.chmod(fake_ssh, 0o755) + env = {"VERIFY_SSH": fake_ssh, "VERIFY_REMOTE_REPO": remote, "VERIFY_LOCK": os.path.join(d, "lock"), + "HOME": home} + r = sh(["scripts/verify.sh", "docs", "--on", "build-host", "--log", "t"], cwd=project, env=env, + check=False) + self.assertEqual(r.returncode, 0, r.stdout + r.stderr) + log = read(os.path.join(home, "t-logs", "docs.log")) + self.assertIn("(채울 것", log) + worktrees = sh(["git", "worktree", "list"], cwd=remote).stdout.strip().splitlines() + self.assertEqual(len(worktrees), 1, worktrees) + + r = sh(["scripts/verify.sh", "docs", "--on", "build-host"], cwd=project, + env={**env, "VERIFY_REMOTE_REPO": os.path.join(d, "missing")}, check=False) + self.assertEqual(r.returncode, 4) + + +class ManifestTest(unittest.TestCase): + def test_marketplace_points_at_the_plugin(self): + market = json.loads(read(os.path.join(REPO, ".claude-plugin", "marketplace.json"))) + entry = next(p for p in market["plugins"] if p["name"] == "harness") + plugin_dir = os.path.join(REPO, entry["source"]) + manifest = json.loads(read(os.path.join(plugin_dir, ".claude-plugin", "plugin.json"))) + self.assertEqual(manifest["name"], "harness") + self.assertRegex(manifest["version"], r"^\d+\.\d+\.\d+$") + self.assertNotIn("version", entry, "버전은 plugin.json 한 곳에 둔다") + hooks = json.loads(read(os.path.join(plugin_dir, "hooks", "hooks.json")))["hooks"] + self.assertEqual(sorted(hooks), ["PostToolUse", "PreToolUse", "SessionStart", "Stop"]) + + def test_skills_are_model_invoked_with_trigger_paragraphs(self): + skills = os.path.join(REPO, "plugins", "harness", "skills") + for name in ("estimate", "retro", "techdebt"): + head = read(os.path.join(skills, name, "SKILL.md")).split("---")[1] + self.assertNotIn("disable-model-invocation", head, "새 스킬은 모델이 부른다(결정 Q9)") + description = head.split("description:", 1)[1].strip() + self.assertTrue(description.startswith("Use "), name) + self.assertLessEqual(len(description), 1536, name) + + def test_repo_root_instructions_stay_short(self): + self.assertLessEqual(len(read(os.path.join(REPO, "AGENTS.md")).splitlines()), 40) + + +if __name__ == "__main__": + unittest.main()