긴 규칙 파일이 컨텍스트를 채우고, 짧은 CLAUDE.md와 필요할 때만 불러오는 스킬로 정리되는 그림

규칙 파일을 늘리면 에이전트가 더 똑똑해질 것 같다.

배포는 승인 후에만, 테스트 실패면 원인부터, 문서는 짧게, 주석은 넣지 마, 리뷰 절차는 이렇게, 검증은 저렇게. 한 줄씩 넣을 때는 다 맞는 말처럼 보인다.

그런데 어느 순간 응답이 느려지고, 서로 다른 지시가 부딪히며, 정작 오늘 요청의 핵심을 놓치는 장면이 나온다. 규칙을 처음 만드는 이야기가 아니라, 이미 길어진 CLAUDE.md와 스킬을 줄여야 하는 이유를 본다.

읽고 나면 “더 넣기” 대신 “매 세션에 올릴 말인지, 필요할 때만 펼칠 말인지”로 나눌 기준이 남는다.

규칙을 쌓을수록 똑똑해진다는 착각

처음에는 반복 지시를 파일로 빼는 것만으로도 이득이다. 같은 금지 조건을 세 번째 붙여 넣고 있다면 규칙 파일 후보라는 점은 여전히 맞다.

그다음은 다른 함정이다. 한 번 파일을 쓰기 시작하면 모든 예외, 모든 팀 습관, 모든 “혹시 모를” 절차를 한곳에 모으기 쉽다. 중앙 저장소에 다 넣어야 에이전트가 찾는다는 믿음도 강하다.

그 결과 매 대화 시작마다 올라가는 문장이 불어난다. 코드 스타일 기본값, 배포 절차, 리뷰 체크리스트, 과거 실패 메모, 다른 도구용 설명까지 한 파일에 섞인다. 에이전트는 똑똑해지기보다, 서로 다른 규칙을 먼저 저울질하느라 시간을 쓴다.

공식 쪽에서 먼저 줄인 이유

2026-07-24 Claude Code 팀의 Thariq Shihipar(@trq212) 글과 같은 날 올라온 Claude 블로그 글은, 새 세대 모델용 시스템 프롬프트에서 상당 부분을 줄였다고 설명한다. 공개 글 기준으로는 Claude Code 시스템 프롬프트의 80% 이상을 제거했고, 코딩 평가에서 측정 가능한 손실은 없었다고 적혀 있다. 같은 스레드의 블로그 안내 게시로도 연결된다. 아래 요약은 2026-07-26에 다시 확인한 공개 글 기준이다.

핵심은 “규칙을 더 세게 쓴다”가 아니라 “과한 제약을 풀고 판단에 맡긴다” 쪽이다. 예전에는 최악의 경우를 막으려고 강한 규칙을 넣었지만, 그 규칙이 사용자 요청·스킬·시스템 메시지와 겹치면 모델이 먼저 충돌을 풀어야 한다. 예로 “문서는 적절히 남겨라”와 “주석을 넣지 마라”가 한 요청 안에 같이 들어오는 식이다.

같은 글에서 CLAUDE.md 권고도 분명하다. 가볍게 유지하고, 저장소 목적과 코드만 봐서는 모르는 함정에 토큰을 쓰라는 것이다. 파일 구조만 보면 알 수 있는 설명은 빼라고 한다. 검증처럼 가끔만 필요한 절차는 검증 스킬로 빼고, CLAUDE.md에서는 그 스킬을 가리키면 된다.

Claude Code 공식 모범 사례 문서도 같은 방향을 반복한다. 매 세션에 읽히는 파일에는 넓게 적용되는 말만 두고, 가끔 필요한 도메인 지식·워크플로는 스킬로 둔다. 한 줄마다 “이걸 빼면 Claude가 실수할까?”를 묻고, 아니면 자르라고 한다. 비대해진 CLAUDE.md는 정작 중요한 지시를 무시하게 만든다고 명시한다.

메모리 문서 쪽 권고 숫자도 참고할 만하다. 파일당 대략 200줄 아래를 목표로 하고, 더 길면 경로별 규칙이나 스킬로 나누라고 한다. 정확한 한도는 제품 버전에 따라 달라지므로, 숫자 자체보다 “매 세션 상주 비용”을 의식하는 편이 낫다.

길면 생기는 세 가지 비용

첫 번째는 지시 충돌이다. 시스템 쪽 기본 안내, 팀 규칙, 개인 스킬, 오늘 채팅 요청이 한 컨텍스트에 모인다. 모델이 대체로 의도를 맞히더라도, 겹친 문장을 해석하는 단계가 늘고 답이 느려지거나 애매해지기도 한다.

두 번째는 컨텍스트 오염이다. 커뮤니티에서도 수백 줄짜리 CLAUDE.md에 무거운 워크플로를 겹치면 토큰은 늘고 응답은 느려지며 초점을 잃는다는 경험이 공유된다. (@yanhua1010, 2026-07-25 게시, 2026-07-26 확인.) 설계 의도가 아니라 잡음이 먼저 쌓이는 상태다.

세 번째는 “항상 올라가는 것”과 “가끔 필요한 것”이 섞이는 문제다. CLAUDE.md는 세션 시작에 읽히는 기본 메모리 층이다. 스킬 본문은 쓰일 때 로드되므로, 긴 참고 자료를 스킬로 두면 쓰지 않을 때의 비용이 훨씬 작다. 공식 스킬 문서도 절차나 긴 참고는 CLAUDE.md에서 빼 스킬로 옮기라고 한다. 스킬이 한 번 로드되면 그 내용이 이후 턴에도 남으므로, 스킬 본문 자체도 짧게 두는 편이 낫다.

짧게 둘 때 남기는 것

짧게 만든다고 해서 규칙을 지우라는 말은 아니다. 어디에 둘지 나누면 된다.

CLAUDE.md에 잘 맞는 말:

  • 이 저장소가 무엇인지 한두 문장
  • 코드만 보면 모르는 함정 (타입이 한 파일에만 있다, 배포 전에 반드시 돌릴 명령 등)
  • 팀 기본 브랜치·PR 관습처럼 거의 모든 작업에 적용되는 것
  • 자주 쓰는 빌드·테스트 명령

스킬이나 보조 파일로 빼기 좋은 말:

  • 코드 리뷰, 배포, 문서 발행처럼 특정 작업에서만 쓰는 절차
  • 긴 예시, API 목록, 과거 마이그레이션 기록
  • “가끔 필요할 수도 있는” 체크리스트 전체

한 줄 테스트는 단순하다.

이 문장을 빼면 에이전트가 반복해서 실수할까?
아니면 파일·테스트를 보면 스스로 알까?

후자라면 매 세션 상주 비용만 늘린다. 전자라면 남기되, 가능하면 한 문장으로 줄인다.

예전 모범 사례 중 일부는 공식 글에서 낡은 관행으로 정리된다. 규칙을 잔뜩 주기보다 주변 코드에 맞춰 판단하게 하기, 예시를 잔뜩 넣기보다 도구 인터페이스를 잘 설계하기, 앞에 다 쌓아 두기보다 필요할 때 펼치기(progressive disclosure)로 옮긴 것이다. 필요한 만큼만 펼쳐 보기는 스킬뿐 아니라 도구 정의 지연 로드에도 쓰인다.

짧다고 항상 좋은 것은 아니다

반론도 분명하다.

약한 모델이나 경험이 적은 팀에서는 강한 규칙이 최악을 막아 준 적이 있다. 공식 글 자체도 예전에는 파일 삭제 같은 사고를 막으려고 강한 가드레일이 필요했다고 적는다. 모델이 바뀌었다고 해서 어제 쌓은 규칙을 하루 만에 전부 지울 필요는 없다. 먼저 충돌하는 문장, 코드·테스트만 보면 드러나는 설명, 한 번도 안 지키는 문장부터 줄이는 편이 안전하다.

팀 공유 규칙과 개인 취향도 다르다. 보안 정책, 라이선스, 고객 데이터 취급처럼 조직이 맞춰야 하는 문장은 짧게라도 공유 파일에 남아야 한다. 취향에 가까운 주석 밀도, 개인 단축키, 로컬 샌드박스 URL은 개인 파일이나 로컬 전용 메모로 빼는 편이 낫다. Claude Code는 프로젝트 CLAUDE.md와 개인용 로컬 파일을 나눈다.

필요할 때만 펼치는 방식에도 한계가 있다. 스킬 설명(description)이 흐리면 에이전트가 아예 안 부른다. 스킬을 너무 잘게 쪼개면 “어느 파일을 언제 열지” 자체가 새 운영 비용이 된다. 그리고 삭제·배포·비밀 유출처럼 한 번 실패하면 큰 일은, 문서 한 줄보다 훅이나 권한 거부 같은 강제 장치가 맞다. 메모리 문서도 CLAUDE.md는 컨텍스트이지 강제 설정이 아니라고 분명히 적는다. 반드시 막아야 할 동작은 훅 쪽으로 둔다.

줄일 때 쓰는 실무 순서

이미 파일이 부풀어 있다면 아래 순서가 현실적이다.

  1. 충돌하는 문장부터 찾는다. “문서를 남겨라”와 “문서를 만들지 마라”처럼 반대 지시가 한 컨텍스트에 있는지 본다.
  2. 코드·테스트·README만 보면 알 설명을 지운다.
  3. 특정 작업 절차는 스킬로 옮기고, CLAUDE.md에는 한 줄 링크만 남긴다.
  4. 안전·컴플라이언스·팀 공통 규칙은 짧게 남기되, 막아야 할 실행은 훅·권한·CI로 옮긴다.
  5. 바꾼 뒤에는 실제 작업 한두 개로 행동이 나아졌는지 본다. 문서만 짧아지고 실수가 늘면 중요한 함정을 지운 것이다.

Claude Code에는 설정·스킬·CLAUDE.md 크기를 점검하는 /doctor 같은 점검 경로가 안내되어 있다. 도구 이름과 메뉴는 버전에 따라 바뀌니, 최신 공식 문서의 명령을 기준으로 보면 된다. 점검 결과가 제안한 삭제를 그대로 믿기보다, “빼면 실수할까” 테스트로 한 번 더 걸러야 한다.

이 글과 이전 글의 자리

반복 지시를 규칙 파일로 빼는 글은 “언제 파일을 만들기 시작하는가”를 다룬다. 이 글은 그 파일이 이미 너무 길 때다.

컨텍스트 엔지니어링 글은 검증 가능한 작업대를 남기는 일반 관점이다. 여기서는 Claude Code의 CLAUDE.md·스킬 층과, 모델이 강해진 뒤 규칙을 줄이는 최근 신호를 좁혀 본다.

세션을 기억처럼 믿으면 흔들린다는 글은 대화창 기억의 착각이다. 이 글의 문제는 대화가 아니라, 세션 시작 전에 미리 조립되는 규칙·스킬이 과할 때다.

스킬을 반복 절차 파일로 보는 글과 맞물리면 그림이 완성된다. 저장소 기본값은 짧게, 반복 절차는 필요할 때만, 위험 실행은 강제 장치로.

가져갈 한 문장

규칙을 더 쌓아 에이전트를 똑똑하게 만들기보다, 매 세션에 올릴 말만 남기고 나머지는 필요할 때 펼치게 만드는 편이 낫다.

모델이 바뀌면 예전에 필요했던 제약이 짐이 되기도 한다. 그래서 CLAUDE.md는 한 번 쓰고 끝내는 설정 파일이 아니라, 가끔 가지치기하는 운영 문서로 다루는 편이 안전하다.

출처

확인 기준일: 2026-07-26.