loop-harness 딥다이브
— 사람이 시키지 않아도 알아서 도는 AI 에이전트 '공장'

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

loop-harness는 코딩 에이전트(특히 Claude Code)를 위한 "루프 엔지니어링(loop engineering)" 하니스다. '하니스(harness)'란 무언가를 붙잡아 안전하게 부리는 마구·받침대를 뜻한다. 즉 이 프로젝트 자체는 AI가 아니라, AI를 정해진 규칙·주기·검증 아래 가둬 자율로 굴리는 '운영 틀'이다.

구성은 단순하다. orchestrator.sh라는 데몬이 30초마다 깨어나 "지금 돌려야 할 루프가 있나?"를 확인하고, 있으면 격리된 작업 공간에서 claude -p(헤드리스 모드)를 띄워 일을 시킨다. 일이 끝나면 또 다른 claude -p가 그 결과를 검증한다. 통과하면 gh CLI로 PR을 열거나 댓글을 달고, Slack으로 알린다. 실패하면 로그만 남기고 다음 주기에 재시도한다.

2왜 주목받는가

트렌딩 이유 · 경쟁 대비 장점.

2026년 들어 "자율 에이전트를 어떻게 안전하게 24시간 굴릴까"가 큰 화두가 됐다. loop-harness가 주목받는 이유는 세 가지다. 첫째, 무거운 SaaS·프레임워크 없이 셸 스크립트 1,000줄로 '에이전트 운영체제'의 핵심을 다 보여준다 — 읽으면 전체가 머리에 들어온다. 둘째, 2-에이전트 검증 게이트(만드는 AI ≠ 검사하는 AI)라는 신뢰성 패턴을 정석대로 구현했다. 셋째, GitHub Actions 같은 클라우드 CI가 아니라 내 노트북/서버에서 로컬로 돌면서도 PR·리뷰·Slack까지 연결된다.

3기술 스택 전체 지도

무거운 프레임워크 0개. 유닉스 기본기로만 짠 자율 에이전트 런타임.

이 프로젝트의 가장 큰 특징은 언어가 셸 스크립트(bash) 단 하나라는 점이다. Python도, Node도, Docker도 없다. 대신 모든 개발자의 컴퓨터에 이미 있는 유닉스 도구들(git·jq·curl)과 CLI(gh·claude)를 '레고 블록'처럼 조립했다. 덕분에 git clone 후 chmod +x 한 번이면 바로 돈다.

4아키텍처 심화 분석

한 번의 루프가 어떻게 깨어나고, 일하고, 검증받고, 발행되는가.

전체 흐름은 README의 한 줄 그림으로 요약된다: 스케줄러 틱 → 마감된 루프 → worktree → 1차 에이전트 → 스테이징 → 검증 에이전트 → (PASS) 발행 → 상태 갱신. 이걸 파일 단위까지 펼치면 다음과 같다.

핵심 설계 1 — 2-에이전트 검증 게이트 (generator ≠ verifier)

이 프로젝트의 심장. 일을 만드는 AI와 그것을 검사하는 AI를 분리한다. 1차 에이전트는 절대 외부로 무언가를 내보낼 수 없고(권한 자체가 없음), 오직 ① worktree 안의 커밋과 ② outbox 폴더 안의 '액션 파일'만 남긴다. 그러면 run_verifier가 별도의 claude -p 세션을 띄워 — 이번엔 읽기 전용 도구(Bash·Read·Glob·Grep)만 쥐어 주고 — "회의적으로 검사하라"는 시스템 프롬프트로 diff와 스테이징 결과를 점검한다.

# lib/runner.sh — 검증관 프롬프트의 핵심(요약)
local verifier_system="You are a strict verification agent...
# 1. git diff 가 최소·정확·시크릿/디버그 잔재 없는가?
# 2. PR_BODY/outbox 내용이 실제 파일·라인을 가리키는가?
# 3. 빠르게 가능하면 테스트/린트를 직접 돌려 본다
# 4. 에이전트의 보고가 디스크의 실제와 일치하는가?
# 마지막 줄은 반드시 'VERDICT: PASS' 또는 'VERDICT: FAIL — 이유'
if grep -q "VERDICT: PASS" "$vout"; then return 0; fi
return 1   # PASS 가 없으면 발행 차단

핵심 설계 2 — 스테이징 아웃박스 (직접 발행 절대 금지)

1차 에이전트가 "이 이슈에 이런 댓글을 달자"고 결정하면, gh를 직접 호출하는 게 아니라 $LOOP_OUTBOX 폴더에 약속된 이름의 파일을 떨군다. 발행은 검증 후 flush_outbox가 파일명을 보고 대신 처리한다. 파일명 앞 NN- 숫자가 발행 순서를 정한다.

핵심 설계 3 — 멱등 상태 원장 (state ledger)

각 루프@저장소 조합마다 JSON 파일 하나가 '처리 이력'을 들고 있다. processed에 들어간 항목 ID는 다음 실행 때 1차 에이전트에게 "이건 건너뛰어"라고 알려 주는 목록이 된다. 상태 변경은 항상 임시파일에 jq로 쓰고 mv로 교체해, 중간에 죽어도 파일이 깨지지 않는다(원자적 쓰기).

// state/<loop>@<repo>.json — 한 루프의 기억
{
  "last_run": 1760000000, "last_status": "success",
  "processed": {"12345": "2026-06-10T09:00:00+0000"},
  "in_progress": {},
  "failures": [{"item":"98","error":"verification failed","retries":1}],
  "metrics": {"runs":42,"successes":40,"items_processed":61}
}

핵심 설계 4 — 죽지 않는 데몬 (graceful by design)

오케스트레이터는 일부러 set -e를 안 쓴다(set -uo pipefail만). "루프 하나가 실패해도 데몬은 절대 죽으면 안 된다"는 원칙 때문이다. SIGTERM을 받으면 진행 중인 루프가 끝나길 최대 5분 기다린 뒤 우아하게 종료하고, 1초 단위로 쪼개 자며 신호에 빠르게 반응한다. 같은 루프의 중복 실행은 mkdir 락(디렉토리 생성이 실패하면 이미 도는 중)으로 막는다.

5디렉토리 구조 해부

약 1,000줄, 18개 파일(셸 8 + YAML 5 + 스킬 MD 5)이 어떻게 나뉘어 있나.

6학습 포인트 (기술별)

이 레포에서 배울 만한 것 + 어디를 보면 되는지.

7시스템 요구사항

돌리려면 무엇이 필요한가 (모두 흔한 CLI들).

8직접 해볼 수 있는 실습 과제

난이도별로 손에 익히는 단계. (위험하므로 테스트용 저장소에서)

# 설정 복사 후 내 레포로 수정
cp config.example.yaml config.yaml && $EDITOR config.yaml
chmod +x orchestrator.sh dashboard.sh connectors/*.sh
# 단일 루프를 포그라운드로 (발행 전 로그부터 확인)
./orchestrator.sh run-once pr-reviewer ~/projects/test-repo

# definitions/my-loop.yaml 예시
name: my-loop
cadence: every 30m       # 또는 cron: "0 9 * * 1-5"
skill: my-loop.md
worktree: false
output: issue-comment
allowed_tools: "Bash,Read,Glob,Grep"
verify: true

9관련 기술 심화 학습 로드맵

한 주씩 따라가는 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: lSAAGl/loop-harness
• Claude Code 문서: docs.claude.com/en/docs/claude-code
• GitHub CLI(gh): cli.github.com
• git worktree: git-scm.com/docs/git-worktree
• jq 매뉴얼: jqlang.github.io/jq/manual
• Slack Incoming Webhooks: api.slack.com/messaging/webhooks