문제: design-docs 위임 장부 55줄과 백엔드 템플릿 예측 장부 6줄이 쌓였는데 원인을 나눈 회고가 한 번도 없었다. 고른 방법: retro 스킬의 일곱 원인으로 빗나간 줄마다 원인 하나를 붙였다. 위임 장부에는 시간 예측이 없어서 「질문·위반·재작업·불일치· 소유자 개입 없이 끝난다」를 예측으로 보고, 막힘만 있는 줄은 게이트가 제 일을 한 것이라 뺐다. 결과: 빗나간 42줄 중 지시 모호 34, 예측 근거 없음 4, 착수 전 조사 부족 2, 외부 대기 2. 예측 장부 4건은 모두 p30 아래였고 실측/p50 중앙값은 시간 0.43·호출 0.52·출력 0.53이다. H11 보고 언어 훅과 매뉴얼 빈틈 수정 1~3차는 장부 숫자로 효과를 판정했다. 다른 repo·설정에서 고칠 후보 일곱 개(C1~C7)를 적었다. 이 repo 장부에는 이 작업의 예측 줄과 h2-harness-repo의 retro 줄 (fix calib-median)을 더했다. 위험: 위임 장부의 원인은 lessons 한 줄을 읽고 붙인 것이라 세션 기록까지 다시 보지 않았다. 백엔드 장부의 retro 줄은 그 repo에 쓰지 않고 문서 7절에 더할 줄로만 두었다(범위 밖). 검증: scripts/check.sh rc=0. ledger.py pending → 회고할 줄 없음, 판정 대기 calib-median 뒤 실측 0건.
2.5 KiB
2.5 KiB
AGENTS.md — claude-harness의 정본
새 프로젝트에 바로 쓰는 Claude Code 작업 환경이다. 공통 동작(훅·스킬·스크립트)은 플러그인 harness로, 프로젝트 파일(루트 지침·설정·검증 뼈대·빈 양식)은 template/ 복사로 나눠 준다. 공개 repo다. 비밀 값·개인 경로·사내 주소를 넣지 않는다.
꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
scripts/check.sh없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.- 플러그인 동작을 바꾸고
plugins/harness/.claude-plugin/plugin.json의version을 올리지 않는다(받는 쪽은 버전이 바뀌어야 갱신된다). plugins/harness/scripts/guard_bash.py의 셸 파서·H12 절을 바꾸고 소유자 기계 전역 훅(~/.claude/hooks/guard_bash.py)의 같은 절을 같이 바꾸지 않는다. 소유자 기계의 전역 훅 시험이 두 사본을 비교한다.- 훅이 출력을 늘린다. 장부 훅은 아무것도 출력하지 않고, 넛지는 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/), 회고 기록(docs/retro/). 설계 정본은 design-docsharness/01-harness-design.md다.
검증
scripts/check.sh: 플러그인 시험, 템플릿 시험,claude plugin validate --strict(claude가 있을 때).- 훅을 고쳤으면 고장 낸 사본에서도 시험이 실패하는지 본다(조건 하나를 끌 때마다 시험 하나 이상이 실패해야 한다).
일하는 방식
- 착수할 때 예측을, 끝날 때 실측을
docs/ledger/estimates.jsonl에 남긴다(estimate스킬). - 커밋 메시지는
type(scope): 한국어 현재형 설명이고 본문은 문제 → 고른 방법과 버린 대안 → 위험 → 검증이다. AI 꼬리말을 넣지 않는다. - 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.