DongHyeonka 9735c3366c docs(lead): cold-read에서 나온 빈틈을 lead 절차와 명단 양식에 메운다
문제: 이 대화를 모르는 서브에이전트에게 lead·명단 양식·new-expert·설계
일부만 주고 리뷰를 시켰더니(cold-read) 짐작한 곳 22개가 나왔다. 실질적인
것: 크기 기준이 없음, 물결과 라운드가 같은지 모름, 사실 다툼과 가치
충돌의 순서, 남의 브랜치를 리드가 고쳐도 되나, 넓은 paths로 렌즈가
다섯 붙음, 렌즈를 묶는 기준, 시험 파일을 누구 렌즈에, 심각도 단계,
reviewer·arch-reviewer·verify·simplifier를 언제, 기준 커밋 정의,
리뷰어가 시험을 돌려도 되나, 소유자가 누구인가, 멈춤 조건.

고른 방법: lead에 물결·라운드 정의와 그림, 크기 기준(brief 우선),
merge-base 기준 커밋, 렌즈는 후보이고 상관없는 것은 뺌, 묶는 기준
(같은 물음끼리, 반대 입장은 나눔), 시험 파일 배정, 리뷰어 종류,
심각도 네 단계, 사실 먼저 반증 → 가치 충돌만 순위, 소유자 정의, 남의
브랜치는 돌려줌, 멈춤 조건을 넣는다. 명단 양식에는 말뜻(렌즈·물결·
라운드·하위 세션·게이트)과 소유자 단서를 넣는다. 설계 4절에 규칙 셋,
5.1에 초안이 실제 repo로 맞춘 백엔드 경로를 반영한다.
버린 대안: 말뜻을 lead 스킬 안에 모두 두기. 스킬 본문이 길어지고 repo마다
쓰는 이름이 달라 명단 문서가 맞는 자리다.

위험: lead 본문이 약 120줄로 늘었다(상한 500줄 안). 프론트 경로는 아직
실제 repo와 맞추지 않았다.

검증: python3 -m unittest discover -s tests → 11건 통과,
claude plugin validate --strict plugins/harness → 통과.
2026-11-11 22:22:10 +09:00

claude-harness

새 프로젝트에 바로 쓰는 Claude Code 작업 환경(하네스)이다. 프로젝트와 상관없는 공통 동작은 플러그인으로 받아 버전으로 갱신하고, 프로젝트마다 다른 파일은 뼈대 복사로 시작한다. 이 repo가 곧 플러그인 마켓이다.

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에서 정한 것, 분야 전문가 설계(experts.md)와 그 조사, 예측·실측 장부 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이다
회고 넛지 세션 시작 repo 장부에 회고 안 한 빗나간 예측이나 효과 판정할 개선이 있으면, repo마다 하루 한 번 한 줄로 알린다. 없으면 출력이 없다
estimate 스킬 착수할 때·끝날 때 착수 보고와 p30·p50·p80 예측, 끝의 실측을 repo 장부 docs/ledger/estimates.jsonl에
retro 스킬 회고 틀린 예측의 이유를 나누고 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나. 고친 뒤 실측 2건으로 효과를 판정하고, 없으면 되돌린다
techdebt 스킬 세션 끝 이번 diff가 더한 TODO·skip·검사 끄기, 남은 파일·worktree·브랜치
lead 스킬 여러 분야에 걸친 변경·리뷰, PR 전, 의견 충돌 바뀐 경로·위험으로 분야 지식 스킬(렌즈)을 고르고, 고정 칸 brief로 새 눈 리뷰어를 병렬로 띄우고, 합쳐서 High를 반증하고, 넘김을 한 번 더 돌리고, 충돌을 정한 순서로 판정하고, 리뷰-수정을 세 번까지로 묶는다
new-expert 스킬 분야 전문가를 더할 때 지식 스킬(paths, 「함정」이 맨 앞)을 정해진 모양으로 만들고, 서브에이전트가 정말 필요한지 세 조건으로 따진 뒤 docs/work/experts.md에 올린다
harness-eval 스킬 사람이 하네스 판 비교를 시킬 때 정답을 아는 과제를 판마다 돌려 장부 eval 줄로 남기고 ledger.py compare로 견준다
  • 훅은 Python 3 표준 라이브러리만 쓴다. 차단은 H12 하나이고, 나머지는 실패해도 작업을 막지 않는다.
  • H12의 판정은 소유자 기계의 전역 훅과 같다. 사용자 전역 ~/.claude/settings.json에 guard_bash.py … H12가 이미 등록돼 있으면 플러그인 H12는 아무것도 하지 않는다(두 번 막지 않는다).
  • 권한 deny(예: .env 읽기 금지)는 플러그인으로 나눠 줄 수 없다. 그래서 template/.claude/settings.json에 둔다.

받기

claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git
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를 붙여 한 번 돌린다. 설정 파일 내용은 바뀌지 않는다.

새 프로젝트

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/work/experts.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의 것을 줄인다(덮어쓰지 않는다).

검증

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다.

S
Description
새 프로젝트용 Claude Code 작업 환경: 하네스 플러그인(되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부)과 복사용 프로젝트 뼈대
Readme
495 KiB
Languages
Python 87.9%
Shell 12.1%