AGENTS.md, Rules, Skills, Hooks: 에이전트를 길들이는 4층 구조

4층은 각각 언제 로드돼요?

1층: AGENTS.md·CLAUDE.md에는 뭘 써요?

세 도구 모두 세션 시작 때 이 파일을 읽어요. Codex는 ~/.codex의 전역 파일부터 저장소 루트를 거쳐 현재 폴더까지 AGENTS.md를 이어 붙이고, 합친 크기가 기본 32KiB를 넘으면 더 붙이지 않아요. Cursor는 루트와 하위 폴더의 AGENTS.md를 지원해요. Claude Code는 CLAUDE.md를 파일당 200줄 이하로 권장하고, @path import도 시작할 때 같이 로드되니 맥락 비용은 줄지 않는다고 안내해요.

그래서 1층에는 매 작업에 필요한 사실만 둬요. 스타일 가이드 전체는 린터에, 긴 절차는 스킬에 맡겨요.

# AGENTS.md

## 명령
- 설치: `pnpm install`
- 검증: `pnpm lint && pnpm test && pnpm e2e`

## 구조
- `src/app/` 화면, `src/server/` API, `db/migrations/` 스키마 변경

## 규칙
- 마이그레이션은 새 파일로만 추가하고 기존 파일은 수정하지 않는다.
- `.env*` 파일은 읽거나 수정하지 않는다.

## 완료 기준
- 검증 명령을 실제로 실행하고 결과를 요약에 붙인다.
- UI를 바꿨다면 `verify-ui` 스킬로 확인한다.

Claude Code는 CLAUDE.md가 있으면 AGENTS.md를 읽지 않아요. 공용 원본을 유지하려면 CLAUDE.md를 이렇게 둬요.

@AGENTS.md

## Claude Code 전용
- 넓은 코드 탐색은 서브에이전트에 맡기고 요약만 받는다.

2층: Cursor Rules는 언제 붙어요?

.cursor/rules/ 안의 .mdc 파일만 규칙으로 인식돼요. 일반 .md는 무시돼요. 붙는 시점은 프론트매터 세 필드로 정해져요.

alwaysApply	description	globs	동작
true	무시	무시	모든 대화에 포함
false	없음	있음	일치하는 파일이 맥락에 있으면 자동 첨부
false	있음	없음	에이전트가 설명을 보고 필요할 때 가져옴
false	없음	없음	@규칙이름으로 직접 부를 때만

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- 서버 데이터는 컴포넌트에서 직접 fetch하지 않고 `src/server/`의 함수를 거친다.
- 버튼과 입력창은 `src/ui/`의 공용 컴포넌트를 재사용한다.

Claude Code에서는 .claude/rules/*.md에 paths 프론트매터를 달면 같은 효과를 내고, Codex에서는 하위 폴더 AGENTS.md나 AGENTS.override.md로 범위를 나눠요. Cursor 문서는 규칙을 500줄 이하로 유지하고, 같은 실수가 반복될 때만 추가하라고 권해요. 참고로 설명만 있는 규칙은 Cursor의 /migrate-to-skills가 스킬로 바꿔 줘요. 설명 기반 규칙과 스킬이 사실상 같은 역할이라는 뜻이에요.

3층: Skills는 왜 따로 둬요?

Agent Skills 스펙에서 스킬은 SKILL.md가 든 폴더예요. 필수 프론트매터는 두 개예요.

• name: 64자 이하, 소문자·숫자·하이픈만, 폴더 이름과 같아야 해요.
• description: 1,024자 이하, 무엇을 하고 언제 쓰는지 둘 다 써요.

핵심은 단계적 로딩이에요. 시작할 때는 모든 스킬의 이름·설명(스킬당 약 100토큰)만 올라가고, 스킬이 선택되면 본문(5,000토큰 미만 권장)을, scripts/·references/·assets/는 필요할 때만 읽어요. 그래서 긴 배포 절차나 검증 절차를 1층에서 빼서 여기로 옮기면 평소 맥락이 가벼워져요.

도구	프로젝트 스킬 위치	부르는 법
Claude Code	.claude/skills/<name>/	/name 또는 자동
Codex	.agents/skills/ (현재 폴더부터 저장소 루트까지)	$name, /skills 또는 자동
Cursor	.agents/skills/, .cursor/skills/ (.claude/skills/, .codex/skills/도 읽음)	/ 메뉴 또는 자동

.agents/skills/verify-ui/
├── SKILL.md
└── scripts/
    └── smoke.sh

---
name: verify-ui
description: 화면, 컴포넌트, CSS를 수정한 뒤 Playwright로 핵심 흐름을 실행해 확인한다. UI 변경을 마무리하기 전에 사용한다.
---

# verify-ui

1. 개발 서버가 떠 있지 않으면 `pnpm dev`를 백그라운드로 실행한다.
2. `scripts/smoke.sh`를 실행한다. 실패하면 로그의 첫 에러부터 고친다.
3. 통과한 테스트 이름과 리포트 경로를 최종 요약의 `Evidence:` 줄에 적는다.

#!/usr/bin/env bash
set -euo pipefail
npx playwright test tests/smoke --reporter=line

Codex와 Cursor는 .agents/skills를 같이 읽어요. Claude Code는 .claude/skills 안의 스킬 폴더가 심볼릭 링크여도 따라가니, 원본은 한곳에 두고 링크만 걸어요. 같은 스킬이 두 곳에서 잡히지 않는지 한 번 확인해 두세요.

mkdir -p .claude/skills
ln -s ../../.agents/skills/verify-ui .claude/skills/verify-ui

자동 호출을 막고 명령처럼만 쓰고 싶다면 Claude Code와 Cursor는 프론트매터에 disable-model-invocation: true를, Codex는 agents/openai.yaml에 allow_implicit_invocation: false를 둬요.

4층: Hooks로 무엇을 강제해요?

1~3층은 모두 모델이 읽고 따르는 글이에요. 반드시 지켜야 하는 건 훅으로 옮겨요. 세 도구 모두 도구 호출 전후 이벤트에 셸 명령을 걸 수 있어요.

• Claude Code: .claude/settings.json의 hooks. PreToolUse에서 종료 코드 2를 내면 호출이 막히고 stderr 메시지가 Claude에게 전달돼요.
• Cursor: .cursor/hooks.json("version": 1). 종료 코드 2는 거부예요. 그 밖의 실패는 기본적으로 통과시키니 보안 훅에는 failClosed: true를 붙여요. 저장소의 프로젝트 훅은 Cloud Agents에서도 돌아요.
• Codex: hooks.json 또는 config.toml의 [hooks]. 기본으로 켜져 있고 PreToolUse, PostToolUse, Stop 같은 이벤트를 써요.

예를 들어 에이전트가 git commit --no-verify로 git 훅을 건너뛰지 못하게 막는 스크립트는 이렇게 써요. Claude Code와 Cursor의 입력 형식이 달라서 둘 다 받도록 했어요.

#!/usr/bin/env bash
# .agent-hooks/no-verify-guard.sh
cmd=$(jq -r '.tool_input.command // .command // empty')
if [[ "$cmd" == *"--no-verify"* ]]; then
  echo "git 훅 우회(--no-verify)는 금지예요. 훅이 실패한 원인을 고치세요." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.agent-hooks/no-verify-guard.sh" }
        ]
      }
    ]
  }
}

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": ".agent-hooks/no-verify-guard.sh", "matcher": "git", "failClosed": true }
    ]
  }
}

위가 Claude Code의 .claude/settings.json, 아래가 Cursor의 .cursor/hooks.json이에요. 마지막 관문은 git 자체예요. 커밋 메시지에 검증 근거 한 줄이 없으면 커밋을 거부하는 commit-msg 훅을 걸어 두면, 어떤 에이전트로 작업하든 같은 기준이 적용돼요.

#!/usr/bin/env bash
# .githooks/commit-msg
if ! grep -qE '^Evidence: .+' "$1"; then
  echo "커밋 메시지에 'Evidence: <실행한 검증과 결과>' 줄을 넣어 주세요." >&2
  exit 1
fi

chmod +x .githooks/commit-msg .agent-hooks/no-verify-guard.sh
git config core.hooksPath .githooks

서브에이전트와 워크트리는 어디에 끼워요?

서브에이전트는 별도 컨텍스트에서 일하고 요약만 돌려줘요. 그래서 코드 탐색, 긴 로그 분석처럼 결과물보다 중간 출력이 큰 일에 맞아요. Claude Code는 .claude/agents/*.md, Codex는 .codex/agents/*.toml로 정의하고, Cursor는 /multitask로 병렬 실행해요. 서브에이전트마다 따로 모델을 호출하니 토큰은 더 써요.

---
name: log-triage
description: 테스트나 빌드 로그가 길 때 첫 번째 실패와 원인 위치만 추려 온다.
tools: Read, Grep, Bash
---

로그에서 첫 번째 실패, 원인 파일과 줄 번호만 5줄 이내로 보고한다. 코드는 수정하지 않는다.

읽기 위주 작업은 병렬로 돌려도 안전하지만, 여러 에이전트가 동시에 파일을 고치면 충돌해요. 쓰기 작업을 병렬로 돌릴 때는 워크트리로 체크아웃을 나눠요. git worktree add ../app-auth -b feat/auth처럼 직접 만들어도 되고, Claude Code의 --worktree, Cursor CLI의 agent --worktree, Codex 데스크톱 앱의 워크트리 기능을 써도 돼요. Cursor는 .cursor/worktrees.json에 의존성 설치 같은 초기 설정을 적어 둘 수 있어요.

4층을 세팅하는 순서는요?

1. AGENTS.md를 짧게 시작
   명령, 폴더 지도, 금지 사항, 완료 기준만 써요. CLAUDE.md는 @AGENTS.md import로 연결해요.
2. 반복되는 실수만 Rule로
   같은 폴더에서 같은 실수가 반복될 때 globs 규칙을 하나 추가해요.
3. 반복되는 절차는 Skill로
   채팅에 계속 붙여 넣던 체크리스트를 SKILL.md와 scripts로 옮겨요.
4. 꼭 지킬 것은 Hook으로
   민감 파일 수정, 훅 우회 같은 행동은 종료 코드 2로 막고, 커밋에는 Evidence 줄을 요구해요.
5. 검증은 테스트와 Playwright로
   완료 판단을 모델의 말이 아니라 실제로 실행한 명령 결과에 묶어요.

정리

• 1층 AGENTS.md·CLAUDE.md는 항상 로드되니 짧게 유지해요.
• 2층 Rules는 경로별 반복 실수를, 3층 Skills는 긴 절차와 스크립트를 맡아요.
• 4층 Hooks와 git 훅은 모델이 무엇을 판단하든 실행돼요. 강제할 건 여기로 옮겨요.
• 서브에이전트는 시끄러운 읽기 작업에, 워크트리는 병렬 쓰기 작업에 써요.

이 구조로 자영업자 AI 비서와 우리 가게 전용 앱을 만들고 있어요. 직접 만들 시간이 없다면 자영업자 AX 구조대를 참고해 보세요.

자영업자 AI, 뭐부터 쓰면 될까? 가게 일별 정리 보기