# 룰

AGENTS.md 등 에이전트가 매 작업마다 참조하는 핵심 작업 규칙을 정의합니다.

원본 URL: https://abc.noco.kr/harness-basics/rules

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

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

기준일: 2026-09-30.

## 룰에 넣을 것

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

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

```markdown
# 프로젝트 규칙

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

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

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

애매한 권장은 룰이 아니라 [스킬](/glossary#skills)이나 문서로 보낸다.

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

## 룰을 갱신하는 시점

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

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

룰 자체를 개선하는 흐름은 [하네스 개선](/harness-basics/self-improve)을 참고한다.

## 로컬·전역 룰 구분

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

[Claude Code](/glossary#claude-code)는 `CLAUDE.md`를, [Codex](/glossary#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](https://code.claude.com/docs/en/memory)

::: details 보충: 룰을 읽는 순서
Claude Code는 상위 지침을 시작 시, 하위 지침을 해당 파일 접근 시 로드한다. Codex는 저장소 루트부터 작업 디렉터리까지의 `AGENTS.md`를 읽고, 같은 디렉터리의 `AGENTS.override.md`가 우선한다. 가까운 지침이 앞선 지침을 보완하거나 덮어쓴다. [Claude Memory](https://code.claude.com/docs/en/memory), [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
:::

## 룰 길이 제한

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

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

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

참고: Claude Code는 `CLAUDE.md`를 파일당 200줄 미만으로 두길 권장한다. Codex는 디렉터리별 `AGENTS.md`를 계층으로 읽으며 합산 로딩을 기본 32KiB(`project_doc_max_bytes`)로 제한한다. 이는 권장 문서 길이가 아니라 로딩 한도다. [Claude Memory](https://code.claude.com/docs/en/memory), [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)

## 룰과 스킬의 경계

- 항상 적용되는 짧은 규칙은 룰에 둔다.
- 특정 작업에서만 필요한 절차는 [스킬](/glossary#skills)로 분리한다.

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