autoharness

AutoHarness
Claude Code를 위한 자기 학습 스킬

autoharness는 Claude Code를 위한 자기 학습 스킬 레이어입니다. 실제 세션에서 스킬을 학습하고, 유사 중복을 쌓아두는 대신 같은 시나리오의 스킬들을 병합하며, 사용 중에 업데이트하고, 더 이상 사용되지 않는 스킬은 정리합니다 — 그래서 레이어가 스스로 깨끗하게 유지되며, 자신이 직접 작성한 스킬에만 손을 댑니다.

같은 모델, 다른 하네스 — CORE-Bench(HAL)에서 42% → 78%.
하네스가 일의 상당 부분을 담당하지만(swyx의 Big Model vs Big Harness), 여전히 매 모델 세대마다 손으로 다시 만들어집니다. autoharness는 그중 한 조각 — 스킬 레이어 — 이 스스로를 유지할 수 있다고 봅니다.

실제 작업에서 학습
각 에피소드는 이미 진행 중이던 세션에서 스킬로 정제됩니다 — 별도의 데이터 수집이나 재생 루프가 없습니다. 세션이 충분한 작업을 마치면 스스로 발동하며, /learn은 지금 당장 교훈을 남기고 싶을 때 온디맨드로 정제합니다.

쌓기만 하지 않고 그룹화
새 에피소드가 항상 스킬을 추가하지는 않습니다 — 리플렉터가 기존 스킬과 비교해 같은 시나리오의 스킬들을 하나로 접어 넣으므로, 레이어는 유사 중복을 누적하는 대신 카테고리별로 통합됩니다. 병합 시 어떤 스킬이 어떤 스킬을 흡수했는지 기록되므로, 병합이 소멸로 오인되지 않습니다.

자신의 라이브러리를 항상 시야에 둠
모든 세션은 자신이 작성한 스킬들의 그룹화된 인덱스로 시작하므로, 호스트가 우연히 이를 노출하는지에 회상이 의존하지 않습니다. 호스트의 네이티브 회상은 그대로 두고, 인덱스는 그 위에 추가됩니다.

벤치마크가 아닌 사용 중에 검증
스킬은 홀드아웃 점수가 아니라 이후 턴에서 준수됨으로써(사용 가능했던 요청 대비 로드됨) 살아남습니다. 활성 경로에 오라클이 없고, 전용 평가에 토큰을 쓰지 않습니다.

자신의 스킬만
이 플러그인을 통해 생성한 스킬에만 손을 댑니다 — 직접 작성했든 설치했든 그 외의 모든 것은 완전히 그대로 둡니다.

나중을 위한 증거 보존
모든 생성/업데이트는 시나리오와 결정을 스킬별 원장에 기록합니다 — 원한다면 실제 사용에서 벤치마크를 구축할 원재료입니다.

설치
PATH의 python3로 Python 3.11+가 필요합니다 — autoharness는 전적으로 Python으로 실행되며(서드파티 의존성 없음), 이것이 없으면 훅과 MCP 서버가 작동하지 않습니다. 훅은 bare python3를 해석하므로, PATH에서 더 앞선 구버전 인터프리터(Xcode는 /usr/bin/python3에 3.9.6을 제공)가 있으면 해당 세션의 모든 훅이 꺼집니다; autoharness는 이를 stderr로 알립니다.

Claude Code 입력 상자에 다음을 입력하세요.

/plugin marketplace add tigerless-labs/autoharness
/plugin install autoharness@autoharness

그런 다음 /reload-plugins를 실행하거나 Claude Code를 재시작하세요.

설정 불필요. 이제 세션을 관찰하고 학습된 스킬을 백그라운드에서 .claude/skills/에 배치합니다. 주기와 라이프사이클 임계값은 조정 가능합니다 — Configuration을 참고하세요.

호출할 것은 없지만, 원할 때를 위한 진입점이 하나 있습니다: /learn은 지금 진행 중인 세션을 정제합니다 — 무언가를 해결한 후 말하면, 그 교훈은 백그라운드 패스가 사용하는 것과 동일한 제안-및-검증 체인을 거칩니다.

MCP 서버 명명. .claude-plugin/plugin.json은 서버를 stage_skill로 등록하지만, 에이전트 정의는 정규화된 이름 mcp__plugin_autoharness_stage_skill__stage_skill을 참조합니다. 이 변환은 자동입니다: 플러그인 런타임이 플러그인 이름(autoharness)과 서버 키로부터 정규화된 이름을 구성합니다. 플러그인 컨텍스트 밖에서(예: 서버를 수동으로 등록)라면 도구는 mcp__stage_skill__stage_skill로 사용 가능하지만, 에이전트 허용 목록은 여전히 플러그인 네임스페이스 형식을 참조합니다. 두 이름 모두 일치시키려면 항상 플러그인으로 설치하세요. 서버는 루트 .mcp.json이 아니라 매니페스트에 선언됩니다. 플러그인 루트가 저장소 루트이기 때문입니다: 그곳의 .mcp.json은 이 체크아웃의 프로젝트 설정이기도 하여, 플러그인의 동일 명령 서버보다 우선하고 저장소 내부 세션에서 리플렉터가 도구를 잃게 만듭니다.

업데이트
업데이트와 제거는 터미널 형식(claude plugin …)으로 표시됩니다; Claude Code 내부에서는 동일한 작업이 /plugin 메뉴에 있습니다.

터미널에서 업데이트 — 마켓플레이스 이름으로 카탈로그를 새로고침한 다음, 전체 plugin@marketplace id로 플러그인을 업데이트하고 재시작하세요:

claude plugin marketplace update autoharness
claude plugin update autoharness@autoharness

그런 다음 Claude Code를 재시작하여 적용하세요 — 버전 범프는 핫 리로드가 아니라 새로 캐시된 사본입니다.

새로고침이 먼저인 것은 의도적입니다: 이것이 없으면 업데이트가 오래된 로컬 카탈로그를 확인하여, 실제로 더 새로운 릴리스가 나왔는데도 이미 최신 버전이라고 보고할 수 있습니다.

서드파티 마켓플레이스는 기본적으로 자동 업데이트가 꺼져 있습니다. 향후 릴리스를 자동으로 받으려면 한 번 활성화하세요: /plugin → Marketplaces → autoharness → Enable auto-update. 설치된 사본은 plugin.json의 버전으로 캐시됩니다; 해당 필드가 범프되어야만 릴리스가 사용자에게 도달합니다.

제거
claude plugin uninstall autoharness@autoharness
claude plugin marketplace remove autoharness

제거는 실행만 중단합니다 — 배치된 스킬과 자체 상태는 플러그인 밖에 있어 디스크에 남습니다. 이것들까지 지우려면 상태 디렉터리(~/.claude/autoharness/ 전역, <repo>/.claude/autoharness/ 프로젝트별)와 .claude/skills/ 아래의 자체 작성 스킬을 삭제하세요(각각 self-authored 원장 마커가 있어 직접 작성한 것과 쉽게 구분됩니다). 직접 작성한 스킬은 절대 건드리지 않습니다.

Configuration
모든 노브는 내장 기본값이 있는 AUTOHARNESS_* 환경 변수입니다 — 속도를 바꾸고 싶지 않다면 설정할 것이 없습니다.

Placement — 관리하는 레이어

변수
기본값
하는 일

AUTOHARNESS_DISABLE_GLOBAL
0
프로젝트 전용 배포를 위해 1로 설정합니다. 전역 생성 인텐트는 스테이징과 배치 전에 거부됩니다; 전역 요청/사용/조회 카운터, 아카이빙, 고아 정리, 회상, 큐레이터 스냅샷, 메트릭은 건너뜁니다. 기존 전역 스킬은 그대로 유지됩니다. 프로젝트 레이어 학습은 정상적으로 계속됩니다.

AUTOHARNESS_GLOBAL_ROOT
(미설정)
전역 레이어의 루트를 ~/.claude로 대체합니다. 미설정 또는 빈 값은 기본 동작 — 실제 홈입니다. autoharness 자체가 샌드박스에서 실행되어야 하고(고정된 클론, CI, 평가 하네스) 프로덕션 스킬 라이브러리는 그대로 유지되어야 할 때 설정하세요. 프로젝트 레이어는 영향받지 않습니다: 여전히 세션 자체의 체크아웃에 키가 맞춰집니다.

Cadence — 언제 학습하는가

변수
기본값
하는 일

AUTOHARNESS_REFLECT_EVERY_N
50
리플렉션 주기로, 턴이 아니라 도구 호출로 계산됩니다: 모든 메인 세션 도구 호출이 카운터를 진행시키고, 이를 N 너머로 밀어내는 턴이 백그라운드 리플렉션으로 끝납니다. 작업 구간이 트리거하며; 대화만 하는 세션은 절대 트리거하지 않습니다. 낮을수록 더 빨리 학습하고 더 많은 자식 세션을 생성합니다.

AUTOHARNESS_CONSOLIDATE_EVERY_N
250
큐레이터(라이브러리 전체를 병합하는 주기적 패스)에 대한 동일한 양자입니다. 리플렉션 주기보다 훨씬 높게 유지됩니다 — 통합은 정제보다 드뭅니다.

AUTOHARNESS_DIGEST_EXCHANGES
20
에피소드 윈도우 이전의 교환 몇 개를 리플렉터의 사전 컨텍스트 다이제스트로 압축할지(텍스트 + 도구 이름만). 실제 대화를 재생하는 fork 캐리어에서는 사용되지 않습니다.

AUTOHARNESS_CARRIER
bundle
리플렉션을 무엇이 운반하는지. bundle은 정제된 윈도우 + 다이제스트를 새 서브에이전트에 전달합니다. fork는 방금 종료된 세션을 재개하고 포크하여, 리플렉터가 부모의 따뜻한 캐시에서 실제 대화를 읽습니다. 캐시 히트 측정이 나올 때까지 bundle로 유지됩니다.

Recall — 모델이 보는 것

변수
기본값
하는 일

AUTOHARNESS_INDEX_SUSPENDED
0
인덱스 주입을 완전히 중단하려면 1로 설정합니다. 나머지는 모두 계속 실행됩니다 — 라이프사이클 패스, 사용/조회 카운터, 마지막 실행 요약 — 그래서 인덱스가 실제로 얼마나 가치 있는지 측정하기 위한 스위치이자, 컨텍스트를 여기에 쓰고 싶지 않은 사람을 위한 것입니다.

AUTOHARNESS_INDEX_DESC_MAX_CHARS
60
세션 시작 인덱스의 줄당 설명 예산. 인덱스는 스캔 표면이지 전체 트리거 텍스트가 아닙니다 — 더 긴 줄을 위해 올리되, 매 세션마다 컨텍스트를 대가로 치릅니다.

AUTOHARNESS_SKILL_DESC_MAX_CHARS
1024
스킬 자체 설명에 대한 하드 캡으로, 호스트의 문서화된 한도와 일치합니다; 더 긴 것은 로드 시 조용히 잘리는 대신 거부됩니다.

AUTOHARNESS_SKILL_BODY_MAX_LINES
25
고도 캡: 이 비어 있지 않은 줄 수를 초과하는 SKILL.md 본문은 규칙이 아닌 트랜스크립트로 거부됩니다. 뒷받침 세부 사항은 스킬의 references/에 속합니다.

Lifecycle — 무엇이 살아남는가

변수
기본값
하는 일

AUTOHARNESS_MATURITY_PROJECT
100
프로젝트 레이어의 시험 기간 게이트: 스킬이 배치된 이후 해당 레이어에 이만큼의 요청이 도착하면 졸업 심사를 받습니다. 그때까지는 평소처럼 회상되지만 아카이빙될 수 없습니다.

AUTOHARNESS_MATURITY_GLOBAL
300
전역 레이어에 대한 동일한 게이트 — 전역 스킬은 모든 프로젝트에서 로드되므로 더 높습니다.

AUTOHARNESS_CAPACITY_PROJECT
50
프로젝트 레이어의 성숙한 스킬 수 상한. 졸업자에게는 용량 경쟁이 유일한 소멸입니다: 성숙한 풀이 이를 초과할 때까지 아무것도 아카이빙되지 않으며, 그 후 가장 낮은 사용률부터 먼저 갑니다. 세션 시작 인덱스를 제한하지는 않습니다: 시험 기간 멤버도 인덱싱되며 이 상한 밖에 있으므로, 인덱스는 두 상한이 아니라 생성률의 함수입니다.

AUTOHARNESS_CAPACITY_GLOBAL
20
전역 레이어에 대한 동일한 상한 — 영향 범위가 모든 프로젝트이므로 더 작습니다.

AUTOHARNESS_GRADUATION_SUSPENDED
0
졸업 심사를 완전히 보류하려면 1로 설정하여, 사용되지 않음으로 인해 아무것도 아카이빙되지 않게 합니다. 회상 표면을 의심할 이유가 있을 때를 위한 것입니다: 그렇다면 제로 사용으로 아카이빙하는 것은 한 번도 제공되지 않은 스킬을 처벌하는 셈이 됩니다. 용량 경쟁은 여전히 적용됩니다.

AUTOHARNESS_SNAPSHOT_KEEP
5
병합 전에 큐레이터가 각 스킬 트리의 실행 전 스냅샷을 몇 개 유지하는지. 병합은 단일 원자적 이름 변경으로 되돌릴 수 없는 유일한 작업입니다.

Notify — 발생하는 대로 듣기

기본적으로 꺼져 있습니다. 세션 시작 요약 줄은 실행을 한 세션 늦게 보고하며, 이름 없이 개수만 알려줍니다; 이들은 드레인이 끝나는 즉시 동일한 실행 계정을 푸시합니다. Fail-open: 알림기는 계정이 기록되고 인텐트 큐가 비워진 후에만 실행되므로, 없거나 실패하거나 멈춘 알림기는 드레인을 지연시킬 수는 있어도 실패시키거나 재생시키지는 않습니다.

변수
기본값
하는 일

AUTOHARNESS_NOTIFY
(미설정)
실행당 네이티브 알림을 위해 desktop으로 설정 — macOS에서는 osascript, Linux에서는 설치된 경우 notify-send(그렇지 않으면 조용한 no-op). 무엇이 배치되고 무엇이 거부되었는지 이름을 붙입니다, 예: create foo, patch bar · rejected: baz. macOS에서는 알림이 Script Editor에 귀속됩니다; 아무것도 나타나지 않으면 시스템 설정 → 알림에서 허용하세요.

AUTOHARNESS_NOTIFY_CMD
(미설정)
실행 기록 JSON(runs/<run-id>.json과 동일한 형태)을 stdin으로 받는 명령(셸 argv처럼 분할되며, 셸을 통해 실행되지 않음)으로, 한 줄 요약은 AUTOHARNESS_NOTIFY_SUMMARY에 담깁니다. Slack, 웹훅 또는 그 밖의 것에 대한 훅입니다. 스킬 이름은 먼저 정제되며, 명령은 자식 세션 가드가 설정된 상태로 실행되므로 claude를 실행하는 알림기 자체가 캡처되지 않습니다. desktop과 함께 작동합니다.

AUTOHARNESS_NOTIFY_TIMEOUT_S
5
채널당 정수 초, 최소 1: 알림기가 드레인을 얼마나 지연시킬 수 있는지. /learn 드레인은 호스트의 Stop 훅 안에서 실행되므로, 이것이 턴을 지연시킬 수 있는 최대치이기도 합니다.

Claude Code가 실행되는 환경에서 설정하세요 — 셸(export AUTOHARNESS_REFLECT_EVERY_N=10) 또는 .claude/settings.json의 env 맵:

{ "env" : { "AUTOHARNESS_REFLECT_EVERY_N" : " 10 " } }
훅은 매 이벤트마다 환경을 읽으므로, 변경은 다음 세션부터 적용됩니다. 기본값은 경험적 보정을 기다리는 의도적인 자리표시자입니다; 캡처된 윈도우와 스테이징된 파일의 바이트 캡은 고정 상수이며 env 노브가 아닙니다.

작동 방식
학습 파이프라인이 호스트 옆에서 실행됩니다. 스킬은 사람이 작성한 것처럼 호스트 자체의 이름-및-설명 메커니즘으로 회상되는 평범한 네이티브 파일입니다 — 그 경로는 그대로 둡니다. 그 위에, 각 세션은 autoharness가 작성한 스킬의 인덱스로 시작하므로, 자체 라이브러리가 제공되는지 여부가…