코딩 에이전트가 저지르는 가장 큰 비용은 버그를 작성하는 것이 아닙니다. 바로 작업이 완료된 것처럼 보이지만 실제로는 그렇지 않은 상태에서 턴을 종료하는 것입니다. 예를 들어, URL 확인 없이 “배포됨(Deployed!)”이라고 하거나, 세 개의 요청 중 하나만 처리했거나, 에이전트가 스스로 할 수 있었던 ‘다음 단계 목록’을 제시하는 경우입니다.
저는 여러 프로젝트를 Claude Code와 Codex를 동시에 사용하여 진행하기 때문에, agent-harness라는 것을 만들었습니다. 이것은 에이전트가 작업을 크기 조정하고(sizes), 완료하며(finishes), 보고하는 방식을 변경하는 일련의 에이전트 스킬(Agent Skills), 규칙 및 훅(hooks)입니다. 이 시스템은 별도의 서비스에 의존하지 않으며, 사용자의 에이전트 설정 파일 내부에 존재하는 파일들로 구성되어 있습니다.
간단한 언어 입력으로 적절한 프로세스 출력하기
이 하네스(harness)는 사용자 요청을 읽고 어떤 방식으로 행동할지 결정합니다:
| 사용자가 입력하는 내용 | 에이전트가 취하는 역할 | 유지되는 것 |
|---|
| 질문 또는 작은 수정 사항 | 엔지니어(engineer) | 추가적인 것은 없음 |
| ... | | |
수정 사항은 수정 사항으로 남습니다. 제품 요청의 경우, 모든 사용자 흐름과 출시 게이트가 기록된 원장(ledger)이 생성됩니다.
완료는 증거를 의미한다
원장의 모든 행은 오직 증거에 의해서만 검증됩니다. 테스트 실행(test run), 휴대폰 및 데스크톱 스크린샷, 또는 URL 확인 등이 그 예입니다. Stop 훅(done-check.py)은 에이전트가 중지하려고 할 때 마지막 요청을 읽고, 작업이 확실하게 완료되지 않았다면 해당 요청을 다시 보냅니다.
한 번에 하나의 소유자 액션만 허용하기
사용자는 OWNER.md 파일에 승인된 내용을 작성합니다. 여기에는 돈의 상한선, 에이전트가 사용할 수 있는 계정 및 채널, 그리고 스스로 결정할 수 있는 결정 사항들이 포함됩니다. 에이전트는 이 범위 내에서 행동하며, 범위를 벗어날 때는 오직 하나의 정확한 것만을 요청합니다:
NEEDS YOU (1 of 3): Stripe -> 계정 생성 -> 결제 과정 잠금 해제
돈을 이동시키거나, 서명하거나, 새로운 제3자 계정을 만드는 작업은 항상 사용자의 통제 하에 남아 있습니다.
계속 실행하고 스스로 개선하기
run-company/scripts/schedule.sh는 몇 시간마다 채팅창을 열지 않은 상태로 프로젝트 내에서 continue를 실행하는 launchd 또는 cron 작업을 설치합니다. 모든 마찰 지점과 소유자의 요청은 기록되며, 주간 검토에서는 현재 버전의 동일한 작업에 대해 하나의 하네스 변경 사항을 테스트한 후 반영됩니다.
직접 사용해 보기
git clone https://github.com/fainir/agent-harness ~/agent-harness && ~/agent-harness/install.sh
설치 프로그램은 멱등적(idempotent)이며 사용자의 기존 콘텐츠를 유지합니다. ./install.sh --uninstall을 실행하면 추가된 모든 것을 제거할 수 있습니다. 이 프로그램은 Claude Code와 Codex 모두에서 작동하며, AGENTS.md 및 ~/.agents/skills를 읽는 모든 에이전트에서도 작동합니다. bash tests/test.sh를 실행하면 오프라인 테스트 스위트(hooks, 학습 스크립트 및 임시 홈 디렉터리에서의 전체 설치 및 제거 주기)가 실행됩니다.
솔직히 말해 한계점도 있습니다. 에이전트의 성능은 모델과 접근할 수 있는 계정에 달려 있으며, 백그라운드 실행은 진행되는 동안 모델 사용량을 소모합니다. schedule.sh --remove <디렉터리명>을 사용하여 일시 중지할 수 있습니다.
코드: https://github.com/fainir/agent-harness