Harness, compact-window and seed (한국어)

다섯 원칙(Ratchet · Evidence · PEV · Structured Task · Default Safe Path)을 한 줄 명령으로 CLAUDE.md에 셋업하고 statusline이 🅷 5/5로 점수화합니다. 같은 에러가 반복되면 🅷⚠ ratchet? 알림이…

🅷 Harness 모드

다섯 원칙(Ratchet · Evidence · PEV · Structured Task · Default Safe Path)을 한 줄 명령으로 CLAUDE.md에 셋업하고 statusline이 🅷 5/5로 점수화합니다. 같은 에러가 반복되면 🅷⚠ ratchet? 알림이 떠서 룰로 승격할 수 있습니다.

sprag harness init                # 이 프로젝트에 셋업
sprag harness init --global       # ~/.claude/CLAUDE.md, 모든 프로젝트에 적용
sprag harness check               # 현재 점수 (글로벌 fallback 인정)
sprag harness analyze             # 훅 없이도 수동으로 전사 분석을 실행해 harness-state.json 갱신
sprag harness promote <N> --global|--project   # 경고 #N → ratchet 룰 (스코프 필수)
sprag harness promote "<룰 텍스트>" --global|--project  # 내가 직접 정의한 룰도 같은 명령으로 등록
sprag harness pull                # 패키지 동봉 큐레이션 룰 → 내 글로벌 래칫에 등록 (opt-in, 중복 스킵)
sprag harness list / rm <N>       # 룰 조회 / 삭제 (자동 .bak)
sprag harness off | on            # 🅷 표시 토글

• promote는 non-TTY 환경(스크립트나 LLM 호출)에서 --project 또는 --global 플래그가 반드시 필요합니다. 적용 범위가 사용자에게 묻지 않은 채 결정되는 사고를 막기 위한 설계입니다.
• pull은 패키지에 동봉된 제작자 큐레이션 래칫 룰(presets/ratchet-rules.json, 실제 반복 사고에서 승격된 범용 룰만)을 내 글로벌 래칫(~/.claude/ratchet.md)에 등록합니다. 설치(install)나 init은 아무것도 자동 주입하지 않으며, pull은 항상 opt-in이고 재실행해도 중복이 없습니다(멱등). 마음에 안 드는 룰은 harness rm으로 제거하면 됩니다.
• seed는 같은 프리셋을 한 건씩 물어보는 경로입니다. pull이 래칫 룰 전체를 한 번에 등록하는 명령인 데 반해, seed는 모델 피팅 프리셋까지 포함해 설치·업그레이드 후 첫 세션에서 한 건씩 제안합니다 (아래).
• 🅷⚠ 런타임 경고(ratchet? no-evidence PEV-skip)는 30분 후 자동 만료되고, 하위 디렉터리 세션도 프로젝트에 올바르게 매칭됩니다. PEV-skip은 변경성 도구(Edit/Write/Bash)만 카운트해 읽기 위주 세션에서는 발동하지 않습니다 (v2.16.0+).

📦 compact-window: 1M 컨텍스트의 자동 압축 지점 고정

Claude Code는 min(autoCompactWindow, 모델 최대 창)에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. 1M은 너무 크니 40만~70만 범위를 권장합니다. 큰 붙여넣기용 여유는 200k 세션의 2~3.5배로 남기면서 꼬리만 잘라냅니다.

권장 범위 안이면 경고하지 않습니다. 40만은 절감이 압축 횟수를 이기는 하한이고, 긴 세션은 그보다 여유가 더 필요한 경우가 많습니다. 미설정이거나 70만을 넘을 때만 알립니다(그보다 낮게 잡은 건 더 공격적으로 아끼겠다는 선택이라 그냥 둡니다).

200k 컨텍스트는 경고 대상이 아닙니다. 창이 이미 200k 이하이므로 이 설정으로 달라지는 것이 없기 때문입니다.

sprag compact-window                       # 현재 상태 (모델·창·설정값·출처)
sprag compact-window set --global          # ~/.claude/settings.json 에 50만 고정 (범위 중간)
sprag compact-window set --project         # <root>/.claude/settings.json 에 고정
sprag compact-window set --global --value 600k    # 값 직접 지정 (10만~1M)
sprag compact-window off | on              # 경고 표시 토글

• 1M 모델인데 미설정이거나 40만을 넘으면 statusline에 🅷⚠ compact-window?가 뜨고, 세션 브리핑이 등록 명령까지 알려줍니다.
• 적용 범위(--global 또는 --project)는 set에서 반드시 지정해야 합니다. 글로벌 설정 파일을 사용자에게 묻지 않고 수정하는 일을 막기 위한 설계입니다.
• 기존 settings.json의 다른 키는 그대로 보존하고 .bak을 남깁니다. JSON이 깨져 있으면 아무것도 쓰지 않고 중단합니다.
• 셸에 CLAUDE_CODE_AUTO_COMPACT_WINDOW가 export돼 있으면 그쪽이 settings.json보다 우선합니다 (set이 이 경우를 감지해 알려줍니다).

🌱 seed: 설치 직후부터 위임이 걸리게 하는 시작 룰

모델 피팅 래칫(ratchet-model.md)은 빈 파일로 시작합니다. route-scan이 사용자의 로그에서 같은 유형의 작업을 여러 번 관측하고, 사용자가 그 후보를 승인해야 룰이 생깁니다. 즉 갓 설치한 상태에서는 위임이 한 건도 걸리지 않고, 그 상태가 며칠 이어집니다. 정작 절감 효과가 가장 클 시기입니다.

seed는 패키지에 동봉된 프리셋으로 그 공백을 메웁니다.

등록 절차: 설치나 업그레이드 후 첫 세션에서 SessionStart 훅이 대기 중인 프리셋을 모델에게 전달하고, 모델이 한 건씩 순서대로 등록 여부를 묻습니다. 사용자가 답하면 곧바로 아래 명령을 실행합니다.

sprag seed                                   # 대기 중인 프리셋과 응답 기록
sprag seed accept <id> --global|--project     # 한 건 등록 (적용 범위 필수)
sprag seed accept all --global                # 사용자가 "전부 등록"이라고 답한 경우
sprag seed skip <id>                          # 거절 — 다시 묻지 않습니다
sprag seed reset                              # 응답 기록을 지워 전체를 다시 제안 대상으로

• 승인 없이는 아무것도 기록되지 않습니다. 거절한 룰은 업그레이드 후에도 다시 묻지 않고, 새 릴리스에서 추가된 프리셋만 다음 세션에 제안됩니다.
• 사용자가 이미 같은 유형(같은 티어·카테고리)의 룰을 직접 승인해 두었다면 그 프리셋은 제안하지 않습니다.
• 프리셋으로 등록한 룰은 남의 통계를 내 것처럼 표시하지 않습니다. 등록 직후에는 preset (curated)로 적히고, 이후 스캔에서 실제 발화와 위임 결과가 측정되면 그 수치로 대체됩니다. 위임 에러율이 기준을 넘으면 다른 룰과 똑같이 재검토 플래그가 붙습니다.
• 적용 범위는 --global과 --project 중 반드시 명시해야 합니다. 훅 환경은 non-TTY라 CLI가 직접 물을 수 없으므로, 모델이 사용자에게 확인한 뒤 플래그를 붙여 실행합니다.