agents.pool.yml 스키마

.relay/agents.pool.yml은 동적 팀 구성에 쓰이는 에이전트 풀을 정의합니다. /relay:relay 세션은 매번 이 풀에서 태스크에 맞는 팀을 선택합니다.

최상위 구조

language: string # 선택 — 모든 에이전트의 기본 언어
shared_blocks: # 선택 — 재사용 가능한 텍스트 블록
  { block_name }: string
review_checklist: string # 선택 — 모든 에이전트에 적용되는 기본 리뷰 체크리스트
agents:
  { agentId }:
    # 에이전트 설정
    ...

에이전트 스키마

agents:
  { agentId }:
    name: string # 표시 이름 (예: "Frontend Engineer")
    emoji: string # 이모지 아이콘 (예: "💻")
    description: string # 짧은 역할 설명 (팀 선택 화면에 표시)
    tags: [string] # 선택 — 팀 자동 추천에 활용
    disabled: boolean # true면 풀에서 제외 (기본값: false)
    extends: string # 상속할 에이전트 ID
    tools: # 허용할 MCP 툴 목록
      - tool_name
    systemPrompt: string # 에이전트 시스템 프롬프트 (여러 줄 가능)
    language: string # 선택 — 이 에이전트의 언어를 개별 지정
    hooks: # 선택 — 태스크 라이프사이클 훅 (아래 참조)
      before_task: string | [string]
      after_task: string | [string]
    # hooks: false         # 상속된 훅을 명시적으로 끄기 (extends 에이전트 전용)
    validate_prompt: string # 선택 — 태스크 완료 전 주입되는 검증 기준
    review_checklist: string # 선택 — 전역 리뷰 체크리스트를 이 에이전트만 오버라이드

사용 가능한 툴

get_server_info
start_session
send_message
get_messages
create_task
update_task
claim_task
get_all_tasks
post_artifact
get_artifact
request_review
submit_review
read_memory
write_memory
append_memory
list_sessions
get_session_summary
save_session_summary
save_orchestrator_state
get_orchestrator_state
list_agents
list_pool_agents
broadcast_thinking

shared_blocks

최상위에 재사용 가능한 텍스트 블록을 정의하고, 에이전트의 systemPrompt에서 {{block_name}}으로 참조합니다. 여러 에이전트가 같은 지침을 공유할 때 프롬프트 중복을 없앨 수 있습니다.

블록 안의 {agent_id}는 로드 시점에 실제 에이전트 ID로 자동 치환됩니다.

systemPrompt에서 정의되지 않은 블록을 참조하면 (예: {{nonexistent}}), 풀 로더가 로드 타임 에러를 발생시킵니다.

shared_blocks:
  coding_standards: |
    - 프로젝트 스타일 가이드를 따를 것
    - 모든 새 코드에 테스트를 작성할 것
    - 에이전트 {agent_id}는 완료 전 리뷰를 요청할 것

agents:
  fe:
    systemPrompt: |
      You are a Frontend Engineer.
      {{coding_standards}}
  be:
    systemPrompt: |
      You are a Backend Engineer.
      {{coding_standards}}

review_checklist

피어 리뷰를 위한 구조화된 리뷰 기준입니다. 최상위에 review_checklist를 설정하면 모든 에이전트에 기본 기준이 적용됩니다. 개별 에이전트는 자체 review_checklist 필드로 오버라이드할 수 있습니다.

extends 기반 에이전트의 상속 우선순위: 에이전트 자체 값 > base 에이전트 값 > 전역 기본값. review_checklist를 따로 설정하지 않은 extends 에이전트는 base 에이전트의 값을 먼저 상속하고, 없으면 전역 기본값을 사용합니다.

리뷰 체크리스트는 Fix-First 프레임워크를 따릅니다. 리뷰어는 승인 전에 각 기준을 검증하고, 충족하지 못한 항목은 수정을 요청해야 합니다.

review_checklist: |
  - [ ] 코드가 프로젝트 컨벤션을 따르는가
  - [ ] 새 기능에 대한 테스트가 있는가
  - [ ] 보안 취약점이 도입되지 않았는가

agents:
  security:
    review_checklist: |
      - [ ] 하드코딩된 시크릿이 없는가
      - [ ] 모든 엔드포인트에 입력 검증이 있는가
      - [ ] OWASP Top 10 준수 여부

hooks 필드

MCP 서버가 태스크 라이프사이클 이벤트 전후에 자동 실행하는 git-hook 방식의 셸 명령어입니다. 프로젝트 루트에서 실행되며, 0이 아닌 종료 코드는 해당 작업을 차단합니다.

`before_task`

claim_task가 태스크를 원자적으로 클레임하기 전에 실행됩니다. 0이 아닌 종료 코드는 claimed: false를 반환하며, 태스크는 todo 상태로 남습니다 (유령 in_progress 없음).

fe:
  hooks:
    before_task: "bun check:types"

`after_task`

update_task(status: "done") 스토어 기록 후에 실행됩니다. 0이 아닌 종료 코드는 태스크 상태를 in_review로 되돌리고 success: false를 반환합니다.

fe:
  hooks:
    after_task:
      - bunx eslint --fix .
      - bunx prettier --write .
      - bun tsc --noEmit

훅에 주입되는 환경변수

변수	값
`RELAY_AGENT_ID`	훅을 실행하는 에이전트 ID
`RELAY_TASK_ID`	클레임/완료 중인 태스크 ID
`RELAY_SESSION_ID`	현재 세션 ID

타임아웃

훅	기본값
`before_task`	30초
`after_task`	120초

타임아웃 시: SIGTERM → 5초 → SIGKILL.

`hooks: false`로 상속 거부

extends 기반 에이전트는 상속된 훅을 명시적으로 비활성화할 수 있습니다:

agents:
  fe:
    hooks:
      after_task: bun tsc --noEmit
    # ... 나머지 페르소나
  fe2:
    extends: fe
    name: "Frontend Engineer 2"
    hooks: false # fe2는 fe의 모든 것을 상속하되 훅은 제외

extends 패턴

extends로 같은 페르소나의 여러 인스턴스를 다른 ID로 만들 수 있습니다. /relay:relay가 세션 파일을 작성할 때 fe, fe2, fe3 등을 구성하는 데 이 패턴을 사용합니다:

# .relay/session-agents-2026-03-14-001-a3f7.yml
agents:
  fe:
    extends: fe # 풀의 systemPrompt + tools 상속
    name: "Frontend Engineer 1"
  fe2:
    extends: fe
    name: "Frontend Engineer 2"

tags 필드

tags는 /relay:relay가 팀을 자동 추천할 때 활용합니다. 태스크 유형에 맞는 태그를 지정해 두면 스킬이 적합한 에이전트를 제안합니다:

agents:
  be:
    tags: [backend, api, database, node, typescript]
  researcher:
    tags: [research, analysis, writing, synthesis]

전체 예시

language: Korean

shared_blocks:
  collaboration_rules: |
    - 작업 시작 전 반드시 broadcast_thinking 호출
    - 태스크 완료 전 동료에게 리뷰 요청
    - 에이전트 {agent_id}는 세션 종료 시 메모리 업데이트 필수

agents:
  pm:
    name: "Product Manager"
    emoji: "📋"
    description: "요구사항 분석 및 태스크 분배"
    tags: [management, planning, coordination]
    tools:
      - create_task
      - update_task
      - get_all_tasks
      - send_message
      - get_messages
    systemPrompt: |
      You are the Product Manager.
      Break down requirements into tasks and coordinate the team.
      {{collaboration_rules}}

  fe:
    name: "Frontend Engineer"
    emoji: "💻"
    description: "React/TypeScript UI 구현"
    tags: [frontend, react, typescript, ui]
    tools:
      - get_messages
      - claim_task
      - update_task
      - post_artifact
      - send_message
      - request_review
    systemPrompt: |
      You are a Frontend Engineer.
      Implement UI components and create PR artifacts for review.
      {{collaboration_rules}}

  security:
    name: "Security Engineer"
    emoji: "🔐"
    description: "보안 취약점 분석"
    tags: [security, audit, owasp]
    tools:
      - get_messages
      - get_artifact
      - post_artifact
      - send_message
    systemPrompt: |
      You are a security expert.
      Review PRs against the OWASP Top 10.

파일 위치

풀 파일은 우선순위 순으로 검색됩니다:

.relay/agents.pool.yml — 프로젝트 레벨 (우선, git 추적)
agents.pool.yml — 프로젝트 루트 폴백

파일이 없으면 relay가 다음 오류를 반환합니다:

No agent pool configured. Create .relay/agents.pool.yml (see agents.pool.example.yml) or run /relay:relay to auto-generate one.