대부분의 서브 에이전트 프롬프트가 실패하는 이유는 단 하나입니다. 바로 '작업(task)' 대신 '영역(area)'을 설명하기 때문입니다. "auth 코드를 보고 정리해 줘"와 같은 지시는 에이전트에게 무한한 재량권을 주고 중단 규칙은 없습니다. 이로 인해 파일들을 읽고, 계획을 제안하고, 무언가를 수정하며, 불확실성을 느끼게 되고, 결국 루프에 빠지거나 병합할 수 없는 요약본을 반환하게 됩니다.
이 문제를 해결하는 네 가지 부분이 있습니다. 키트에 있는 모든 서브 에이전트 프롬프트는 이 네 가지를 순서대로 포함하고 있습니다.
1. 작업 경계 (Task boundary) — 한 문장, 하나의 결과물
단일 변경 사항과 관찰 가능한 결과를 명시하세요. 만약 "~와(and)" 없이 문장을 완성할 수 없다면, 그것은 두 개의 서브 에이전트가 필요하다는 의미입니다.
Task: make POST /orders reject amounts <= 0 with HTTP 422.
Result: an integration test that posts -5 and asserts 422 passes.
2. 허용 파일 (Allowed files) — 제안이 아닌 화이트리스트
이 부분은 사람들이 건너뛰는 부분이며, 이 부분이 diff가 검토 가능한지 여부를 결정합니다. 에이전트는 악의적으로 방황하는 것이 아니라, 어디가 경계인지 아무도 알려주지 않았기 때문에 방황하는 것입니다.
You may edit: app/api/orders.py, tests/test_orders.py
You may read: anything
You may not touch: migrations/, app/billing/, *.lock, CI config
...
마지막 줄이 목록보다 더 중요합니다. 이 규칙은 불가능한 작업을 창의적인 우회책 대신 메시지로 변환해 줍니다.
3. 완료 조건 (Done condition) — 스스로 증명하는 방법
에이전트가 반드시 실행하고 그 출력을 붙여넣어야 하는 명령어입니다. "테스트 통과"는 주장일 뿐입니다. pytest tests/test_orders.py -q와 그 결과의 끝부분이야말로 증거입니다.
검증할 수 없는 작업은 자신감 넘치는 보고서를 생성합니다. 검증 가능한 작업은 diff를 생성합니다.
만약 테스트로 결과를 표현할 수 없다면, 대신 diff 크기와 파일 개수 제한을 사용하세요: "최대 3개 파일, 최대 120줄 변경; 더 크다면 중단하고 보고하라."
DONE / BLOCKED
files changed: <list>
command run: <cmd>
...
"decisions(결정 사항)" 필드가 가장 가치가 높은 부분입니다. 에이전트가 라이브러리, 오류 형태 또는 명명 규칙을 조용히 선택하는 곳이며, 바로 이 부분이 검토 시간을 사라지게 만드는 지점입니다.
왜 하나의 긴 대화보다 세 개의 서브 에이전트가 더 나은가
각 서브 에이전트는 깨끗한 컨텍스트(context)에서 시작하므로, 초기에 잘못된 가정이 나머지 작업에 오염되지 않습니다. 그 대가는 사실들이 전달되지 않는다는 것입니다. 따라서 부모 에이전트가 파일 경로(file paths), 규칙(conventions), 제약 조건(constraints)을 명시적으로 전달해야 합니다. 이 비용은 실제이며, 40턴 동안 잘못된 작업을 수행한 에이전트의 비용보다 적습니다.
안티 패턴 (The anti-pattern)
결정하는 것을 피하기 위해 위임(delegating)하는 것. 만약 무엇이 "완료(done)" 상태인지 모른다면, 서브 에이전트는 임의로 정의하고 당신은 그것이 무엇을 정의했는지 알아내는 데 검토 예산(review budget)을 쓸 것입니다. 먼저 완료 조건을 작성한 다음, 위임하세요.
이 파일들은 AI Agent Engineering Kit에 포함되어 제공됩니다($12, 18개의 일반 텍스트 파일, 결제 시 이메일 전송). 무료 시작 파일: ceo-devkit-lab.surge.sh/free.html.