Claude Code를 위한 나의 전역 지침 파일에는 서브 에이전트가 어떤 모델에서 실행되어야 하는지에 대한 5줄 규칙이 있습니다. 이 규칙은 모든 세션이 돈을 쓰는 방식을 변화시키며, 짧은 테스트를 통해 실제로 그렇게 한다는 것을 보여줍니다. 제가 읽었던 대부분의 지침 파일들은 정반대입니다. 에이전트가 실제로 수행하는 작업에 눈에 띄는 영향이 없는, 길고 상식적인 조언 목록들입니다.
차이점은 영리한 문구에 있는 것이 아닙니다. 각 규칙이 작동할 수 있는 위치에 놓여 있는지, 트리거(trigger)가 있는지, 그리고 누군가 그것을 테스트했는지 여부입니다. 저는 이 세 가지를 결정하는 방식입니다.
규칙이 존재할 수 있는 네 가지 장소
Claude Code는 모든 세션 시작 시 CLAUDE.md (또는 저장소의 AGENTS.md)를 읽습니다. 스킬(Skills)은 작업이 설명과 일치할 때만 로드되는 SKILL.md 파일을 가진 폴더입니다. 훅(Hooks)은 도구 호출(tool call) 전과 같은 고정 지점에서 하네스(harness)가 실행하는 스크립트이며, 모델은 이것들이 실행될지 여부에 대해 투표권을 갖지 못합니다. CI는 이 모든 것 후에, 푸시(push)마다 실행됩니다.
Four layers: CLAUDE.md or AGENTS.md loaded every session; skills loaded when a task matches; hooks run by the harness; CI as the last check
규칙이 아래쪽에 위치할수록 무시하기가 더 어렵습니다.
문서에서는 첫 번째 계층에 대해 솔직하게 이야기합니다: CLAUDE.md는 강제되는 설정(enforced configuration)이 아니라 컨텍스트(context)입니다. 모델은 이것을 읽고 보통 따릅니다. "보통"이라는 것은 스타일이나 선호도에는 괜찮습니다. 하지만 "main 브랜치에 절대 푸시하지 않기" 또는 "프로덕션 데이터베이스 URL을 절대 출력하지 않기" 같은 것에는 적합하지 않습니다. 그것들은 더 아래쪽에 속해야 합니다.
CLAUDE.md에 무엇을 넣어야 하는가
모든 세션에서 사실이며 매번 읽기에 충분히 짧은 것들: 빌드 및 테스트 명령어, 파일이 위치하는 곳, 코드가 명확하게 만들지 않는 규칙(conventions), 그리고 모든 작업에 적용되는 몇 가지 규칙입니다. Anthropic의 문서는 각 파일을 200줄 미만으로 유지할 것을 제안하며, 저는 그 절반보다 훨씬 적게 목표로 합니다. 모든 줄은 매 세션마다 컨텍스트 비용을 발생시키며 다른 모든 줄과 주의를 놓고 경쟁합니다.
저장소(repository)에서 여러 종류의 에이전트가 작동하는 경우, AGENTS.md는 여러 도구가 읽는 공유 이름이며, Claude Code는 이를 CLAUDE.md 대신 읽을 수 있습니다. 저는 서로 어긋나기 쉬운 두 개의 사본을 유지하기보다 하나의 파일을 유지합니다. 아래 모델 규칙과 같이 모든 프로젝트에서 저를 따라야 하는 개인적인 선호 사항은 어떤 저장소에도 넣지 않고 홈 디렉터리의 전역 파일에 넣습니다.
이것이 제 전역 파일에 있는 모델 규칙이며, 정확히 다음과 같습니다:
~/.claude/CLAUDE.md
# Subagent models (cost)
When work goes to subagents, always set the `model` on every Agent call by how hard the task is:
- `haiku`: copy-only edits, mechanical changes, screenshots, data gathering, simple checks.
...
에이전트가 건너뛰는 것들
Four kinds of rule that fail: adjectives like write clean code, rule 140 of 200 buried in a long file, two rules that clash, and rules with no trigger such as be careful with auth
이러한 항목들은 잘 읽히지만 변화를 거의 주지 않습니다.
같은 종류의 규칙들은 반복적으로 실패합니다. 확인 절차(check)가 없는 형용사("깨끗하고 유지보수 가능한 코드를 작성하라")는 모델에게 다르게 할 일을 아무것도 주지 못하는데, 이미 그것이 자신이 하는 일이라고 믿고 있기 때문입니다. 긴 파일 깊숙한 곳에 있는 규칙들은 모델 앞에 놓인 코드에 패배합니다. "변경 사항을 최소로 유지하라"와 "발견하는 모든 문제를 수정하라"처럼 서로 모순되는 두 규칙은 작업이 어느 방향으로 기울어지느냐에 따라 결정됩니다. 그리고 "인증(auth)에 주의하라"와 같이 트리거가 없는 규칙은 아무것도 이 순간이 인증 순간이라고 에이전트에게 알려주지 않기 때문에 절대 작동하지 않습니다.
규칙은 트리거, 액션, 그리고 이유를 갖는다
When work goes to a subagent, do set model on every Agent call, because mechanical work should run on haiku
작은 if-문처럼 작성한다.
작동하는 규칙들은 작은 if-문처럼 보입니다. 특정 일이 발생하면, 이유를 근거로 에이전트가 목록에 없는 경우에도 사용할 수 있는 구체적인 한 가지 행동을 수행합니다. 모델 규칙은 이 세 가지 요소(트리거, 액션, 이유)를 모두 갖추고 있습니다: 트리거는 서브 에이전트로 이동하는 것이고, 액션은 모든 Agent 호출에 model을 설정하는 것이며, 이유는 비용이며 각 등급별 예시가 제공됩니다. 그 이유는 보이는 것보다 더 중요합니다. 이유가 없다면, 특이한 경우를 만난 에이전트는 추측해야 하지만, 이유가 있다면 제가 원했던 바를 처리할 수 있습니다.
부정 규칙은 대체재와 함께 사용할 때 더 효과적입니다. "any는 사용하지 마라"라는 지침은 유형이 까다로워질 때 에이전트를 막히게 만듭니다. "any는 사용하지 말고, unknown을 사용하여 좁혀라"라고 하면 나아갈 곳을 제공합니다.
복잡한 사용법을 위한 스킬(Skills)
어떤 지식은 길고 가끔만 필요합니다: 사내 스타일로 다이어그램을 그리는 방법, 릴리스를 분리하는 방법, 시드 스크립트가 게시물을 어떻게 기대하는지 등입니다. CLAUDE.md에 넣는다면 관련 없는 세션마다 컨텍스트 비용이 들 것입니다. 스킬(Skill)은 이를 대신 저장합니다. 오직 이름과 설명만 미리 컨텍스트에 포함되고, 작업이 일치할 때 본문이 로드됩니다.
.claude/skills/blog-diagram/SKILL.md
---
name: blog-diagram
description: 사이트의 다크 스타일로 블로그 게시물용 SVG 다이어그램을 그립니다. 포스트에 플로우차트, 아키텍처 그림 또는 비교가 필요할 때 사용합니다.
...
설명(description)이 트리거 역할을 하므로, CLAUDE.md 규칙처럼 작성해야 합니다: 스킬이 무엇을 하는지 설명하고, 이어서 "다음 상황에서 사용"과 같이 로드되어야 할 상황들을 명시하는 것입니다. 모호한 설명은 스킬이 절대 로드되지 않음을 의미하며, 외부적으로는 작동하지 않는 스킬과 정확히 똑같이 보입니다.
발생해서는 안 될 일에 대한 훅(Hooks)
훅(Hook)은 하네스(harness)가 고정된 시점에 실행하는 스크립트입니다. Bash의 PreToolUse 훅은 명령어가 실행되기 전에 각 명령어를 JSON 형태로 stdin으로 받습니다. 종료 코드 0은 실행을 허용합니다. 종료 코드 2는 이를 차단하고, 해당 스크립트가 stderr로 보낸 내용을 에이전트에게 되돌려줍니다. 모델은 그 과정을 논리적으로 우회할 수 없습니다. 왜냐하면 모델 자체가 그것을 실행하는 주체가 아니기 때문입니다.
The agent calls Bash with git push; the hook script reads the call as JSON; exit 0 lets it run, exit 2 blocks it and sends stderr to the agent, which changes course
이유가 있는 거절은 루프를 종료시킨다. 단순한 거절은 루프를 시작한다.
.claude/settings.json
{
"hooks": {
"PreToolUse": [
...
.claude/hooks/no-push.sh
#!/usr/bin/env bash
# 에이전트로부터의 git push를 차단한다. 메인 세션은 검토 후에 푸시한다.
cmd=$(jq -r '.tool_input.command // empty')
...
stderr 메시지는 설계의 일부이다. 단순한 거절은 에이전트가 동일 명령의 변형을 시도하게 만든다. 대신 무엇을 해야 하는지 명시하는 거절은 시도를 종료시킨다. 또한 이 훅(hook)이 무엇인지 명확히 할 필요가 있다: 이는 실수에 대한 가드 레일(guard rail)이지, 보안 경계(security boundary)가 아니다. 명령은 스크립트 파일 내부에 푸시를 숨길 수 있다. 확정된 명령에 저항해야 하는 모든 것은 권한(permissions) 또는 에이전트가 단순히 가지고 있지 않은 자격 증명(credentials)에 속한다.
규칙을 코드로 테스트하기
나는 규칙이 행동을 변화시키는 것을 볼 때까지 신뢰하지 않는다. 테스트는 프로브(probe)이다: 규칙을 트리거해야 하는 작은 작업으로, 새로운 헤드리스 세션(headless session)에서 실행되어야 하며, 에이전트가 무엇을 했는지에 대한 자체 기록보다는 로그의 도구 호출(tool calls)을 통해 확인되어야 한다.
Write the rule, run a probe task in a fresh claude -p session, read the tool calls in the log, check it passes three runs out of three; if not, reword it or move it to a hook; keep the probe and re-run it when the file changes
프로브가 없는 규칙은 추측이다.
probe-model-rule.sh
$ claude -p "Rename the CSS class .blog-card to .post-card everywhere. Use a subagent." \
--output-format stream-json --verbose > run.jsonl
$ jq -c 'select(.type == "assistant") | .message.content[]
...
순수한 이름 변경은 `haiku`로 가야 합니다. 만약 프로브(probe)가 `null`을 출력하면, 에이전트가 모델을 선택하지 않은 채 서브에이전트를 시작했고 규칙이 실패했다는 의미입니다. (구형 Claude Code 버전에서는 도구 이름이 `Task`였으므로, 사용자의 경우 필터를 조정하세요.) 저는 각 프로브를 세 번 실행합니다. 한 번의 시도는 운에 좌우될 수 있기 때문입니다. 만약 규칙이 재작성 후에도 계속 실패한다면, 그것은 해당 규칙이 스택의 더 낮은 계층(hook, 프런트매터에 `model:`이 포함된 서브에이전트 정의, 또는 CI 체크)에 속한다는 것을 알려줍니다.
프로브는 회귀(regressions)도 잡아냅니다. 규칙을 추가할 때마다 이전 프로브를 다시 실행합니다. 새로운 줄이 기존의 규칙을 은밀하게 약화시킬 수 있기 때문입니다.
## 파일 간결하게 유지하기
* 에이전트가 어차피 따르는 규칙은 삭제하세요. 새로운 세션에서 해당 줄 없이도 이미 그 행동을 한다면, 그 줄은 노이즈입니다.
* 길고 가끔 사용되는 내용은 스킬(skill)로 옮기고, 특정 경로에만 적용되는 내용은 `.claude/rules/` 아래의 범위 지정 규칙 파일(scoped rule file)로 옮기세요.
* 절대 발생해서는 안 되는 것은 후크(hook)나 권한(permission)으로 옮기세요.
* 세 문장의 설명보다는 하나의 구체적인 예시를 선호하세요.
* 모델을 변경할 때마다 파일을 다시 읽어보세요. 이전 모델의 습관을 교정하기 위해 작성된 규칙이 더 새로운 모델에게는 해로울 수 있습니다.
모든 줄에 대한 테스트는 같습니다. 이 줄을 제거했을 때 에이전트의 행동이 달라지는 프로브를 보여줄 수 있습니까? 그렇지 않다면, 그 줄은 삭제합니다.
[Claude Code hooks 참고 자료](https://code.claude.com/docs/en/hooks): 모든 후크 이벤트, 해당 JSON 입력, 그리고 각 이벤트에 대한 종료 코드 2의 동작을 확인하세요.
_원래 게시된 곳: [내 사이트](https://mahmadmanzoor.com/blog/agent-instructions-claude-md-skills-hooks). 더 많은 포스트와 프로젝트는 [mahmadmanzoor.com](https://mahmadmanzoor.com)에서 확인하세요._
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
