ai-rules › handbook › Agent Operating Model

Agent Operating Model

특정 프로젝트가 아니라 여러 저장소에서 공통으로 적용할 수 있는 에이전트 팀 운영 모델을 정의

guide 2026-04-03 docs/guide/AGENT_OPERATING_MODEL.md

작성일: 2026-04-03
목적: 특정 프로젝트가 아니라 여러 저장소에서 공통으로 적용할 수 있는 에이전트 팀 운영 모델을 정의

1. 목표

이 문서는 "에이전트를 도구처럼 쓰는 방식"이 아니라 "에이전트가 팀처럼 일하는 방식"을 기준으로 한다.

핵심 목표는 네 가지다.

  • 반복 작업은 자동화한다
  • 승인 피로는 줄인다
  • 위험한 변경은 사람 판단을 남긴다
  • 상태, 인계, 검증을 구조화한다

2. 기본 원칙

에이전트 운영은 아래 원칙을 따른다.

  • 진실원은 대화가 아니라 상태 데이터다
  • 구현보다 검증이 먼저 설계되어야 한다
  • 모든 작업은 역할과 종료 조건이 있어야 한다
  • 모든 세션은 handoff를 남겨야 한다
  • 사람 승인은 "매번"이 아니라 "범위 단위"로 받는다

3. 운영 계층

전체 구조는 4개 계층으로 나눈다.

3.1 State Plane

에이전트가 남기는 구조화된 상태와 기록 계층이다.

권장 자산:

  • SESSION.md
  • WORKLOG/
  • ACTIVE_WORK.md
  • ops/agent-events.jsonl
  • ops/approval-matrix.json
  • ops/approval-overrides/<project>.json

이 중 문서는 사람이 읽기 쉽고, JSONL은 대시보드와 자동화가 읽기 쉽다.

3.2 Execution Plane

에이전트를 실제로 깨우는 실행 계층이다.

권장 조합:

  • Claude GitHub Actions: 팀 공용 정기 작업
  • Claude Desktop scheduled task: 로컬 파일 접근이 필요한 개인 보조 작업
  • openclaw + Telegram: 알림, 질의응답, 승인, 수동 호출
  • 직접 대화 세션: 복잡한 구현과 예외 상황 처리

openclaw + Telegram은 가정용 옵션이 아니라, 이미 AITEM에서 운영 중인 ChatOps 레이어를 공통 운영 모델의 레퍼런스 구현으로 본다. 즉, 새로 발명할 대상이 아니라 다른 프로젝트가 따라붙을 수 있는 reference implementation이다.

3.3 Analysis Plane

역할별 에이전트가 상태를 읽고 판단하는 계층이다.

권장 역할:

  • Leader
  • Planner
  • Builder
  • Reviewer
  • QA
  • Security
  • Release Lead

3.4 Visibility Plane

사람이 현재 상태를 보는 계층이다.

권장 자산:

  • 대시보드
  • Telegram / Slack / Discord 알림
  • 일간 / 주간 리포트

대시보드는 핵심이 아니라 관찰 레이어다. 핵심은 State Plane이다.

4. 역할 모델

Leader

  • 데일리 스크럼 생성
  • blocker 에스컬레이션
  • 승인 대기 큐 정리
  • 스프린트 우선순위 제안

현재 ai-rules의 기본 에이전트 목록에는 Leader가 별도 base agent로 존재하지 않을 수 있다. 초기 도입 단계에서는 Leader를 독립 에이전트가 아니라 planner + orchestrator의 운영 역할 조합으로 본다.

Planner

  • 작업 의도 정리
  • 범위 분해
  • 승인 레벨 판정 보조
  • 다음 작업 제안

Builder

  • 코드 구현
  • 문서 수정
  • 테스트 작성
  • 명확한 범위의 버그 수정

Reviewer

  • 변경의 위험 지적
  • 품질, 회귀, 범위 드리프트 검토
  • 추가 테스트 필요 여부 판단

QA

  • 테스트 실행
  • 회귀 확인
  • 재현 시나리오 검증

Security

  • 인증, 권한, 결제, 민감정보 변경 점검
  • STRIDE 기반 리스크 확인

Release Lead

  • 이번 변경이 배포 가능한지 판단
  • 미해결 리스크와 롤백 포인트 정리

현재 Release Lead 역시 별도 base agent보다는 qa + security + reviewer 결과를 종합하는 운영 역할로 두는 편이 현실적이다. 정식 에이전트로 승격할지는 운영이 안정화된 후 결정한다.

5. 승인 모델

승인은 작업 단위가 아니라 범위 단위로 관리해야 한다.

P0 자동

사람 승인 없이 실행한다.

예:

  • 상태 수집
  • 요약 생성
  • 문서 읽기
  • 리포트 작성
  • 테스트와 lint 실행

P1 범위 자동

미리 허용된 범위 안에서는 자동으로 수정하고 종료 후 보고한다.

단, 이 레벨은 "아무 구현이나 자동 허용"을 뜻하지 않는다. 이미 사람이나 상위 계획 단계에서 범위가 확정된 후속 실행에만 적용한다.

예:

  • docs/**
  • tests/**
  • 명확한 소규모 버그 수정
  • lint / format fix

P2 배치 승인

브랜치, 티켓, 스프린트 같은 묶음 단위로 승인 후 자동 실행한다.

예:

  • 특정 feature 브랜치 범위
  • 이번 주 flaky test fix 묶음
  • 문서 체계 정리 작업

P3 명시 승인

항상 사람의 명시 승인이 필요하다.

예:

  • DB 스키마 변경
  • 인증, 권한, 결제 변경
  • 의존성 추가 / 제거
  • API breaking change
  • push, PR, 배포
  • 외부 시스템 상태 변경

6. 공통 승인 매트릭스

기본적으로 아래 원칙을 따른다.

  • observe는 P0
  • small edit는 P1
  • feature batch는 P2
  • critical change와 ship은 P3

권장 정책 예시:

{
  "default": {
    "observe": "P0",
    "docs_edit": "P1",
    "small_code_fix": "P1",
    "feature_batch": "P2",
    "dependency_change": "P3",
    "auth_change": "P3",
    "db_change": "P3",
    "push_pr_deploy": "P3"
  }
}

프로젝트별 차이는 override로만 처리하고, 기본 프레임은 공통으로 유지한다.

기존 core 규칙과의 매핑

이 문서는 core/ 규칙을 대체하지 않는다. 해석 순서는 항상 기존 상위 규칙을 따른다.

  • 보안, 인증, 결제, 권한, DB, 배포는 기존 security / git / workflow 규칙이 우선한다
  • P1은 이미 승인된 범위 안의 저위험 후속 실행에만 적용한다
  • 구현 요청 자체가 모호하거나 범위가 넓으면 기존 workflow 규칙에 따라 Plan 또는 설계 단계가 먼저 온다
  • P2는 "티켓/브랜치/스프린트 단위의 사람 승인"을 받은 뒤의 배치 실행 모델이다
  • P3는 기존 규칙의 approval required, protected branch, deploy, external side effect와 같은 강한 승인 구간에 대응한다

즉, P0~P3는 공통 운영 언어이고, 실제 강제는 기존 core/ 규칙과 하네스가 담당한다.

7. 작업 흐름

7.1 Daily Scrum

  1. 스케줄러가 Leader를 깨운다.
  2. SESSION.md, WORKLOG, 최근 이벤트를 읽는다.
  3. 어제 한 일, 오늘 할 일, blocker, 승인 필요 항목을 요약한다.
  4. 리포트를 대시보드와 메신저 채널에 반영한다.

7.2 Build Flow

  1. Planner가 작업 범위와 종료 조건을 정리한다.
  2. 승인 레벨을 판정한다.
  3. Builder가 구현한다.
  4. Reviewer와 QA가 검증한다.
  5. 보안 관련이면 Security가 추가 검토한다.
  6. 배포 후보면 Release Lead가 readiness를 정리한다.

7.3 Blocked Flow

  1. Builder 또는 QA가 task_blocked 이벤트를 남긴다.
  2. 일정 시간 이상 지속되면 Leader가 에스컬레이션한다.
  3. 사람 판단이 필요하면 approval_needed를 만든다.
  4. 메신저와 대시보드에 승인 대기 상태를 노출한다.

8. 이벤트 모델

문서 기반 handoff만으로는 대시보드와 자동화가 약하다. 따라서 이벤트 원장을 함께 두는 것이 좋다.

권장 이벤트 예시:

  • task_created
  • task_started
  • task_completed
  • task_blocked
  • approval_needed
  • approval_granted
  • review_requested
  • review_completed
  • qa_passed
  • qa_failed
  • security_required
  • release_ready

예시:

{"ts":"2026-04-03T08:55:00Z","project":"ai-rules","agent":"leader","event":"daily_scrum_started"}
{"ts":"2026-04-03T09:02:10Z","project":"ai-rules","agent":"builder","event":"task_blocked","reason":"approval_needed"}
{"ts":"2026-04-03T09:03:00Z","project":"ai-rules","agent":"leader","event":"approval_needed","scope":"feature_batch"}

9. 대시보드의 역할

대시보드는 "에이전트를 굴리는 엔진"이 아니라 "현재 상태를 보는 관제판"이다.

대시보드에 보여줄 최소 항목:

  • 현재 실행 중인 에이전트
  • blocked task
  • approval queue
  • 최근 handoff
  • 브랜치 상태
  • 오늘 완료 / 진행 / 지연
  • release readiness

권장 원칙:

  • 대시보드는 상태를 추론하지 말고 구조화된 이벤트를 읽는다
  • polling으로 시작하고, 필요할 때 websocket으로 확장한다
  • 보고서와 메신저 알림은 대시보드의 보조 출력이다

10. 스케줄러 선택 기준

Claude GitHub Actions

적합:

  • 팀 공용 정기 작업
  • 일간 / 주간 보고
  • 릴리즈 readiness 분석
  • PR, 브랜치, 이슈 기반 자동화

장점:

  • 내구성이 높다
  • 로그와 이력이 남는다
  • 저장소 중심 운영에 잘 맞는다

Claude Desktop scheduled task

적합:

  • 로컬 파일 접근이 필요한 보조 작업
  • 개인 워크스페이스 상태 수집
  • PC가 켜져 있는 환경의 개인 자동화

장점:

  • 로컬 맥락에 강하다
  • 개인 작업 습관과 붙이기 쉽다

openclaw + Telegram

적합:

  • 수동 호출
  • 질문 응답
  • 승인 요청
  • 요약 확인

장점:

  • 사람과 에이전트 사이의 상호작용이 빠르다
  • 이미 AITEM에서 운영 중인 패턴을 reference implementation으로 재사용할 수 있다

권장 결론:

  • 정기 실행은 Claude GitHub Actions 또는 Claude Desktop scheduled task
  • 호출과 알림은 openclaw + Telegram
  • 조회는 대시보드

운영 이식 시에는 AITEM의 ChatOps 구성을 직접 복제하기보다, 그 패턴을 공통 상태 원장과 승인 정책 위에 연결하는 방식이 권장된다.

11. 지표

에이전트 운영은 감으로 평가하지 않는다.

최소 지표:

  • agent-created PR 수
  • merge rate
  • CI first-pass rate
  • blocker 평균 체류 시간
  • 사람 승인 대기 시간
  • retry 횟수
  • release readiness 경고 수

이 지표는 "AI를 많이 썼는가"가 아니라 "검증 가능한 속도와 품질 개선이 있었는가"를 보기 위한 것이다.

12. 도입 순서

1단계

  • SESSION.md, WORKLOG, ACTIVE_WORK 정착
  • daily scrum 자동화
  • P0 / P1 / P3 승인 기준 확정
  • openclaw + Telegram을 이미 운영 중인 프로젝트는 그 구성을 reference로 문서화

2단계

  • ops/agent-events.jsonl 도입
  • Reviewer, QA, Security 게이트 추가
  • approval queue 추가
  • ops/ 최소 scaffold 생성

3단계

  • 대시보드 연결
  • Release Lead 추가
  • project override 정책 추가

4단계

  • 실패 기반 자동 트리거
  • 메신저 승인 플로우 정교화
  • websocket 또는 richer viewer 도입

13. 결론

좋은 에이전트 운영 모델은 "항상 자동"도 아니고 "매번 승인"도 아니다.

가장 좋은 구조는 다음과 같다.

  • 상태는 구조화해서 남긴다
  • 정기 실행은 durable scheduler에 맡긴다
  • 사람 승인은 범위 단위로 묶는다
  • 구현과 검증 역할을 분리한다
  • 대시보드는 결과를 보여주는 층으로 둔다

즉, 에이전트 문화를 만들려면 먼저 viewer가 아니라 운영 모델이 있어야 한다.

14. Migration Path

이미 특정 프로젝트에서 일부 운영 레이어를 쓰고 있다면, 그것을 버리지 말고 공통 모델에 편입한다.

예:

  • AITEM의 openclaw + Telegram은 호출/알림/승인 채널의 레퍼런스 구현으로 사용
  • 다른 프로젝트는 같은 패턴을 따르되, 상태 기록과 승인 기준은 공통 ops/ 모델을 공유
  • 프로젝트 고유 규칙은 approval-overrides와 project-specific guide로 제한

즉, 공통화의 목표는 각 프로젝트를 동일하게 만드는 것이 아니라, 같은 운영 언어와 같은 승인 모델 위에서 움직이게 만드는 것이다.