Commit Graph
5 Commits
Author SHA1 Message Date
DongHyeonka 3bc36479d6 feat(plugin): 분야 전문가 협업 스킬 lead·new-expert·harness-eval을 더하고 0.3.0으로 올린다
문제: 여러 분야에 걸친 변경을 리뷰할 때 누구에게 무엇을 맡기고, 결과를
어떻게 합치고, 의견이 부딪치면 누가 정하는지 정한 절차가 없다. 전문가를
더하는 모양과 하네스 판을 비교하는 절차도 없다.

고른 방법:
- lead: 바뀐 경로·위험으로 분야 지식 스킬(렌즈)을 고르고, 고정 칸 brief로
  새 눈 reviewer를 병렬로 띄우고, High는 반증해 살아남은 것만 남기고,
  넘김은 한 번만 더, 충돌은 정한 일곱 순서로, 리뷰-수정은 세 번까지
  (두 번째부터 고친 diff만). 근거: Anthropic 위임 4요소, 공식 code-review의
  반증 필터, Claude Code 팀의 리뷰 라운드 상한.
- new-expert: 전문가 = paths 지식 스킬(함정이 맨 앞). 서브에이전트는 세
  조건(긴 출력, 버려도 되는 병렬, 지시 충돌·자기 리뷰) 중 하나를 보일 때만.
- harness-eval: 정답을 아는 과제를 판마다 돌려 장부 eval 줄로 비교.
  시킬 때만 돈다는 것을 설명에 쓴다.
- 13절 Q9(새 스킬은 모두 모델 호출, 발동 조건을 설명에)를 지킨다.
- 시험: 플러그인 스킬 목록을 고정하고, 설명이 1,024자 안이며
  PROACTIVELY·MUST·CRITICAL·IMPORTANT·<example>이 없는지 본다.
- 버린 대안: 분야 에이전트·범용 리뷰어를 플러그인에 싣기. 플러그인
  에이전트는 harness: 아래 이름이라 템플릿 것과 둘 다 목록에 뜬다.

위험: 세 스킬 설명(약 400~500자)이 모든 세션의 스킬 목록에 더해진다.
스킬 목록이 예산 근처인 기계에서는 덜 쓰는 스킬 설명이 먼저 잘린다.

검증: python3 -m unittest discover -s tests → 10건 통과,
claude plugin validate --strict plugins/harness → 통과.
2026-11-11 22:05:03 +09:00
DongHyeonka cdde857adb feat(ledger): 하네스 판 비교를 eval 줄로 남기고 시작 컨텍스트를 잰다
문제: 하네스 v2(분야 전문가 협업)를 v1과 견주려면 같은 과제를 판마다
돌린 실행을 한 줄씩 남기고 비교해야 하는데, 장부에는 예측·실측만 있다.
실측도 시간·호출·토큰뿐이라 모든 세션의 시작 비용(첫 호출 입력 토큰)과
서브에이전트가 메인에 돌려준 양(컨텍스트 비용)을 볼 수 없다.

고른 방법:
- usage에 start_context(본 기록 첫 호출), subagents·subagent_output_tokens,
  agent_calls(Agent·Task 호출), agent_return_chars를 더한다. 반환 글자는
  Agent 도구 결과와, 백그라운드 결과가 들어오는 대기열 알림
  (queued_command의 <agent-message·<task-notification 머리)을 센다.
  2026-11-11 세션 기록에서 백그라운드 결과가 tool_result가 아니라
  알림으로 오는 것을 확인했다.
- 새 줄 종류 eval(arm·case 필수)과 명령 eval(초안)·compare(과제·판별
  중앙값, 마지막 판/첫 판 비율). precedents는 eval만 있는 작업을 세지 않는다.
- Stop 훅이 0.2.0이 저장한 상태 파일을 이어 읽어도 깨지지 않게 새 칸은
  setdefault로 채운다.
- 버린 대안: eval을 actual 줄에 arm 칸으로 붙이기. 같은 작업의 판 여럿이
  by_task에서 덮이고 회고 대기 계산에 섞인다.

위험: 대기열 알림 모양은 앱 내부 형식이다. 바뀌면 agent_return_chars가
조용히 줄어든다(시험이 지금 모양을 고정한다).

검증: python3 -m unittest discover -s plugins/harness/tests → 24건 통과
(알려진 실패 1). 조건을 하나씩 끈 변이 9개가 모두 시험에 걸렸다.
2026-11-11 22:04:24 +09:00
DongHyeonka f7e235bad7 feat(plugin): 장부가 회고 대기와 효과 판정을 세고 세션 시작에 알린다
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이다. 회고는 사람이
「주 1회」를 기억해야 돌고, 고친 뒤 효과가 없으면 되돌린다는 규칙을
적을 칸도 없다. 지난 4작업은 모두 실측이 p30 아래였는데(실측/p50
시간 중앙값 0.43), 매번 이유 한 줄만 바꿔서 치우침이 그대로 남았다.

고른 방법:
- precedents 끝에 보정 줄을 낸다: 실측/p50 중앙값(시간·호출·출력)과
  p30 아래·p80 위 건수. --ledger를 여러 번 받아 다른 repo 장부를 더한다.
  estimate 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄.
- pending은 예측 밖(p30~p80 밖이거나 why가 있음)인데 retro 줄이 없는
  작업만 보이고, 효과 판정이 없는 개선도 보인다.
- retro 줄에 fix(개선 id)·applied_at, 새 줄 verdict(effective·reverted).
  판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건의 실측이 끝나면 한다.
  개선 전에 예측한 작업은 그 개선의 영향을 받지 않아 세지 않는다.
- SessionStart에 ledger.py nudge를 따로 건다. startup일 때만, 같은
  repo(worktree를 git common dir로 묶어)에 20시간에 한 번 한 줄.
  append가 actual 줄을 쓸 때 예측 밖이면 그 자리에서 한 줄 알린다.
버린 대안: session-start 장부 훅에서 출력(장부 훅 출력 0 규칙을 깬다),
매 세션 넛지(하위 세션마다 같은 줄이 컨텍스트에 쌓인다), 별도
retro 스크립트(이미 있는 ledger.py 명령으로 충분하다).

위험: 넛지는 그 repo의 첫 세션이 하위 세션이어도 나온다. 문구에
「맡은 일이 회고가 아니면 넘긴다」를 넣었다. 다른 repo 장부에 retro
줄이 더해질 때까지 그 repo에서는 하루 한 번 넛지가 나온다.
보정 규칙은 같은 4건으로 잰 값이라 아직 효과를 모른다.

검증: scripts/check.sh rc=0(플러그인 시험 21개 OK, expected failure 1,
템플릿 시험 10개 OK, plugin validate --strict 통과). 새 조건 15개를
하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다. 백엔드 템플릿
장부에 nudge를 돌리면 「회고 안 한 빗나간 예측 3건」 한 줄이 나왔다
(상태 폴더는 scratchpad).
2026-11-08 23:09:32 +09:00
DongHyeonka cf8c8c9575 test(plugin): main checkout 안 worktree의 rm 빈틈을 알려진 실패로 둔다
문제: 이 repo를 `.claude/worktrees/<이름>` worktree에서 시험하면
GuardBashTest.test_rm_outside_or_too_broad_is_blocked가 실패한다.
H12 허용 폴더에 main checkout(git common dir의 부모)이 들어가서,
worktree 자신을 지우는 `rm -rf ./*`와 옆 worktree를 지우는
`rm -rf ../x`가 「작업 폴더 안」으로 통과한다. main checkout에서
돌리면 통과하는 시험이라 지금까지 보이지 않았다.

고른 방법: 두 사례를 따로 떼어, main checkout 안 worktree에서 돌 때만
expectedFailure로 둔다. 판정 코드는 고치지 않았다. H12 절은 소유자
기계의 전역 훅과 같이 바꿔야 하고(AGENTS.md 3번), 전역 훅은 이 작업
범위 밖이다. 버린 대안: 시험의 cwd를 main checkout으로 옮기기(빈틈을
가린다), skip(고쳐져도 알리지 않는다). expectedFailure는 고쳐지면
「뜻밖의 통과」로 시험이 실패해 표시를 지우게 만든다.

위험: worktree 세션에서 위 두 명령은 여전히 막히지 않는다.
전역 훅과 플러그인을 같이 고치는 작업이 따로 필요하다.

검증: worktree에서 python3 -m unittest discover -s plugins/harness/tests
→ OK (expected failures=1). main checkout에서는 예전처럼 통과로 돈다
(NESTED_WORKTREE가 거짓이면 데코레이터가 없다).
2026-11-08 23:08:48 +09:00
DongHyeonka ddbfc3dcc3 feat(plugin): 하네스 플러그인과 마켓을 더한다
문제: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부가 소유자
기계의 ~/.claude에만 있거나 아예 없다. 다른 기계·파생 서비스·새 프로젝트는
받을 길이 없고, 훅 코드에 이력과 리뷰도 없다.

고른 방법: 이 repo를 플러그인 마켓으로 두고 공통 플러그인 harness 하나를
싣는다(설계 harness/01-harness-design.md 11절, 결정 Q13 (c)·Q15).
- H12(PreToolUse Bash): 호스팅 원격 force push·--mirror·보호 브랜치 지우기,
  작업 폴더·/tmp 밖이나 너무 넓은 rm -r, DB·볼륨·migration 삭제를 막는다.
  셸 파서는 소유자 전역 guard_bash.py와 정의가 같은 사본이다. 사용자 전역
  설정에 guard_bash.py H12가 있으면 건너뛰어 두 번 막지 않는다.
- N4(PostToolUse Write·Edit): 비밀 값 모양을 몇 줄로 알리고 막지 않는다.
- 장부 SessionStart·Stop 훅: ~/.claude/harness/에 세션 기록 경로와 누적
  실측을 쓴다. 출력이 없어 컨텍스트 비용이 0이다.
- 스킬 estimate·retro·techdebt: 모두 모델이 부르고 발동 조건을 설명에
  문단으로 적었다(결정 Q9).
버린 대안: H12에 git reset --hard·clean·checkout -- .를 넣는 것(설계
5.1절). 이 기계 세션 기록의 Bash 명령 43,078개에서 정당한 사용이
61·32·31건이라 거짓 양성이 크다. 전역 훅을 플러그인으로 옮기는 것은
Q13대로 안정된 뒤에 한다.

위험: H12 판정이 전역 훅과 두 벌이다. 소유자 기계의 전역 훅 시험이 두
사본의 정의를 비교한다. 원격(ssh) rm은 작업 폴더를 몰라 너무 넓은
대상만 막는다.

검증:
- python3 -m unittest discover -s plugins/harness/tests: 17개 통과.
  조건을 하나씩 끈 사본 12개에서 모두 실패를 확인했다.
- 같은 판정을 이 기계 세션 기록 명령 43,078개에 돌려 5건이 막힘:
  의도한 막힘 3(desktop 작업 폴더 통째 rm 2, -p 없는 down -v 1),
  시험용 볼륨 rm 1, 당시 프로젝트 폴더를 알 수 없는 rm 1.
- claude plugin validate --strict: 마켓·플러그인 모두 통과.
- 로컬 경로 마켓으로 설치(--scope local) 뒤 새 세션에서 스킬 셋이 보이고
  SessionStart·Stop 훅이 기록을 썼다. 항상 드는 비용 약 698토큰.
2026-11-08 00:02:22 +09:00