Ancienttwo/repo-harness
File-backed workflow harness for reliable Claude Code and Codex sessions.
해결하는 문제
repo-harness는 AI 코딩 세션이 휘발성 채팅 메모리에 의존하는 문제를 해결합니다. 개발자가 서로 다른 AI 에이전트(Claude 및 Codex 등) 사이를 전환하거나 새로운 세션을 시작할 때, 이전 계획, 진행 상황 및 결정 사항의 컨텍스트가 손실되는 경우가 많아 에이전트가 리포지토리 구조와 현재 상태를 다시 찾는 데 토큰과 시간을 낭비하게 됩니다.
작동 방식
이 프로젝트는 프로젝트 상태의 "진실"이 채팅 기록이 아닌 리포지토리 자체에 저장되는 파일 기반 워크플로우를 구현합니다. CLI와 호스트 어댑터(~/.claude/settings.json 및 ~/.codex/hooks.json 등)와 통합되는 훅 시스템을 사용합니다.
주요 메커니즘은 다음과 같습니다:
- 세션 핸드오프 (Session Handoffs): 훅이 컨텍스트, 계획 및 핸드오프 내용을 프로젝트 파일(예:
.ai/harness/handoff/resume.md)에 다시 기록하여, 새로운 세션이 마지막 세션이 중단된 지점에서 정확히 재개될 수 있도록 합니다. - 토큰 효율성: 구조적 쿼리를 위해 사전 구축된 CodeGraph 인덱스를 사용하고
context-map.json을 통한 점진적 컨텍스트 로딩을 활용하여, 비용이 많이 드는 grep-and-read 루프의 필요성을 줄입니다. - 가드레일 (Guardrails): 프로세스 내 변조 가드를 통해 활성 계획이 "Approved" 또는 "Executing"으로 표시되지 않는 한 구현 편집을 차단할 수 있습니다.
- 구조화된 아티팩트: 리포지토리를 사양(
docs/spec.md), 계획(plans/), 작업 계약(tasks/contracts/)을 위한 특정 영역으로 구성합니다.
대상 사용자
복잡하고 장기간 지속되는 코딩 작업에 AI 에이전트(특히 Claude 및 Codex)를 사용하며, 반복 가능하고 검증 가능하며 토큰 효율적인 워크플로우를 원하는 AI 도구 소유자 및 개발자를 위해 설계되었습니다.
주요 특징
- 파일 기반 상태 관리: 에이전트 조율을 채팅 스레드에서 리포지토리 로컬 파일로 이동합니다.
- 점진적 컨텍스트 로딩: 작은 루트 컨텍스트와 기능 블록을 사용하여 토큰을 절약합니다.
- 자동 핸드오프: 세션 상태와 dirty-bit 이벤트를 캡처하여 원활한 세션 재개를 촉진합니다.
- 엄격한 강제 게이트: 활성 계획의 상태에 따라 코드 편집을 차단할 수 있는 기능.
- MCP 커넥터: 워크플로우 아티팩트를 MCP 클라이언트에 노출하기 위한 옵션 사이드카.