Files
claude-harness/README.md
T
DongHyeonka e762248c4e fix(template): 마켓 주소를 CLI가 쓰는 모양으로 두고 수동 설치 두 줄을 안내한다
문제: 템플릿 프로젝트를 비대화형(claude -p)으로 열면 .claude/settings.json에
적힌 마켓과 플러그인을 설치하지도 묻지도 않는다(2026-11-08 시험 프로젝트에서
확인). 또 claude plugin install --scope project가 settings.json을 다시 쓰면서
마켓 source의 "ref": "main"을 빼서, 템플릿과 설치 뒤 파일이 달라진다.

고른 방법: 템플릿의 마켓 source에서 ref를 뺀다(기본 브랜치 main과 같은 뜻).
new-project.sh 끝 안내와 README에 그 폴더에서 한 번 돌릴 두 줄
(marketplace add, install --scope project)을 적는다.
버린 대안: new-project.sh가 claude plugin을 직접 부르기. 스크립트가 사용자의
~/.claude/plugins 상태를 바꾸게 된다.

위험: 대화형 앱이 폴더를 믿을 때 설치를 묻는지는 공식 문서 설명이고 직접
보지 않았다(README에 그렇게 적음).

검증: scripts/check.sh 통과. 시험 프로젝트에서 두 줄을 돌린 뒤 claude plugin
list가 harness@claude-harness 0.1.0 project 범위 enabled를 보였고,
settings.json은 ref 한 칸 말고 내용이 같았다.
2026-11-08 10:42:02 +09:00

74 lines
5.2 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
```
새 세션부터 훅과 스킬이 돈다. 공개 repo라 인증 없이 받는다. 갱신은 `plugin.json`의 `version`이 오른 뒤 `claude plugin marketplace update claude-harness`와 `claude plugin update harness@claude-harness`다.
템플릿으로 만든 프로젝트는 `.claude/settings.json`이 마켓과 플러그인을 이미 적어 둔다. 대화형 Claude Code는 그 폴더를 처음 믿을 때 설치를 묻는다(공식 문서의 설명이고, 이 repo에서 직접 보지는 않았다). 비대화형(`claude -p`)은 묻지도 설치하지도 않는다(2026-11-08 확인). 그때는 그 폴더에서 위 두 명령에 `--scope project`를 붙여 한 번 돌린다. 설정 파일 내용은 바뀌지 않는다.
## 새 프로젝트
```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`다.