코딩 에이전트의 품질이 저하되는 경우는 대개 모델의 능력이 떨어졌기 때문이 아니라, 에이전트가 무엇을 읽고 무엇을 하며 변경 사항을 어떻게 검토할지를 통제하는 명확한 운영 체계가 프로젝트에 없기 때문이다. 작업이 수주 동안 이어지고 수천 건의 변경이 발생하면, 이러한 단계가 강제되지 않을 경우 에이전트는 같은 파일을 다시 탐색하거나, 이전 결정을 뒤집거나, 테스트 명령을 추측하거나, 테스트 작성을 중단할 수 있다.
「LLM 시스템을 프로덕션에서 운영하기」 시리즈의 여섯 번째 글에서 Stack Overflow Blog는 모델을 둘러싼 조직화 계층을 구축할 것을 제안한다. 여기에는 간결한 프로젝트 헌법, 자율성의 한계, 다층 컨텍스트, 영구 메모리, 검토 위원회, 모든 변경 후 실행되는 훅이 포함된다. 여러 에이전트를 동일한 저장소에서 실행할 때는 파일 소유권 맵, 프롬프트 로그, 공동 결정 기록도 추가한다.
문제는 모델 하나가 아니라 운영 벨트에 있다
이 글은 에이전트를 모델에 지침, 도구, 컨텍스트 정책, 훅, 격리, 하위 에이전트, 모니터링 메커니즘을 더한 것으로 정의한다. 또한 Terminal-Bench 2.0의 일반적인 결과를 인용한다. LangChain은 모델 자체를 그대로 유지한 채 운영 벨트만 변경하여 에이전트를 상위 30위 밖에서 상위 5위로 끌어올렸고, 점수는 52.8%에서 66.5%로 13.7포인트 상승했다.
실무적 의미는 불완전한 도구, 모호한 규칙, 과도하게 혼잡한 컨텍스트가 가장 개선하기 쉬운 실패 원인일 수 있다는 것이다. 모델과 달리 개발 팀은 이 계층을 수정하고 자신의 저장소에 맞게 조정할 수 있다.
규율 있는 단일 에이전트를 위한 여섯 가지 요소
- 프로젝트 헌법: CLAUDE.md 또는 AGENTS.md와 같은 파일에서 계획, 문서화, 구현, 테스트, 검토, 커밋의 작업 순서를 정의한다. 품질 기준과 공급업체 패키지 사용의 한계도 포함해야 하며, 모든 세션에서 읽히므로 짧게 유지해야 한다.
- 자율성의 한계: 에이전트는 읽기, 편집, 테스트, 커밋 생성과 같은 되돌릴 수 있는 작업을 수행할 수 있지만, 푸시, 배포, 인프라 변경 적용에는 승인이 필요하다. 또한 광범위한 규칙, 예를 들어 npm:*가 실수로 배포를 허용하지 않도록 명령어 매칭의 의미를 검증해야 한다.
- 다층 컨텍스트: 루트의 CONTEXT.md에는 프로젝트 구조와 실행 및 테스트 방법을 담고, 각 모듈의 파일에는 해당 모듈의 책임, 파일, 의존성을 설명한다. DECISIONS.md에는 결정, 그 이유, 거부된 대안을 기록한다. 오래된 컨텍스트는 변경 자체에서 수정해야 하는 오류로 간주한다.
- 영구 메모리: 이 글은 각 사실을 별도의 메모리 파일에 저장하고, 간결한 색인과 모듈 및 결정을 의존하거나 대체하는 관계로 연결하는 graph.jsonl 파일을 둘 것을 제안한다.
- 다중 관점 검토 위원회: 하위 에이전트가 제품, 엔지니어링, 인프라, 보안, 테스트의 관점에서 변경 사항을 검토한다. 장애물이나 높은 확신을 가진 중대한 문제만 변경을 차단한다.
- 변경 후 훅: PostToolUse는 각 Edit, Write 또는 MultiEdit 후에 실행되며, 파일을 조용히 다시 작성하는 대신 변경 자체에서 컨텍스트, 메모리, 결정 기록을 업데이트하도록 상기시키는 목록을 출력한다.
에이전트 군집을 실행할 때
여러 에이전트가 동일한 저장소에서 작업하면 새로운 문제가 나타난다. 즉, 같은 파일을 수정하거나 서로의 결정을 되돌리는 문제다. 이 글은 에이전트 간 직접 대화에 의존하는 대신, 감사 가능한 공동 기록을 사용할 것을 제안한다. 여기에는 경로 소유권 맵, CLAIM 및 RELEASE 기록, 진행 기록, 각 작업별 독립 브랜치와 인간의 병합이 포함된다.
이러한 클레임은 진정한 잠금이 아니다. 두 에이전트가 동일한 상태를 읽고 동시에 같은 경로를 주장할 수 있기 때문이다. 실제 격리가 필요할 때 이 글은 고유한 이름의 Git 브랜치나 조정 저장소의 조건부 쓰기와 같은 원자적 메커니즘을 권장한다.
이 접근법이 중요한 이유
여기서 실제 변화는 에이전트가 함수를 작성하는 능력에서, 주변 시스템이 시간이 지나도 에이전트를 지향된 상태와 검토 가능한 상태로 유지하는 능력으로 초점을 옮기는 것이다. 결정 기록은 단순한 문서가 아니라 계약적 역할을 한다. 기존 결정을 수정하는 대신, 이유와 거부된 대안을 명시하면서 이를 대체하는 새로운 결정을 추가한다. 이렇게 하면 설계의 역사가 보존되고 특정 임포트를 금지하는 것과 같은 자동 검사와 연결할 수 있다.
이 접근법은 여전히 출력의 정확성을 보장하는 것이 아니라 조직적 지침을 제공한다. 또한 이 글은 동시 충돌이 발생할 때 파일 기반 클레임이 자문적 성격에 그친다는 점과, 병합·푸시·배포 시점에는 인간 검토가 여전히 통제 지점으로 남는다는 점을 인정한다. 글의 결론은 더 똑똑한 모델을 기다리는 것보다 모델을 제한하고 감사 가능한 흔적을 구축하는 일이 장기 작업의 신뢰성에 더 큰 영향을 미칠 수 있다는 것이다.