Files
DongHyeonka 86a6446c3c feat(harness): 큰 일 전에 사람이 부르는 brief 점검 스킬을 더한다
문제: 큰 일을 맡길 때 완료 기준·범위·검증 명령이 빠진 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 포함).
2026-11-18 21:10:40 +09:00

7.3 KiB

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, 작업 폴더 안이라도 git checkout(등록된 worktree 포함)을 통째로 지우거나 옆 worktree 안을 지우는 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이다
컨텍스트 알림 프롬프트 제출·도구 실행 직후 마지막 호출의 컨텍스트(입력 + cache 생성 + cache 읽기)가 40만 토큰 이상이면 세션마다 한 번, 사용자와 모델 둘 다에게 두 줄로 "이 작업 단위를 끝내면 인계 메모를 쓰고 새 세션에서 이어 가라"고 알린다. 막지 않는다. 기록을 끝에서부터 읽는다. 문턱은 HARNESS_CONTEXT_NUDGE(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에 올린다
prompt-check 스킬 사람이 큰 일 전에 부를 때만 프롬프트를 다시 쓰지 않고 목표·완료 기준·범위와 금지·검증 명령·코드에 없는 제약·출력 형식 6칸 중 빈 칸만 한 번에(최대 3개) 묻고, 원문에 칸을 붙여 진행한다
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다.