Commit Graph
6 Commits
Author SHA1 Message Date
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 435cf790d0 chore(ledger): 회고 루프 작업의 실측과 회고를 남긴다 2026-11-08 23:10:29 +09:00
DongHyeonka 403716f0f4 docs(retro): 두 장부의 첫 회고 표와 보정 숫자를 남긴다
문제: 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건.
2026-11-08 23:09:32 +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 72078ca1d4 chore(ledger): 첫 작업의 예측과 실측을 남긴다
이 repo를 만든 작업(h2-harness-repo)의 착수 예측(2026-11-07 23:39)과
실측을 장부 첫 두 줄로 둔다. 작업 중 38분·호출 125·출력 19.3만으로
예측 p30(70분·200·25만)보다 작았다. 틀린 이유와 다음에 바꿀 것은 actual
줄의 why 칸에 있다.

검증: ledger.py append가 칸을 검사해 통과했고 precedents가 두 줄을
묶어 보였다.
2026-11-08 10:42:29 +09:00
DongHyeonka 73da7065b0 feat(template): 새 프로젝트 뼈대와 new-project.sh를 더한다
문제: 새 프로젝트마다 루트 지침, Claude Code 설정, 검증 진입점, 비전·
문제 정의 양식, 장부를 손으로 다시 만든다. 플러그인으로는 루트 문서와
권한 deny를 나눠 줄 수 없다(플러그인 CLAUDE.md·권한은 읽히지 않는다).

고른 방법: 공통 동작은 플러그인, 프로젝트 파일은 template/ 복사로
나눈다(결정 Q15). scripts/new-project.sh가 template/을 빈 폴더에 복사하고
이름·설명·마켓 주소를 바꾼 뒤 git init까지 한다. 커밋은 하지 않는다.
- AGENTS.md 양식(40줄 이하, 결정 Q2)과 CLAUDE.md(@AGENTS.md)
- .claude/settings.json: .env deny, 마켓과 harness 플러그인 켜기.
  Agent deny는 넣지 않는다(결정 Q5)
- scripts/verify.sh: 단계(docs·unit·pr·app) 뼈대와 --on <호스트> 운반부.
  작업 트리를 패치로 옮겨 기준 커밋의 새 worktree에 적용하고 트리 해시를
  맞춘 뒤 잠금 아래에서 돌린다. push하지 않는다(설계 6.1절)
- 빈 양식: docs/vision.md, docs/problem-statement.md, docs/adr/0000-template.md
- docs/ledger/: 빈 장부와 형식 설명, .gitattributes merge=union(결정 Q11)
repo 자신의 AGENTS.md·README·docs/README.md(설계와 다르게 정한 것)와
scripts/check.sh도 같이 둔다.
버린 대안: 템플릿만(공통 훅 수정이 모든 repo 손작업), 플러그인만(루트
문서·deny를 못 준다).

위험: verify.sh의 원격 운반부는 가짜 ssh(같은 기계)로만 시험했다. 실제
desktop에서는 아직 돌리지 않았다. unit·pr·app 단계 본문은 비어 있다
(종료 코드 3).

검증: scripts/check.sh 통과(플러그인 17, 템플릿 10, validate --strict).
템플릿 시험은 이름 바꾸기, 남은 {{…}} 없음, AGENTS.md 40줄 이하,
settings의 플러그인·deny, 빈 폴더가 아니면 멈춤, verify docs, 가짜 ssh로
패치 적용·트리 해시·worktree 정리와 원격 실패(종료 코드 4)를 본다.
scratchpad에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
2026-11-08 00:02:33 +09:00