YDMmobile / oss

CLAUDE.md는 왜 얇게 유지해야 할까? (지침 문서가 둘이면 생기는 일)

2026-08-13

CLAUDE.md도 있고 AGENTS.md도 있다면, 둘 다 길고 자세하게 쓰는 편이 친절할까요? 처음에는 그래 보입니다. 도구마다 알아듣기 쉬운 문서를 하나씩 주면 될 것 같으니까요. 그런데 두 문서가 같은 빌드 명령, 같은 작업 규칙, 같은 검증 절차를 반복하기 시작하면 친절은 금세 두 개의 정답 후보가 됩니다. 문서가 두 명의 교장 선생님처럼 서로 다른 말을 하기 시작하는 순간이죠 (둘 다 진지해서 더 곤란합니다).

이 문제를 피하는 한 가지 관리 패턴이 얇은 도구별 어댑터입니다. 여기서 어댑터란, 특정 AI 도구가 저장소의 운영 방식을 찾고 따르도록 연결해 주는 짧은 문서입니다. 이 패턴에서는 AGENTS.md 같은 한 문서를 정본 운영 계약으로 정하고, CLAUDE.md는 그 계약을 복제하지 않습니다. 대신 “무엇이 정본인지”, “어떤 문서를 먼저 볼지”, “이 도구에만 필요한 행동은 무엇인지”만 짧게 적습니다.

중요한 전제부터 짚고 갈게요. 이 글은 CLAUDE.md를 없애야 한다거나 모든 저장소에서 낡은 문서라고 말하는 글이 아닙니다. 특정 저장소가 AGENTS.md를 운영 계약으로 선택했을 때, CLAUDE.md가 어떻게 겹치지 않고 역할을 가질 수 있는지를 설명하는 글입니다.

잘못된 생각: 문서가 둘이면 내용을 반씩 나누면 된다

가장 자연스러운 시작은 이런 방식입니다.

AGENTS.md에는 일반 규칙을, CLAUDE.md에는 Claude가 알아야 할 규칙을 적는다.

문제는 “Claude가 알아야 할 규칙”이라는 상자가 너무 쉽게 커진다는 데 있습니다. 처음에는 응답 형식 한 줄만 넣습니다. 다음에는 테스트 명령이 들어갑니다. 그다음에는 린트 규칙, 폴더별 주의사항, 배포 절차까지 따라옵니다. 그러다 보면 두 파일 모두 운영 정책을 설명하고, 언젠가 한쪽만 수정됩니다.

이것이 문서 드리프트입니다. 문서 드리프트는 같은 사실을 담은 문서들이 시간이 지나면서 서로 다른 내용을 말하게 되는 상태를 뜻합니다. 코드가 바뀌어도 복사해 둔 안내문까지 동시에 고치기란 생각보다 어렵습니다. 문서는 얌전히 앉아 있지만, 오래된 명령을 슬쩍 건네는 장난을 합니다.

요리책으로 비유해 볼까요? 주방의 대표 레시피가 한 권 있고, 특정 조리 도구 옆에 그 레시피를 통째로 복사해 둔다고 해 봅시다. 소금 양을 고칠 때 두 책을 모두 바꾸지 않으면 어느 쪽이 최신인지 알 수 없습니다. 도구 옆 메모에는 “이 기기는 예열부터 한다”처럼 그 도구에만 필요한 내용만 남기는 편이 낫습니다. 대표 레시피는 한 권이면 됩니다.

정본 하나와 얇은 어댑터 하나

얇은 어댑터 패턴의 구조는 단순합니다. 운영 정책은 한 문서에 모으고, 도구별 문서는 그 문서를 가리킵니다.

AGENTS.md
  └─ 저장소의 정본 운영 계약

CLAUDE.md
  ├─ AGENTS.md를 먼저 읽으라는 안내
  ├─ 필요한 계획 또는 제품 문서로 가는 포인터
  └─ Claude에만 적용되는 짧은 행동 규칙

여기서 정본 운영 계약은 작업 범위, 검증 방식, 저장소에서 지켜야 할 운영 정책처럼 여러 도구와 사람이 함께 참고할 내용을 한곳에 두는 문서를 말합니다. 한 저장소에 기록된 사례에서는 AGENTS.md가 이 역할을 맡고, CLAUDE.md는 이를 대체하지 않는 얇은 어댑터로 자신을 설명합니다.

CLAUDE.md가 할 수 있는 일은 분명합니다. 예를 들어 먼저 읽을 문서를 알려 주고, 계획 문서나 제품 의도를 담은 문서로 연결할 수 있습니다. 또한 작은 단위로 변경하기, 추측보다 코드나 문서로 확인하기, 간결한 응답 형태처럼 Claude에게만 적용할 행동 규칙을 둘 수 있습니다. 하위 디렉터리에서 작업할 때 가까운 AGENTS.md를 우선 확인하라는 안내도 이런 도구별 행동 규칙에 들어갈 수 있습니다.

반대로 빌드 명령의 전체 목록이나 반복되는 운영 정책을 다시 적는 일은 피합니다. 기록된 사례에서는 특정 폴더의 명령 목록도 그 폴더의 AGENTS.md를 출처로 삼고, 어댑터 문서에는 복제하지 않습니다. 짧은 문서가 비어 보인다고 걱정할 필요는 없습니다. CLAUDE.md는 정책 창고가 아니라 안내 데스크이기 때문입니다.

왜 얇아야 실제로 도움이 될까?

첫째, 규칙의 주소가 하나가 됩니다. 새 운영 규칙이 필요하면 정본 문서에 추가하면 됩니다. “이 내용은 CLAUDE.md에도 써야 하나?”라는 후속 질문이 줄어듭니다. 규칙이 한곳에 있으면 검토할 때도 비교 대상이 줄어듭니다.

둘째, 도구별 문서의 목적이 선명해집니다. CLAUDE.md가 특정 도구의 시작 안내와 행동 차이만 맡으면, 새로 합류한 사람이 읽어도 왜 이 파일이 존재하는지 이해하기 쉽습니다. 운영 정책을 담은 문서와 도구의 진입점을 담은 문서를 구별할 수 있기 때문입니다.

셋째, 변경 비용이 작아집니다. 운영 규칙을 고칠 때 정본 한 곳을 수정하고, 포인터가 여전히 맞는지만 확인하면 됩니다. 복사한 내용을 여러 파일에서 찾는 일은 줄어듭니다. AI도 같은 명령을 서로 다른 두 문서에서 받아 들고 고민할 일이 적어집니다. 파일이 “나는 지침도 하고 색인도 하고 명령 사전도 할게요”라고 욕심내기 시작하면, 그때가 얇게 다듬을 신호일지 모릅니다.

바로 적용하는 작은 기준

문서에 문장을 추가하기 전, 다음 질문을 해 보세요.

  1. 이 규칙은 사람과 여러 도구가 공통으로 지켜야 하나요? 그렇다면 정본 운영 계약에 둡니다.
  2. 이 규칙은 Claude처럼 특정 도구의 응답 방식이나 탐색 행동에만 필요한가요? 그렇다면 CLAUDE.md에 짧게 둡니다.
  3. 이 규칙은 특정 폴더에서만 필요한가요? 그렇다면 그 폴더의 AGENTS.md에 둡니다.
  4. 이미 다른 문서에 같은 내용이 있나요? 그렇다면 한쪽을 다시 쓰기보다, 정본을 가리키는 포인터로 바꿉니다.

이 기준은 문서 개수를 줄이는 방법이 아닙니다. 같은 정책의 복사본 수를 줄이는 방법입니다. 그래서 도구별 문서가 필요한 경우에도 그 존재 이유를 지킬 수 있습니다.

정리: 얇다는 것은 부족하다는 뜻이 아니다

CLAUDE.md를 얇게 유지한다는 말은 정보를 숨기자는 뜻이 아닙니다. 정보의 원본 위치를 분명하게 하고, 도구별 문서에는 그 도구만의 연결과 행동만 남기자는 뜻입니다. 한 문서는 운영 계약을 지키고, 다른 문서는 그 계약으로 가는 길을 알려 줍니다.

당신의 저장소에도 지침 문서가 둘 이상이라면, 오늘 한 번만 확인해 보세요. 두 문서가 같은 명령과 같은 정책을 반복하고 있지는 않은가요? 그렇다면 하나를 정본으로 정하고, 다른 하나는 짧은 어댑터로 다듬어도 됩니다. 문서가 적어서 단순한 것이 아니라, 서로 역할을 빼앗지 않아서 단순한 상태를 만드는 겁니다. 이 정도면 지침 파일들도 각자 자기 자리에서 꽤 의젓하게 일할 수 있겠죠.