AGENTS.md 설계 가이드: 멀티 에이전트 컨텍스트 분리와 권한 위임 패턴

AI 에이전트 하나에게 "이 레포 전체를 리팩터링해줘"라고 맡겨봤다가 컨텍스트 윈도우가 한계에 다다르거나, 에이전트가 갑자기 엉뚱한 파일을 수정하는 상황을 경험해보신 적 있으신가요? 저도 처음엔 단일 에이전트에 모든 걸 몰아넣다가 몇 번 곤혹스러운 상황을 겪었는데요. 그 이후로 멀티 에이전트 오케스트레이션을 도입하면서 작업의 품질과 안정성이 눈에 띄게 달라졌습니다.

멀티 에이전트 시스템의 핵심은 "누가 뭘 알고, 누가 뭘 할 수 있는가"를 명확히 정의하는 것입니다. 그리고 그 정의를 담는 그릇이 바로 AGENTS.md입니다. 이 글에서는 AGENTS.md를 계층적으로 설계해서 오케스트레이터와 서브에이전트 간 컨텍스트를 깔끔하게 분리하고, 역할별 권한을 안전하게 위임하는 패턴을 코드 예시와 함께 살펴봅니다.

Claude Code, Cursor, GitHub Copilot, Gemini CLI 등 주요 AI 코딩 도구들이 이미 AGENTS.md를 지원하고 있어서, 지금 이 패턴을 익혀두면 어떤 툴체인을 쓰더라도 바로 적용해볼 수 있습니다.

핵심 개념

AGENTS.md — 에이전트를 위한 README

AGENTS.md는 코딩 에이전트에게 프로젝트 컨텍스트와 행동 규칙을 전달하는 마크다운 파일입니다. README가 인간 개발자를 위한 문서라면, AGENTS.md는 AI 에이전트를 위한 문서라고 생각하면 됩니다. 특별한 스키마나 YAML 프론트매터 없이 순수 마크다운으로 작성하면 되고, 에이전트가 편집하려는 파일에 가장 가까운 위치의 AGENTS.md가 우선 적용됩니다.

단순한 규칙 파일처럼 보이지만, 멀티 에이전트 시스템에서는 각 계층의 AGENTS.md가 해당 에이전트의 "헌법"처럼 작동합니다. 오케스트레이터용 AGENTS.md는 전체 시스템의 큰 그림과 에이전트 레지스트리를 담고, 서브에이전트용 AGENTS.md는 해당 도메인에만 집중한 좁고 깊은 규칙을 담습니다.

오케스트레이터-워커 패턴

실무에서 가장 널리 쓰이는 멀티 에이전트 구조입니다. 비유하자면 프로젝트 매니저가 팀원들에게 역할을 나눠주고 결과를 모아 보고하는 방식과 비슷합니다. 중앙 오케스트레이터가 사용자 요청을 받아 서브태스크로 분해하고, 각 전문 워커 에이전트에 라우팅한 뒤, 결과를 집계하는 구조입니다.

사용자 요청
    │
    ▼
┌─────────────────────────┐
│      오케스트레이터       │  ← 작업 분해, 라우팅, 결과 집계
│  (전체 맥락 유지)         │
└─────────────────────────┘
    │           │           │
    ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐
│코드생성 │ │테스트  │ │보안감사│  ← 각자의 컨텍스트에서 독립 실행
│에이전트 │ │에이전트│ │에이전트│
└────────┘ └────────┘ └────────┘
    │           │           │
    └───────────┴───────────┘
              요약만 반환

여기서 핵심은, 서브에이전트가 작업을 마치면 전체 탐색 이력은 서브에이전트의 컨텍스트 안에 격리되고 오케스트레이터에게는 최종 요약만 올라온다는 점입니다. 이 덕분에 오케스트레이터의 컨텍스트 윈도우가 깔끔하게 유지됩니다.

컨텍스트 분리 — 왜 중요한가

서브에이전트가 스폰될 때마다 새 컨텍스트 윈도우(예: Claude의 경우 200K 토큰)가 할당됩니다. 이 격리 구조가 제대로 설계되어 있지 않으면, 오케스트레이터가 불필요한 중간 탐색 기록으로 컨텍스트를 잡아먹고, 컨텍스트 후반부로 갈수록 출력 품질이 저하되는 현상—흔히 "컨텍스트 로트(Context Rot)"라고 부릅니다—이 발생합니다. 병렬로 실행 중인 서브에이전트들이 서로의 상태에 간섭하는 문제도 생기고요.

이런 이유로 2025~2026년에 걸쳐 업계에서 "프롬프트 엔지니어링"보다 "컨텍스트 엔지니어링"이 더 중요한 화두로 떠올랐습니다. 핵심은 어떤 토큰을 언제 모델에게 줄 것인가를 설계하는 것입니다. 에이전트 초기화 시 모든 컨텍스트를 한 번에 로딩하는 대신, 현재 작업 단계에 필요한 정보만 단계적으로 제공하는 "프로그레시브 디스클로저(Progressive Disclosure)" 기법이 이 문제의 표준 해법으로 자리잡고 있습니다. 특정 구현 사례에 따라 토큰 사용량을 크게 줄이면서 품질을 유지하는 결과가 실제로 보고되고 있습니다.

역할별 권한 위임 패턴

에이전트 권한 설계는 세 가지 핵심 원리를 따릅니다:

원리	설명
위임된 접근 (Delegated Access)	에이전트가 사용자 토큰을 상속받아 실시간으로 사용자 권한 수준을 유지
고유 에이전트 ID	에이전트마다 비공유 식별자를 부여해 모든 액션을 감사 추적 가능하게 함
컨텍스트 인식 권한 (Context-Aware Permissions)	정적 상속 대신 동적 교환으로 하위 자격증명을 조건에 맞게 트리밍

정적으로 권한을 상속받는 방식은 "부모가 할 수 있으면 자식도 다 할 수 있다"는 논리인데, 실무에서는 꽤 위험합니다. 오케스트레이터가 DB 삭제 권한을 가지고 있다고 해서 코드 생성 서브에이전트에게도 그 권한이 넘어가면 안 되잖아요. 그래서 컨텍스트 인식 권한 설계가 필요합니다.

실전 적용

예시 1: 계층형 AGENTS.md 디렉터리 구조 설계

가장 많이 쓰이는 구조는 루트에 전역 규칙, 서브디렉터리에 도메인별 특화 규칙을 두는 방식입니다.

bash

/AGENTS.md                  # 전역: 기술 스택, 아키텍처 원칙, 에이전트 레지스트리
/agents/
  code-reviewer.md          # 코드 리뷰 서브에이전트 정의
  test-runner.md            # 테스트 실행 서브에이전트 정의
  security-auditor.md       # 보안 감사 서브에이전트 정의
/src/AGENTS.md              # 소스 코드 작성 규칙 (전역 규칙 참조 + 추가)
/docs/AGENTS.md             # 문서화 규칙

상속은 어떻게 작동하나요? AGENTS.md의 "상속"은 프레임워크가 파일을 자동으로 병합해주는 것이 아닙니다. 에이전트가 작업 대상 파일에서 루트 방향으로 거슬러 올라가며 각 디렉터리의 AGENTS.md를 직접 읽는 방식입니다. /src/AGENTS.md에 "inherits from /AGENTS.md"라고 명시해두면 에이전트가 두 파일을 모두 참고한다는 의도를 명확히 전달할 수 있습니다.

루트 AGENTS.md 예시입니다:

markdown

# Project: MyApp
 
## 기술 스택
- Runtime: Node.js 22, TypeScript 5.x
- Framework: NestJS (백엔드), Next.js 15 (프론트엔드)
- DB: PostgreSQL 16, Redis 7
 
## 아키텍처 원칙
- 비즈니스 로직은 Service 레이어에만 작성
- Controller는 얇게 유지 (thin controller)
- 모든 외부 입력은 DTO로 검증
 
## 에이전트 레지스트리
| 에이전트 | 역할 | 진입점 |
|---------|------|--------|
| code-reviewer | PR 리뷰 및 코드 품질 검사 | /agents/code-reviewer.md |
| test-runner | 테스트 실행 및 커버리지 분석 | /agents/test-runner.md |
| security-auditor | 보안 취약점 감사 (읽기 전용) | /agents/security-auditor.md |
 
## 전역 금지 사항
- production DB에 직접 쿼리 금지
- .env 파일 수정 금지
- main/master 브랜치 직접 푸시 금지

/src/AGENTS.md는 루트 규칙을 참고하면서 소스 코드 작성에 특화된 규칙만 추가합니다:

markdown

# Source Code Rules (inherits from /AGENTS.md)
 
## 코드 스타일
- 2-space indentation
- async/await 사용 (not .then())
- TypeScript strict mode 필수
 
## 파일 구조 규칙
- Service 파일: *.service.ts
- Controller 파일: *.controller.ts
- DTO 파일: dto/*.dto.ts
 
## 이 디렉터리에서 허용하는 작업
- src/ 하위 파일 읽기/쓰기
- 새 모듈 생성
 
## 이 디렉터리에서 금지하는 작업
- 테스트 파일(*.spec.ts) 직접 수정
- DB 마이그레이션 파일 수정

항목	루트 AGENTS.md	서브디렉터리 AGENTS.md
범위	전체 프로젝트 공통 규칙	해당 도메인 특화 규칙
에이전트 레지스트리	포함 (전체 에이전트 목록)	미포함
권한 정의	전역 금지/허용 목록	도메인별 세부 권한
권장 길이	100줄 이내	50줄 이내

예시 2: 역할별 권한 분리 AGENTS.md 작성

각 서브에이전트의 AGENTS.md에는 해당 에이전트가 할 수 있는 것과 할 수 없는 것을 명확하게 정의하는 것이 중요합니다. 솔직히 처음엔 "그냥 프롬프트에 써주면 되지 않나?" 싶었는데, AGENTS.md로 분리하면 에이전트가 작업 전에 해당 파일을 로드해서 자신의 경계를 인지하기 때문에 일관성이 훨씬 높아집니다.

한 가지 미리 말씀드릴 점이 있습니다. AGENTS.md에 명시한 허용/금지 규칙은 선언적 약속입니다. 에이전트가 이 파일을 읽고 스스로 판단해서 지키는 것이지, 런타임 레벨에서 강제로 막아주는 메커니즘이 아닙니다. 실제 운영 환경에서는 샌드박스나 툴 필터링 같은 런타임 레벨 권한 제한을 AGENTS.md 규칙과 병행하는 것을 권장합니다.

markdown

# Security Auditor Agent
 
## 역할
코드베이스의 보안 취약점을 탐지하고 리포트를 생성합니다.
OWASP Top 10 기준으로 분석하며, 수정 제안만 제공하고 실제 수정은 하지 않습니다.
 
## 허용된 작업
- 모든 소스 파일 읽기 (read-only)
- 의존성 파일 분석 (package.json, pom.xml 등)
- 보안 리포트 파일 생성 (reports/ 디렉터리에만)
- 외부 CVE 데이터베이스 조회 (읽기)
 
## 절대 금지 사항
- 소스 파일 수정 또는 삭제
- 설정 파일(.env, config/) 접근
- 네트워크 연결 (CVE DB 조회 제외)
- 다른 에이전트 스폰
 
## 출력 형식
결과는 반드시 다음 구조로 반환:
{
  "severity": "critical|high|medium|low",
  "location": "파일경로:라인번호",
  "description": "취약점 설명",
  "cwe": "CWE-XXX",
  "recommendation": "수정 방향 (코드 직접 수정 없이)"
}

markdown

# Code Generation Agent
 
## 역할
오케스트레이터의 지시에 따라 새 기능의 소스 코드를 생성합니다.
 
## 허용된 작업
- src/ 디렉터리 하위 파일 읽기/쓰기
- 새 파일 생성 (src/ 내부에만)
- 타입 정의 파일 수정 (src/types/)
- pnpm 패키지 설치 (devDependencies 제외)
 
## 절대 금지 사항
- src/ 외부 파일 수정
- DB 스키마 변경 (migrations/ 접근 금지)
- 환경 변수 파일(.env*) 수정
- 테스트 파일 수정 (*.spec.ts, *.test.ts)
- 다른 에이전트 직접 호출
 
## 완료 시 반환 형식
작업 완료 후 요약만 반환:
- 생성/수정된 파일 목록
- 핵심 변경 사항 3줄 이내 요약
- 이어서 필요한 작업 (있다면)

예시 3: 계층적 오케스트레이션 설계 (3계층)

단순한 1:N 구조보다 실무에서 더 효과적인 3계층 구조입니다. 오케스트레이터가 6개의 서브에이전트를 직접 관리하는 대신, 피처 리드 에이전트가 각자의 전문가들을 조율합니다. 오케스트레이터의 컨텍스트가 훨씬 가볍게 유지되는 게 핵심입니다.

bash

오케스트레이터 (컨텍스트: 전체 작업 계획만)
├── 피처 리드 A: 사용자 인증 기능
│   ├── 프론트엔드 전문가 (src/components/auth/)
│   └── API 전문가 (src/modules/auth/)
└── 피처 리드 B: 결제 기능
    ├── DB 전문가 (migrations/, src/repositories/)
    └── 테스트 전문가 (test/payment/)

오케스트레이터 AGENTS.md:

markdown

# Orchestrator Agent
 
## 역할
사용자 요청을 분석하고 피처 리드 에이전트에게 위임합니다.
직접 코드를 작성하거나 파일을 수정하지 않습니다.
 
## 작업 분해 원칙
1. 요청을 독립적인 기능 단위로 분리
2. 각 기능을 담당할 피처 리드 에이전트를 선택
3. 피처 리드에게 명확한 인터페이스 계약(입출력)을 포함한 지시 전달
4. 결과를 통합하고 충돌 시 조율
 
## 허용된 작업
- 파일 읽기 (전체 범위, 탐색 목적)
- 피처 리드 에이전트 스폰
- 결과 통합 리포트 작성
 
## 절대 금지 사항
- 직접 파일 수정/삭제
- 외부 API 직접 호출
- DB 접근
- 서브에이전트 결과를 컨텍스트에 전체 저장 (요약만 수신)
 
## 컨텍스트 관리 규칙
- 서브에이전트 스폰 시 필요한 정보만 전달 (Progressive Disclosure)
- 서브에이전트 탐색 이력은 컨텍스트에 포함하지 않음
- 각 피처 리드의 최종 요약만 집계

피처 리드 에이전트 AGENTS.md는 오케스트레이터보다 좁은 범위에서 조율 역할을 담당합니다:

markdown

# Feature Lead Agent: Auth
 
## 역할
사용자 인증 기능 구현을 조율합니다.
프론트엔드 전문가와 API 전문가를 스폰하고 결과를 통합합니다.
 
## 담당 범위
- src/components/auth/ (프론트엔드)
- src/modules/auth/ (백엔드 API)
 
## 허용된 작업
- 담당 범위 파일 읽기
- 프론트엔드 전문가, API 전문가 스폰
- 인터페이스 계약 검증 (입출력 타입 일치 여부)
 
## 절대 금지 사항
- 담당 범위 외 파일 수정
- DB 스키마 직접 접근
- 다른 피처 리드 영역 간섭

장단점 분석

장점

항목	내용
클린 컨텍스트	서브에이전트 격리로 오케스트레이터 컨텍스트 오염 방지, 각 에이전트가 단일 책임에만 집중
병렬 실행	독립적인 서브태스크 동시 실행으로 전체 처리 시간 단축
명확한 감사 추적	각 에이전트가 단일 역할을 가지므로 각 단계 출력이 명확하고 검증 가능
최소 권한 원칙	각 에이전트에게 필요한 권한만 부여해 보안 위협 표면 축소
모듈형 재사용	계층형 AGENTS.md 구조로 규칙 참조·오버라이드, 중복 제거

단점 및 주의사항

항목	내용	대응 방안
토큰 비용 급증	멀티 에이전트는 단일 에이전트 대비 4~15배 토큰 소모	Progressive Disclosure로 필요한 컨텍스트만 로딩
AGENTS.md 비대화	150~200줄 초과 시 성능 저하, LLM 생성 AGENTS.md는 성공률 저하·비용 증가 유발	파일을 짧고 명확하게 유지, 직접 작성 권장
컨텍스트 로트	과도한 컨텍스트가 출력 품질 저하 유발	단계적 컨텍스트 로딩, 불필요한 중간 결과 배제
중첩 제한	일부 환경에서 서브에이전트가 다른 서브에이전트를 직접 스폰 불가	오케스트레이터가 모든 스폰을 중앙 관리하도록 설계
핸드오프 가드레일 공백	OpenAI Agents SDK에서 핸드오프 호출 자체에 도구 가드레일 미적용	핸드오프 전후 입출력 검증 로직 별도 추가
규칙 충돌	계층형 AGENTS.md에서 상위·하위 파일 간 규칙 충돌 시 행동 예측 불가	명시적 우선순위 규칙 작성 ("이 파일의 규칙이 루트보다 우선")
단일 장애점	오케스트레이터 장애 시 전체 시스템 중단	오케스트레이터 상태를 외부에 주기적 저장, 재시작 전략 설계

실무에서 가장 흔한 실수

AGENTS.md를 너무 상세하게 작성하기: "더 많은 규칙 = 더 좋은 결과"라는 직관과 달리, AGENTS.md가 길수록 오히려 성능이 저하됩니다. 연구에 따르면 LLM이 자동 생성한 AGENTS.md는 작업 성공률을 떨어뜨리고 비용을 증가시킵니다. 핵심 규칙만 간결하게 담고 직접 손으로 작성하는 것을 권장합니다.
오케스트레이터에게 너무 많은 일 맡기기: 오케스트레이터가 직접 파일을 탐색하고 코드를 작성하기 시작하면 컨텍스트가 금방 차오르고 서브에이전트에 위임할 여력이 없어집니다. 오케스트레이터는 "지휘자" 역할에만 집중하고 실무는 서브에이전트에 위임하는 것을 권장합니다.
권한 설계를 나중으로 미루기: "일단 작동하게 만들고 나중에 권한 제한하자"는 접근은 실제로 잘 작동하지 않습니다. 처음부터 각 에이전트의 허용·금지 목록을 명시해두면 디버깅할 때 훨씬 편하고, 의도치 않은 파일 수정이나 권한 남용 사고를 예방할 수 있습니다.

마치며

AGENTS.md의 핵심은 규칙을 많이 쌓는 것이 아니라, 각 에이전트가 "나는 무엇을 해야 하고 무엇을 하면 안 되는가"를 명확히 알 수 있도록 책임 경계를 설계하는 것입니다.

지금 바로 시작해볼 수 있는 3단계:

루트 파일 생성: 기존 프로젝트 루트에 /AGENTS.md 파일을 만들고, 기술 스택·아키텍처 원칙·전역 금지 사항 세 가지만 50줄 이내로 작성해볼 수 있습니다. Claude Code나 Cursor 같은 도구를 쓰고 있다면 파일을 만드는 것만으로 바로 인식됩니다.
역할 파일 작성: 반복적으로 맡기는 작업(코드 리뷰, 테스트 실행 등)을 하나 골라 /agents/[역할명].md를 작성해보시면 좋습니다. "허용된 작업"과 "절대 금지 사항" 두 섹션만 있어도 충분히 시작할 수 있습니다.
컨텍스트 관리 규칙 추가: 오케스트레이터 에이전트의 AGENTS.md에 "완료 시 서브에이전트 탐색 이력 없이 요약만 반환" 규칙을 추가해보시면, 컨텍스트 효율이 눈에 띄게 달라지는 것을 확인해볼 수 있습니다.

다음 글: 이 글에서 다룬 에이전트 간 역할 경계를 프로토콜 레벨에서 구현하려면 결국 표준 선택의 기로에 서게 됩니다 — MCP(Model Context Protocol)와 A2A(Agent-to-Agent) 프로토콜의 차이점, 그리고 두 표준을 어떻게 조합할 것인지를 다뤄볼 예정입니다.

참고 자료

AGENTS.md 설계 가이드: 멀티 에이전트 컨텍스트 분리와 권한 위임 패턴 | DEV BAK - 기술블로그

AGENTS.md 설계 가이드: 멀티 에이전트 컨텍스트 분리와 권한 위임 패턴

핵심 개념

AGENTS.md — 에이전트를 위한 README

오케스트레이터-워커 패턴

사용자 요청
    │
    ▼
┌─────────────────────────┐
│      오케스트레이터       │  ← 작업 분해, 라우팅, 결과 집계
│  (전체 맥락 유지)         │
└─────────────────────────┘
    │           │           │
    ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐
│코드생성 │ │테스트  │ │보안감사│  ← 각자의 컨텍스트에서 독립 실행
│에이전트 │ │에이전트│ │에이전트│
└────────┘ └────────┘ └────────┘
    │           │           │
    └───────────┴───────────┘
              요약만 반환

컨텍스트 분리 — 왜 중요한가

역할별 권한 위임 패턴

에이전트 권한 설계는 세 가지 핵심 원리를 따릅니다:

원리	설명
위임된 접근 (Delegated Access)	에이전트가 사용자 토큰을 상속받아 실시간으로 사용자 권한 수준을 유지
고유 에이전트 ID	에이전트마다 비공유 식별자를 부여해 모든 액션을 감사 추적 가능하게 함
컨텍스트 인식 권한 (Context-Aware Permissions)	정적 상속 대신 동적 교환으로 하위 자격증명을 조건에 맞게 트리밍

실전 적용

예시 1: 계층형 AGENTS.md 디렉터리 구조 설계

가장 많이 쓰이는 구조는 루트에 전역 규칙, 서브디렉터리에 도메인별 특화 규칙을 두는 방식입니다.

bash

/AGENTS.md                  # 전역: 기술 스택, 아키텍처 원칙, 에이전트 레지스트리
/agents/
  code-reviewer.md          # 코드 리뷰 서브에이전트 정의
  test-runner.md            # 테스트 실행 서브에이전트 정의
  security-auditor.md       # 보안 감사 서브에이전트 정의
/src/AGENTS.md              # 소스 코드 작성 규칙 (전역 규칙 참조 + 추가)
/docs/AGENTS.md             # 문서화 규칙

상속은 어떻게 작동하나요? AGENTS.md의 "상속"은 프레임워크가 파일을 자동으로 병합해주는 것이 아닙니다. 에이전트가 작업 대상 파일에서 루트 방향으로 거슬러 올라가며 각 디렉터리의 AGENTS.md를 직접 읽는 방식입니다. /src/AGENTS.md에 "inherits from /AGENTS.md"라고 명시해두면 에이전트가 두 파일을 모두 참고한다는 의도를 명확히 전달할 수 있습니다.

루트 AGENTS.md 예시입니다:

markdown

# Project: MyApp
 
## 기술 스택
- Runtime: Node.js 22, TypeScript 5.x
- Framework: NestJS (백엔드), Next.js 15 (프론트엔드)
- DB: PostgreSQL 16, Redis 7
 
## 아키텍처 원칙
- 비즈니스 로직은 Service 레이어에만 작성
- Controller는 얇게 유지 (thin controller)
- 모든 외부 입력은 DTO로 검증
 
## 에이전트 레지스트리
| 에이전트 | 역할 | 진입점 |
|---------|------|--------|
| code-reviewer | PR 리뷰 및 코드 품질 검사 | /agents/code-reviewer.md |
| test-runner | 테스트 실행 및 커버리지 분석 | /agents/test-runner.md |
| security-auditor | 보안 취약점 감사 (읽기 전용) | /agents/security-auditor.md |
 
## 전역 금지 사항
- production DB에 직접 쿼리 금지
- .env 파일 수정 금지
- main/master 브랜치 직접 푸시 금지

/src/AGENTS.md는 루트 규칙을 참고하면서 소스 코드 작성에 특화된 규칙만 추가합니다:

markdown

# Source Code Rules (inherits from /AGENTS.md)
 
## 코드 스타일
- 2-space indentation
- async/await 사용 (not .then())
- TypeScript strict mode 필수
 
## 파일 구조 규칙
- Service 파일: *.service.ts
- Controller 파일: *.controller.ts
- DTO 파일: dto/*.dto.ts
 
## 이 디렉터리에서 허용하는 작업
- src/ 하위 파일 읽기/쓰기
- 새 모듈 생성
 
## 이 디렉터리에서 금지하는 작업
- 테스트 파일(*.spec.ts) 직접 수정
- DB 마이그레이션 파일 수정

항목	루트 AGENTS.md	서브디렉터리 AGENTS.md
범위	전체 프로젝트 공통 규칙	해당 도메인 특화 규칙
에이전트 레지스트리	포함 (전체 에이전트 목록)	미포함
권한 정의	전역 금지/허용 목록	도메인별 세부 권한
권장 길이	100줄 이내	50줄 이내

예시 2: 역할별 권한 분리 AGENTS.md 작성

markdown

# Security Auditor Agent
 
## 역할
코드베이스의 보안 취약점을 탐지하고 리포트를 생성합니다.
OWASP Top 10 기준으로 분석하며, 수정 제안만 제공하고 실제 수정은 하지 않습니다.
 
## 허용된 작업
- 모든 소스 파일 읽기 (read-only)
- 의존성 파일 분석 (package.json, pom.xml 등)
- 보안 리포트 파일 생성 (reports/ 디렉터리에만)
- 외부 CVE 데이터베이스 조회 (읽기)
 
## 절대 금지 사항
- 소스 파일 수정 또는 삭제
- 설정 파일(.env, config/) 접근
- 네트워크 연결 (CVE DB 조회 제외)
- 다른 에이전트 스폰
 
## 출력 형식
결과는 반드시 다음 구조로 반환:
{
  "severity": "critical|high|medium|low",
  "location": "파일경로:라인번호",
  "description": "취약점 설명",
  "cwe": "CWE-XXX",
  "recommendation": "수정 방향 (코드 직접 수정 없이)"
}

markdown

# Code Generation Agent
 
## 역할
오케스트레이터의 지시에 따라 새 기능의 소스 코드를 생성합니다.
 
## 허용된 작업
- src/ 디렉터리 하위 파일 읽기/쓰기
- 새 파일 생성 (src/ 내부에만)
- 타입 정의 파일 수정 (src/types/)
- pnpm 패키지 설치 (devDependencies 제외)
 
## 절대 금지 사항
- src/ 외부 파일 수정
- DB 스키마 변경 (migrations/ 접근 금지)
- 환경 변수 파일(.env*) 수정
- 테스트 파일 수정 (*.spec.ts, *.test.ts)
- 다른 에이전트 직접 호출
 
## 완료 시 반환 형식
작업 완료 후 요약만 반환:
- 생성/수정된 파일 목록
- 핵심 변경 사항 3줄 이내 요약
- 이어서 필요한 작업 (있다면)

예시 3: 계층적 오케스트레이션 설계 (3계층)

bash

오케스트레이터 (컨텍스트: 전체 작업 계획만)
├── 피처 리드 A: 사용자 인증 기능
│   ├── 프론트엔드 전문가 (src/components/auth/)
│   └── API 전문가 (src/modules/auth/)
└── 피처 리드 B: 결제 기능
    ├── DB 전문가 (migrations/, src/repositories/)
    └── 테스트 전문가 (test/payment/)

오케스트레이터 AGENTS.md:

markdown

# Orchestrator Agent
 
## 역할
사용자 요청을 분석하고 피처 리드 에이전트에게 위임합니다.
직접 코드를 작성하거나 파일을 수정하지 않습니다.
 
## 작업 분해 원칙
1. 요청을 독립적인 기능 단위로 분리
2. 각 기능을 담당할 피처 리드 에이전트를 선택
3. 피처 리드에게 명확한 인터페이스 계약(입출력)을 포함한 지시 전달
4. 결과를 통합하고 충돌 시 조율
 
## 허용된 작업
- 파일 읽기 (전체 범위, 탐색 목적)
- 피처 리드 에이전트 스폰
- 결과 통합 리포트 작성
 
## 절대 금지 사항
- 직접 파일 수정/삭제
- 외부 API 직접 호출
- DB 접근
- 서브에이전트 결과를 컨텍스트에 전체 저장 (요약만 수신)
 
## 컨텍스트 관리 규칙
- 서브에이전트 스폰 시 필요한 정보만 전달 (Progressive Disclosure)
- 서브에이전트 탐색 이력은 컨텍스트에 포함하지 않음
- 각 피처 리드의 최종 요약만 집계

피처 리드 에이전트 AGENTS.md는 오케스트레이터보다 좁은 범위에서 조율 역할을 담당합니다:

markdown

# Feature Lead Agent: Auth
 
## 역할
사용자 인증 기능 구현을 조율합니다.
프론트엔드 전문가와 API 전문가를 스폰하고 결과를 통합합니다.
 
## 담당 범위
- src/components/auth/ (프론트엔드)
- src/modules/auth/ (백엔드 API)
 
## 허용된 작업
- 담당 범위 파일 읽기
- 프론트엔드 전문가, API 전문가 스폰
- 인터페이스 계약 검증 (입출력 타입 일치 여부)
 
## 절대 금지 사항
- 담당 범위 외 파일 수정
- DB 스키마 직접 접근
- 다른 피처 리드 영역 간섭

장단점 분석

장점

항목	내용
클린 컨텍스트	서브에이전트 격리로 오케스트레이터 컨텍스트 오염 방지, 각 에이전트가 단일 책임에만 집중
병렬 실행	독립적인 서브태스크 동시 실행으로 전체 처리 시간 단축
명확한 감사 추적	각 에이전트가 단일 역할을 가지므로 각 단계 출력이 명확하고 검증 가능
최소 권한 원칙	각 에이전트에게 필요한 권한만 부여해 보안 위협 표면 축소
모듈형 재사용	계층형 AGENTS.md 구조로 규칙 참조·오버라이드, 중복 제거

단점 및 주의사항

항목	내용	대응 방안
토큰 비용 급증	멀티 에이전트는 단일 에이전트 대비 4~15배 토큰 소모	Progressive Disclosure로 필요한 컨텍스트만 로딩
AGENTS.md 비대화	150~200줄 초과 시 성능 저하, LLM 생성 AGENTS.md는 성공률 저하·비용 증가 유발	파일을 짧고 명확하게 유지, 직접 작성 권장
컨텍스트 로트	과도한 컨텍스트가 출력 품질 저하 유발	단계적 컨텍스트 로딩, 불필요한 중간 결과 배제
중첩 제한	일부 환경에서 서브에이전트가 다른 서브에이전트를 직접 스폰 불가	오케스트레이터가 모든 스폰을 중앙 관리하도록 설계
핸드오프 가드레일 공백	OpenAI Agents SDK에서 핸드오프 호출 자체에 도구 가드레일 미적용	핸드오프 전후 입출력 검증 로직 별도 추가
규칙 충돌	계층형 AGENTS.md에서 상위·하위 파일 간 규칙 충돌 시 행동 예측 불가	명시적 우선순위 규칙 작성 ("이 파일의 규칙이 루트보다 우선")
단일 장애점	오케스트레이터 장애 시 전체 시스템 중단	오케스트레이터 상태를 외부에 주기적 저장, 재시작 전략 설계

실무에서 가장 흔한 실수

AGENTS.md를 너무 상세하게 작성하기: "더 많은 규칙 = 더 좋은 결과"라는 직관과 달리, AGENTS.md가 길수록 오히려 성능이 저하됩니다. 연구에 따르면 LLM이 자동 생성한 AGENTS.md는 작업 성공률을 떨어뜨리고 비용을 증가시킵니다. 핵심 규칙만 간결하게 담고 직접 손으로 작성하는 것을 권장합니다.
오케스트레이터에게 너무 많은 일 맡기기: 오케스트레이터가 직접 파일을 탐색하고 코드를 작성하기 시작하면 컨텍스트가 금방 차오르고 서브에이전트에 위임할 여력이 없어집니다. 오케스트레이터는 "지휘자" 역할에만 집중하고 실무는 서브에이전트에 위임하는 것을 권장합니다.
권한 설계를 나중으로 미루기: "일단 작동하게 만들고 나중에 권한 제한하자"는 접근은 실제로 잘 작동하지 않습니다. 처음부터 각 에이전트의 허용·금지 목록을 명시해두면 디버깅할 때 훨씬 편하고, 의도치 않은 파일 수정이나 권한 남용 사고를 예방할 수 있습니다.

마치며

지금 바로 시작해볼 수 있는 3단계:

루트 파일 생성: 기존 프로젝트 루트에 /AGENTS.md 파일을 만들고, 기술 스택·아키텍처 원칙·전역 금지 사항 세 가지만 50줄 이내로 작성해볼 수 있습니다. Claude Code나 Cursor 같은 도구를 쓰고 있다면 파일을 만드는 것만으로 바로 인식됩니다.
역할 파일 작성: 반복적으로 맡기는 작업(코드 리뷰, 테스트 실행 등)을 하나 골라 /agents/[역할명].md를 작성해보시면 좋습니다. "허용된 작업"과 "절대 금지 사항" 두 섹션만 있어도 충분히 시작할 수 있습니다.
컨텍스트 관리 규칙 추가: 오케스트레이터 에이전트의 AGENTS.md에 "완료 시 서브에이전트 탐색 이력 없이 요약만 반환" 규칙을 추가해보시면, 컨텍스트 효율이 눈에 띄게 달라지는 것을 확인해볼 수 있습니다.

다음 글: 이 글에서 다룬 에이전트 간 역할 경계를 프로토콜 레벨에서 구현하려면 결국 표준 선택의 기로에 서게 됩니다 — MCP(Model Context Protocol)와 A2A(Agent-to-Agent) 프로토콜의 차이점, 그리고 두 표준을 어떻게 조합할 것인지를 다뤄볼 예정입니다.

핵심 개념

AGENTS.md — 에이전트를 위한 README

오케스트레이터-워커 패턴

컨텍스트 분리 — 왜 중요한가

역할별 권한 위임 패턴

실전 적용

예시 1: 계층형 AGENTS.md 디렉터리 구조 설계

예시 2: 역할별 권한 분리 AGENTS.md 작성

예시 3: 계층적 오케스트레이션 설계 (3계층)

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

핵심 개념

AGENTS.md — 에이전트를 위한 README

오케스트레이터-워커 패턴

컨텍스트 분리 — 왜 중요한가

역할별 권한 위임 패턴

실전 적용

예시 1: 계층형 AGENTS.md 디렉터리 구조 설계

예시 2: 역할별 권한 분리 AGENTS.md 작성

예시 3: 계층적 오케스트레이션 설계 (3계층)

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

추천 포스트

Andrej Karpathy의 바이브 코딩 전환기 — CLAUDE.md로 LLM 에이전트 행동 교정하는 법

MCP 프롬프트 인젝션 완전 분석 — 툴 포이즈닝 공격부터 실전 방어까지

MCP 멀티에이전트 파이프라인 보안: 프롬프트 인젝션 전파를 차단하는 신뢰 체인 설계 패턴 5가지

AGENTS.md로 Claude Code · 코딩 에이전트 행동 제어하기: Always / Ask first / Never 3계층 컨텍스트 엔지니어링 실전 가이드

AGENTS.md 동기화 자동화: PR 템플릿과 pre-commit 훅으로 컨텍스트 로트 잡는 법

AGENTS.md vs CLAUDE.md — 드리프트를 막는 단일 소스 전략과 심링크 동기화 실전 가이드