Autoharness: 실제 세션에서 스킬을 자동 학습·관리하는 Claude Code 오픈소스 플러그인

타이거리스 랩스(Tigerless Labs)가 개발한 '오토하네스(Autoharness, v0.5.3)'는 Claude Code 사용자의 실제 코딩 세션 흐름을 관찰하여 재사용 가능한 에이전트 스킬을 자동으로 추출하고 유지보수하는 MIT 라이선스 기반의 오픈소스 플러그인입니다. 별도의 벤치마크 평가 루프나 백그라운드 상주 데몬 없이, 개발자가 실제로 수행한 작업 에피소드에서 교훈을 증류(distill)해 .claude/skills/ 디렉터리에 네이티브 스킬로 정착시킵니다.

이미지 출처: tigerless-labs / GitHub

에이전트에게 반복 작업을 가르치기 위해 사람이 수동으로 스킬 명세서를 작성하거나, 세션이 누적되면서 유사한 스킬 파일이 난립해 프롬프트 컨텍스트를 낭비하던 문제를 해결하기 위해 고안되었습니다. Autoharness는 단순히 스킬을 쌓아두는 데 그치지 않고 유사 시나리오를 자동 통합하며, 사용되지 않는 스킬을 스스로 정리하는 자가 학습 레이어를 제공합니다.

세션 관찰 기반의 스킬 추출과 4단계 분리 아키텍처

Autoharness의 가장 큰 기술적 특징은 에이전트의 작업 경로를 방해하지 않는 분리형(Decoupled) 파이프라인 구조입니다.

플러그인은 Claude Code의 세션 수명 주기 이벤트에 연동되는 파이썬 훅과 경량 컴포넌트들로 구성되어 있으며, 세션당 추가 토큰 오버헤드는 매니페스트 번들 기준 약 77토큰 수준으로 최소화되었습니다.

• 캡처 훅(Capture Hooks): 세션 내 호스트 턴과 도구 호출(Tool Calls)을 기록하며, 민감한 정보는 사전에 마스킹(redact) 처리하여 저장합니다.
• 리플렉터(Reflector, REF): 설정된 턴 윈도우가 종료되는 에피소드 경계에서 작동합니다. 최근 N회 턴의 상세 도구 I/O 및 이전 대화의 압축 요약을 기존 스킬 인덱스와 비교 분석하여 신규 생성, 병합, 패치, 삭제 등의 '의도(Intent)'를 생성합니다. 리플렉터는 제안만 수행하며 디스크 쓰기 권한이 없습니다.
• 프로모터(Promoter): 메모리 상에서 리플렉터의 제안을 안전성, 구조, 완성도, 자체 작성 여부 기준으로 검증(Lint)한 뒤, 원자적 이름 변경(atomic rename)을 통해 실제 .claude/skills/ 디렉터리에 반영하는 유일한 쓰기 주체입니다.
• 라이프사이클 매니저(Lifecycle Manager, MNG): 상주 데몬 없이 새 세션이 시작될 때 1회 게으른 계산(lazy evaluation)으로 실행되어 스킬들의 사용 빈도와 수명 주기를 재계산합니다.
• 즉시 학습 명령어(/learn): 백그라운드 주기 외에도 사용자가 특정 작업을 마친 뒤 터미널에서 /learn 명령어를 입력하면 현재 세션의 내용을 즉시 분석하여 스킬 반영 체계를 호출할 수 있습니다.

스킬 증식 방지: 중복 병합, 격리 원칙, 아카이브 수명 주기

에이전트가 자체적으로 스킬을 작성할 때 발생하는 가장 큰 위험은 유사한 파일이 무한히 증식해 컨텍스트 창을 채우거나, 사용자가 수동으로 작성한 중요한 규칙을 덮어쓰는 문제입니다. Autoharness는 엄격한 격리 및 정리 규칙을 적용합니다.

• 우산형 스킬로의 병합(Grouping & Folding): 새로운 작업 시나리오가 기존 스킬과 유사할 경우 신규 파일을 추가하지 않고 기존 스킬에 통합(fold)합니다. 병합 시 어떤 스킬이 흡수되었는지 기록하여 스킬이 유실된 것으로 오인되지 않도록 관리합니다.
• 자체 생성 스킬 격리 원칙: 플러그인은 자신이 직접 생성한 스킬(self-authored 마커 보유)만 수정하거나 아카이브합니다. 사용자가 직접 작성했거나 외부에서 설치한 스킬은 일체 변경하지 않습니다.
• 사이드카 원장(.sidecar.json) 유지: 스킬마다 생성 및 수정 이유, 실제 세션 증거, 리플렉션 워터마크를 별도의 JSON 원장에 기록하여 사후 추적성을 보장합니다.
• 유예 기간 및 용량 기반 아카이브: 새로 생성된 스킬은 프로젝트 단위 유예 게이트(기본 100회 요청) 동안 관찰되며, 이 기간 동안 단 한 번도 호출되지 않은 스킬은 .claude/skills/.archive/로 안전하게 이동됩니다. 유예를 통과한 성숙 스킬이라도 프로젝트 최대 용량(기본 50개)을 초과하면 사용 빈도가 가장 낮은 스킬부터 아카이브됩니다.

설정 환경변수와 실무 도입 시 유의점

Autoharness의 모든 동작 파라미터는 AUTOHARNESS_* 환경변수를 통해 조정할 수 있습니다.

• AUTOHARNESS_REFLECT_EVERY_N: 리플렉션 트리거 주기입니다. 소셜 미디어 일각에서는 50회 툴 호출마다 동작한다고 소개되기도 했으나, 공식 리포지토리 기본값은 호스트 턴 10회 기준입니다. 값을 낮출수록 학습 주기가 빨라지지만 하위 세션 생성이 늘어납니다.
• AUTOHARNESS_MATURITY_PROJECT: 프로젝트 레벨의 스킬 수습 유예 기준(기본값 100회 요청)입니다.
• AUTOHARNESS_CAPACITY_PROJECT: 성숙 스킬의 프로젝트 보관 한도(기본값 50개)입니다.

실무에 도입할 때 고려해야 할 주의사항도 존재합니다. 백그라운드 리플렉션은 별도의 하위 Claude Code 세션을 스폰하므로 API 토큰 소비량이 증가합니다. 또한 개발자가 문제 해결 과정에서 일시적으로 적용한 임시 우회책(workaround)이나 비효율적인 코드 수정 패턴을 에이전트가 영구 스킬로 잘못 학습해 고착화할 위험이 있습니다.

따라서 소셜 미디어 상에서 언급되는 CORE-Bench 벤치마크 상승(42% → 78%) 주장과 같은 마케팅성 수치에 전적으로 의존하기보다는, 리포지토리의 설계 철학대로 실제 사용 준수율(adherence)을 중심으로 평가하고 .sidecar.json 원장을 주기적으로 점검하는 운영 방식이 권장됩니다. 파이썬 3 표준 라이브러리만을 요구하며 리눅스 및 macOS 환경의 Claude Code에서 구동됩니다.

출처

• GitHub: tigerless-labs/autoharness
• ClaudePluginHub: tigerless-labs-autoharness
• RoundtableSpace X (@RoundtableSpace): Autoharness 소개 트윗