feat(template): 새 프로젝트 뼈대와 new-project.sh를 더한다

문제: 새 프로젝트마다 루트 지침, 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에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
This commit is contained in:
DongHyeonka
2026-11-08 00:02:33 +09:00
parent ddbfc3dcc3
commit 73da7065b0
22 changed files with 772 additions and 0 deletions
+1
View File
@@ -0,0 +1 @@
docs/ledger/estimates.jsonl merge=union
+2
View File
@@ -0,0 +1,2 @@
__pycache__/
.claude/settings.local.json
+29
View File
@@ -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 꼬리말을 넣지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.
+5
View File
@@ -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`와 새 세션이 있어야 바뀐 훅이 돈다.
+71
View File
@@ -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`다.
+20
View File
@@ -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-<uid>` 자체는 막음 | 설계는 scratchpad와 `/tmp/claude-<uid>`만 | 빌드 도구가 /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 마켓을 받는지는 보지 않았다(소유자는 데스크톱 앱 로컬 세션만 쓴다).
+49
View File
@@ -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`(고친 커밋이나 문서).
View File
+18
View File
@@ -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: 통과"
+87
View File
@@ -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 <<EOF
새 프로젝트를 만들었다: $target (이름 $name)
다음 할 일
1. docs/vision.md를 소유자가 세 문장으로 쓴다(AI에게 맡기지 않는다).
2. docs/problem-statement.md와 AGENTS.md의 「(채울 것」 자리를 채운다. AGENTS.md는 40줄 이하로 둔다.
3. scripts/verify.sh의 run_unit·run_pr·run_app을 이 프로젝트의 명령으로 채운다.
4. 이 폴더에서 Claude Code를 처음 열면 하네스 마켓(claude-harness)과 플러그인을 믿을지 묻는다. 승인한다.
확인: scripts/verify.sh docs
EOF
+26
View File
@@ -0,0 +1,26 @@
{
"permissions": {
"deny": [
"Read(**/.env)",
"Read(**/.env.local)",
"Read(**/.env.*.local)",
"Read(**/.env.production)",
"Edit(**/.env)",
"Edit(**/.env.local)",
"Edit(**/.env.*.local)",
"Edit(**/.env.production)"
]
},
"extraKnownMarketplaces": {
"claude-harness": {
"source": {
"source": "git",
"url": "{{HARNESS_GIT_URL}}",
"ref": "main"
}
}
},
"enabledPlugins": {
"harness@claude-harness": true
}
}
+1
View File
@@ -0,0 +1 @@
docs/ledger/estimates.jsonl merge=union
+8
View File
@@ -0,0 +1,8 @@
# 개인 설정과 비밀 값
.claude/settings.local.json
.env
.env.local
.env.*.local
.env.production
__pycache__/
+36
View File
@@ -0,0 +1,36 @@
# AGENTS.md — {{PROJECT_NAME}}의 정본
{{PROJECT_DESCRIPTION}} 방향은 `docs/vision.md`, 풀 문제와 하지 않을 것은 `docs/problem-statement.md`다.
## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
1. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다.
3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다.
4. (채울 것: 이 프로젝트의 아키텍처 불변식. 예: 도메인 계층이 프레임워크·DB를 import한다)
## 지도
- (채울 것: 최상위 폴더 → 하는 일. 개수·버전 숫자는 적지 않는다. 정본이 따로 있으면 그 파일을 가리킨다)
- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다. 작업 파일과 가장 가까운 것을 따른다.
- 결정 기록은 `docs/adr/`(양식 `0000-template.md`), 예측·실측 장부는 `docs/ledger/`다.
## 맡은 일
- (채울 것: 일의 종류 → 먼저 읽을 문서. 예: 새 기능 → `docs/…`)
- brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
## 검증
- 진입점은 하나다: `scripts/verify.sh <단계>`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다.
- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다).
## 헷갈리는 곳
- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다)
## 일하는 방식
- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬).
- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다.
- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로)
+7
View File
@@ -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/`에 둔다.
+35
View File
@@ -0,0 +1,35 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 새 결정 기록은 이 파일을 복사해 NNNN-<짧은-이름>.md로 만든다 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 제안
- 작성일: YYYY-MM-DD
- 요약: 무엇을 정했는지 한국어 한 문장
- 현재 정본: 지금 동작을 설명하는 살아 있는 문서의 경로. 없으면 「없음 — 이유」
<!-- 머리 블록 끝 -->
# NNNN. (결정 제목: 무엇을 정했나)
## 맥락
무엇이 문제였고, 무엇이 결정을 강요했나. 숫자와 사건으로 쓴다.
## 결정
정한 것을 한두 문장으로. 누가 정했는지(소유자·팀·에이전트 판단)를 밝힌다.
## 고른 이유와 버린 대안
| 안 | 장점 | 단점 | 고름 |
|---|---|---|---|
| A | | | 예 |
| B | | | 아니요 — 이유 |
## 결과
- 좋아지는 것:
- 치르는 값:
- 다시 볼 때: (어떤 숫자나 사건이 생기면 이 결정을 다시 보나)
## 틀렸다면 어디서 드러나나
이 결정의 가정이 틀렸다면 무엇을 보면 알 수 있나. 잴 수 있게 쓴다.
+49
View File
@@ -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`(고친 커밋이나 문서).
+34
View File
@@ -0,0 +1,34 @@
# 문제 정의 — {{PROJECT_NAME}}
> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다.
> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다.
## 고객의 말 그대로
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
## 지금은 어떻게 버티나
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
## 하지 않는 것
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
## 성공 기준
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|---|---|---|---|---|
| (채울 것) | | | | |
## 세 관점 점검
| 관점 | 묻는 것 | 답 |
|---|---|---|
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
## 되돌릴 수 없는 결정
- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
+10
View File
@@ -0,0 +1,10 @@
# 비전 — {{PROJECT_NAME}}
> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다.
> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다.
1. 누구의 어떤 문제를 푸는가: (채울 것)
2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것)
3. 속도보다 먼저 지킬 것: (채울 것)
점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다.
+128
View File
@@ -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/<repo 이름>),
# 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 <<EOF
set -u
cd $remote_repo || exit 4
git fetch -q origin || exit 4
wt=\$(mktemp -d /tmp/$id.XXXXXX)
git worktree add -q --detach "\$wt" $base || exit 4
cleanup() { cd $remote_repo && git worktree remove --force "\$wt"; rm -f /tmp/$id.patch; }
trap cleanup EXIT
cd "\$wt"
if [ -s /tmp/$id.patch ]; then git apply --binary --index /tmp/$id.patch || exit 4; fi
got=\$(git write-tree)
if [ "\$got" != "$tree" ]; then echo "트리 해시가 다르다: 원격 \$got, 여기 $tree" >&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 "$@"
+156
View File
@@ -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()