AI 네이티브 팀의 위임 패킷: 코딩 에이전트에게 일을 맡기는 최소 명세
Claude Code와 Codex 같은 코딩 에이전트가 실제 팀 속도를 올리려면 프롬프트가 아니라 위임 패킷이 필요합니다. 목적, 범위, 권한, 검증, 중단 조건을 한 장으로 설계하는 실전 방법을 정리합니다.
AI 네이티브 팀의 위임 패킷: 코딩 에이전트에게 일을 맡기는 최소 명세
AI 코딩 에이전트를 도입한 팀에서 자주 보이는 실패는 비슷합니다. 모델이 약해서가 아니라, 사람이 일을 너무 느슨하게 맡깁니다.
"이 버그 고쳐줘."
"이 기능 만들어줘."
"테스트도 알아서 해줘."
사람 동료에게도 부족한 지시를 에이전트에게 주면 결과는 더 불안정해집니다. Claude Code나 OpenAI Codex처럼 코드 읽기, 수정, 명령 실행, 테스트 수행을 할 수 있는 도구일수록 더 명확한 위임 구조가 필요합니다. Anthropic은 Claude Code 문서에서 설정과 권한, 훅을 통해 동작을 제어할 수 있다고 설명하고, OpenAI는 Codex를 클라우드 기반 소프트웨어 엔지니어링 에이전트로 소개합니다. 이런 도구가 강해질수록 팀이 설계해야 할 것은 "더 긴 프롬프트"가 아니라 위임 패킷(delegation packet) 입니다.
위임 패킷은 에이전트에게 일을 맡길 때 함께 전달하는 작은 작업 명세입니다. PRD처럼 거창할 필요는 없습니다. 하지만 목적, 변경 범위, 금지 영역, 검증 방법, 중단 조건은 반드시 들어가야 합니다.
이 글은 AI Transformation, 즉 AIAx를 개발 조직에 적용할 때 바로 쓸 수 있는 위임 패킷 설계법을 다룹니다.
왜 프롬프트가 아니라 패킷인가
프롬프트는 대화입니다. 패킷은 계약입니다.
프롬프트는 보통 이런 식으로 끝납니다.
로그인 후 리다이렉트가 잘못되는 버그를 고쳐줘.
반면 위임 패킷은 이렇게 시작합니다.
Task: 로그인 후 next 파라미터가 보존되지 않는 버그 수정
Outcome: /login?next=/billing 성공 후 /billing로 이동
Scope: src/app/[lang]/login, src/lib/auth, 관련 테스트만 수정
Do not touch: 결제 로직, OAuth provider 설정, DB schema
Verify: npm run lint, npm run build, 수동 시나리오 3개
Stop if: 인증 플로우 변경이 필요하거나 provider 설정 변경이 필요하면 중단
차이는 큽니다. 에이전트는 "무엇을 해야 하는지"뿐 아니라 "무엇을 하지 말아야 하는지"를 알아야 합니다. 특히 코딩 에이전트는 한 번 잘못된 가정을 하면 파일 여러 개를 동시에 바꿀 수 있습니다. 그래서 범위와 중단 조건이 품질 장치가 됩니다.
위임 패킷의 7가지 필드
실무에서는 아래 7개 필드면 충분합니다.
1. Outcome: 성공 상태를 한 문장으로 쓴다
에이전트에게는 작업명보다 성공 상태가 중요합니다.
나쁜 예:
회원가입 개선
좋은 예:
신규 사용자가 이메일 인증 후 대시보드로 진입하고, 인증 전에는 결제 페이지 접근이 차단된다.
Outcome은 테스트와 리뷰의 기준이 됩니다. 구현 방식은 달라도 Outcome이 만족되면 성공입니다.
2. Context: 왜 지금 하는지 알려준다
에이전트는 코드만 보고 제품 맥락을 완전히 알 수 없습니다. 다음 정보를 짧게 제공합니다.
- 현재 문제가 사용자에게 어떻게 보이는가
- 최근 변경이나 장애와 관련 있는가
- 임시 패치인지, 장기 구조 개선인지
- 성능, 비용, 보안 중 무엇이 우선인지
예시:
Context:
지난 릴리즈 이후 모바일 사용자의 가입 완료율이 떨어졌다. 원인은 이메일 인증 후 언어 prefix가 사라지면서 404로 이동하는 문제로 추정된다. 이번 작업은 구조 개편이 아니라 리다이렉트 보존 버그 수정이 목표다.
이 정도만 있어도 에이전트가 불필요한 리팩터링을 줄입니다.
3. Scope: 수정 가능한 파일과 계층을 제한한다
에이전트에게 가장 강한 안전장치는 범위입니다.
Scope:
- src/app/[lang]/auth/**
- src/lib/redirect.ts
- src/content/docs/auth-flow.mdx
- 관련 테스트 추가 가능
범위는 "추천"이 아니라 "허용 목록"처럼 써야 합니다. Claude Code의 설정과 권한 구조, 그리고 훅은 이런 정책을 도구 차원에서 보강할 수 있습니다. Anthropic의 Claude Code hooks 문서는 특정 이벤트에서 셸 명령을 실행해 워크플로우를 자동화할 수 있다고 설명합니다. 즉, 패킷의 정책을 리뷰 규칙이나 검증 스크립트로 연결할 수 있습니다.
4. Non-goals: 하지 말아야 할 일을 명시한다
Non-goals가 없으면 에이전트는 "좋은 의도"로 범위를 넓힙니다.
Non-goals:
- OAuth provider 교체 금지
- DB schema 변경 금지
- 디자인 시스템 컴포넌트 리팩터링 금지
- 기존 한국어/영어 라우팅 구조 변경 금지
사람 리뷰어는 이런 변경을 보면 바로 의심하지만, 에이전트는 "더 깔끔한 해결"이라고 판단할 수 있습니다. AIAx에서 중요한 것은 자동화의 양이 아니라 자동화의 경계입니다.
5. Permissions: 읽기, 쓰기, 실행 권한을 분리한다
모든 작업에 같은 권한을 주면 운영 리스크가 커집니다.
Codex처럼 클라우드 작업 환경에서 병렬로 태스크를 실행할 수 있는 에이전트는 생산성을 높일 수 있지만, 동시에 권한 분리 없이는 여러 작업이 같은 위험을 반복합니다. 팀은 "이 에이전트가 무엇을 할 수 있는가"보다 "이 작업에서는 무엇만 할 수 있는가"를 기준으로 권한을 줘야 합니다.
6. Verification: 통과해야 할 검증을 선명하게 쓴다
"테스트 해줘"는 충분하지 않습니다. 에이전트가 어떤 검증을 실행해야 하는지, 실패하면 무엇을 해야 하는지 적어야 합니다.
Verification:
1. npm run lint
2. npm run build
3. 로그인 성공 후 next 파라미터 보존 확인
4. next가 외부 URL이면 기본 대시보드로 이동하는지 확인
5. 한국어 /ko, 영어 /en 라우트 모두 확인
If verification fails:
- 로그를 요약한다.
- 원인을 하나만 가정한다.
- 수정 후 같은 검증을 다시 실행한다.
- 2회 실패하면 중단하고 사람에게 넘긴다.
검증은 에이전트의 자율성을 줄이는 장치가 아닙니다. 오히려 안전하게 더 많이 맡기기 위한 장치입니다.
7. Stop conditions: 언제 멈출지 정한다
좋은 에이전트 워크플로우는 자동 진행뿐 아니라 자동 중단도 설계합니다.
Stop if:
- 인증 provider 설정 변경이 필요하다.
- DB migration이 필요하다.
- 기존 테스트 기대값을 바꿔야 한다.
- 결제 또는 권한 정책 파일을 수정해야 한다.
- 문제 원인이 재현되지 않는다.
중단 조건이 없으면 에이전트는 "해결하려고" 계속 움직입니다. 하지만 운영에서는 모르는 상태에서 멈추는 것이 아는 척 고치는 것보다 낫습니다.
바로 복사해서 쓰는 위임 패킷 템플릿
## Delegation Packet
Task:
-
Outcome:
-
Context:
-
Scope:
- Allowed files/directories:
- Allowed commands:
Non-goals:
-
Permissions:
- Read:
- Write:
- Execute:
- Publish:
Verification:
-
Stop conditions:
-
Report format:
- Summary:
- Files changed:
- Verification results:
- Risks / follow-ups:
이 템플릿을 이슈, PR 설명, Claude Code 세션 시작 문서, Codex 작업 지시서에 그대로 붙여 넣으면 됩니다.
예시 1: 프론트엔드 버그 수정 패킷
Task:
- 모바일 내비게이션에서 언어 전환 후 현재 경로가 유지되지 않는 문제 수정
Outcome:
- /ko/blog/foo에서 영어로 전환하면 /en/blog/foo로 이동한다.
- 대응되는 영어 글이 없으면 /en/blog로 이동한다.
Context:
- 블로그는 route-based i18n을 사용한다.
- 한국어가 기본 언어이고 영어는 선택 언어다.
Scope:
- src/components/layout/LanguageSwitcher.tsx
- src/i18n-config.ts
- 필요 시 관련 utility 추가
Non-goals:
- 전체 라우팅 구조 변경 금지
- dictionary 파일 변경 금지
- 디자인 변경 금지
Permissions:
- Read: src/app, src/components/layout, src/i18n-config.ts
- Write: Scope에 명시된 파일만
- Execute: npm run lint, npm run build
- Publish: PR 생성까지만
Verification:
- npm run lint
- npm run build
- /ko/blog, /en/blog, /ko/projects 경로에서 전환 시나리오 확인
Stop conditions:
- generateStaticParams 구조 변경이 필요하면 중단
- locale middleware 도입이 필요하면 중단
이 패킷은 작지만 충분합니다. 에이전트가 수정해야 할 영역과 건드리면 안 되는 영역이 분리되어 있습니다.
예시 2: CI 실패 복구 패킷
Task:
- develop 브랜치의 최신 CI 실패 원인을 찾아 최소 수정으로 복구
Outcome:
- 실패한 체크가 통과한다.
- CI 실패와 무관한 파일은 수정하지 않는다.
Context:
- 직전 커밋은 MDX 포스트 추가다.
- 코드 기능 변경은 의도하지 않았다.
Scope:
- 실패 로그가 지목하는 파일
- 새로 추가된 MDX 파일
Non-goals:
- ESLint rule 완화 금지
- TypeScript strict 옵션 완화 금지
- 패키지 업그레이드 금지
Permissions:
- Read: repository, CI logs
- Write: 실패 원인과 직접 관련된 파일만
- Execute: npm run lint, npm run build
- Publish: fix commit push 가능
Verification:
- 동일 명령 재실행
- 변경 diff가 실패 원인과 직접 연결되는지 확인
Stop conditions:
- 의존성 설치나 lockfile 재생성이 필요하면 중단 후 보고
- 2회 수정 후 같은 실패가 반복되면 중단
CI 복구는 에이전트에게 맡기기 좋은 작업입니다. 로그, 원인, 수정, 재검증 루프가 명확하기 때문입니다. 단, 권한이 넓으면 "CI를 통과시키기 위한 나쁜 수정"이 생길 수 있으므로 non-goals가 중요합니다.
팀 운영에 붙이는 방법
위임 패킷은 개인 습관이 아니라 팀 인터페이스가 되어야 합니다.
1. 이슈 템플릿에 넣기
작업 요청자가 Outcome, Scope, Non-goals만 채워도 품질이 올라갑니다. 나머지는 담당 개발자나 에이전트 운영자가 보완할 수 있습니다.
2. PR 설명에 Verification을 고정하기
에이전트가 만든 PR은 특히 검증 결과가 중요합니다.
## Verification
- [x] npm run lint
- [x] npm run build
- [ ] manual mobile language switch
체크박스가 비어 있으면 리뷰어는 기능보다 검증 누락을 먼저 봐야 합니다.
3. 위험도별 패킷 길이를 다르게 하기
모든 작업에 긴 문서가 필요하지는 않습니다.
4. 훅과 스크립트로 정책을 자동화하기
Claude Code hooks 같은 기능은 패킷의 일부 규칙을 자동화하는 데 유용합니다. 예를 들어 특정 디렉터리 수정 후 lint를 자동 실행하거나, 금지 파일 변경을 감지해 세션을 멈추게 할 수 있습니다. 중요한 것은 훅을 "마법"으로 보지 않는 것입니다. 훅은 정책을 실행하는 장치이고, 정책은 패킷에 먼저 적혀 있어야 합니다.
흔한 실수
실수 1: 에이전트에게 PM 역할까지 맡긴다
에이전트는 구현을 도울 수 있지만, 제품 판단까지 자동으로 위임하면 위험합니다. Outcome과 non-goals는 사람이 정해야 합니다.
실수 2: 검증을 마지막에 생각한다
검증이 나중이면 구현이 먼저 폭주합니다. 패킷 작성 시점에 검증을 먼저 정의해야 합니다.
실수 3: 권한을 도구 단위로만 본다
"Claude Code는 가능하다"와 "이 작업에서 허용한다"는 다릅니다. 권한은 도구가 아니라 작업 단위로 줘야 합니다.
실수 4: 실패 보고 형식이 없다
에이전트가 실패했을 때 "안 됐습니다"만 남기면 학습이 없습니다. 실패 보고에는 최소한 원인 가설, 실행한 명령, 로그 요약, 다음 선택지가 들어가야 합니다.
AIAx 관점: 위임 패킷은 조직의 API다
AI Transformation은 단순히 AI 도구를 많이 쓰는 것이 아닙니다. 조직의 업무 단위를 AI가 실행 가능한 형태로 바꾸는 과정입니다. 그런 의미에서 위임 패킷은 조직의 API입니다.
좋은 API는 입력, 출력, 권한, 오류 처리가 명확합니다. 좋은 위임 패킷도 같습니다.
- 입력: Context, Scope
- 출력: Outcome, Report format
- 권한: Permissions, Non-goals
- 오류 처리: Verification, Stop conditions
이 구조가 생기면 팀은 특정 모델이나 도구에 덜 종속됩니다. 오늘은 Claude Code를 쓰고, 내일은 Codex를 쓰고, 다음 달에는 사내 에이전트를 붙여도 위임 방식은 유지됩니다.
30분 도입 체크리스트
오늘 바로 시작하려면 아래 순서로 충분합니다.
- 최근 에이전트 작업 실패 사례 3개를 고른다.
- 각 실패가 Outcome, Scope, Non-goals, Verification 중 무엇이 없어서 생겼는지 표시한다.
- 이슈 템플릿에 위임 패킷 7개 필드를 추가한다.
- 낮은 위험도의 문서/테스트 작업부터 패킷으로 위임한다.
- 에이전트 결과 보고에 "검증 결과"와 "중단 조건 위반 여부"를 필수로 만든다.
- 2주 후 패킷 필드를 줄이거나 늘린다.
처음부터 완벽한 에이전트 운영 체계를 만들 필요는 없습니다. 하지만 위임 패킷 없이 에이전트 사용량만 늘리면 생산성보다 리뷰 부담이 먼저 늘어납니다.
마무리
AI 코딩 에이전트의 성능은 계속 좋아지고 있습니다. 하지만 팀의 실행 품질은 모델 성능만으로 올라가지 않습니다. 일을 맡기는 방식이 바뀌어야 합니다.
위임 패킷은 작지만 강력한 습관입니다. 목적을 분명히 하고, 범위를 제한하고, 검증을 고정하고, 멈출 조건을 정합니다. 이 네 가지가 있으면 에이전트는 단순한 자동완성 도구가 아니라 팀의 안정적인 실행 파트너가 될 수 있습니다.
오늘 하나의 작업만 패킷으로 위임해 보세요. 프롬프트를 잘 쓰는 팀과 에이전트를 잘 운영하는 팀의 차이가 바로 거기서 시작됩니다.