본문으로 건너뛰기

룰 ​

항상 적용할 룰과 필요할 때 꺼내 쓰는 스킬, 문서를 분리해야 에이전트의 실수를 줄일 수 있다.
항상 적용할 룰과 필요할 때 꺼내 쓰는 스킬, 문서를 분리해야 에이전트의 실수를 줄일 수 있다.

룰은 에이전트가 매 작업마다 항상 읽는 짧은 규칙이다. 커밋·배포 여부와 금지 사항처럼 어느 작업에나 적용할 것만 적는다.

기준일: 2026-09-30.

룰에 넣을 것 ​

  • 커밋 정책: 언제 커밋하는지, 어떤 파일만 올리는지. ‘작업 단위가 끝나면 그 단위의 변경만 커밋한다’처럼 적는다.
  • push·배포 정책: 요청받았을 때만 하는지. ‘push는 요청받았을 때만 한다’가 대표적이다.
  • 수정 범위: ‘워크스페이스 밖 파일은 수정하지 않는다’처럼 금지 경계를 분명히 적는다.
  • 테스트: 어떤 명령으로 확인하는지. ‘테스트는 pnpm test로 확인하고, 통과하지 않으면 커밋하지 않는다’처럼 명령까지 적는다.
  • 구조 제한: 모듈 길이, 주석, 아키텍처 경계. ‘모듈은 128줄, 2000자를 넘기지 않게 나눈다’처럼 수치로 적는다.
  • 문서 위치: 결정 기록과 계획 문서가 어디 있는지.

예를 들어 AGENTS.md는 이런 식으로 적는다.

markdown
# 프로젝트 규칙

- 작업 단위가 끝나면 그 단위의 변경만 커밋한다. push는 요청받았을 때만 한다.
- 워크스페이스 밖 파일은 수정하지 않는다.
- 모듈은 128줄, 2000자를 넘기지 않게 나눈다.
- 커밋 메시지는 <type>(<scope>): <요약> 형식으로 쓴다.
- 테스트는 pnpm test로 확인하고, 통과하지 않으면 커밋하지 않는다.
- 결정 기록은 docs/adr/에 남긴다.

해야 할 것과 하지 말아야 할 것을 분명하게 쓴다. 판단이 흔들리는 표현 대신 확인할 수 있는 형태로 적는다.

  • 나쁨: ‘코드를 깔끔하게 작성한다.’
  • 좋음: ‘모듈은 128줄, 2000자를 넘기지 않는다.’

애매한 권장은 룰이 아니라 스킬이나 문서로 보낸다.

  • 매번 판단이 필요한 내용은 룰에 넣지 않는다. 룰이 길어질수록 정작 중요한 금지 사항이 묻힌다.

AGENTS.md 공식 표준 ​

AGENTS.md는 에이전트에게 프로젝트 컨텍스트를 전하는 개방형 포맷이다. 공식 사이트는 이를 에이전트용 README(README for agents)라고 설명한다. 사람이 읽는 README가 빠른 시작·소개·기여 안내를 담는 것과 달리, AGENTS.md는 빌드·테스트 명령, 코드 스타일, 프로젝트 구조처럼 에이전트가 작업에 바로 쓰는 정보를 전용 위치에 둔다. AGENTS.md

  • 6만 개 이상의 오픈소스 프로젝트가 채택했다(2026-10-01 확인). 특정 도구 전용이 아니라 Codex, Jules, Factory, Aider, Goose, OpenCode, Zed, Warp, Cursor, Devin 등 여러 에이전트가 공통으로 읽는다. AGENTS.md
  • 필수 필드가 없고 표준 Markdown으로 쓴다. 저장소가 크면 하위 디렉터리에 AGENTS.md를 두며, 에이전트는 편집 중인 파일에 가장 가까운 파일을 먼저 읽는다. AGENTS.md

런타임마다 읽는 방식이 다르다.

  • Codex는 ~/.codex의 전역 지침을 먼저 읽고, 저장소 루트부터 작업 디렉터리까지 계층적으로 기본 로드한다. 가까운 파일이 나중에 붙어 우선한다. Codex AGENTS.md
  • Claude Code는 CLAUDE.md를 기본으로 읽고, 작업 디렉터리 위쪽에 CLAUDE.md 계열 지침이 없으면 AGENTS.md를 대신 읽는다. Claude Memory

룰을 갱신하는 시점 ​

룰은 한 번 쓰고 끝나는 문서가 아니다. 다음 신호가 보일 때 한 줄씩 고친다.

  • 같은 지적이 두 번 반복되면 룰 후보로 올린다. 사람이 매번 말하는 대신 룰이 매번 읽힌다.
  • 작업마다 다르게 판단하는 항목은 룰에서 뺀다. 룰은 예외를 외우게 하는 문서가 아니다.
  • 룰이 길어지면 절차 부분을 스킬로 분리하고, 룰에는 참조 한 줄만 남긴다.
  • 바뀐 룰은 저장소에 함께 커밋한다. 왜 바뀌었는지는 커밋 기록에 남는다.

룰 자체를 개선하는 흐름은 하네스 개선을 참고한다.

로컬·전역 룰 구분 ​

  • 저장소 규칙은 저장소 루트의 AGENTS.md, CLAUDE.md에 둔다.
  • 개인 규칙은 사용자 홈의 전역 파일(~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)에 둔다.

Claude Code는 CLAUDE.md를, Codex는 AGENTS.md를 기본으로 읽는다. 같은 내용을 두 파일에 복사하면 한쪽만 고쳐지는 일이 생긴다. 심볼릭 링크로 묶어 두면 파일이 하나로 유지된다.

bash
ln -s AGENTS.md CLAUDE.md
ls -l AGENTS.md CLAUDE.md

ls -l로 두 이름이 같은 파일을 가리키는지 확인한다. ln -sf는 기존 파일을 덮어쓸 수 있으므로 기본 예시로 쓰지 않는다. 링크 공유는 공식 필수 방식이 아니라 이 자료집의 관례다.

참고: Claude Code는 프로젝트 CLAUDE.md 계열 지침이 없으면 AGENTS.md도 읽는다. 런타임별 링크 처리 방식은 바뀔 수 있으므로 적용 전에 공식 문서를 확인한다. Claude Memory

보충: 룰을 읽는 순서

Claude Code는 상위 지침을 시작 시, 하위 지침을 해당 파일 접근 시 로드한다. Codex는 저장소 루트부터 작업 디렉터리까지의 AGENTS.md를 읽고, 같은 디렉터리의 AGENTS.override.md가 우선한다. 가까운 지침이 앞선 지침을 보완하거나 덮어쓴다. Claude Memory, Codex AGENTS.md

룰 길이 제한 ​

룰은 매 요청에 함께 로드되므로 길어질수록 컨텍스트를 차지한다. 지켜 온 보수적 기준은 32줄·4000자 안쪽이다.

  • 32줄·4000자: 엄격한 운영 기준이다. 공식 권장이 아니다.
  • 100줄 안쪽: 공식 문서의 실제 사례에서 참고한 수준이다.
  • 200줄: 넘기지 않는 느슨한 상한으로 본다.

4000자는 토큰 수와 정확히 대응하지 않으므로 글자 수는 보조 지표로 쓴다. 길어지는 내용은 스킬이나 문서로 옮기고, 룰에는 참조 한 줄만 남긴다.

참고: Claude Code는 CLAUDE.md를 파일당 200줄 미만으로 두길 권장한다. Codex는 디렉터리별 AGENTS.md를 계층으로 읽으며 합산 로딩을 기본 32KiB(project_doc_max_bytes)로 제한한다. 이는 권장 문서 길이가 아니라 로딩 한도다. Claude Memory, Codex AGENTS.md

룰과 스킬의 경계 ​

  • 항상 적용되는 짧은 규칙은 룰에 둔다.
  • 특정 작업에서만 필요한 절차는 스킬로 분리한다.

같은 내용을 두 곳에 복사하지 않는다. 룰에는 ‘커밋은 커밋 스킬을 따른다’ 정도만 적고 상세 절차는 스킬에 둔다. 스킬의 구성과 호출 방법은 스킬에서 다룬다.