AI 코딩 에이전트 지침서 최적화 — AGENTS.md 단일화와 온디맨드 스킬 시스템 구축기

요즘 코딩할 때 AI 에이전트 안 쓰시는 분 계신가요? 🤖

저 역시 사이드 프로젝트를 개발하면서 Claude Code를 비롯한 여러 AI 에이전트를 페어 프로그래밍 파트너로 적극 활용하고 있습니다. 복잡한 아키텍처 리팩토링부터 백엔드 연동, 세밀한 UI 작업까지 AI의 도움을 톡톡히 받고 있어요 👍

뾰족하게 세운 머리의 남성이 '정말 고마워!'라고 말하는 예능 방송 장면

그런데 프로젝트가 점점 커질수록 에이전트 지침서를 포함해 다양한 지침서가 늘어나게 되더라고요? 저는 좀 다양하게 만들어서 쓰고 있습니다

📁 my-project/
├── 📄 AGENTS.md      # Codex, Cursor 등 범용 에이전트 지침서 (4KB)
├── 📄 CLAUDE.md      # Claude Code 전용 지침서 (15KB)
└── 📄 DESIGN.md      # 109KB에 달하는 방대한 디자인 계약서

도구마다 지침서 파일이 따로 놀고, 내용은 30% 이상 중복되어 있었습니다. 무엇보다 “간단한 UI 버그 하나 고치는데, AI가 매 턴마다 수만 토큰에 달하는 운영 보안 서약서와 코드 아키텍처나 SQL 쿼리 예산까지 통째로 읽고 있다보니” 토큰 낭비가 좀 신경이 쓰이더라고요? 필요없는 부분까지 항상 컨텍스트로 붙잡고있는거 아닌가..? 요즘은 아닌가..?

오늘은 이 파편화된 지침서들을 어떻게 단일 진실 공급원(SoT)으로 통합하고, 점진적 공개(Progressive Disclosure) 스킬 시스템을 통해 컨텍스트를 최적화했는지 그 과정을 정리해 보겠습니다.

1. 문제의 시작: 파편화와 컨텍스트 낭비

초기에는 Claude Code용으로 CLAUDE.md를 작성했고, 이후 다른 에이전트 도구도 함께 쓰게 되면서 대부분의 도구가 표준으로 읽는 AGENTS.md를 루트에 추가했습니다. Claude Code만 CLAUDE.md를 따로 읽다 보니 같은 내용을 두 군데에 써야 했습니다.

당장은 문제가 아닐수도 있지만 점점 아래와 같은 문제가 생겼습니다:

지침서 동기화 누락 (Rule Drift): 새로운 빌드 명령어나 커밋 컨벤션을 바꿀 때 한쪽에만 적고 다른 쪽은 까먹는 일이 빈번해졌습니다.
복붙의 향연: 빌드 명령어, 네이밍 규칙, 코딩 스타일 등이 두 파일에 고스란히 중복되어 있었습니다.
컨텍스트 인플레이션:
- AGENTS.md + CLAUDE.md를 합치면 17KB(약 4,500 토큰).
- 여기에 DESIGN.md는 무려 109KB(약 28,000 토큰)에 달했습니다.
-> 만약 이 모든 걸 지침서 하나로 합쳐버리면, AI와 대화 한 번 나눌 때마다 프롬프트 캐시가 깨지거나 매 턴 기본 주입 비용으로 수만 토큰이 공중분해 되진 않을까 하는 걱정이 들더라고요 🤔

“버튼 색상 하나 바꾸는데, 백엔드 쿼리 예산과 프로덕션 DB 접근 정책까지 AI가 읽을 필요가 있을까?“

2. 반가운 변화: Claude Code의 AGENTS.md 공식 지원

먼저 가장 큰 걸림돌이었던 “도구별 파일 분리” 문제부터 해결책을 찾았습니다. 최근 Claude Code 릴리즈(v2.1.277, 2026년 9월)부터 AGENTS.md를 프로젝트 기본 지침서로 공식 지원하기 시작했습니다!

CLAUDE.md가 없으면 자동으로 AGENTS.md를 루트 지침서로 인식
Codex, Cursor, Copilot 등 대부분의 에이전트 도구가 이미 쓰고 있던 AGENTS.md 표준에 Claude Code까지 합류

덕분에 더 이상 CLAUDE.md를 따로 유지할 이유가 사라졌습니다. 드.디.어..! 중복된 내용을 걷어내고 CLAUDE.md의 고유한 도메인 지식(아키텍처 레이어 규칙, 서버 제약, Prod 접근 보안)을 AGENTS.md 하나로 완벽히 통합한 뒤, CLAUDE.md를 과감히 삭제했습니다.

3. 핵심 아이디어: 점진적 공개(Progressive Disclosure)

하지만 CLAUDE.md를 AGENTS.md에 그대로 합치니, AGENTS.md 파일 크기만 17KB(137줄)로 무거워졌습니다.

여기서 한 단계 더 나아갔습니다:

점진적 공개 (Progressive Disclosure)란?

모든 세부 규칙을 처음부터 컨텍스트에 쏟아붓지 않고, 평소에는 규칙의 이름과 한 줄 요약(Description)만 가볍게 노출하다가, 에이전트가 특정 도메인 작업을 수행할 때만 해당 전문 문서를 온디맨드로 직접 로드하는 방식입니다.

Claude Code를 비롯한 주요 에이전트 도구의 스킬 시스템이 이 Progressive Disclosure 메커니즘을 지원하는 걸로 알고 있습니다 !

어떻게 분리했나?

지침서를 두 가지 계층으로 나눴습니다:

Core Guidelines (AGENTS.md, ~8KB):
- 모든 대화에서 항상 알아야 하는 최소한의 정보
- 프로젝트 정체성과 핵심 설계 원칙
- 자주 쓰는 빌드/테스트 명령어, 코딩 스타일, 커밋 & PR 컨벤션
- 온디맨드 스킬 카탈로그 (인덱스)
On-Demand Skills (.agents/skills/):
- 특정 상황에서만 필요한 무거운 도메인/보안 규칙들

📁 my-project/
├── 📄 AGENTS.md                           # 항상 로드되는 가벼운 코어 지침 (~8KB)
├── 📄 DESIGN.md                           # 필요할 때만 참조하는 디자인 계약서
├── 📁 .agents/skills/
│   ├── 📁 architecture/SKILL.md           # 레이어 경계, 의존 방향, 모듈 규칙
│   ├── 📁 backend/SKILL.md                # 서버 런타임 제약, 쿼리/성능 예산
│   ├── 📁 prod-access/SKILL.md            # 운영 DB 읽기 스코프, 쓰기 금지, 배포 컨펌
│   └── 📁 design-philosophy/SKILL.md      # UI/UX 철학 큐레이션 가이드
└── 📁 .claude/skills/                     # .agents/skills로 심볼릭 링크 연결

스킬 정의 예시 (`architecture/SKILL.md`)

---
name: architecture-rules
description: >-
  Architectural constraints for this project: layer boundaries, dependency direction,
  module ownership, state/storage rules, and data migration conventions.
  Activate when refactoring, adding new features, editing screens/components, or modifying stores/repositories.
---

# Architecture & Layer Guidelines
(아키텍처 레이어 규칙 및 위반하기 쉬운 세부 제약 사항들...)

에이전트는 대화가 시작될 때 상단 YAML frontmatter의 name과 description만 읽습니다. 그러다 사용자가 “설정 화면 리팩토링하자” 라고 하면, 에이전트 스스로:

“어? 이건 화면/컴포넌트 수정이고 레이어 제약이 걸려있네? architecture-rules 스킬을 읽어야겠다!”

하고 해당 SKILL.md를 열어서 정확한 규칙을 확인합니다. 반면 단순 오타 수정이나 일반 스크립트 작성 시에는 무거운 규칙을 전혀 읽지 않습니다. 예전과 다르게 모델 자체의 성능도 워낙 좋아졌기 때문에 적재적소하게 스킬을 잘 로드하더라고요 👍

4. 도입 후 무엇이 개선되었을까?

① 컨텍스트 윈도우 다이어트 (50% 이상 절감)

기본 주입 지침서 크기: 17KB+ → ~8KB (코어 지침 + 스킬 메타데이터 몇 줄)
디자인 작업이나 백엔드 작업이 아닐 때 불필요하게 낭비되던 토큰 비용을 확실하게 잡았습니다.

차트 로딩 중...

② 모델의 주의집중(Attention)과 준수율 향상

LLM에 한 번에 수십 가지 규칙을 주면, 중간에 적힌 규칙을 무시하는 현상이 종종 일어납니다.
작업을 특정 분야(백엔드, 아키텍처, 디자인)로 좁히고 그 작업에 필요한 스킬만 집중적으로 주입하니, 레이어 의존 방향이나 쿼리 예산 같은 까다로운 제약을 위반하지 않는 확률이 훨씬 높아졌습니다.

③ 단일 진실 공급원(SoT) 확립

CLAUDE.md와 AGENTS.md의 중복이 사라져 문서 유지보수 비용이 0에 수렴하게 되었습니다.
.claude/skills와 .agents/skills를 심볼릭 링크로 연결하여, 어떤 에이전트 도구를 쓰든 완전히 동일한 규칙과 스킬을 공유합니다.

5. 마치며

AI 에이전트와 함께 일하는 규모가 커질수록, “에이전트에게 전달하는 문서의 아키텍처” 역시 소프트웨어 아키텍처만큼이나 중요해진다고 생각합니다.

무작정 하나의 거대한 AGENTS.md에 모든 걸 때려 넣고 계셨다면
혹은 도구마다 설정 파일을 따로 만드느라 싱크 맞추기에 지치셨다면

AGENTS.md를 코어로 삼고, 도메인 규칙을 온디맨드 스킬(Progressive Disclosure)로 분리하는 구조도 나쁘지 않으니 한 번 시도해 보시길 추천합니다! 🚀