내가 에이전트 (Agents)를 일상 업무에 연결하기 시작했을 때, 예상했던 대로 상황은 흘러갔습니다. 미완성된 변경 사항이 쏟아지고, 동일한 파일에 대해 서로 충돌하는 편집이 발생하며, 각자가 무엇을 해야 하는지에 대한 공유된 메모리 (Shared memory)도 없었습니다. 에이전트들은 유능했습니다. 오케스트레이션 (Orchestration)이 그렇지 못했을 뿐입니다.

다음은 이를 안정화시킨 기둥 (Pillars)들에 대한 내용입니다. 이는 튜토리얼도, 제품 홍보도 아니며, 그대로 복사해서 사용하라는 것도 아닙니다. 맞는 부분은 취하고, 나머지는 버리십시오.

1. 신(God), 왕(King), 일꾼(Worker) — 평면적인 풀(Pool)이 아닌 형태를 갖춘 위임

평면적인 에이전트 풀 (Flat agent pools) — 즉, N명의 일꾼을 가동하고, 작업을 던져주고, 결과를 수집하는 방식 — 은 작업에 의존성 (Dependencies)이 있거나 판단이 필요할 때 무너집니다. 어떤 결정은 방향 제시가 필요하고, 어떤 것은 라우팅 (Routing)이 필요하며, 어떤 것은 그저 순수한 실행만을 필요로 합니다.

여기서 효과적이었던 형태는 세 가지 역할로 나눈 것입니다:

• 신 (God): 방향을 설정합니다. 우리가 무엇을 만들고 있는지, 왜 만드는지, 그리고 "완료"의 의미가 무엇인지를 결정합니다. 최상위에는 하나의 목소리만 존재합니다.
• 왕 (King): 작업을 라우팅합니다. 계약 (Contracts)을 읽고, 계획을 분해하며, 일꾼들에게 작업을 배분하고, 결과물이 배포되기 전에 진실의 원천 (Source of truth)과 대조하여 검증합니다.
• 일꾼 (Workers): 새로운 컨텍스트 윈도우 (Context windows)를 가지고 실행합니다. 누적된 편향 (Drift)이나 세 단계 전 작업에서 비롯된 오래된 가정이 없습니다. 각 일꾼은 정확히 필요한 조각만을 전달받으며 그 외의 것은 받지 않습니다.

이것은 단순히 계층 구조를 만들기 위함이 아닙니다. 각 역할에 적절한 컨텍스트 (Context)를 부여하기 위함입니다. 프로젝트의 전체 상태를 모두 들고 다니는 일꾼은 토큰 (Tokens)을 낭비하고 편향 (Drift)이 발생합니다. 직접 일을 수행하는 왕은 조감도 (Bird's-eye view)를 잃게 됩니다. 일꾼을 마이크로매니징 (Micromanaging)하는 신은 병목 현상 (Bottleneck)이 됩니다.

배치 너비 (Batch width)가 중요합니다. 작업이 실제로 분해되는 만큼만 넓게 배분하십시오. 그 이상은 안 됩니다. 독립적인 조각들을 직렬화 (Serializing)하는 것은 시간을 낭비하며, 지어낸 작업으로 배치를 채우는 것은 컴퓨팅 자원 (Compute)을 낭비합니다. 왕은 실제 경계선을 찾아내고, 조각 간의 계약을 사전에 정의하며, 일꾼들이 중간 협상 없이 병렬로 실행될 수 있도록 합니다.

복사 붙여넣기 방지 노트: 당신의 팀에는 두 개의 역할이나 다섯 개의 역할이 필요할 수도 있습니다. 핵심은 이름이 아니라, 위임이 당신의 작업이 분해되는 방식과 일치하는 형태를 갖추어야 한다는 것입니다.

2. 진실의 원천으로서의 계약 (Contracts as source of truth)

에이전트 시스템을 망가뜨리는 가장 빠른 방법은 에이전트가 추측하게 만드는 것입니다. 에이전트는 추론(extrapolate) 능력은 뛰어나지만, 지난번에 어떤 추론이 틀렸었는지는 잊어버립니다.

계약(Contracts)이 이를 해결합니다. 어떤 수정(edit)을 수행하기 전에, 에이전트는 자신이 건드리고 있는 파일의 계약 체인(contract chain)을 따라 확인합니다. 계약은 어떤 불변량(invariants)이 유지되어야 하는지, 어떤 접점(seams)이 존재하는지, 그리고 마지막으로 누군가 이곳을 작업했을 때 무엇이 변경되었는지를 명시합니다. 수정이 완료되면 계약이 업데이트됩니다. 공백은 채워지고 추적됩니다.

이것은 문서화(documentation)가 아닙니다. 문서는 시간이 지나면 실제와 어긋나기 마련입니다. 계약은 차단(blocking) 기능을 수행합니다. 만약 계약에 "에이전트별 정체성을 암시하는 서브커맨드(subcommand)를 절대 추가하지 말 것"이라고 명시되어 있다면, 에이전트는 이를 추가할 수 없습니다. 이는 오래된 문단이 아니라 살아있는 제약 조건(constraint)입니다.

계약 계층(contract layer)은 배포 규칙, 테스트 게이트(testing gates), 관측성 계약(observability contracts), LLM 라우팅 규칙과 같은 횡단 관심사(cross-cutting concerns)도 처리합니다. 시스템을 건드리는 에이전트들은 모두 동일한 진실의 원천(source of truth)을 읽습니다.

복사-붙여넣기 방지 참고 사항: 여기서 사용된 계약 형식은 이 프로젝트의 규모와 속도에 적합합니다. 두 명의 팀이라면 공유된 마크다운(Markdown) 파일을 사용할 수도 있습니다. 50명의 엔지니어와 15개의 서비스라면 더 무거운 무언가가 필요할 것입니다. 핵심 원칙인 "에이전트는 읽을 수 있는 것을 절대 추측하지 않는다"는 원칙은 그대로 유지됩니다.

3. 표면에서는 계획하고, 계약을 통해 라우팅하라 (Plan on the surface, route through contracts)

에이전트들은 코딩을 시작하고 싶어 안달이 나 있습니다. 에이전트에게 작업을 주면 변경 사항의 형태를 고민하기도 전에 파일을 열어버립니다.

해결책: 실행 전, 가시적인 표면(visible surface)에서 반드시 계획(planning)이 이루어져야 합니다. 계획에는 무엇이 변경되는지, 무엇이 그대로 유지되는지, 어떤 계약을 건드리는지, 그리고 수락 기준(acceptance criteria)이 무엇인지가 명시됩니다. 계획 그 자체는 계약 산출물(contract artifact)입니다. 미래의 에이전트(또는 미래의 당신)는 이를 읽고 왜 무언가가 지금과 같은 방식으로 구축되었는지 이해할 수 있습니다.

계획은 한 명 이상의 대상에게 기여합니다: 인간 운영자, 작업을 분해하는 King, 자신의 몫을 가져가는 Workers, 그리고 몇 달 후 이 코드베이스를 맡게 될 에이전트가 그 대상입니다.

복사-붙여넣기 방지 참고 사항: 여기서의 계획(planning) 형식은 속성 기반(property-based)입니다. 즉, "이 변경 이후에도 반드시 유지되어야 하는 것"을 정의하는 방식인데, 이는 에이전트들이 존중하는 방식이기 때문입니다. 귀하의 팀은 다르게 계획할 수도 있습니다. 핵심 원칙은 계획이 행동(action)이 일어나기
_전(before)_에, 모든 사람이 볼 수 있는 표면 위에서 이루어져야 한다는 것입니다.

4. 일급 시민으로서의 드리프트 탐지 (Drift detection as a first-class concern)

한 번도 점검되지 않는 시스템은 드리프트(drift, 변질)가 발생합니다. 에이전트로 오케스트레이션되는 시스템은 드리프트가
더 빠르게 발생합니다. 에이전트는 자신감이 넘치고 속도가 빠르며, 이는 기반(ground)이 변했을 때 매우 나쁜 조합이 됩니다.

이를 포착하는 데 도움이 되는 두 가지 점검 방식이 있습니다:

• 아키텍처 드리프트 스캔 (Architecture drift scans): 실제 코드베이스를 명시된 원칙과 비교합니다. 만약 어떤 원칙이 "모든 테스트는 보장된 정리(teardown) 과정을 포함하는 임시 작업 공간(scratch workspace)을 생성해야 한다"라고 규정하고 있는데 새로운 테스트가 이를 따르지 않는다면, 스캔이 이를 잡아냅니다. 이러한 격차(gap)는 버그이거나, 새로운 원칙이 필요하다는 증거입니다.
• 계약 감사 (Contract audits): 특정 경로에 대한 전체 계약 체인(contract chain)을 따라가며 일치하지 않는 모든 항목을 표시합니다. 교차 참조(Cross-references), 오래된 제약 조건(stale constraints), 누락된 격차 해결(missing gap resolutions) 등이 예상치 못한 문제를 일으키기 전에 드러납니다.

복사-붙여넣기 방지 참고 사항: 몇 가지 불변량(invariants)을 선택하여 자동으로 점검하고, 모든 격차를 수정 사항 또는 새로운 불변량으로 취급하세요.

5. 모든 세션은 회고(retro)로 종료된다

에이전트도 실수를 합니다. 문제는 그 실수를 반복하느냐입니다.

모든 중요한 세션이 끝난 후, 에이전트는 회고(retro)를 수행합니다. 무엇이 잘못되었는지, 어느 단계에서 발생했는지, 그것이 모델(model)의 문제였는지, 하네스(harness)의 문제였는지, 아니면 작업 범위(task-scoping)의 문제였는지를 파악합니다. 카테고리별로 분류(triage)되면 세션 전반에 걸쳐 패턴이 가시화됩니다. 타입 인식 리팩토링(type-aware refactors)에서 지속적으로 실패하는 모델은 플래그(flag)가 지정됩니다. 특정 부류의 작업을 모두 차단하는 하네스의 한계점도 드러나게 됩니다.

회고 결과는 계약(contracts)과 계획(planning)에 정보를 제공할 수 있으므로, 다음 세션의 에이전트는 시작하기 전에 지난 실수를 참조할 수 있습니다.

6. 긴급 작업은 그 자체의 형태를 갖는다

긴급 작업은 일반적인 위임 파이프라인(delegation pipeline)에 맞지 않습니다. 지금 당장 수정해야 할 일이 있을 때 God→King→Worker로 이어지는 팬아웃(fan-out) 구조를 원하지는 않을 것입니다.

긴급 분류 (Urgent triage)는 별도의 라우터입니다. 문제를 분류하고, 영향 범위를 파악하며, 프로브 (probes)를 실행하여 적절한 대응자에게 전달합니다. 이는 계획의 깊이를 속도와 맞바꾸는 방식입니다. 첫 번째 임무는 억제 (containment)이며, 이해는 그 다음에 이루어질 수 있습니다.

안티 카피-페이스트 노트 (Anti-copy-paste note): 중요한 점은 당신의 일반적인 워크플로우 (workflow)와 긴급 워크플로우가 서로 _다른 것_이라는 사실입니다. 하나의 파이프라인 (pipeline)이 두 가지를 모두 처리하도록 만들려 하지 마세요.

이 중 마법 같은 것은 없습니다. 이는 에이전트 (agents)가 예측 가능한 방식으로 실패하는 것을 관찰하고, 그 실패 지점에 가드레일 (guardrails)을 구축하며 나타난 6가지 패턴입니다. 위임 (Delegation)에는 형태가 필요합니다. 계약 (Contracts)은 단순히 문서화하는 것이 아니라 차단 (block)할 수 있어야 합니다. 계획 (Plans)은 실행 전에 가시화되어야 합니다. 드리프트 (Drift)는 그것이 누적되기 전에 포착되어야 합니다. 세션 (Sessions)은 학습해야 합니다. 긴급한 작업은 그 자체의 경로가 필요합니다.

당신의 시스템을 더 안전하게 만드는 것들만 취하십시오. 나머지는 무시해도 좋습니다. 당신의 프로젝트는 나의 프로젝트가 아니며 — 바로 그것이 핵심입니다.