문제: 새 프로젝트마다 루트 지침, 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에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
72 lines
4.8 KiB
Markdown
72 lines
4.8 KiB
Markdown
# 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`다.
|