문제: 큰 일을 맡길 때 완료 기준·범위·검증 명령이 빠진 brief가 긴 세션과 되묻기로 이어진다. 소유자는 모든 프롬프트를 거치는 재작성 agent는 만들지 않고, 사람이 직접 부르는 점검 skill만 두기로 했다 (2026-11-18). 사전 재작성의 효과 근거는 외부 조사에서 못 찾았다. 고친 방법: prompt-check 스킬. 목표·완료 기준(검사할 수 있는 문장)· 범위와 금지·검증 명령·코드에서 읽을 수 없는 제약·출력 형식 6칸을 판정하고, repo에서 채울 수 있는 칸은 묻지 않고 출처와 함께 채운다. 빈 칸만 한 번에 최대 3개 묻고(기본값을 붙여), 사람 원문을 그대로 둔 채 칸을 붙인 brief를 보인 뒤 진행한다. 설명은 "사람이 시킬 때만"으로 써서 보통 요청에 끼어들지 않게 한다(docs/README.md 13·18번). 버린 대안: 사용자 호출 전용(disable-model-invocation, 결정 Q9와 어긋난다), 프롬프트를 다듬어 다시 쓰기(소유자 결정과 어긋난다). 위험: 모델 호출형이라 설명 문장이 발동을 막는 유일한 장치다. SKILL.md 56줄. 스킬이 늘어 harness 0.5.0으로 올린다. 검증: 템플릿 시험(스킬 목록, 설명이 Use로 시작, 1,024자 이하, 강조어 없음)과 scripts/check.sh 통과(claude plugin validate --strict 포함).
30 lines
2.7 KiB
Markdown
30 lines
2.7 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, 분야 전문가 협업 lead·new-expert, 판 비교 harness-eval, brief 점검 prompt-check), `tests/`.
|
|
- `template/`: 새 프로젝트에 복사하는 뼈대. `scripts/new-project.sh`가 복사하고 이름을 바꾼다.
|
|
- `docs/`: 이 repo에서 정한 것(`docs/README.md`), 분야 전문가 설계(`docs/experts.md`)와 그 조사(`docs/research/`), 예측·실측 장부(`docs/ledger/`), 회고 기록(`docs/retro/`). v1 설계 정본은 design-docs `harness/01-harness-design.md`다.
|
|
|
|
## 검증
|
|
|
|
- `scripts/check.sh`: 플러그인 시험, 템플릿 시험, `claude plugin validate --strict`(claude가 있을 때).
|
|
- 훅을 고쳤으면 고장 낸 사본에서도 시험이 실패하는지 본다(조건 하나를 끌 때마다 시험 하나 이상이 실패해야 한다).
|
|
|
|
## 일하는 방식
|
|
|
|
- 착수할 때 예측을, 끝날 때 실측을 `docs/ledger/estimates.jsonl`에 남긴다(`estimate` 스킬).
|
|
- 커밋 메시지는 `type(scope): 한국어 현재형 설명`이고 본문은 문제 → 고른 방법과 버린 대안 → 위험 → 검증이다. AI 꼬리말을 넣지 않는다.
|
|
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.
|