팀 문서화 문화 만들기
에이전트 지침, Skill, Plugin, MCP를 운영하는 팀 거버넌스
핵심 요약
- 에이전트 지침·Skill·Plugin·MCP가 늘면 문서화는 문화가 아니라 권한과 책임의 문제가 됩니다.
- 표면마다 owner·리뷰어·변경 위험을 정하고, 변경 정책에 누구의 리뷰가 필요한지 명시합니다.
- 문서화 ROI는 벤치마크 숫자가 아니라 재작업률·온보딩 속도·MTTR 같은 팀 자체 baseline으로 측정합니다.
- Phase 1(지침 원본 정리)→Phase 4(Plugin/거버넌스 확산) 4단계로 점진 도입합니다.
- Big Bang 전환·도구 먼저·규칙 누적·Plugin 남발 같은 안티패턴을 피하고 owner와 review policy를 먼저 둡니다.
도구보다 운영 체계가 먼저입니다.
AGENTS.md, CLAUDE.md, Skills, Plugins, MCP 서버가 늘어나면 문서화는 문화 문제가 아니라 권한과 책임의 문제가 됩니다.
이 장은 AI 시대의 문서화 문화를 "문서 많이 쓰기"가 아니라 "에이전트가 따르는 지침을 안전하게 운영하기"로 봅니다.
| 표면 | 소유자 | 리뷰어 | 변경 위험 |
|---|
AGENTS.md | repo owner | tech lead | 높음. 모든 에이전트 작업에 영향 |
CLAUDE.md | repo owner + Claude Code 사용자 | tech lead | 중간. Claude Code 세션에 영향 |
.claude/rules/ | 영역별 owner | 영역 담당자 | 중간. 특정 경로에 영향 |
.agents/skills/** | workflow owner | 도메인 owner | 중간~높음. 반복 절차에 영향 |
| Plugin | platform/enablement team | security + platform | 높음. 여러 팀에 배포 |
| MCP 서버 | platform/security owner | security + data owner | 높음. 외부 시스템 접근 |
| API docs/OpenAPI | API owner | consumer 대표 | 높음. SDK/tool 생성에 영향 |
| KB/RAG 색인 | docs/platform owner | domain owner | 중간. 답변 품질에 영향 |
| 문서 유형 | 필수 포맷 | 필수 필드 |
|---|
| 프로젝트 규칙 | AGENTS.md, CLAUDE.md | 명령어, 위치 안내, 검증, 금지사항 |
| API 문서 | OpenAPI + Markdown | operationId, schema, auth, error, diff |
| Skill | SKILL.md + supporting files | name, description, 사용 조건, 절차, 출력 |
| Plugin | .codex-plugin/plugin.json | version, description, skills/MCP/apps, 권한 |
| MCP 서버 | server config + tool/resource docs | scope, tool annotations, approval policy |
| ADR | MADR 계열 구조 | status, date, decision, alternatives |
| 런북 | 조건-행동-확인-승인 | trigger, mode, rollback, escalation |
| KB 문서 | atomic + frontmatter | id, owner, status, updated, review_after |
## Agent Documentation Change Policy
- `AGENTS.md` 변경: tech lead 리뷰 필수
- `CLAUDE.md` 변경: repo owner 리뷰 필수
- 하위 rules 변경: 해당 경로 owner 리뷰 필수
- Skill 변경: workflow owner + 사용자 1명 리뷰
- Plugin 변경: platform owner + security 리뷰
- MCP Tool 추가: data owner + security 리뷰
- destructive Tool 추가: 별도 change approval 필요
- OpenAPI breaking change: consumer 영향 분석과 migration note 필요
| 변경 유형 | 함께 확인할 문서 |
|---|
| API route 변경 | OpenAPI, API Markdown, MCP Tool schema |
| 인증/권한 변경 | AGENTS.md, runbook, security guide |
| 배포/운영 변경 | runbook, incident Skill, monitoring docs |
| 반복 작업 자동화 | Skill 또는 Plugin |
| 외부 시스템 연동 | MCP server docs, scope, approval policy |
| 데이터/PII 처리 변경 | KB, security docs, data classification |
| 도구 | AI 통합 | 장점 | 주의 |
|---|
| Fumadocs/MDX | Git, MDX, 빌드 검증 | 코드와 함께 리뷰 가능 | 비개발자 작성 경험 보완 필요 |
| Docusaurus | MDX, 검색 플러그인 | 생태계 풍부 | 문서 구조 discipline 필요 |
| GitBook | WYSIWYG, 협업 | 비개발자 친화적 | Git/source of truth 정책 필요 |
| Confluence/Notion | API/RAG 연동 | 조직 내 채택 쉬움 | atomic 문서와 export 품질 관리 필요 |
| 필요 | 선택 |
|---|
| 모든 작업에서 읽을 짧은 규칙 | AGENTS.md |
| Claude Code 전용 규칙 | CLAUDE.md, .claude/rules/ |
| 반복 절차 | Skill |
| 팀 배포 | Plugin |
| 외부 시스템/문서 조회 | MCP Resource |
| 외부 동작 실행 | MCP Tool |
문서화 ROI는 벤치마크 숫자로 설득하지 말고 팀의 실제 작업에서 측정합니다.
| 지표 | 측정 방법 |
|---|
| 에이전트 재작업률 | AI 생성 PR의 수정 코멘트 수, 재시도 횟수 |
| 온보딩 속도 | 첫 PR 머지까지 걸린 기간 |
| 운영 대응 | 런북 참조 장애의 MTTR |
| API 품질 | OpenAPI diff에서 잡힌 breaking change 수 |
| 문서 freshness | review_after 초과 문서 수 |
| 보안 | 승인 없는 destructive action 시도 차단 수 |
- 도입 전 2주간 baseline을 잡습니다.
AGENTS.md와 핵심 Skill을 도입합니다.- 같은 유형의 작업 5~10개를 비교합니다.
- 개선이 확인된 항목만 표준으로 승격합니다.
- 효과가 없는 규칙은 제거합니다.
- repo root
AGENTS.md를 공통 원본으로 지정
CLAUDE.md는 @AGENTS.md import 또는 명확한 분리- 중복된
.cursorrules, .windsurfrules는 호환 레이어로 낮춤
- 검증 명령과 금지사항부터 정리
- API 문서를 OpenAPI + Markdown으로 분리
- 런북을 Diagnose/Recommend/Act 모드로 재작성
- KB에
id, status, owner, review_after 추가
llms.txt와 RAG 색인 링크 검증
- 반복 절차를 Skill로 분리
- MCP Resource와 Tool의 scope, annotation, approval policy 문서화
- 에이전트 smoke test를 릴리스 체크에 포함
- freshness 리포트 자동화
- 안정화된 Skill과 MCP 설정만 Plugin으로 승격
- Plugin 배포 전 security review
- 팀별 owner와 sunset 정책 지정
- 월간 지침/Skill/Plugin 정리
| 안티패턴 | 문제 | 대안 |
|---|
| Big Bang 전환 | 모든 문서를 한 번에 바꾸다 중단 | 지침 원본부터 정리 |
| 도구 먼저 | 도구는 생겼지만 책임자가 없음 | owner와 review policy 먼저 |
| 규칙 누적 | AGENTS.md가 긴 위키가 됨 | 긴 절차는 Skill/MCP로 분리 |
| Plugin 남발 | 실험 절차가 여러 팀에 배포 | repo skill에서 검증 후 승격 |
| 권한 불명확 | Tool이 과도한 권한으로 실행 | least privilege, approval, audit |
| 숫자 과장 | ROI 신뢰 하락 | baseline과 팀 자체 측정 |
| 항목 | 레벨 1 | 레벨 2 | 레벨 3 | 레벨 4 |
|---|
| 프로젝트 규칙 | README만 | AGENTS.md 있음 | 중복 제거 | smoke test |
| Claude Code | 없음 | CLAUDE.md 있음 | @import/rules 사용 | path-scoped governance |
| API 문서 | 산문형 | OpenAPI 있음 | diff/contract test | MCP Tool schema 연동 |
| 런북 | 위키 산재 | 구조화 | 권한 모드 분리 | incident Skill 연동 |
| KB | 긴 페이지 | atomic/frontmatter | RAG eval | MCP Resource freshness |
| Skill | 없음 | 개인/실험 | repo skill | Plugin 승격 정책 |
| 보안 | 수동 주의 | checklist | approval policy | audit/reporting |
| 항목 | 확인 |
|---|
| 에이전트 지침 표면별 owner가 있는가 | ☐ |
AGENTS.md와 CLAUDE.md 중복/충돌을 정기 검토하는가 | ☐ |
| Skill과 Plugin 승격 기준이 있는가 | ☐ |
| MCP Tool 추가 시 data/security owner 리뷰가 있는가 | ☐ |
| destructive action에 승인 정책이 있는가 | ☐ |
| 문서화 ROI를 팀 내부 baseline으로 측정하는가 | ☐ |
| stale 규칙과 미사용 Skill을 제거하는 월간 정리 루틴이 있는가 | ☐ |