AGENTS.md Adapter 설계 계획

### 현재 ai-rules agents/ 포맷

목표: Linux Foundation AGENTS.md 표준과 현재 ai-rules agents/ 포맷을 비교하고, adapters/agents-md.mjs를 통해 AGENTS.md를 secondary output으로 생성하는 방법 설계.

---

1. 포맷 비교 분석

현재 ai-rules agents/ 포맷

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

# Builder Agent — 코드 구현 전문
## 역할 / 작업 범위 / 필수 규칙 / 금지 사항 / 실패 프로토콜

특징:

• YAML frontmatter + Markdown body
• Claude Code .claude/agents/ 디렉토리에 배치
• tools 배열로 Claude Code 권한 제어
• 한국어 내용, 프로젝트 특화 규칙 포함

Linux Foundation AGENTS.md 표준 (agentprotocol.ai)

복사# AGENTS.md

## Agents

### builder
- **description**: Code implementation specialist
- **capabilities**: file_read, file_write, shell_exec
- **constraints**:
  - Always run type check before commit
  - No direct push to protected branches
- **triggers**: When INTENT.md exists and design phase is complete

### planner
- **description**: Task analysis and INTENT.md authoring
- **capabilities**: file_read, web_search
- **constraints**:
  - Read-only (no file modifications)

특징:

• 단일 AGENTS.md 파일 (루트 또는 .agents/AGENTS.md)
• 도구 간 공통 포맷 (Cursor, Copilot, Windsurf 등)
• 기능 레벨 capabilities (플랫폼 독립적)
• 일반 영어 (도구 중립)

핵심 차이점

항목	ai-rules 포맷	AGENTS.md 표준
파일 구조	에이전트당 1 파일	단일 AGENTS.md
배치 위치	.claude/agents/	프로젝트 루트 / .agents/
도구 지정	Claude Code 전용 (Read, Edit)	플랫폼 독립 (file_read, shell_exec)
언어	한국어	영어 (표준)
규칙 상세도	매우 상세 (전체 프로토콜)	간결한 constraints 목록
확장성	Claude Code 한정	모든 AI 도구 공통

---

2. adapters/agents-md.mjs 구현 설계

목표

현재 agents/*.md 파일을 파싱하여 표준 AGENTS.md 생성. 기존 포맷은 그대로 유지하고 AGENTS.md는 secondary output.

입력/출력

복사입력: agents/builder.md, agents/planner.md, ... (YAML frontmatter + body)
출력: AGENTS.md (단일 파일, 표준 포맷)

구현 스케치

복사// adapters/agents-md.mjs

/**
 * @param {object[]} agentDefs - 파싱된 에이전트 정의 배열
 *   [{ name, description, tools, body }]
 * @param {object} toolConfig - profiles/*.yaml의 tools.agents-md 설정
 * @param {object} profile - 전체 프로파일
 * @returns {{ path: string, content: string }[]}
 */
export function generate(agentDefs, toolConfig, profile) {
  const outputPath = toolConfig.output || 'AGENTS.md'
  const lang = toolConfig.lang || 'en'  // 표준은 영어

  const sections = agentDefs.map(agent => formatAgent(agent, lang))

  const header = [
    `# AGENTS.md`,
    ``,
    `> Auto-generated by [ai-rules](https://github.com/your-org/ai-rules).`,
    `> Edit source in \`ai-rules/agents/\`.`,
    `> Profile: ${profile.project}`,
    ``,
    `## Project Rules`,
    ``,
    `See \`CLAUDE.md\` or \`.claude/CLAUDE.md\` for full rule set.`,
    `Core constraints apply to all agents:`,
    `- No direct push to main/master/develop`,
    `- No destructive DB operations (migrate reset, DROP TABLE)`,
    `- Type check required before commit`,
    ``,
    `## Agents`,
    ``,
  ].join('\n')

  return [{
    path: outputPath,
    content: header + sections.join('\n\n---\n\n'),
  }]
}

function formatAgent(agent, lang) {
  const capabilities = mapToolsToCapabilities(agent.tools)
  const constraints = extractConstraints(agent.body)

  return [
    `### ${agent.name}`,
    ``,
    `- **description**: ${translateIfNeeded(agent.description, lang)}`,
    `- **capabilities**: ${capabilities.join(', ')}`,
    constraints.length > 0 ? `- **constraints**:\n${constraints.map(c => `  - ${c}`).join('\n')}` : '',
    `- **source**: \`agents/${agent.name}.md\``,
  ].filter(Boolean).join('\n')
}

// Claude Code tools → 플랫폼 독립 capabilities 매핑
function mapToolsToCapabilities(tools) {
  const map = {
    'Read': 'file_read',
    'Edit': 'file_write',
    'Write': 'file_write',
    'Bash': 'shell_exec',
    'Glob': 'file_search',
    'Grep': 'file_search',
    'WebSearch': 'web_search',
    'WebFetch': 'web_fetch',
  }
  const caps = [...new Set((tools || []).map(t => map[t]).filter(Boolean))]
  return caps
}

// body에서 "금지 사항" / "Hard Bans" 섹션을 constraints로 추출
function extractConstraints(body) {
  // 간단 구현: "금지" 또는 "Hard Ban" 섹션의 bullet 추출
  // TODO: 실제 파싱 로직
  return []
}

profiles/*.yaml 설정

복사# profiles/ax-studio-plan.yaml 예시
tools:
  claude-code:
    enabled: true
    output: .claude/CLAUDE.md
  agents-md:
    enabled: true
    output: AGENTS.md          # 프로젝트 루트
    lang: en                   # AGENTS.md 표준은 영어
    include_agents:            # 포함할 에이전트 목록
      - builder
      - planner
      - reviewer
      - qa
      - security

---

3. 다른 AI 도구에서 동일 규칙 사용 전략

Cursor

현재: adapters/cursor.mjs → .cursor/rules/*.mdc 생성 (이미 구현됨) AGENTS.md 추가 시: .cursor/rules/AGENTS.md 또는 프로젝트 루트 AGENTS.md 겸용

Windsurf

현재: adapters/windsurf.mjs 구현됨 (구조 추정) AGENTS.md를 .windsurf/agents/ 또는 루트 AGENTS.md로 배치

GitHub Copilot

Copilot은 .github/copilot-instructions.md 참조. 전략: AGENTS.md + .github/copilot-instructions.md 동시 생성

복사# profiles/*.yaml
tools:
  copilot:
    enabled: true
    output: .github/copilot-instructions.md
    # copilot.mjs adapter가 AGENTS.md와 동일 내용을 Copilot 포맷으로 변환

통합 전략 요약

복사ai-rules/agents/*.md (소스)
         ↓
    sync.mjs
         ↓
  ┌──────────────────────────────────────────┐
  │ claude-code.mjs → .claude/agents/*.md   │ Claude Code
  │ agents-md.mjs  → AGENTS.md             │ 표준 (Cursor, Copilot, Windsurf 등)
  │ cursor.mjs     → .cursor/rules/*.mdc   │ Cursor 전용
  │ copilot.mjs    → .github/copilot...    │ GitHub Copilot 전용
  └──────────────────────────────────────────┘

---

4. 마이그레이션 경로

Phase 1 — agents-md.mjs 기본 구현

• YAML frontmatter 파싱 (이미 sync.mjs에서 처리 중이면 재활용)
• tools → capabilities 매핑 테이블 완성
• description 영어 번역 지원 (수동 translations 필드 추가)

Phase 2 — 제약 조건 추출 자동화

• agent body에서 "금지 사항" 섹션 파싱 → constraints 자동 생성
• 또는 frontmatter에 constraints: 필드를 명시적으로 추가

복사# agents/builder.md frontmatter 확장
---
name: builder
description: >
  코드 구현, 기능 개발, 버그 수정 전문.
description_en: >
  Code implementation, feature development, and bug fixing specialist.
tools: [Read, Edit, Write, Glob, Grep, Bash]
constraints:
  - No direct commit to main/master/develop
  - Type check required before commit
  - No eslint-disable or @ts-ignore
---

Phase 3 — 다른 도구 adapter 추가

• adapters/copilot.mjs 구현
• adapters/windsurf.mjs 에이전트 섹션 추가

현재 포맷 유지 보장

• agents/*.md 포맷 변경 없음 (frontmatter에 선택적 필드 추가만)
• Claude Code 기존 동작 그대로 유지
• AGENTS.md는 sync 시 자동 생성되는 부가 파일

---

5. 검증 기준

AGENTS.md가 올바르게 생성되었는지 확인:

복사# 모든 에이전트가 포함되었는지
grep "^### " AGENTS.md

# capabilities가 비어있지 않은지
grep "capabilities:" AGENTS.md

# 표준 포맷 준수 (source 링크 존재)
grep "source:" AGENTS.md