claude-agent-harness

개발자 한 명이 Claude Code로 프로젝트 30개를 병렬 운영하면서 만들어진 에이전트 운영 규칙 모음입니다. 4년간 실제로 굴리며 깎인 것들이고, 지금도 매일 돌아가고 있습니다.

에이전트를 만드는 방법이 아니라, 여러 개가 동시에 돌 때 사고가 안 나게 하는 규칙들입니다.

---

세 가지

몰래 우회 금지

에이전트가 제약에 부딪혔을 때 뚫지 않고 보고하게 만드는 규칙입니다. 오판으로 보이는 차단도 우회하지 않습니다. 근거를 정리해서 올리고 확인을 받습니다. 그리고 차단이 규칙의 결함을 드러내면, 그 결함을 고치는 것까지가 대응입니다.

FAIL을 PASS로 쓰지 않는다

지시로 종결하는 건이라도 실측 상태를 그대로 적고 재오픈 조건을 남깁니다. 보고는 Before/After 실측 수치로, 잔여와 리스크를 성과보다 먼저 씁니다.

22 → 17

에이전트를 22개까지 늘렸다가 17개로 줄였습니다. 늘리는 건 쉬웠고, 접는 판단이 어려웠습니다. 무엇을 왜 접었는지는 케이스 스터디에 있습니다.

---

무엇이 들어있나

---

핵심 패턴 몇 개

SSOT 참조 — 원문 복붙 금지 에이전트 문서에는 판단용 요약만 둡니다. 세부와 수치는 원본을 가리킵니다. 컨텍스트 비용이 줄고, 원본이 바뀌어도 문서 여러 곳을 고칠 필요가 없습니다.

판정과 집행의 분리 검증·조사는 읽기 전용 서브에이전트로 병렬 팬아웃, 파일·DB 집행은 중앙 직렬. 공유 파일을 여러 에이전트가 동시에 수정하면 반드시 깨집니다.

캐스케이드 차단 다른 에이전트의 결과만으로 단독 결정을 내리지 못하게 합니다. 전달받은 컨텍스트는 출처와 시각을 함께 기록합니다.

게이트 플래그 특정 경로에 플래그 파일이 없으면 에이전트 전체가 no-op입니다. 기본값 OFF. 파일 생성이 곧 가동, 삭제가 곧 중단입니다.

정량 임계값으로 자율성 정의 "허용/금지" 이분법 대신 1파일·5줄·등급·임팩트 점수의 AND 조건으로 자율 수정 범위를 정합니다. 애매하면 상신이 기본값입니다.

---

쓰는 법

설치할 것이 없습니다. 마크다운 파일입니다.

git clone https://github.com/YoungChulMoon/claude-agent-harness

agent-template.md를 .claude/agents/ 아래에 두고 필요한 부분만 채우십시오. 규칙 문서는 프로젝트에 맞게 골라 쓰시면 됩니다.

---

전제

• 특정 모델 버전에 의존하지 않습니다. 절차로 보존되어 있습니다.
• 하나의 정답이 아니라, 4년간 이 환경에서 작동한 방식입니다.
• 팀 규모와 프로젝트 성격에 따라 맞지 않을 수 있습니다.
• 도메인 고유 정보(서비스명·서버 경로·계정)는 플레이스홀더로 치환되어 있습니다.

라이선스

MIT