Claude Code의 불안정한 결과물을 제어하는 로컬 우선 디스패처, GeneralStaff

섹션별 상세

AI 코딩 에이전트의 '자신감 있는 거짓 완료' 문제: 에이전트가 테스트를 통과하지 못하거나 프로젝트 범위를 벗어난 코드를 작성해도 작업을 완료한 것으로 간주하는 현상이 발생한다.

yaml

projects:
  - id: myapp
    path: /home/ray/myapp
    engineer_command: "claude -p --dangerously-skip-permissions"
    verification_command: "bun test && bun x tsc --noEmit"
    cycle_budget_minutes: 30
    hands_off:
      - src/pricing.ts
      - src/auth/
      - CLAUDE.md

GeneralStaff에서 프로젝트를 등록하고 에이전트의 작업 명령과 검증 명령, 접근 제한 경로를 설정하는 예시입니다.

검증 게이트(Verification Gate) 도입: 에이전트가 작업을 수행한 후, 별도의 검증 에이전트가 JSON 형식으로 테스트 통과 여부, 스코프 준수 여부, 접근 금지 파일 수정 여부를 확인한다.

Git Worktree를 활용한 격리: 에이전트의 작업은 별도의 Git worktree에서 수행되며, 검증 실패 시 롤백하여 메인 브랜치를 안전하게 보호한다.

실무 성능 데이터: GeneralStaff 자체 개발 과정에서 210건의 검증 중 19건(약 9%)이 게이트에 의해 차단되었으며, 이는 에이전트의 실수를 실시간으로 걸러낼 수 있음을 입증한다.

용어 해설

Git 워크트리(Git Worktree): — 하나의 Git 저장소에서 여러 브랜치를 동시에 다른 디렉토리에 체크아웃하여 작업할 수 있게 해주는 기능입니다. 에이전트가 메인 코드베이스를 직접 수정하지 않고 별도의 격리된 환경에서 작업을 수행하도록 보장하는 데 사용됩니다.
JSON Lines(JSONL): — 각 줄이 독립적인 JSON 객체로 구성된 텍스트 파일 형식입니다. 대규모 로그 데이터를 한 줄씩 순차적으로 읽고 처리하기에 효율적이며, 에이전트의 작업 이력을 기록하는 audit log로 활용됩니다.
에이전트 루프(Agent Loop): — 에이전트가 작업을 계획하고, 실행하고, 결과를 검증한 뒤 다시 계획을 수정하는 반복적인 실행 과정입니다. 본문에서는 검증 게이트를 통해 이 루프의 안정성을 높이는 방식을 다룹니다.