Claude Code, Codex, Antigravity CLI(구 Gemini CLI) 등의 AI 코딩 에이전트를 사용하다 보면, 각 도구용 '규칙 파일(rule file)'을 어떻게 관리할지 고민하게 됩니다.

예를 들어 다음과 같은 파일들입니다.

CLAUDE.md ← Claude Code
AGENTS.md ← Codex / Cursor / Copilot 외 다수
GEMINI.md ← Gemini CLI

"같은 규약을 여러 파일에 복사해 두었다가, 업데이트 누락으로 내용이 어긋나는 문제"

이는 많은 사람이 한 번쯤 겪게 되는 경로입니다.

2026년 현재, 이 문제에 대응하는 방식은 상당히 변했습니다. 본 기사에서는,

애초에 지금은 무엇이 표준인가
파일의 종류(CLAUDE.md / Rules / Skills)를 어떻게 구분해서 사용하는가
"규칙은 많을수록 좋다"는 것이 아니라는 주의점

을 입문자용으로 정리합니다.

이 글을 작성함에 있어, 용어와 현황은 2026년 6월 시점의 각 도구의 공식 문서 및 표준 사양에 근거하여 확인했습니다. AI 도구 주변은 변화가 빠르므로, 실제로 도입하기 전에 최신 공식 정보도 확인하시기 바랍니다.

수년 전에는 도구마다 별도의 지시 파일을 작성해야 했습니다.

하지만 현재는 AGENTS.md라는, 도구를 넘나드는 공통 포맷이 널리 보급되어 있습니다.

AGENTS.md는 "에이전트용 README"라고 불리는 단순한 Markdown 파일입니다. 특별한 스키마는 없습니다. OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Zed, Amp 등 주요 도구의 대부분이 이 파일 하나를 읽습니다.

즉, "같은 내용을 여러 개 복사하는" 문제는 표준화를 통해 대부분 해소되고 있다는 뜻입니다.

여러 도구를 병용하면서 AGENTS.md 이외의 파일(CLAUDE.md 등)도 필요한 경우, 갑자기 복잡한 메커니즘을 만들 필요는 없습니다. 난이도가 낮은 순서대로 몇 가지 정석적인 방법이 있습니다.

AGENTS.md를 본체로 삼고, 다른 파일은 그곳으로의 링크로 만드는 방법입니다.

ln -s AGENTS.md CLAUDE.md

이렇게 하면 CLAUDE.md의 실체는 AGENTS.md가 되어, 편집 지점이 하나가 됩니다. 소~중규모라면 이것만으로도 충분한 경우가 많습니다.

repo/
├ AGENTS.md # 공통 규칙 (본체)
├ CLAUDE.md # → 심볼릭 링크(symbolic link)로 AGENTS.md를 참조

Claude Code는 AGENTS.md를 그대로는 읽지 않습니다 (2026년 중반 시점).

따라서 CLAUDE.md에서 AGENTS.md를 가져오는 "가교" 역할을 하는 한 줄을 작성합니다.

repo/
├ AGENTS.md # 공통 규칙 (본체)
├ CLAUDE.md # → @AGENTS.md 라고만 기재 (AGENTS.md를 전개하여 가져옴)

CLAUDE.md에 이 한 줄을 두면, Claude Code는 읽어들일 때 AGENTS.md의 내용을 전개하여 가져옵니다.

Expo의 공식 문서도 이 "@AGENTS.md 한 줄만 적힌 CLAUDE.md"를 생성하는 구성을 채택하고 있습니다.

방법 1(심볼릭 링크)과의 차이점은, 실체가 있는 단순한 텍스트 파일라는 점입니다.

symlink가 올바르게 복원되는 것은 Mac / Linux이며, Windows에서는 core.symlinks가 비활성화되어 있다면 (기본적으로 자주 비활성화되어 있음) 내용이 "AGENTS.md라는 문자열만 있는 파일"로 변질되어 망가집니다.

에러가 발생하지 않기 때문에 빠지기 쉽습니다.

Mac 사용자는 정상이고 Windows 사용자만 망가지는 형태가 되어, Windows 멤버가 편집하면 망가진 상태가 리포지토리 전체로 전파될 수도 있습니다.

여러 환경에서 개발하는 경우에는 방법 2가 안전하고 비용도 적게 듭니다.

방법 1과 방법 2 모두 "하나의 본문을 재사용"하기 위한 것입니다. 간편함은 방법 1, 환경을 넘나드는 안전성과 Claude 전용 추가 기입의 여지는 방법 2라고 기억해 두면 좋습니다.

도구마다 미묘하게 포맷이 다를 수 있습니다.

• Cursor의 .cursor/rules/

• Copilot의 .github/copilot-instructions.md

• Cline의 .clinerules

등등…

이러한 경우에는 하나의 원본 파일로부터 각 도구용 파일을 생성하는 도구가 유용합니다. 대표적인 것이 rulesync입니다.

npm install -g rulesync
rulesync init # .rulesync/ 에 원본 규칙을 준비
# .rulesync/rules/ に 규칙을 작성
...

.rulesync/를 "유일한 정답 파일(Single Source of Truth)"로 삼고, CLAUDE.md나 .cursor/rules/ 등을 자동 생성하는 발상입니다. 기존의 CLAUDE.md로부터 역으로 가져오는 (import) 기능도 있습니다.

포인트: 본 기사의 소재가 되기 쉬운 "자체 제작 참조 레이어"는 이미 이러한 도구들이 구현하고 있습니다. 바퀴를 재발명하기 전에, 먼저 기존 도구를 검토해 보는 것도 좋을 것입니다.

여기까지는 지시 파일 (CLAUDE.md / AGENTS.md)에 대한 이야기였지만, Skill에도 완전히 동일한 문제가 발생합니다.

Skill 파일은 어떤 도구에서도 SKILL.md (대문자)로 공통되지만, 위치만 도구마다 다르기 때문에 그대로 두면 이중 관리 상태가 됩니다.

repo/
├ .agents/skills/
│ └ commit/SKILL.md # Codex / Antigravity 등을 위해 SKILL.md 가 필요
...

내용은 동일한 SKILL.md인데 디렉토리만 나누어져 있는—CLAUDE.md / AGENTS.md와 같은 구조입니다.

대처법도 지시 파일과 마찬가지로, 수동으로 복사하지 않는 것이 철칙입니다. 다만 사용할 수 있는 방법은 조금 다릅니다.

• 심볼릭 링크 (방법 1): SKILL.md를 하나 준비하고, 각 도구의 스킬 디렉토리로 링크를 겁니다. Windows / WSL / CI 환경에서 깨질 수 있다는 점은 방법 1과 동일한 주의가 필요합니다.
• import (방법 2)는 사용할 수 없습니다: @AGENTS.md와 같은 "한 줄로 가져오기" 표기법은 지시 파일 전용이며, Skill에는 대응하지 않습니다. Skill은 파일의 위치를 통해 발견되는 메커니즘이기 때문입니다.

import는 사용할 수 없지만, Claude 측에 스텁 (stub) SKILL.md를 두고, 그 본문에서 .agents 하위의 실체를 참조하게 하는 방법이 있습니다. 본체(절차)는 .agents/skills/에 하나만 두고, Claude 측은 참조만 수행합니다.

---
name: commit
description: 변경 파일을 커밋한다. ignore 대상 파일은 제외한다.
...

repo/
├ .agents/skills/
│ ├ commit/SKILL.md # 커밋 스킬의 실체 (유지보수는 여기서만 수행)
...

주의: 참조 경로 (위치: .agents/skills/...)는 반드시 실체 디렉토리 이름과 일치시켜야 합니다. 어긋나면 제안(suggest)에는 나타나더라도 본체를 읽지 못해 헛스윙하게 됩니다. 또한 description을 실제 문장으로 작성해 두면 Claude의 자동 실행이 작동합니다 ( /commit 이라고 명시적으로 입력하는 운용 방식이라면 생략해도 작동합니다).

이 부분이 입문자가 가장 혼란스러워하기 쉬운 지점입니다.

"공통 규칙을 스킬로 묶는다"라고 적힌 기사를 자주 볼 수 있지만, Claude Code에서의 "Skills"는 규약을 정리한 Markdown을 의미하는 것이 아닙니다.

현재의 Claude Code에는 목적이 다른 3가지 레이어가 있습니다.

대략적으로 말하자면,

• CLAUDE.md / AGENTS.md 및 Rules는 「형용사」… 프로젝트가 어떠한 것인지를 설명합니다.
• Skills는 「동사」… 에이전트가 무엇을 할 수 있는지 (절차)를 정의합니다.

코딩 규약이나 리뷰 방침과 같이 "항상 지키게 하고 싶은 규칙"은 Skills가 아니라 CLAUDE.md 또는 Rules에 두는 것이 올바른 구분법입니다.

.claude/rules/에 Markdown을 두고, 프론트매터 (Frontmatter)로 대상 경로를 지정하면, 해당 파일에 접근했을 때만 그 규칙이 로드됩니다.

---
paths:
- "src/frontend/**"
...

이를 통해 백엔드 작업 중에 프론트엔드 규약을 읽어오는 것과 같은 낭비를 피할 수 있습니다 (프론트매터를 붙이지 않으면 CLAUDE.md와 마찬가지로 매번 읽어옵니다).

SKILL.md는 YAML 프론트매터 (name과 description)로 시작하는 Markdown입니다.

---
name: deploy-pipeline
description: 운영 환경 배포 절차. 릴리스나 배포를 요청받았을 때 사용함.
...

Skills의 핵심은 실행 시 로드 (Runtime loading)입니다.

• 기동 시: 모든 Skill의 name과 description만 로드됩니다 (가벼움)
• 관련된다고 판단될 때: 해당 SKILL.md의 본문이 읽힙니다
• 더 상세한 정보가 필요할 때: 동봉된 참조 파일이나 스크립트가 읽힙니다

이 메커니즘 덕분에 Skill을 많이 넣어도 컨텍스트 (Context)를 압박하지 않습니다. 게다가 SKILL.md의 사양은 도구를 넘나드는 표준이 되어가고 있으며, Cursor나 Copilot, Codex에서도 재사용할 수 있는 방향으로 나아가고 있습니다.

요약하자면,

"규약 → CLAUDE.md / Rules", "절차·능력 → Skills"입니다. 기사에서 『규약을 스킬로 묶는다』라고 쓰면, 독자가 공식 Skills 사양 (프론트매터 필수·호출형)과 맞닥뜨려 혼란을 겪을 수 있으므로 주의해야 합니다.

지금까지 "공통화하여 재사용하자"는 이야기를 해왔지만, 반대 방향의 지견도 있습니다.

ETH Zurich의 연구 그룹은 실제 코딩 태스크에서 컨텍스트 파일 ( AGENTS.md와 같은 지시 파일)의 효과를 검증했습니다 (AGENTbench). 결과는 직관과 반대되는 것이었는데, 컨텍스트 파일은 에이전트의 단계(Steps)와 비용을 일관되게 증가시키는 반면, 최종적인 성과 (패치의 품질)를 개선하지는 못했다는 것이었습니다. 지시에 따라 테스트를 불필요하게 실행하거나 파일을 너무 많이 읽게 되어, 오히려 우회하게 된다는 분석입니다.

연구 측의 권장 사항은 심플합니다. LLM이 자동 생성한 지시 파일은 생략할 것, 인간이 작성하는 지시는 추론으로 얻을 수 없는 정보 (고유한 도구 이름, 커스텀 빌드 명령 등)로 한정할 것이었습니다.

「집약·자산화」 자체를 부정하는 것은 아니지만, 규약을 추가한다고 해서 에이전트가 똑똑해지는 것은 아니다라는 중요한 제동 장치입니다. 공통화의 목적은 「양을 늘리는 것」이 아니라,

• 한 곳에서 관리하여 차이를 없애는 것
• 각 태스크에 필요한 것만 읽게 하는 것 (Rules의 경로 한정, Skills의 실행 시 로드)
• 쓰지 않아도 알 수 있는 것은 쓰지 않는 것

이라고 의식하면 설계가 흔들리지 않습니다.

2026년 시점의 메타 패턴으로서 짚고 넘어가야 할 점은 다음과 같습니다.

• @AGENTS.md를 공통 표준으로 삼는다. 우선 이것을 중심으로 둔다. 여러 파일이 필요하다면 심볼릭 링크, AGENTS.md의 import, rulesync 등의 생성 도구를 통해 일원화한다.
• CLAUDE.md / Rules / Skills를 혼동하지 않는다. 규약은 CLAUDE.md 또는 Rules (경로 한정), 절차·능력은 Skills (호출형·실행 시 로드)이다.
• 규칙은 최소한으로, 필요할 때만. 집약의 목적은 차이를 없애는 것이지 양을 늘리는 것이 아니다. 쓰지 않아도 알 수 있는 것은 쓰지 않는다.

AI 코딩 도구는 앞으로도 늘어나거나 교체될 것입니다 (Gemini CLI에서 Antigravity CLI로의 이행이 그 좋은 예입니다).

그렇기 때문에, 도구마다 설정을 늘리는 것이 아니라, 표준(AGENTS.md)과 적절한 레이어링 (Layering)을 중심에 두어야 도구가 바뀌더라도 규칙 자산을 유연하게 유지할 수 있습니다.