AI가 시작할 때마다 읽는 규약에,気づいたことを足し続けていたら、CLAUDE.md

・AGENTS.md

와 공통 규칙을 맞춰 16KB까지 부풀어 있었습니다.

Claude Code와 Codex를 두 가지 환경에서 사용하고 있는 제 환경에서, 이를 7.8KB까지 줄였습니다. 줄인 후에도 지켜야 할 것은 지켜지고 있고, AI의 우회 경로도 줄었습니다.

이 글에서는 무엇을 남기고 무엇을 제거했는지, 그 판단 기준과, 줄이기 전후의 측정값을 소개합니다. 마지막으로, 자신의 규약을 검토할 때 사용할 수 있는 질문들도 정리했습니다.

규약은 쓸수록 좋아지는 것이 아니다

ETH Zürich의 조사(2026년 2월, arXiv:2602.11988)는 규약 파일(AGENTS.md)
의 효과를 실측하고 있습니다.

• LLM이 자동 생성한 규약 파일: 성공률이 약 2~3% 하락하고, 추론 비용이 20% 이상 증가함
• 사람이 작성한 규약 파일: 성공률은 약 4% 상승하지만, 비용은 최대 19% 증가함
• 개요 설명이나 디렉토리 목록은 도움이 되지 않음(없어도 같은 속도로 목적 파일에 도달할 수 있음)
• 쓰여진 지시는 잘 지켜짐. 즉 불필요한 요구까지 성실하게 지키며 우회한다

OpenAI의 공식 가이드에도

• 이 줄이 없으면, AI는
  실제로 틀릴까? (틀리지 않는다면 삭제) - 이 내용은, AI가
  파일을 보면 알 수 있는 것 아닐까? (알 수 있다면 삭제) - 같은 것이
  다른 파일에도 쓰여 있지 않은지? (있다면 한쪽에 모으기) - 매번이 아니라
  특정 작업일 때만 필요한 것은 아닌가? (그렇다면 별도 문서로 만들고, 읽는 계기만 남기기) - 글로 써도
  지켜지지 않는 규약은 아닌가? (그렇다면 글을 없애고, 후크나 허용 설정으로 대체하기)

Anthropic의 컨텍스트 설계(context design) 기사에 '원하는 결과의 확률을 최대화하는 최소한의 고신호 토큰 집합을 찾아라'라는 문장이 있습니다. 이를 실제 절차에 적용하면 이 5가지 질문이 생겼습니다.

요약하자면, 남겨야 할 것은 '읽지 않으면 AI가 판단을 잘못할 것'인 부분, 즉 커맨드(command)나 금지 사항(prohibition), 환경의 함정(pitfall)뿐입니다. 개요나 근거는 필요할 때 읽는 문서로 옮기고, 글로 쓰여서 지켜지지 않는 규칙은 후크(hook)나 허용 설정(permission setting)에 맡깁니다.

규약과 후크 양식

이 글은 Zenn의 책 『Claude Code × Codex ― AI가, AI와 함께한다. 자율 협업하는 개인 개발 하네스』 제3장의 요점입니다.

본문에서는 규약을 읽게 하는 방법 외에도 다음 내용을 실측값과 양식과 함께 정리했습니다.

• 사용 한도에 3개월 동안 80회 도달해도 작업이 멈추지 않는 진행 방식
• 구현한 AI와 다른 AI에게 반드시 검토(review)를 받게 하는 시스템
• 지켜지지 않는 규약을 후크로 대체하는 절차
• 노력 설정(추론의 깊이, depth of reasoning) 활용법

앞선 2장까지는 무료로 읽을 수 있습니다. 규약이나 후크 양식을 그대로 사용하고 싶으신 분은 책도 참고해 주세요.

Discussion