룰

룰, 스킬, 문서를 체계적으로 정리해 에이전트의 작업 환경을 다듬는 구조

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

기준일: 2026-09-30.

룰에 넣을 것

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

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

# 프로젝트 규칙

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

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

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

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

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

룰을 갱신하는 시점

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

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

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

로컬·전역 룰 구분

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

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

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

룰과 스킬의 경계

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

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