코딩 에이전트(coding agents)를 다룰 때 범하는 실수는 그것들을 단일 채팅창처럼 취급하는 것입니다.

당신은 작업을 붙여넣습니다. 에이전트는 패치(patch)를 작성합니다. 당신은 그것을 확인합니다. 무언가 빠져 있습니다. 당신은 또 다른 작업을 붙여넣습니다. 그다음 또 다른 작업을 붙여넣습니다. 그러다 CI가 실패합니다. 그다음 리뷰 코멘트가 들어옵니다. 그러다 당신은 자신이 여전히 프로젝트 매니저(project manager), QA 루프(QA loop), 스케줄러(scheduler), 그리고 모든 스레드가 무엇을 해야 하는지 기억해야 하는 사람이라는 것을 깨닫게 됩니다.

더 나은 워크플로우는 하나의 Codex 스레드를 오케스트레이션(orchestration) 담당으로 만드는 것입니다.

단순히 코드만이 아닙니다.

코드를 둘러싼 루프(loop)입니다.

당신은 Codex에게 정의된 작업 배치를 주고 오케스트레이션 매니저(Orchestration Manager)로서 행동하라고 요청합니다. Codex는 작업을 스레드로 나누고, 목표를 부여하며, 주기적으로 진행 상황을 확인하고, PR(Pull Request)이나 인수인계를 모니터링하며, 피드백을 라우팅하고, 검증을 요구하며, 작업이 실제로 완료될 때까지 계속 진행합니다.

이 방식은 범위가 정해진 모든 작업에 적용 가능합니다.

버그 수정(bug fix), 리팩터링(refactor), 마이그레이션(migration), 문서 정리(documentation cleanup), 테스트 스위트 수리(test suite repair), 리서치 작업(research task), 또는 작은 개선 사항들의 백로그(backlog)가 될 수 있습니다.

이 모든 과정은 단 하나의 프롬프트에서 시작됩니다.

복사-붙여넣기용 프롬프트

매니저 스레드의 시작 프롬프트로 다음을 사용하세요:

당신은 이 작업을 위한 오케스트레이션 매니저(Orchestration Manager)입니다.

당신의 임무는 작업이 실제로 완료될 때까지 작업을 진전시키는 것입니다. 그것이 가장 작고 안전한 경로가 아니라면, 모든 것을 직접 구현하지 마십시오. 당신은 계획, 일정 관리, 조정, 후속 조치, 검증 및 모멘텀(momentum) 유지를 책임집니다.
...

이것이 바로 워크플로우입니다.

단 하나의 프롬프트가 Codex 스레드를 특정 작업에 대한 오케스트레이션 매니저로 변환합니다.

이것이 작동하는 이유

대부분의 에이전트 워크플로우는 인수인계(handoff) 지점에서 무너집니다.

첫 번째 출력물은 괜찮을 수 있습니다. 문제는 출력물 주변의 모든 것입니다:

에이전트가 테스트를 실행했는가?
결과를 검증했는가?
PR을 생성했는가?
...

그 지점이 바로 인간이 다시 끌려 들어오게 되는 부분입니다.

오케스트레이션 매니저 프롬프트는 이러한 인수인계 지점들을 에이전트의 직무 기술서(job description) 안으로 옮겨 놓습니다.

매니저 스레드(manager thread)의 목적은 영리해지는 것이 아닙니다. 상태(state)를 유지하고 계속해서 추진력을 제공하는 데 있습니다.

멘탈 모델 (The mental model)

시스템을 세 가지 계층으로 생각하십시오.

Human
-> 업무를 정의하고 판단(judgment calls)을 검토함

...

인간은 여전히 취향(taste), 판단(judgment), 그리고 최종 승인권을 가집니다.

매니저는 추진력(momentum)을 가집니다.

워커(worker)는 실행(execution)을 담당합니다.

이러한 분리가 중요한 이유는, 하나의 스레드가 기획자(planner), 구현자(implementer), 검토자(reviewer), 테스터(tester), 프로젝트 매니저(project manager), 그리고 메모리(memory) 역할을 동시에 수행해야 할 때 코딩 에이전트의 성능이 저하되기 때문입니다.

매니저 스레드는 워크 루프(work-loop) 수준에 머물러야 합니다. 워커 스레드는 태스크(task) 수준에 머물러야 합니다.

업무 범위(work scope)는 실질적이어야 합니다

이 워크플로우는 업무가 이미 정의되어 있을 때 가장 잘 작동합니다.

나쁜 입력:

앱을 더 개선해줘.

더 나은 입력:

업무 범위(Work scope):
1. 기존 빌링 웹훅 핸들러(legacy billing webhook handler)를 새로운 이벤트 라우터(event router)로 교체
2. invoice.paid, invoice.failed, subscription.updated, subscription.deleted에 대한 테스트 추가
...

해당 범위는 오케스트레이션 매니저(Orchestration Manager)가 유용한 워커 스레드로 분할할 수 있을 만큼 충분히 구체적입니다:

워커 1: 이벤트 라우터 구현
워커 2: 웹훅 픽스처 백필(webhook fixture backfill)
워커 3: 테스트 커버리지
...

매니저는 계획을 정교화하는 데 도움을 줄 수 있지만, 당신의 마음을 읽을 수는 없습니다.

모호한 업무를 주면 모호한 워커를 만들 것이고, 명확한 업무를 주면 유용한 스레드를 스케줄링할 수 있습니다.

워커의 목표(worker goal)가 중요합니다

워커 프롬프트는 기능 요청(feature request)이 되어서는 안 됩니다.

그것은 결승선(finish line)이어야 합니다.

약한 목표:

빌링 웹훅 코드를 수정해줘.

더 나은 목표:

/goal 기존 빌링 웹훅 핸들러를 새로운 이벤트 라우터로 교체하십시오. 변경 사항은 웹훅 라우팅, 빌링 이벤트 핸들러, 그리고 직접적으로 관련된 테스트로 제한하십시오. invoice.paid, invoice.failed, subscription.updated, subscription.deleted에 대한 기존 동작을 유지하십시오. 마이그레이션된 경로가 작동함을 증명하는 테스트를 추가하거나 업데이트하십시오. 변경된 파일, 테스트 결과, 차단 요소(blockers), 그리고 권장되는 다음 조치를 보고하십시오. 구현이 PR(Pull Request) 준비 상태가 되거나 작업이 차단될 때만 중단하십시오.

그 하나의 프롬프트는 작업자(worker)에게 역할(role), 범위(scope), 테스트 기대치(test expectation), 인계 형식(handoff format), 그리고 중단 조건(stop condition)을 부여합니다.

매니저(manager)가 이러한 목표들을 자동으로 생성할 수는 있지만, 목표의 형태는 이처럼 명시적이어야 합니다.

하트비트(Heartbeats)는 안전망입니다

하트비트(heartbeat)는 이것이 일반적인 채팅과 다르게 느껴지게 만드는 요소입니다.

매 10분마다, 매니저는 시스템을 점검합니다:

무엇이 활성화되어 있는가?
무엇이 차단되었는가?
무엇이 변경되었는가?
...

하트비트가 정보가 이동하는 유일한 방법이 되어서는 안 됩니다.

작업자는 마일스톤(milestone)에 도달했을 때 즉시 체크인(check-in)해야 합니다. 하트비트는 정체된 작업을 포착합니다. 작업자의 체크인은 루프(loop)를 반응성 있게 유지합니다.

두 가지를 모두 사용하십시오.

피드백은 워크플로(workflow)의 일부입니다

많은 에이전트 워크플로(agent workflows)가 "PR(Pull Request) 오픈" 또는 "초안 생성" 단계에서 멈춥니다.

그것은 너무 이릅니다.

오케스트레이션 매니저(Orchestration Manager)는 피드백을 새로운 작업으로 취급해야 합니다.

리뷰 코멘트(review comments)가 나타나면, 매니저는 이를 분류해야 합니다:

버그 (bug)
스타일 (style)
테스트 요청 (test request)
...

그런 다음 모든 코멘트를 하나의 작업자에게 할당하거나, 후속 작업자들에게 나누어 할당해야 합니다.

후속 목표(follow-up goal) 예시:

/goal 결제 이벤트 라우터(billing event router)와 관련된 미해결 리뷰 코멘트를 처리하십시오. 해당 코멘트에 필요한 파일만 수정하십시오. 동작이 변경되면 테스트를 추가하거나 업데이트하십시오. 관련 테스트 스위트(test suite)를 실행하십시오. 어떤 코멘트가 해결되었는지, 변경된 파일, 테스트 결과, 그리고 남아있는 리뷰 피드백이 있는지 보고하십시오. 이 코멘트들이 해결되거나 차단될 때만 중단하십시오.

이 지점에서 워크플로가 유용해집니다.

첫 번째 패스(pass)가 최종 패스인 경우는 드뭅니다. 매니저는 두 번째와 세 번째 패스가 잊히지 않도록 하기 위해 존재합니다.

견제와 균형 (Checks and balances)

이것을 에이전트를 완전히 신뢰하는 것과 혼동하지 마십시오.

매니저 스레드(manager thread)는 정체될 수 있습니다. 작업자 스레드(worker threads)는 완료되었다고 환각(hallucinate)할 수 있습니다. 하트비트는 잘못된 루프를 계속 유지시킬 수 있습니다. UI 변경 사항은 코드상으로는 올바르게 보일 수 있지만 앱에서는 여전히 잘못되게 느껴질 수 있습니다. 연구(research)는 기본 출처를 놓치면서도 완료된 것처럼 들릴 수 있습니다.

따라서 프롬프트는 점검을 강제해야 합니다:

실행 가능한 경우 코드 변경 사항에는 테스트가 필요합니다.
PR (Pull Request)에는 리뷰가 필요합니다.
CI (Continuous Integration) 상태가 중요합니다.
...

핵심은 인간의 판단을 제거하는 것이 아닙니다.

핵심은 인간의 과도한 관리 (babysitting)를 제거하는 것입니다.

재사용 가능한 패턴

패턴은 간단합니다:

작업을 정의합니다.
Orchestration Manager Codex 스레드를 시작합니다.
작업자 (worker) 스레드를 스케줄링하도록 요청합니다.
...

이것은 하나의 거대한 프롬프트보다 더 나은 기본 설정입니다.

단일 에이전트 (single agent)는 당신에게 한 번의 시도를 제공합니다.

Orchestration Manager는 당신에게 운영 루프 (operating loop)를 제공합니다.

무엇이 중요한지는 여전히 인간이 결정합니다.

에이전트는 작업이 계속 진행되도록 유지합니다.