문제: 새 프로젝트마다 루트 지침, 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에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
30 lines
2.5 KiB
Markdown
30 lines
2.5 KiB
Markdown
# 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 꼬리말을 넣지 않는다.
|
|
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.
|