[Claude Code] .claude 설정 우선순위와 계층 구성 요소

개요

Claude Code 는 설정과 지침을 한 파일에서 통째로 읽지 않는다. 사용자 홈, 프로젝트 루트, 그 아래 하위 프로젝트까지 여러 위치에 흩어진 .claude 디렉토리를 각각 읽어 하나로 합친다. 그리고 그 .claude 안에는 에이전트, 스킬, 룰, 훅 같은 서로 역할이 다른 구성 요소가 들어간다. 설정이 어떻게 합쳐지는가와 구성 요소가 어떤 역할을 맡는가를 모르고, 정의되지 않는다면 매 요청마다 다른 산출물을 얻게 된다.

용어	의미
전역 계층	~/.claude, 사용자의 모든 프로젝트에 공통 적용
프로젝트 계층	<project>/.claude, 특정 프로젝트에 적용(팀 공유)
하위 프로젝트 계층	<project>/<sub-project>/.claude, 모노레포 하위 패키지에 국소 적용
병합(merge)	계층별로 지정한 값을 얹되, 겹치는 키는 가까운 계층이 덮어씀
누적(accumulate)	겹쳐도 덮지 않고 전부 이어 붙임(지침, 목록형 설정)
상향 탐색	현재 작업 디렉토리에서 상위로 올라가며 .claude 를 수집

설정 계층과 우선순위

세 단계 계층

설정 계층은 크게 세 단계다. 위로 갈수록 넓게 적용되고, 아래로 갈수록 좁고 구체적으로 적용된다.

계층	경로	적용 범위
사용자 전역	~/.claude/	내 모든 프로젝트 공용
프로젝트 루트	<project>/.claude/	이 프로젝트 전체(팀 공유)
중첩 하위 프로젝트	<project>/<sub-project>/.claude/	모노레포 하위 패키지 국소

설정이 겹칠 때 어떻게 동작하는가

같은 설정이 여러 계층에 있으면 다음 순서로 우선순위가 정해진다. 위쪽이 강하다.

순위	출처	성격
1	관리 정책(managed settings)	조직이 강제, 개인이 못 바꿈
2	명령행 인자	실행할 때 일회성으로 지정
3	<sub-project>/.claude/settings.local.json	하위 프로젝트 개인 로컬
4	<sub-project>/.claude/settings.json	하위 프로젝트 공유
5	<project>/.claude/settings.local.json	프로젝트 개인 로컬
6	<project>/.claude/settings.json	프로젝트 공유
7	~/.claude/settings.json	사용자 전역
8	내장 기본값	Claude Code 기본

여기서 settings.local.json 은 개인 로컬 오버라이드 전용이며 버전 관리에서 제외되는 파일이다. 팀과 공유하면 안 되는 개인 토큰이나 실험용 권한을 여기에 둔다.

우선순위가 높다고 낮은 계층을 통째로 무시하지는 않는다. 각 계층은 지정한 항목만 얹고, 지정하지 않은 항목은 아래 계층 값이 그대로 살아남는다. 겹치는 항목의 처리 방식은 설정 유형에 따라 갈린다.

설정 유형	처리 방식	결과
스칼라 값(모델, 타임아웃)	덮어쓰기	가장 가까운 계층 값 채택
권한 목록(permissions)	누적	전 계층 합집합
훅(Hook)	누적 후 덮어쓰기	같은 이벤트는 구체 계층 우선, 아니면 합쳐짐
환경 변수(env)	키 단위 덮어쓰기	키마다 가까운 계층이 이김

예를 들어 전역에는 모델과 기본 권한을 두고, 프로젝트에는 그 프로젝트에서만 필요한 권한을 추가한다.

// ~/.claude/settings.json (전역)
{
  "model": "claude-sonnet",
  "permissions": {
    "allow": ["Bash(git diff:*)"]
  }
}

// <project>/.claude/settings.json (프로젝트 공유)
{
  "permissions": {
    "allow": ["Bash(npm test:*)"]
  }
}

이때 최종 적용값은 모델은 전역의 claude-sonnet 을 그대로 쓰고, 권한은 git diff 와 npm test 두 항목의 합집합이 된다. 프로젝트에서 권한을 새로 지정했다고 전역 권한이 사라지지 않는다.

프로젝트 루트에서 실행하면 하위 프로젝트는 어떤 설정으로 동작하는가

Claude Code는 현재 작업 디렉토리에서 상위 디렉토리로만 거슬러 올라가며 .claude 를 모은다. 작업 디렉토리보다 아래에 있는 하위 폴더의 .claude 를 자동으로 내려가 모으지 않는다.

• project/.claude (루트 계층)
• project/sub-project/.claude (하위 계층)

작업 디렉토리가 프로젝트 루트(project)라면 하위 프로젝트의 .claude 는 작업 디렉토리보다 아래에 있으므로 탐색 경로에 들어오지 않는다. 즉 이 상황에서 하위 프로젝트의 코드를 다루더라도 적용되는 설정은 project/.claude 와 ~/.claude 를 합친 값이다. 하위 프로젝트의 settings.json 은 우선순위가 낮은 것이 아니라 로드 자체가 되지 않는다.

앞의 우선순위표에서 하위 프로젝트 계층이 프로젝트 루트보다 높게 놓인 것도 하위 프로젝트가 상향 탐색 경로에 들어와 있을 때, 즉 그 안에서 작업할 때에 한한다.

하위 프로젝트의 .claude 를 적용하려면

방법은 하위 프로젝트를 작업 디렉토리로 만드는 것이다. 그 안에서 실행하면 상향 탐색 경로가 하위 프로젝트부터 시작하므로, 하위 프로젝트의 .claude 가 그 세션의 기준이 된다.

# 하위 프로젝트를 작업 디렉토리로 두고 실행
cd project/sub-project
claude

이렇게 하면 탐색 순서가 project/sub-project/.claude, project/.claude, ~/.claude 가 되어 하위 프로젝트가 우선한다. 작업 디렉토리를 옮기기 어렵다면 실행 시 대상 디렉토리를 명시하는 방법도 있다. 어느 쪽이든 하위 프로젝트가 탐색 경로에서 가장 가까운 계층이 되도록 만드는 것이 목적이다.

하위 프로젝트 안에서 작업하면 그 하위에 정의된 .claude 가 그대로 쓰인다. settings.json 의 권한·훅·모델은 물론이고, 그 하위의 agents, commands, skills 와 CLAUDE.md 가 참조하는 룰까지 활성화된다. 상위 project/.claude 와 ~/.claude 도 그 아래 계층으로 함께 누적되며, 겹치는 설정은 하위 값을 우선으로 한다.

루트에서 하위 프로젝트를 함께 다루고 싶다면

그런데 루트에 머문 채로 특정 하위 프로젝트를 다뤄야 하는 경우도 많다. 이때는 하위 프로젝트에서 얻으려는 것이 지침(컨텍스트)인지 설정인지를 나눠서 봐야 한다. 둘의 로드 방식이 다르기 때문이다.

지침이 목적이라면 루트에 있어도 된다. 루트에서 실행한 채 하위 프로젝트 안의 파일을 열면 그 하위의 CLAUDE.md 가 필요 시 자동으로 주입된다. 그래서 여러 하위 프로젝트를 오가며 각자의 맥락을 참고해야 하는 작업은 오히려 루트에서 하는 편이 낫다.

예를 들어 하위 A를 고치면서 하위 B의 코드를 참고해야 하는 상황이다. 여기서 A는 실제로 작업하는 대상이고, B는 그냥 읽어 보는 참고용 코드다. 루트에서 실행하면 두 하위의 파일에 모두 접근할 수 있고, A 파일을 열면 A 의 CLAUDE.md 가, B 파일을 열면 B 의 CLAUDE.md 가 각각 주입된다. 반대로 cd 로 A 안에 들어가면 B는 상향 경로 밖이라 함께 다루기 번거롭다.

다만 루트에서 자동으로 딸려오는 것은 각 하위의 CLAUDE.md(지침)뿐이다. B의 코드를 참고한다고 해서 A 나 B의 .claude 설정을 가져다 쓰지 않는다. 하위의 settings.json 이나 agents, skills 같은 나머지 .claude 구성은 루트에서 로드되지 않는다.

설정(.claude)이 목적이라면 루트로는 안 된다. 하위 프로젝트의 settings.json 이 담는 권한·훅·모델은 그 하위가 상향 탐색 경로에 들어와 있을 때만 로드되므로, cd 로 그 안에서 실행해야 적용된다. --add-dir 로 다른 디렉토리를 작업 대상에 추가하면 그 폴더의 파일에는 접근할 수 있지만, 권한·훅 같은 설정 기준은 여전히 실행 위치의 상향 경로를 따른다.

하위 프로젝트에서 얻으려는 것	어디서 실행	동작
지침·컨텍스트(CLAUDE.md)	루트에서 실행	하위 파일 접근 시 그 하위 CLAUDE.md 자동 주입, 여러 하위 동시 참고 가능
설정(settings.json 의 권한·훅·모델)	하위에서 실행(cd sub-project)	하위가 가장 가까운 계층이 되어 우선 적용

만약 여러 하위의 코드와 지침을 함께 보려면 루트에서 실행하고 프롬프트에서 @경로 로 파일을 지목한다. 이때 각 파일이 속한 하위의 CLAUDE.md 도 함께 붙는다. 트리 밖 저장소는 --add-dir 로 추가한다. 특정 하위의 설정까지 적용하려면 그 하위에서 실행한다.

cd project && claude              # 여러 하위 함께: 루트 실행 + @경로 지목
claude --add-dir ../other-repo    # 트리 밖 저장소를 참고 대상에 추가
cd project/sub-a && claude        # sub-a 의 권한·훅·모델까지 적용

매번 @경로 를 치기 싫다면 지시와 참고 대상을 설정에 넣어 자동화한다. 가장 간단한 방법은 sub-a/CLAUDE.md 에 지침과 import 를 두는 것이다. 그 파일이 로드될 때 import 한 파일이 함께 딸려 오므로, sub-a 를 건드리는 순간 지목 없이 참고가 붙는다.

# sub-a 작업 지침
- payment 로직은 sub-b 구현을 기준으로 맞춘다.
@../sub-b/src/payment.ts

이 지침을 sub-a/CLAUDE.md 에 두면 A 를 다룰 때만, 루트 CLAUDE.md 에 두면 항상 로드된다. 이 밖에 매번 바뀌는 상태는 settings.json 의 훅으로 주입하고, 상황에 따른 판단과 위임은 에이전트·스킬의 description 으로 맡긴다. 자동화 수단은 대상에 따라 고른다.

자동화 대상	방법
고정된 참고 파일·규칙	CLAUDE.md 상시 지침 + @import
매번 바뀌는 동적 상태	settings.json 의 SessionStart 또는 UserPromptSubmit 훅
상황에 따른 판단과 위임	에이전트·스킬의 description 을 명확히

CLAUDE.md 는 덮어쓰지 않고 누적된다

CLAUDE.md 는 설정이 아니라 지침(메모리)이다. settings.json 이 겹치는 키를 덮어쓰는 것과 달리, CLAUDE.md 는 계층별 내용을 모두 이어 붙여 컨텍스트에 주입한다.

전역 CLAUDE.md, 프로젝트 CLAUDE.md, 하위 프로젝트 CLAUDE.md 가 모두 있으면 셋을 전부 합친 지침이 적용된다. 하위 지침이 상위와 모순되면 더 구체적인 하위 지침을 우선하지만, 상위 지침 자체가 지워지는 것은 아니다.

세 계층이 합쳐지는 전체 예시

계층	지정한 내용
~/.claude/settings.json	모델 claude-sonnet, 권한 git diff
<project>/.claude/settings.json	권한 npm test, 훅 lint:fix
<sub-project>/.claude/settings.json	모델 claude-opus

이때 하위 프로젝트에서 작업하면 최종 적용값은 다음과 같이 정해진다.

항목	최종값	근거
모델	claude-opus	스칼라 값은 가장 가까운 하위 계층이 덮어씀
권한	git diff + npm test	목록형은 전 계층 합집합
훅	lint:fix	프로젝트 계층에서만 정의, 그대로 유지

같은 저장소라도 하위 프로젝트가 아닌 루트에서 작업하면 하위 계층은 로드되지 않으므로 모델은 다시 claude-sonnet 이 된다. 어느 위치에서 작업하는지가 최종값을 바꾼다.

.claude 를 이루는 계층 구성 요소

구성 요소	역할	한 줄 정의
CLAUDE.md	진입 지시	컨텍스트가 로드되면서 가장 먼저 읽는 지시사항
settings.json	설정	권한 등록, 훅 등록, 모델 설정
agents/	페르소나	시니어·주니어·TPM 같은 역할을 정의하고 룰·스킬을 참조해 작업 수행
skills/	기술·작업	수행 가능한 작업을 정의, 독립 실행도 되고 에이전트가 참조도 함
rules/	제약·규칙	코드 컨벤션, 아키텍처, 기술별 제약과 규칙
hooks	자동화	도구 실행 전후 등 이벤트에 발동, 사전 훅은 작업을 막을 수도 있음
commands/	/이름 으로 실행하는 슬래시 커맨드	~/.claude/commands/ 또는 <project>/.claude/commands/ 에 .md

CLAUDE.md, settings.json, agents/, skills/, commands/, hooks 는 Claude Code 가 직접 인식하는 내장 메커니즘이다. 반면 rules/ 는 내장 기능이 아니라 관습이다. Claude Code 가 rules/ 폴더를 자동으로 읽어 주지는 않는다. 임의로 만든 폴더에 규칙 문서를 두고, CLAUDE.md 의 import 나 에이전트·커맨드 프롬프트가 링크로 참조할 때만 로드된다.

이 외에 추가 계층은 없는가

앞의 일곱 외에 실무에서 함께 보게 되는 구성 요소가 더 있다. 각각의 역할과 등록 위치를 정리한다.

구성 요소	역할	위치 / 등록 방식
출력 스타일(output styles)	답변 어조와 형식을 세션 단위로 바꾸는 프리셋	~/.claude/output-styles/ 에 정의, /output-style 로 전환
상태줄(statusline)	프롬프트 하단에 표시할 정보를 정의	settings.json 의 statusLine 에 명령 등록
MCP 서버 설정	외부 도구를 연결하는 서버 등록	프로젝트 루트 .mcp.json 또는 settings.json·명령행
플러그인·마켓플레이스	에이전트·커맨드·스킬·훅 묶음을 패키지로 설치	마켓플레이스에서 설치, settings.json 에 등록

로드 시점과 적용 범위

구성 요소는 언제 로드되는지가 다르다. 상시 로드되는 것은 CLAUDE.md 뿐이고 나머지는 필요할 때만 로드된다.

파일	로드 시점	적용 범위
CLAUDE.md	세션 시작·해당 트리 진입 시 항상	프롬프트에 늘 포함
agents/*.md	해당 에이전트 호출 시	위임된 작업 한정
commands/*.md	/커맨드 실행 시	그 실행 흐름 한정
skills/*/SKILL.md	스킬 트리거 시	그 스킬 실행 한정
rules/*.md	다른 파일이 링크·import 할 때	참조된 곳에서만

비용 관점에서 보면 매 요청에 항상 실리는 것은 CLAUDE.md 뿐이다. 그래서 무겁고 상세한 내용은 rules, agents, commands 로 내리고, CLAUDE.md 에는 핵심 규칙만 짧게 둔다.

예시: ~/.claude/CLAUDE.md

# 개인 작업 지침
 
- 답변은 한국어 해요체로 한다.
- 코드를 고치기 전에 관련 테스트를 먼저 확인한다.
- 커밋 메시지는 한 줄 요약과 본문으로 나눠 쓴다.
 
## 공통 규칙
@rules/coding-style.md
@rules/git-workflow.md

agents: 페르소나

에이전트는 특정 역할을 맡은 페르소나다. 시니어 개발자, 주니어 개발자, TPM 처럼 관점과 책임이 다른 인격을 정의하고, 프런트매터(frontmatter)로 이름, 사용할 도구, 모델을 제한한다. 본문이 곧 그 에이전트의 프롬프트이며, 에이전트가 호출됐을 때만 시스템 프롬프트로 주입된다.

한 가지 짚을 점은 에이전트가 룰이나 스킬을 참조하는 것이 자동이 아니라는 것이다. 룰이 에이전트에 저절로 적용되지는 않는다. 따라야 할 규칙 파일이나 쓸 스킬을 에이전트 프롬프트에서 명시적으로 가리켰을 때만 참조한다. 그래서 에이전트 본문에 필요한 룰 링크를 적어 두는 설계가 중요하다.

예시: ~/.claude/agents/senior-reviewer.md

---
name: senior-reviewer
description: 운영 리스크와 엣지 케이스를 보는 시니어 리뷰어
tools: [Read, Grep, Glob, Bash]
model: opus
---
 
너는 시니어 백엔드 리뷰어다. 동작하는 코드와 운영 가능한 코드의 차이를 본다.
 
## 관점
- 실패 경로와 타임아웃, 중복 처리, 권한 누락을 먼저 본다.
- 코드 컨벤션은 rules/coding-style.md 기준으로 판단한다.
 
## 출력
- 지적을 심각도(높음·중간·낮음)로 분류해 파일:라인 형식으로 남긴다.

skills: 기술과 작업

스킬은 수행 가능한 작업을 정의한다. 변경 이력 작성, 문서 이관, 배포 절차처럼 재사용되는 작업 단위를 담는다. 스킬의 동작 방식은 참조보다 자동 선택에 가깝다. 평소에는 스킬의 이름과 설명만 로드되어 있고, 사용자의 요청이 그 설명과 맞아떨어질 때 Claude 가 스스로 해당 스킬을 골라 SKILL.md 본문을 읽는다. 이 점진적 로드 덕분에 스킬이 많아도 평소 컨텍스트를 크게 잡아먹지 않는다. 스킬은 독립적으로도 쓰이고, 에이전트가 자기 프롬프트에서 특정 스킬을 쓰도록 지시하면 그 능력을 빌려 온다. SKILL.md 본문이 스킬이 발동했을 때 따르는 프롬프트다.

예시: ~/.claude/skills/changelog-writer/SKILL.md

---
name: changelog-writer
description: 커밋 로그를 사용자용 변경 이력으로 정리한다
---
 
# changelog-writer
 
최근 릴리스 태그 이후의 커밋을 모아 사용자 관점의 변경 이력으로 다시 쓴다.
 
## 절차
1. 마지막 릴리스 태그를 찾는다.
2. 그 이후 커밋 메시지를 수집한다.
3. 기능 추가, 수정, 제거로 분류해 항목별로 한 줄씩 쓴다.

rules: 제약과 규칙

룰은 코드 컨벤션, 아키텍처 원칙, 인프라나 기술별 제약을 담는다. 스스로 로드되지 않고 CLAUDE.md 나 에이전트, 커맨드가 링크하거나 import 할 때만 적용된다. 여러 곳이 공유하는 규칙을 한 곳에만 정의하는 단일 원천 역할이라, 규칙을 고칠 때 한 파일만 바꿔도 참조하는 모든 곳에 전파된다.

예시: ~/.claude/rules/coding-style.md

# 코딩 스타일 규칙
 
- 변수명은 축약하지 않는다. 의미가 드러나는 전체 단어를 쓴다.
- 한 함수는 한 가지 일만 한다.
- 매직 넘버 대신 이름 있는 상수를 쓴다.
- 예외를 조용히 삼키지 않는다. 처리하거나 다시 던진다.

이 파일은 앞의 CLAUDE.md 예시에서 @rules/coding-style.md 로 끌어와 적용되고, senior-reviewer 에이전트도 판단 기준으로 참조한다.

hooks: 후속 자동화

훅은 특정 작업의 전후에 발동해 추가 작업을 자동으로 수행한다. 여기서 오해하기 쉬운 점은 훅이 작업 후에만 도는 것이 아니라는 것이다. 도구 실행이 끝난 뒤 결과를 받아 포맷터를 돌리는 사후 훅(PostToolUse)뿐 아니라, 도구 실행 직전에 끼어드는 사전 훅(PreToolUse)도 있다. 사전 훅은 조건에 맞으면 그 작업을 아예 거부해 위험한 명령을 막을 수 있다. 이 밖에 프롬프트 제출, 세션 시작과 종료, 컨텍스트 압축 직전 같은 여러 이벤트에도 훅을 걸 수 있다. 훅은 별도 .md 가 아니라 settings.json 안에 이벤트와 명령으로 등록한다.

예시: ~/.claude/settings.json 의 훅 등록

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "prettier --write $FILE" }]
      }
    ]
  }
}

훅도 권한과 마찬가지로 계층 간 누적된다. 전역에 공통 포맷터를 두고 프로젝트에 프로젝트 전용 린트를 더하면 편집 후 둘 다 실행된다. 한쪽이 다른 쪽을 대체하지 않는다.

계층별로 주로 쓰이는 구성 요소

같은 구성 요소라도 계층마다 놓이는 빈도가 다르다. 전역은 재사용 자산을 모두 두는 자리이고, 아래로 갈수록 대개 CLAUDE.md 하나로 수렴한다.

계층	주로 두는 것
~/.claude (전역)	CLAUDE.md, agents/, skills/, commands/, rules/, 기본 settings.json
<project>/.claude (프로젝트)	CLAUDE.md, rules/, 프로젝트 settings.json, 드물게 agents·commands
<sub-project>/.claude (하위)	주로 CLAUDE.md, 필요 시 국소 settings.json

에이전트, 스킬, 커맨드, 룰은 대부분 전역에 한 번만 정의해 모든 프로젝트가 물려받게 한다. 프로젝트 계층은 저장소 고유 규칙을 담은 CLAUDE.md 와 rules/ 가 중심이고, 하위 계층은 언어나 프레임워크가 루트와 다를 때 그 사정을 적은 CLAUDE.md 정도만 둔다. 하위에 에이전트·룰까지 두면 관리 지점이 흩어지므로 가급적 전역이나 프로젝트로 올린다.

에이전트 사용 시나리오

senior-reviewer 에이전트에게 PR 리뷰를 맡기는 상황이다.

메인 세션에서 리뷰를 요청하면, 메인 에이전트가 작업을 senior-reviewer 서브에이전트에게 위임한다. 서브에이전트는 자기 프런트매터에 정의된 도구만 쓸 수 있는 별도 컨텍스트에서 실행되며, 프롬프트에 지정된 대로 rules/coding-style.md 를 참조해 판단 기준을 세운다. 리뷰가 끝나면 결과만 메인으로 돌려주고, 메인이 사용자에게 정리해 전달한다.

sequenceDiagram
    participant U as 사용자
    participant M as 메인 에이전트
    participant A as senior-reviewer 서브에이전트
    participant R as rules / skills
    U->>M: 이 PR 리뷰해줘
    M->>A: 리뷰 작업 위임(도구·모델 제한 적용)
    A->>R: coding-style 규칙 로드
    R-->>A: 규칙 내용
    A-->>M: 위반 목록과 심각도
    M-->>U: 정리된 리뷰 결과
    Note over M,A: 서브에이전트는 별도 컨텍스트에서 실행된다

첫째, 에이전트는 페르소나로서 관점을 좁혀 준다. 시니어 리뷰어는 운영 리스크를 먼저 본다. 둘째, 에이전트는 룰과 스킬을 참조해 판단 기준과 작업 방식을 빌려 온다. 규칙을 에이전트 프롬프트에 복사하지 않고 rules/ 를 참조한다. 셋째, 서브에이전트는 별도 컨텍스트에서 돌기 때문에 메인 대화의 컨텍스트를 오염시키지 않고, 정해진 도구만 쓴다.

에이전트를 부르는 방식은 두 가지다. 하나는 사용자가 특정 에이전트를 지목해 위임하는 것이고, 다른 하나는 메인 에이전트가 작업 성격에 맞는 에이전트를 스스로 골라 위임하는 것이다. 어느 쪽이든 에이전트 정의의 description 이 선택 기준이 되므로, 언제 쓰는 에이전트인지 설명에 분명히 적어 두는 것이 중요하다.

계층을 조합해 잘 쓰는 법

구성 요소는 따로 쓰기보다 조합할 때 힘이 커진다. 기반, 페르소나, 능력, 제약, 자동화가 각자 자리를 지키도록 설계하는 것이 요령이다.

요소	조합에서 맡는 자리
CLAUDE.md	항상 로드되는 기반 지시, 짧게 유지
settings.json	권한·모델·훅의 기반 설정
rules/	규칙의 단일 원천, 여러 곳이 참조
skills/	재사용 작업 단위, 독립 실행과 참조 겸용
agents/	룰·스킬을 끌어 쓰는 페르소나
hooks	작업 전후를 잇는 자동화, 사전 훅은 차단도 가능

규칙은 rules/ 에 한 번만 정의하고, CLAUDE.md 와 에이전트는 그것을 참조만 한다. 반복되는 작업은 스킬로 떼어 내고, 에이전트는 그 스킬을 자기 능력으로 참조한다. 에이전트는 관점이 다른 만큼 여러 개를 두되, 공통 규칙은 룰로 공유해 중복을 없앤다. 마지막으로 사람이 매번 잊는 마무리 작업, 예를 들어 포맷팅이나 테스트 실행은 훅으로 자동화해 손을 떠나게 한다.

이 구조의 이점은 변경 지점이 한 곳으로 모인다는 데 있다. 컨벤션이 바뀌면 rules/ 만 고치면 그 룰을 참조하는 모든 에이전트와 CLAUDE.md 에 전파된다. 새 작업이 필요하면 스킬을 하나 추가하고 에이전트가 참조하게 한다. 각 요소가 자기 역할만 갖고 서로를 참조하도록 두면, 규모가 커져도 관리 지점이 흩어지지 않는다.

작업 위임 시나리오: 기능 구현을 계층에 나눠 맡기기

지금까지 본 구성 요소를 한 작업에 모아 본다. 사용자 알림 기능을 추가하는 일을 계층에 나눠 위임하는 흐름이다. 각 계층이 자기 역할만 맡고, 공통 규칙은 룰로 공유하는 구조를 그대로 따른다.

먼저 위임 전에 자리를 잡아 두는 기반이 있다. CLAUDE.md 는 항상 로드되어 공통 지침을 깔고 @rules 로 상세 규칙을 끌어온다. settings.json 은 사용할 도구 권한을 부여하고, 편집 후 포맷터와 테스트를 돌리는 사후 훅과 위험한 명령을 막는 사전 훅을 등록한다. rules/ 에는 코드 컨벤션과 아키텍처 제약을 단일 원천으로 둔다. skills/ 에는 테스트 작성이나 PR 생성 같은 재사용 작업을 담는다. agents/ 에는 관점이 다른 페르소나를 둔다.

작업은 이렇게 흐른다.

sequenceDiagram
    participant U as 사용자
    participant C as /feature 커맨드
    participant T as tpm 에이전트
    participant I as implementer 에이전트
    participant K as skills / rules
    participant H as 훅
    U->>C: /feature 알림 기능 추가
    C->>T: 요구사항 분해 위임
    T->>K: rules 참조로 티켓 경계 판단
    T-->>C: 티켓 목록
    C->>I: 티켓별 구현 위임
    I->>K: 컨벤션 rules + 테스트 skill 사용
    I->>H: 파일 편집 도구 실행
    H-->>I: 포맷터와 테스트 자동 실행
    Note over I,H: 위험 명령은 사전 훅이 차단한다
    I-->>U: 구현과 검증 결과

흐름을 계층별로 끊어 보면 누가 무엇을 맡는지 분명해진다.

단계	맡는 계층	하는 일
진입	commands/ (/feature)	위임 파이프라인을 한 번에 시작
기반 지침	CLAUDE.md	항상 로드되는 공통 규칙과 rules 참조
권한·자동화	settings.json	도구 권한 부여, 사전·사후 훅 등록
분해	tpm 에이전트	요구사항을 티켓으로 나누고 rules 로 경계 판단
구현	implementer 에이전트	티켓을 구현, 컨벤션 rules 참조, 테스트 skill 사용
규칙·능력 공급	rules/ · skills/	판단 기준과 재사용 작업을 여러 에이전트에 제공
마무리 자동화	hooks	편집 후 포맷·테스트 실행, 위험 명령 차단

위임의 요령은 세 가지다. 첫째, 관점이 다른 일은 다른 에이전트에 맡긴다. 분해는 tpm, 구현은 implementer 가 각자 페르소나로 판단한다. 둘째, 규칙과 능력은 에이전트에 복사하지 않고 rules/ 와 skills/ 에서 참조하게 한다. 두 에이전트가 같은 컨벤션 룰을 참조하므로 판단 기준이 어긋나지 않는다. 셋째, 사람이 매번 챙기기 어려운 마무리와 안전장치는 훅에 맡긴다. 편집 뒤 포맷과 테스트는 사후 훅이 돌리고, 위험한 명령은 사전 훅이 차단한다.

이 시나리오에서 앞서 본 설정 우선순위가 다시 맞물린다. 대상 코드가 모노레포 하위 프로젝트라면 그 하위 디렉토리에서 실행해야 하위 프로젝트의 규칙과 권한이 적용된다. 루트에서 실행하면 하위 계층이 로드되지 않아, 위임한 에이전트가 하위 프로젝트 규칙을 놓친 채 작업하게 된다. 위임 전에 어디에서 실행하는지를 먼저 맞춰 두는 것이 시작점이다.

정리하면 위임은 계층 역할을 그대로 나눠 주는 일이다. 커맨드가 흐름을 열고, 에이전트가 관점을 나눠 맡고, 룰과 스킬이 기준과 능력을 공급하고, 훅이 뒤를 자동으로 잇는다. 각 계층이 자기 역할만 갖고 서로를 참조하도록 두면, 작업이 커져도 위임 구조가 흐트러지지 않는다.