Agent Team Playbook

한눈에 보기

Agent Team Playbook은 AI agent를 개별 도구가 아니라 역할, 상태, 승인, 증거를 가진 팀으로 운영하는 방법을 설명합니다. 계획, 설계, 구현, QA, 리뷰, 보안, 배포 판단이 어디서 나뉘고 어디서 다시 합쳐지는지 보여줍니다.

• 핵심 질문: agent가 많아질수록 책임과 상태를 어떻게 잃지 않을 것인가?
• 읽는 대상: 다중 agent 작업을 구조화하려는 운영자, reviewer, project lead
• 연결 문서: Agent Orchestration, AX Solution Orchestration, Evidence Dashboard

이 문서에서 확인할 것

• planner, architect, builder, QA, reviewer, security의 역할 카드
• 작업 규모와 위험도에 따른 라우팅 기준
• 이벤트 원장과 운영 리듬으로 상태를 남기는 방식

에이전트를 도구가 아니라 팀으로 운영하기

에이전트 운영의 목표는 모든 일을 자동화하는 것이 아닙니다. 반복 작업은 자동화하고, 위험한 판단은 사람에게 남기며, 상태와 검증을 구조화하는 것입니다.

flowchart TD
  U["사용자 요청"] --> I["Intake<br/>목표와 경계"]
  I --> P["Planner<br/>범위와 종료 조건"]
  P --> A["Architect<br/>설계와 계약"]
  A --> B["Builder<br/>구현"]
  B --> Q["QA<br/>테스트와 재현"]
  Q --> R["Reviewer<br/>회귀와 품질"]
  R --> S{"보안/배포 영향?"}
  S -->|있음| SEC["Security / Release Lead"]
  S -->|없음| D["Done with evidence"]
  SEC --> D

  subgraph State["State Plane"]
    LOG["WORKLOG"]
    EVT["agent-events.jsonl"]
    HAND["handoff"]
  end

  P -.-> LOG
  B -.-> EVT
  Q -.-> EVT
  D -.-> HAND

역할 카드

역할	책임	종료 조건
Planner	의도, 범위, 승인 레벨 정리	작업 단위와 검증 기준이 명확함
Architect	상태 전이, API, 데이터 흐름 설계	구현자가 추측하지 않아도 됨
Builder	코드, 문서, 테스트 구현	변경이 범위 안에 있음
QA	테스트, 재현, 브라우저 검증	실패/성공 증거가 남음
Reviewer	회귀, 품질, 범위 드리프트 점검	승인 또는 수정 요청이 명확함
Security	인증, 권한, 결제, 비밀값 점검	위험과 완화책이 분리됨
Release Lead	배포 가능성, 롤백 포인트 판단	ship/no-ship 근거가 있음

규모별 라우팅

작업 규모	라우팅	이유
1~3개 파일	Builder 직행	계획 비용이 구현 비용보다 크지 않게 유지
4~15개 파일	Planner -> Builder -> QA	범위와 검증 기준을 먼저 고정
16개 이상 또는 다중 도메인	Orchestrator -> 병렬 subagent	역할별 책임과 결과 통합 필요
반복 오류 2회 이상	Investigator 투입	같은 전략으로 재시도하지 않음
인증/권한/결제/DB	Security gate 추가	위험이 기능 구현보다 큼

승인 모델

flowchart LR
  P0["P0 Observe<br/>읽기, 요약, lint"] --> P1["P1 Scoped Auto<br/>docs, tests, 작은 수정"]
  P1 --> P2["P2 Batch Approval<br/>브랜치, 티켓, 스프린트"]
  P2 --> P3["P3 Explicit Approval<br/>DB, auth, deploy, push"]

승인은 매번 묻는 방식보다 범위 단위로 관리하는 것이 낫습니다. 단, P1 자동 실행은 이미 범위가 확정된 저위험 후속 작업에만 적용합니다.

이벤트 원장

대화만으로 운영 상태를 추적하면 대시보드와 자동화가 약해집니다. 작업 상태는 사람이 읽는 문서와 기계가 읽는 이벤트를 같이 남기는 편이 좋습니다.

이벤트	의미
task_created	작업이 큐에 들어옴
task_started	담당 에이전트가 실행 시작
task_blocked	외부 판단이나 정보가 필요
approval_needed	사람 승인 대기
qa_passed / qa_failed	검증 결과
security_required	보안 검토 필요
release_ready	배포 후보 상태

운영 리듬

1. Daily Scrum은 상태를 요약하고 blocker를 드러낸다.
2. Build Flow는 계획, 구현, 검증, 리뷰를 분리한다.
3. Blocked Flow는 사람 판단이 필요한 항목을 승인 큐로 올린다.
4. Retrospective는 반복 실패를 rule, skill, hook 후보로 보낸다.

공개용 설명 방식

에이전트 운영을 공개 문서로 쓸 때는 “어떤 모델을 썼다”보다 “어떤 역할이 어떤 증거를 남겼다”가 중요합니다. 역할, 상태, 승인 기준, 검증 결과가 보이면 내부 시스템을 공개하지 않아도 운영 수준을 설명할 수 있습니다.

Source Notes

이 문서는 ai-rules의 Agent Operating Model, agents guide와 keystone-hub의 manager/orchestrator, team, self-improve 운영 문서를 공개용 플레이북으로 재구성했습니다.