에이전트 관리 가이드

ai-rules sync 시스템으로 `.claude/agents/` 에이전트 파일을 중앙 관리하고 프로젝트별로 배포합니다.

root docs/agents-guide.md

ai-rules sync 시스템으로 .claude/agents/ 에이전트 파일을 중앙 관리하고 프로젝트별로 배포합니다.

개념

agents/                ← base 에이전트 (범용 뼈대, 모든 프로젝트 공통)
agents-ext/{project}/  ← 프로젝트별 확장 디렉토리 (base body 끝에 append)
profiles/*.yaml        ← 프로파일에서 조합 방식 지정
output/{project}/.claude/agents/  ← sync 결과물

base + extension append 패턴

CLAUDE.md의 core/ + extensions/ 패턴을 재활용합니다.

base (agents/): YAML frontmatter + 범용 마크다운 body
extension (agents-ext/{project}/): 순수 마크다운 (frontmatter 없음), base body 끝에 append
frontmatter는 base에서만 정의 — extension이 tools를 변조할 수 없음 (보안)

현재 에이전트 목록

범용 에이전트 (base 그대로 사용)

에이전트	역할	도구
`planner`	작업 계획, 작업 의도 확인, 백로그 관리	Read, Glob, Grep, Bash
`architect`	작업 의도→DESIGN.md 설계, API/DB 매트릭스	Read, Glob, Grep, Bash
`orchestrator`	파이프라인 게이트 관리, 에이전트 디스패치	Read, Glob, Grep, Bash
`security`	STRIDE 기반 보안 감사	Read, Glob, Grep, Bash
`qa`	테스트 작성/실행, FAILURE_LOG 관리	Read, Edit, Write, Glob, Grep, Bash

커스터마이징 가능 에이전트 (base + extension)

에이전트	역할	확장 예시
`builder`	코드 구현, 기능 개발, 버그 수정	`agents-ext/aitem/builder.md` (디자인 토큰 규칙)
`reviewer`	코드 리뷰, PR 체크리스트	`agents-ext/aitem/reviewer.md` (디자인 토큰 체크리스트)
`designer`	UI/UX 설계, 디자인 토큰 관리	`agents-ext/aitem/designer.md` (토큰 체계, 폰트 규칙)

파일 형식

base 에이전트 (`agents/*.md`)

YAML frontmatter + 마크다운 body:

---
name: builder
description: >
  코드 구현, 기능 개발, 버그 수정 전문.
  INTENT.md/DESIGN.md 기반으로 구현한다.
tools: [Read, Edit, Write, Glob, Grep, Bash]
---

# Builder Agent — 코드 구현 전문

## 역할
코드 구현, 기능 개발, 버그 수정을 담당하는 에이전트.
...

frontmatter 필수 필드:

name — 에이전트 식별자
description — 역할 설명
tools — 사용 가능한 도구 목록 (Claude Code가 참조)

extension (`agents-ext/{project}/*.md`)

순수 마크다운, frontmatter 없음:

### AITEM 디자인 토큰 준수 규칙

UI 코드 작성 시 반드시 `docs/design/DESIGN_TOKENS.md` 참조:
- **색상**: CSS 변수만 사용, 하드코딩 금지
- **간격**: Tailwind 표준 스케일만 사용
...

프로파일 설정

profiles/*.yaml의 agents 섹션:

agents:
  enabled: true          # false면 에이전트 파일 생성 안 함
  include:
    - planner            # string → base 그대로 복사
    - builder:           # object → base + extensions 합성
        extensions: [builder]  # → agents-ext/{project}/builder.md
  overrides:             # 인라인 추가 (3줄 이하, 선택사항)
    planner: |
      추가 내용...

include 형식

형식	예시	결과
string	`- planner`	`agents/planner.md` 그대로
object	`- builder: {extensions: [builder]}`	base body + `agents-ext/{project}/builder.md` append

overrides

3줄 이하의 짧은 추가 내용은 프로파일 YAML에 인라인으로 작성 가능. 길면 agents-ext/{project}/에 파일로 분리.

프로젝트별 구성 예시

AITEM (풀 에이전트 8개 + 확장 3개)

agents:
  enabled: true
  include:
    - planner
    - architect
    - orchestrator
    - security
    - qa
    - builder:
        extensions: [builder]    # → agents-ext/aitem/builder.md
    - reviewer:
        extensions: [reviewer]   # → agents-ext/aitem/reviewer.md
    - designer:
        extensions: [designer]   # → agents-ext/aitem/designer.md

→ builder/reviewer/designer에 AITEM 디자인 토큰 규칙이 추가됨

prompt-store (기본 에이전트 3개)

agents:
  enabled: true
  include:
    - planner
    - builder
    - reviewer

→ base 에이전트만 사용 (확장 없음)

global (에이전트 비활성화)

agents:
  enabled: false

→ 전역 규칙에는 에이전트 불필요

새 에이전트 추가

1. 범용 에이전트 추가

agents/ 에 .md 파일 생성:

---
name: my-agent
description: 이 에이전트의 역할 설명
tools: [Read, Glob, Grep, Bash]
---

# My Agent

## 역할
...

2. 프로젝트별 확장 추가

agents-ext/{project}/ 에 .md 파일 생성 (frontmatter 없이 순수 마크다운):

### 프로젝트 전용 규칙

- 규칙 1
- 규칙 2

3. 프로파일에 등록

profiles/{project}.yaml:

agents:
  enabled: true
  include:
    - my-agent                     # base만
    - my-agent:                    # base + extension
        extensions: [my-agent]     # → agents-ext/{project}/my-agent.md

4. 검증 & 배포

# 검증 (참조 누락, frontmatter 오류 체크)
npm run validate

# output/ 생성
npm run sync

# 실제 프로젝트에 적용
npm run sync:apply

검증 항목 (`validate.mjs`)

검증	설명
frontmatter 검증	`name`, `description` 필수
include 참조 확인	프로파일에서 참조한 base 에이전트가 `agents/`에 존재하는지
extensions 참조 확인	프로파일에서 참조한 확장이 `agents-ext/{project}/`에 존재하는지
orphan 확인	`agents-ext/{project}/`에 있지만 프로파일에서 참조 안 하는 파일 경고

sync 처리 흐름

1. loadAgents('agents/')
   → { planner: { frontmatter, body }, builder: { frontmatter, body }, ... }

2. loadBlocks('agents-ext/{project}/')
   → { 'builder': '### AITEM 디자인 토큰...', ... }

3. assembleAgents(profile, baseAgents, projectExtBlocks)
   → include 목록 순회
   → string이면 base 그대로
   → object이면 base body + extension append
   → overrides 있으면 추가 append
   → frontmatter + body 재조합

4. output/{project}/.claude/agents/{name}.md 에 기록

5. --apply 시 target_path/.claude/agents/ 에 복사

주의사항

base 에이전트 수정 시: 해당 에이전트를 사용하는 모든 프로젝트에 영향 → npm run sync:apply 필요
extension은 append only: base body 끝에 추가됨 (중간 삽입이나 기존 내용 수정 불가)
frontmatter 변조 불가: extension에서 tools를 바꿀 수 없음 (보안)
adapter 미사용: 에이전트는 Claude Code 전용이므로 adapter를 거치지 않고 sync.mjs에서 직접 처리