[AI] Claude Code 활용법, 다 .md 파일인데 뭐가 다른 거지? (Rules, Skills, Agents, Hooks, MCP..)

이전 글에서 "판단력이 먼저고, 도구 활용은 그다음이다. 하지만 그다음이 안 중요하다는 뜻은 아니다"라고 썼다. 이번 글은 그 그다음 이야기다. 나는 처음에 Anthropic 해커톤 우승자의 셋업을 그대로 가져다 썼다. 내가 막 Claude Code를 쓰던 때 주위에서 가장 많이 추천하던 것이기 때문이다.. 그래서 무작정 깔고 사용했다. 근데 그렇게 쓰다 보니까 문제가 생겼다. CLAUDE.md에도 코딩 스타일이 있고, Rules에도 비슷한 내용이 있고, 뭐가 어디서 적용되는 건지 모르겠는 거다. 남이 만든 걸 쓸 때는 몰라도 됐는데, 내가 직접 만들려고 하니까 각각이 뭔지를 알아야 했다.

 

그래서 찾아보면 CLAUDE.md, Rules, Skills, Agents, Hooks, MCP... 이런 것들이 나온다. 근데 처음 봤을 때 솔직히 헷갈렸다. 다 .md 파일이잖아. 뭐가 다른 거지? CLAUDE.md도 마크다운, Rules도 마크다운, Skills도 마크다운, Agents도 마크다운. 형식이 같으니까 차이가 안 느껴진다. 근데 각각의 역할이 명확히 다르다. 어디에 두느냐, 언제 로딩되느냐, 누가 호출하느냐에 따라 완전히 다른 기능이 된다.

 

이 글은 그 차이를 정리한 글이다. 각각이 뭔지, 왜 있는지, 언제 쓰는지. 공식 문서 기반으로 정리하되, 내가 직접 쓰면서 느낀 것들을 섞었다. 먼저 말하면, 형식은 다 마크다운이지만 결국 중요한 건 각각의 목적이었다.

 

전체 구조부터

Claude Code에서 커스터마이징 할 수 있는 것들을 한눈에 보면 이렇다.

Claude Code 커스터마이징 구조

┌────────────────────────────────────────────────┐
│  CLAUDE.md / Rules                             
│  → "넌 이런 원칙을 따라" (회사 문화/원칙)            
├────────────────────────────────────────────────┤
│  Skills (= Commands)                         
│  → "이 작업은 이 절차대로 해" (매뉴얼/SOP)     
├────────────────────────────────────────────────┤
│  Agents (Subagents)                          
│  → "이건 전문가한테 맡겨" (전문가 파견)            
├────────────────────────────────────────────────┤
│  Hooks                 
│  → "이건 자동으로 해" (자동 품질 관리)  
├────────────────────────────────────────────────┤
│  MCP (Model Context Protocol) 
│  → "외부 도구도 연결해" (외부 시스템 연동)  
└────────────────────────────────────────────────┘

회사에 비유하면 이해가 빠르다. CLAUDE.md는 사원이 입사했을 때 읽는 사규/문화 가이드이고, Skills는 특정 업무의 매뉴얼이고, Agents는 전문가를 파견하는 것이고, Hooks는 자동화된 품질 검수 라인이고, MCP는 외부 협력사를 연결하는 것이다.

이제 하나씩 살펴보겠다.

 

CLAUDE.md & Rules : AI의 원칙을 설계한다

CLAUDE.md란?

CLAUDE.md는 Claude Code가 세션을 시작할 때 가장 먼저 읽는 파일이다. 쉽게 말하면, "넌 이런 원칙을 지켜"라고 미리 써놓는 것이다. 공식 문서에서는 이걸 "Memory"라고 분류한다. 두 종류가 있다.

• Auto memory: Claude가 대화 중에 알아서 저장하는 정보. 프로젝트 패턴, 주요 명령어, 선호사항 같은 것들이 ~/.claude/projects//memory/MEMORY.md에 자동으로 쌓인다.
• CLAUDE.md: 사용자가 직접 작성하고 관리하는 지침서.

CLAUDE.md는 여러 위치에 둘 수 있고, 위치에 따라 적용 범위가 다르다.

• 위치는 ~/.claude/CLAUDE.md, 적용범위는 내 모든 프로젝트, 공유는 나만
• 위치는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md, 적용범위는 해당 프로젝트, 공유는 팀 전체 (VCS)
• 위치는 ./CLAUDE.local.md, 적용범위는 해당 프로젝트 (로컬) , 공유는 나만

상위 디렉토리의 CLAUDE.md는 세션 시작 시 전부 로딩되고, 하위 디렉토리의 것은 해당 디렉토리의 파일을 읽을 때 동적으로 로딩된다. 그리고 더 구체적인 위치의 지침이 우선한다. @path/to/file 문법으로 다른 파일을 import 할 수도 있다.

Rules는 CLAUDE.md의 모듈화

CLAUDE.md 하나에 다 넣으면 파일이 너무 길어진다. 그래서 나온 것이 .claude/rules/ 디렉토리다.

.claude/rules/
├── security.md          보안 규칙
├── testing.md           테스트 규칙
├── coding-style.md      코딩 스타일
├── frontend/
│   └── react.md         React 전용 규칙
└── backend/
└── api.md           API 설계 규칙

.claude/rules/ 안의 모든 .md 파일은 세션 시작 시 자동으로 로딩된다. 하위 디렉토리까지 재귀적으로 탐색한다. CLAUDE.md와 같은 우선순위로 취급된다. 여기서 유용한 기능이 하나 있다. 경로 기반 조건부 적용이다. YAML 프론트매터에 paths를 지정하면, 해당 경로의 파일을 다룰 때만 규칙이 활성화된다.

- --
paths:
- "src/api/***/**.ts"
- "lib/***/**.ts"
- --

**# API 개발 규칙**
- 모든 API 엔드포인트에 입력 검증을 포함할 것

없으면 뭐가 불편한가?

간단하다. 매번 같은 말을 반복해야 한다. "코드 짤 때 immutable 패턴 써줘", "에러 핸들링 꼭 해줘", "console.log 쓰지 마"... 이걸 매 세션마다 말하는 건 비효율적이다. 한 번 써놓으면 끝이다. 내 실제 구조를 보면, ~/.claude/rules/ 아래에 언어별로 분리해서 쓰고 있다. typescript/coding-style.md, python/security.md 같은 식이다. 프로젝트마다 다시 쓸 필요 없이, 글로벌로 한 번 설정하면 어디서든 적용된다.

 

Skills : 반복 작업을 워크플로우로 만든다

Skill이란?

Skill은 특정 작업의 절차를 미리 정의해 놓은 것이다. /명령어로 호출하면 Claude가 해당 절차대로 동작한다. 예를 들어 /plan 사용자 인증 시스템 구현이라고 치면, Claude가 기획 모드에 들어가서 내가 정의한 절차(요구사항 분석 → 아키텍처 설계 → 구현 계획 → 확인 후 개발)를 따른다. 중간에 "JWT 말고 세션 방식으로 해줘"라고 방향을 틀 수도 있다. Skill은 .claude/skills/<스킬명>/SKILL.md 파일로 만든다. YAML 프론트매터로 옵션을 설정하고, 본문에 지시사항을 마크다운으로 쓴다.

- --
name: plan
description: 요구사항을 분석하고 구현 계획을 세우는 스킬.
Use when user says "설계해줘", "구현 계획", "아키텍처" 등.
argument-hint: [feature description]
- --

# 구현 계획 스킬
## 절차
1. 요구사항을 정리하고 빠진 것이 없는지 질문
2. 아키텍처 설계 (기술 스택, 계층 구조, 데이터 모델)
3. 단계별 구현 계획 작성
4. 사용자 확인 후 개발 시작
...

주요 프론트매터 옵션들은 이렇다.

옵션	설명
name	스킬 이름 (생략 시 디렉토리 이름 사용)
description	Claude가 스킬을 언제 적용할지 판단하는 기준
argument-hint	자동완성 시 표시되는 인자 힌트
disable-model-invocation	true면 Claude가 자동 로딩하지 않음 (수동 호출만)
user-invocable	false면 /메뉴에 안 뜸 (Claude만 호출 가능)
allowed-tools	이 스킬에서 사용 가능한 도구 제한
model	모델 오버라이드 (sonnet, opus, haiku)
context: fork	별도 서브에이전트에서 실행

Skill도 위치에 따라 적용 범위가 다르다. ~/.claude/skills/에 두면 모든 프로젝트에서 사용 가능하고, .claude/skills/에 두면 해당 프로젝트에서만 쓸 수 있다.

Commands? 사실상 Skills와 같다

Claude Code 초기에는 "Commands"라는 기능이 따로 있었다. .claude/commands/review.md에 마크다운 파일을 두면 /review로 호출 가능한 명령어가 되는 방식이었다. 근데 공식 문서에서 이걸 명확히 정리했다.

Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Your existing .claude/commands/ files keep working.

• Commands와 Skills는 사실상 같은 것이다. 기존 commands 파일은 그대로 동작하고, Skills는 거기에 디렉토리 구조(보조 파일, 템플릿 등), 프론트매터 옵션, 자동 호출 제어 같은 기능을 추가한 확장판이다. 만약 같은 이름으로 commands와 skills가 둘 다 있으면, skill이 우선한다.

결론적으로 commands를 따로 배울 필요가 없다. skills를 쓰면 된다. 솔직히 처음에 이게 좀 헷갈렸다. "Commands랑 Skills가 다른 건가? 같은 건가?" 문서를 왔다 갔다 하면서 시간을 꽤 썼다. 근데 Anthropic이 공식적으로 "merged"라고 못 박은 걸 보고 정리가 됐다. 그리고 이게 단순히 이름만 바꾼 게 아니라, Skills 쪽으로 기능을 확장하면서 Commands를 흡수한 것이다. 디렉토리 구조, 프론트매터 옵션, 자동 호출 제어, Progressive Disclosure... 이런 것들이 전부 Skills에서 추가된 것들이다.

그리고 좀 흥미로운 것은, Anthropic이 "The Complete Guide to Building Skills for Claude"라는 30페이지짜리 공식 PDF 가이드를 따로 낸 게 있다. 확인해 봤는데 이런 별도 PDF 가이드가 나온 건 CLAUDE.md, Agents, Hooks, MCP 중에서 Skills가 유일하다. 아마 Skill 하나만 잘 만들어도 AI의 작업 효율이 확 올라가니까, 가장 실용적인 기능에 집중한 게 아닐까 싶다. (실제로 내 주위도 skill을 위주로 AI를 잘 쓰시는 개발자 분들이 많다.)

없으면 뭐가 불편한가?

매번 긴 프롬프트를 복사해서 붙여 넣어야 한다."이 기능 구현해 줘. 근데 먼저 요구사항 정리하고, 아키텍처 먼저 잡고, 모르는 건 나한테 물어보면서 해줘. 테스트도 먼저 짜고..." 이걸 매번 치는 것과, /plan으로 한 번에 끝내는 것은 차이가 크다.

 

Agents (Subagents) : 전문가를 파견한다

Agent란?

Agent(Subagent)는 별도의 독립된 프로세스로 실행되는 전문가다. 메인 대화와 분리된 자체 컨텍스트 윈도우를 갖고, 자신만의 시스템 프롬프트와 도구 접근 권한을 가진다. 중요한 것은 독립 컨텍스트이다. 메인 대화의 컨텍스트를 오염시키지 않으면서, 특정 작업을 맡길 수 있다. 공식 문서에서 기본 제공하는 빌트인 에이전트는 이렇다.

에이전트	모델	도구	용도
Explore	Haiku (빠름)	읽기 전용	파일 탐색, 코드 검색
Plan	상속	읽기 전용	코드베이스 분석, 계획 수립
general-purpose	상속	전체	복잡한 리서치, 멀티스텝 작업
Bash	상속	Bash	터미널 명령 실행

커스텀 에이전트는 .claude/agents/ 디렉토리에 마크다운 파일로 만든다.

- --
name: code-reviewer
description: 코드 품질과 보안을 리뷰하는 전문가
tools: Read, Glob, Grep, Bash
model: sonnet
maxTurns: 50
- **--**

당신은 코드 리뷰 전문가입니다. 코드를 분석하고
품질, 보안, 유지보수성 관점에서 피드백을 제공합니다.

여기서 눈여겨볼 옵션들이 몇 가지 있다.

옵션	설명
tools / disallowedTools	사용 가능/불가능한 도구 제어
model	모델 선택 (비용/성능 트레이드오프)
maxTurns	최대 턴 수 (무한 루프 방지)
memory	영구 메모리 (user/project/local 스코프)
background	백그라운드 실행
isolation: worktree	git worktree 격리 환경에서 실행
skills	에이전트에 미리 로딩할 스킬 목록

 

Hooks : 자동으로 품질을 관리한다

Hook란?

Hooks는 Claude Code의 특정 시점에 자동으로 실행되는 커맨드다. 사용자가 직접 호출하는 게 아니라, 이벤트가 발생하면 알아서 실행된다. 공식 문서에서 정의하는 Hook 이벤트는 꽤 많다. 주요한 것만 추리면 이렇다.

이벤트	실행 시점	차단 가능
PreToolUse	도구 실행 전	O
PostToolUse	도구 실행 성공 후	X (피드백만)
Stop	Claude 응답 완료 시	O
UserPromptSubmit	사용자 프롬프트 제출 시	O
SubagentStart	서브에이전트 생성 시	X
SubagentStop	서브에이전트 종료 시	O

Hook에는 세 가지 타입이 있다.

1. Command hook (type: "command"): 쉘 커맨드 실행. 가장 기본적.
2. Prompt hook (type: "prompt"): LLM에게 단일 턴 평가를 맡김. { "ok": true/false, "reason": "..." }를 반환.
3. Agent hook (type: "agent"): 멀티턴 에이전트가 Read, Grep, Glob 도구를 써서 검증.

설정은 settings.json에서 한다.

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

이 예시는 파일이 수정될 때마다 자동으로 Prettier를 돌리는 설정이다. matcher로 어떤 도구에 반응할지 필터링하고, hooks에 실행할 동작을 정의한다.

없으면 뭐가 불편한가?

매번 깜빡한다. 파일 수정하고 포맷팅 안 돌리거나, console.log 남겨두거나, 린트 에러 놓치거나. 사람이 매번 기억하기 어려운 것들을 자동화하는 것이 Hook의 존재 이유다.

 

MCP : 외부 도구와 연결한다

MCP란?

MCP(Model Context Protocol)는 AI와 외부 도구를 연결하는 오픈소스 표준이다. Claude Code가 외부 시스템과 통신할 수 있게 해주는 프로토콜이다. 쉽게 말하면, Claude Code의 손발을 늘려주는 것이다. 기본적으로 Claude Code는 파일을 읽고 쓰고 터미널 명령을 실행할 수 있다. 여기에 MCP를 연결하면, Jira에서 이슈를 가져오거나, Slack에 메시지를 보내거나, PostgreSQL을 직접 쿼리하거나, Figma 디자인을 참조하는 것 같은 일들이 가능해진다. 연결 방법은 세 가지 전송 방식이 있다.

# HTTP (원격 서버, 권장)
claude mcp add --transport http notion <https://mcp.notion.com/mcp>

# SSE (Server-Sent Events, 레거시)
claude mcp add --transport sse asana <https://mcp.asana.com/sse>

# Stdio (로컬 프로세스)
claude mcp add --transport stdio postgres -- npx -y @anthropic/mcp-postgres

MCP도 스코프가 있다.

스코프	저장 위치	설명
local (기본)	~/.claude.json (프로젝트별)	현재 프로젝트에서만
project	.mcp.json (프로젝트 루트)	팀 공유 (VCS 커밋)
user	~/.claude.json (글로벌)	모든 프로젝트에서

 

재밌는 건, Claude Code 자체를 MCP 서버로 내보낼 수도 있다는 점이다. claude mcp serve를 실행하면, Claude Desktop 같은 다른 MCP 클라이언트에서 Claude Code의 도구들을 사용할 수 있다.

없으면 뭐가 불편한가?

Claude Code가 아무리 똑똑해도, 기본 도구만으로는 외부 시스템에 접근하지 못한다. Jira 이슈를 보려면 브라우저를 따로 열어야 하고, DB를 확인하려면 터미널에서 직접 쿼리를 날려야 한다. MCP를 연결하면 이런 컨텍스트 스위칭이 줄어든다.

 

다만 요즘은 Skill에서 OAuth를 받아서 외부 API를 직접 호출하는 경우도 있어서, 반드시 MCP여야만 외부 연결이 되는 건 아니다. 그리고 MCP를 많이 연결해 두면 각 서버의 도구 정의가 컨텍스트를 잡아먹는다는 이야기도 있다. 실제로 필요한 것만 최소한으로 연결하는 쪽이 나은 것 같다.

 

그래서 언제 뭘 쓰는가?

여기가 이 글의 메인이다. 기능을 아는 것과 적절히 쓰는 것은 다르다.

판단 기준 정리

상황	쓸 것	이유
매번 같은 원칙을 지키게 하고 싶다	Rules	세션마다 자동 로딩
반복 작업을 명령어 하나로 하고 싶다	Skill	/명령어로 즉시 호출
대화하면서 반복 수정이 필요하다	Skill	메인 컨텍스트에서 피드백 루프
자율적으로 알아서 해오길 원한다	Agent	독립 프로세스, 결과만 받음
여러 작업을 동시에 돌리고 싶다	Agent(병렬)	독립 컨텍스트로 동시 실행
파일 수정 후 자동으로 뭔가 하고 싶다	Hook	이벤트 기반 자동 실행
외부 시스템을 Claude가 직접 쓰게 하고 싶다	MCP	외부 도구 연결

 

Skill vs Agent : "그냥 Skill로 다 하면 안 돼?"

솔직히 이 질문이 제일 먼저 든다. Skill로 웬만한 건 다 되는데, Agent는 대체 왜 있는 걸까?

결론부터 말하면, Skill만으로는 해결이 안 되는 구조적 한계가 3가지 있다.

 

1. 컨텍스트 오염

Skill은 메인 대화 안에서 돌아간다. 이게 장점이자 단점이다. 코드 리뷰를 시키면, 리뷰 내용이 메인 컨텍스트에 전부 쌓인다. 파일 100개를 분석하는 리뷰를 돌리면? 메인 대화의 컨텍스트가 리뷰 내용으로 가득 차서, 이후 작업에 영향을 준다. Agent는 독립 컨텍스트에서 돌아가니까 이 문제가 없다. 결과만 요약해서 돌려준다.

 

2. 병렬 실행

보안 리뷰, 성능 분석, 타입 체크를 동시에 돌리고 싶으면? Skill로는 불가능하다. 순차적으로 하나씩 해야 한다. Agent는 3개를 동시에 병렬로 실행할 수 있다. 각각 독립된 프로세스이다.

 

3. 중간에 개입할 필요가 없는 작업

기능 개발은 대화하면서 같이 해야 한다. "이 부분은 JWT 말고 세션으로 바꿔줘", "여기 에러 핸들링 추가해 줘" 같은 피드백이 필수다. 이건 Skill이 맞다. 근데 코드 리뷰는? "이 코드 리뷰해 줘"하고 결과만 받으면 된다. 중간에 개입할 게 없다. 이런 작업을 Skill로 하면 메인 대화가 리뷰 결과로 길어지기만 한다.

 

실제로 내가 이걸 고민한 경험이 있다. 기능 구현 워크플로우를 만들 때, Skill로 할지 Agent로 할지 꽤 고민했다.

• 기능 구현은 한 번에 완성되지 않는다. 요구사항 정리하고, 아키텍처 잡고, 구현하면서 방향을 틀고.. 대화가 필수이다.
• 만약 Agent로 만들었다면? "인증 시스템 만들어줘"하고 결과를 받는데, 방식이 마음에 안 들면? 처음부터 다시 해야 한다. 중간 수정이 불가능하다.
• 그래서 Skill로 만들었다. /plan으로 시작하고, 단계별로 피드백을 주면서 함께 완성해 가는 구조이다.

반대로, 코드 리뷰는 Agent로 만들었다. "리뷰해 줘"하고 결과만 받으면 된다. 거기에 보안 리뷰까지 동시에 돌리면 시간도 절약된다.

정리하면, 판단 기준은 이 3가지 질문이다.

 

질문	Yes	No
중간에 피드백을 주면서 조율해야 하는가?	Skill	Agent도 가능
메인 대화 컨텍스트를 오염시키면 안 되는가?	Agent	Skill로 충분
여러 작업을 동시에 돌려야 하는가?	Agent	Skill로 충분

 

	Skill	Agent
실행 방식	메인 대화 안에서	독립 프로세스
컨텍스트	메인 컨텍스트 공유 (오염 가능)	자체 컨텍스트 (격리)
중간 피드백	가능 (대화형)	불가능 (결과만)
병렬 실행	불가능	가능
적합한 작업	기능 구현, 기획, 반복 수정	리뷰, 분석, 검증, 탐색
비유	옆에 앉아서 같이 일하는 동료	과제 맡기고 보고 받는 외주 전문가

 

실제로 쓰다 보면 Skill을 압도적으로 많이 쓴다. 대부분의 작업은 대화하면서 조율이 필요하니까. Agent는 "맡기고 잊어" 유형의 작업에 쓰는데, 한 번 맛을 보면 코드 리뷰나 보안 검사 같은 건 무조건 Agent로 빼게 된다. 메인 대화가 깔끔해지는 게 체감이 확 된다.

 

혼자 다 만들 필요는 없다!

이런 Skill이나 Agent를 직접 만드는 것도 좋지만, 사실 이미 만들어진 것들이 꽤 많다. Anthropic에서 Skills를 Agent Skills라는 이름으로 오픈 표준(Open Standard)으로 공개했다. 이건 Claude Code만을 위한 것이 아니라, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI 등 27개 이상의 도구에서 호환된다. 한 번 만들면 여러 도구에서 쓸 수 있다는 뜻이다.

 

공식/커뮤니티 리소스들을 정리하면 이렇다.

• Agent Skills 공식 스펙 : Agent Skills 오픈 표준 사이트 
• Anthropic Skills 레포 : Anthropic이 직접 만든 예제 스킬들

커뮤니티 모음집

• awesome-claude-code : Skills, Hooks, Commands, Plugins 큐레이션 
• awesome-agent-skills : 300개 이상의 Agent Skills 모음
• awesome-claude-code-toolkit :135 agents, 35 skills, 42 commands, 120 plugins 모음

마켓플레이스/디렉토리

• SkillsMP : 200,000개 이상의 Agent Skills 디렉토리
• SkillHub : Claude Skills & Agent Skills 마켓플레이스

이 외에도 많으니 다른 사람이 만든 걸 참고하거나 가져다 쓰면서, 자기 환경에 맞게 조금씩 커스터마이징 하는 것이 현실적으로 가장 빠른 접근 방법이다.

 

실제로 써본 것: superpowers 플러그인

직접 만들기 전에 다른 사람이 만든 걸 먼저 써보면 감이 잡힌다. 내가 실제로 쓴 건 superpowers라는 플러그인이다. "코딩 에이전트를 위한 소프트웨어 개발 방법론"이라는 컨셉인데, 실제로 브레인스토밍할 때 꽤 유용했다. 요구사항을 말하면 소크라테스식으로 질문을 던지면서 설계를 다듬어주는 방식이다. 구성을 보면 다음과 같다.

superpowers/
├── skills/
│   ├── brainstorming/         소크라테스식 설계 토론
│   ├── writing-plans/         구현 계획 작성
│   ├── executing-plans/       계획 실행 (체크포인트 포함)
│   ├── test-driven-development/  RED-GREEN-REFACTOR 사이클
│   ├── systematic-debugging/  4단계 디버깅
│   ├── requesting-code-review/  코드 리뷰 요청
│   └── ...
├── agents/
├── hooks/
└── commands/

결국 Skills + Agents + Hooks를 조합해서 하나의 개발 워크플로우를 만든 거다. 브레인스토밍 → 계획 → TDD → 코드 리뷰까지 자동으로 이어지는 구조. 재밌는 건 코드 리뷰 단계에서 Critical 이슈가 나오면 다음 단계로 못 넘어가게 막아놓은 것이다. 시니어 개발자가 옆에서 계속 체크하는 느낌이다. 처음부터 직접 만들기보다, 이런 걸 깔아보고 "아, 이런 식으로 조합하는 거구나"를 체감한 다음에 자기 것을 만드는 게 훨씬 빠르다.

 

 

나는 어떻게 쓰고 있는지? (내 설정)

내가 실제로 쓰고 있는 구조다.

~/.claude/
├── CLAUDE.md              글로벌 원칙 (Agent-First, TDD, Security-First 등)
├── rules/
│   ├── security.md        보안 체크리스트
│   ├── testing.md         TDD 워크플로우, 80% 커버리지
│   ├── coding-style.md    불변성, 파일 조직, 에러 핸들링
│   ├── git-workflow.md    커밋 메시지 포맷, PR 워크플로우
│   ├── agents.md          에이전트 오케스트레이션 규칙
│   ├── hooks.md           Hook 사용 가이드라인
│   ├── patterns.md        API 응답 포맷, Repository 패턴
│   ├── performance.md     모델 선택 전략, 컨텍스트 관리
│   ├── spring/        spring 전용 규칙
│   │   ├── coding-style.md
│   │   ├── testing.md
│   │   └── security.md
│   └── python/            Python 전용 규칙
│       ├── coding-style.md
│       ├── testing.md
│       └── security.md
├── agents/                커스텀 에이전트
│   ├── code-reviewer.md
│   ├── security-reviewer.md
│   └── ...
├── skills/                커스텀 스킬
│   └── plan/
│       └── SKILL.md       요구사항 분석 + 구현 계획 스킬
└── settings.json          Hooks, 권한, MCP 설정

이게 실제로 어떻게 돌아가는지를 설명하는 게 나을 것 같다.

 

1단계: 요구사항 정의 (Skill)

나는 superpowers에서 가져온 브레인스토밍 스킬을 쓰고 있다. AI가 먼저 질문을 던지고, 내가 답하면서 요구사항을 구체화하는 방식이다. "사용자 인증 구현해 줘"라고 대충 던져도, "세션 기반이야 JWT야?", "소셜 로그인 필요해?", "토큰 만료 정책은?" 이런 식으로 물어보면서 정리해 준다. 결과물은 요구사항 정의서가 되기도 하고, 테크 스펙이 되기도 한다.

 

2단계: 구조 잡기 (Rules + Agents)

Rules에는 코딩 스타일, 테스트 규칙, 보안 체크리스트 같은 원칙을 넣어뒀다. 언어별로 분리해서 공통 규칙(security.md, testing.md)과 언어별 규칙(spring/, python/)이 따로 있다. 그리고 agents.md에 "코드 작성 후에는 code-reviewer를 돌려라", "보안 관련 변경은 security-reviewer를 거쳐라" 같은 오케스트레이션 규칙을 넣어두면, Claude가 알아서 에이전트를 호출한다.

 

3단계: 병렬 개발 (Agents)

요구사항이 정리되면, 에이전트들이 병렬로 작업한다. API가 여러 개면 API별로 나눠서 동시에 개발하고, 그게 아니면 프론트/백엔드를 동시에 돌리거나 기능 구현과 테스트 코드 작성을 병렬로 진행하기도 한다. 어떤 식이든 1단계에서 병렬로 쪼갤 수 있게 나눠놓는 게 포인트다. 만약 병렬로 좀 더 잘 나누고 싶다면 병렬로 잘 나눠주는 서브에이전트나 스킬을 생성해서 작업 전에 한번 돌려서 티켓들을 발행해도 좋을 것 같다.

 

4단계: 검증 (Agents + Hooks)

개발이 끝나면 code-reviewer가 코드 품질을 보고, security-reviewer가 보안 취약점을 잡고, tdd-guide가 테스트 커버리지를 확인한다. 이것들이 병렬로 돌아간다. 그리고 Hooks에서 git commit 전에 보안 체크를 자동으로 돌려서, 시크릿이 코드에 남아있으면 커밋 자체가 안 되게 막아뒀다.

 

5단계: 문서화

중간중간 /decision으로 트레이드오프를 기록한다. "왜 JWT 대신 세션을 골랐는지", "왜 Redis 대신 인메모리 캐시를 썼는지" 같은 결정들. 나중에 "이거 왜 이렇게 했지?" 싶을 때 돌아볼 수 있다. 마지막에 doc-updater 에이전트가 API 문서나 README를 정리한다.

 

부록) Skill, 제대로 만들려면 (Anthropic 공식 가이드)

위에서 언급한 Anthropic 공식 가이드(30페이지 PDF)를 읽으면서, 직접 만들어보기 전에 알았으면 삽질을 줄였겠다 싶은 내용이 꽤 있었다. 개념 설명은 위에서 했으니, 여기서는 실전에서 차이를 만드는 디테일들만 추린다.

 

Progressive Disclosure : Skill의 중요 설계 원칙

Skill이 "그냥 마크다운 파일"이 아닌 이유가 여기 있다. Skill은 3단계로 정보를 점진적으로 공개하는 구조다.

단계	로딩 시점	내용
1단계: YAML 프론트매터	항상 (시스템 프롬프트에 포함)	이름, description. Claude가 "이 Skill을 쓸지 말지" 판단하는 근거
2단계: SKILL.md 본문	관련될 때만 (Claude가 판단)	실제 지시사항, 절차, 규칙
3단계: 링크된 파일	필요할 때만 (references/, scripts/ 등)	상세 문서, 템플릿, 실행 스크립트

 

왜 이렇게 하는가? 토큰 절약이다. Skill이 20개, 30개 설치되어 있는데 매번 전부 로딩하면 컨텍스트가 낭비된다. 1단계(프론트매터)만 항상 로딩하고, 나머지는 필요할 때만 가져온다.

 

따라서 description 필드가 가장 중요하다. Claude가 Skill을 쓸지 말지 결정하는 유일한 근거가 프론트매터이기 때문이다. 근데 여기서 드는 의문이 있다. "그냥 /plan처럼 슬래시 명령어로 직접 호출하면 되는 거 아닌가? description이 뭐가 그렇게 중요해?" 맞다. /명령어로 직접 호출하면 description은 사실 상관없다. 문제는 자동 호출이다. Claude가 대화 흐름 중에 "아, 이건 저 스킬을 쓰면 되겠다"라고 스스로 판단해서 스킬을 로딩하는 기능이 있는데, 이때 판단 기준이 오직 description뿐이다. 자동 호출을 안 쓸 거면 대충 써도 된다. 근데 자동 호출까지 활용하려면 description을 잘 써야 한다.

 

description 필드 : 가장 중요한 한 줄

공식 가이드에서 대놓고 "The most important part"라고 명시한 부분이다. 구조는 이렇다.

[무엇을 하는가] + [언제 쓰는가] + [핵심 기능]

좋은 예시와 나쁜 예시를 보면 차이가 확 느껴진다.

# 나쁨 - 너무 모호함
description: Helps with projects.

# 나쁨 - 트리거 조건 없음
description: Creates sophisticated multi-page documentation systems.

# 좋음 - 구체적이고 트리거 포함
description: Analyzes Figma design files and generates developer handoff
documentation. Use when user uploads .fig files, asks for "design specs",
"component documentation", or "design-to-code handoff".

 

주요 규칙!

• 1024자 이하
• "무엇을 하는가"와 "언제 쓰는가"를 반드시 둘 다 포함
• 사용자가 실제로 말할 법한 트리거 문구를 포함 ("sprint planning", "create tickets" 등)
• XML 태그(< >) 사용 금지 (보안 이유)
• name 필드는 kebab-case만 허용 (공백, 대문자, 밑줄 불가)

 

Skill의 3가지 카테고리 : 뭘 만들지 감이 안 잡힐 때

"Skill 만들어볼까"까지는 생각이 드는데, 뭘 만들지 막막할 때가 있다. Anthropic이 관찰한 사용 패턴 3가지를 보면 감이 좀 잡힌다.

 

1. Document & Asset Creation (문서/결과물 생성) : 가장 만들기 쉽고, 체감도 빠르다

외부 도구 없이 Claude의 내장 기능만으로 동작한다. MCP 연동도 필요 없고, 스타일 가이드와 템플릿만 잘 정의하면 바로 쓸 수 있다. 처음 Skill을 만든다면 이 카테고리부터 시작하는 걸 추천한다.

• API 문서 생성 스킬, 프론트엔드 디자인 스킬 같은 것들
• 핵심: 스타일 가이드 내장 + 템플릿 구조 + 완성 전 품질 체크리스트

2. Workflow Automation (워크플로우 자동화) : 반복되는 다단계 프로세스가 있을 때

단계별로 검증하고, 통과하면 다음으로 넘어가는 구조. "이 순서대로 해"를 스킬로 만드는 것이다.

• 예: TDD 워크플로우 (테스트 작성 → 실행(실패 확인) → 구현 → 실행(통과 확인) → 리팩토링)
• 예: PR 리뷰 프로세스 (변경 분석 → 보안 체크 → 성능 체크 → 리뷰 코멘트 생성)
• 핵심: 단계별 워크플로우와 검증 게이트 + 반복적 개선 루프

3. MCP Enhancement (MCP 기능 강화) : MCP를 쓰는데 매번 같은 패턴이 반복될 때

이게 좀 재밌는 카테고리다. MCP가 "손발"이라면, Skill은 "매뉴얼"이다.

MCP (Connectivity)	Skills (Knowledge)
서비스에 연결 (Notion, Asana 등)	서비스를 효과적으로 쓰는 법을 가르침
실시간 데이터 접근과 도구 호출	워크플로우와 베스트 프랙티스를 담음
Claude가 할 수 있는 것	Claude가 해야 하는 방법

 

예를 들어 Sentry MCP만 연결하면 Claude는 에러 데이터를 가져올 수 있다. 근데 거기에 코드 리뷰 스킬을 얹으면 에러 데이터를 가져와서 → PR을 분석하고 → 버그를 자동으로 수정하는 워크플로우가 된다. MCP가 이미 연결되어 있는데 매번 "Sentry에서 이 에러 가져와서 이렇게 저렇게 해줘"라고 설명하고 있다면, 그게 바로 스킬로 만들 타이밍이다.

 

5가지 실전 패턴 : "이럴 때 이 구조로 만들어라"

공식 가이드에서 소개하는 패턴인데, 단순 나열보다는 "내가 뭘 만들려고 할 때 어떤 패턴을 골라야 하는가" 관점에서 정리해 본다.

 

Pattern 1: Sequential Workflow (순차 실행): 이 순서대로 해

가장 직관적인 패턴. A → B → C 순서가 정해져 있고, 각 단계를 건너뛸 수 없을 때.

• 예: 고객 온보딩 (계정 생성 → 결제 설정 → 구독 생성 → 환영 이메일)
• 핵심: 각 단계에 검증을 넣고, 실패하면 롤백 지시를 포함할 것
• 이럴 때 써라: 팀에서 "이거 할 때 항상 이 순서로 해야 하는데 누가 맨날 빠뜨린다"는 불만이 나올 때

 

Pattern 2: Multi-MCP Coordination (멀티 MCP 조율): 여러 서비스를 하나로 엮어

여러 외부 시스템을 하나의 워크플로우로 묶는 패턴. MCP를 2개 이상 쓸 때.

• 예: 디자인 핸드오프 (Figma에서 추출 → Drive에 저장 → Linear에 태스크 생성 → Slack에 알림)
• 핵심: 단계 간 데이터 전달 명시, 다음 단계 전 검증, 에러 시 중앙 처리
• 이럴 때 써라: "Figma 보고, Drive 가서, Linear 열고, Slack까지..." 이런 컨텍스트 스위칭 지옥이 반복될 때

 

Pattern 3: Iterative Refinement (반복 개선): 품질이 될 때까지 돌려

초안 → 검증 → 수정 → 재검증 루프. 한 번에 완벽한 결과가 안 나오는 작업에 적합하다.

• 예: 보고서 생성 (초안 → 검증 스크립트 → 이슈 수정 → 재검증 반복 → 품질 통과 시 종료)
• 핵심: 명시적인 품질 기준과 종료 조건이 필수. 안 그러면 무한 루프
• 이럴 때 써라: 문서 생성, 보고서, 코드 생성 등 "완성도"가 중요한 작업. superpowers의 writing-plans 스킬이 이 패턴이다. 계획 작성 → 검증 → 수정 반복

 

Pattern 4: Context-aware Tool Selection (상황별 도구 선택): 상황 봐서 알아서 골라

같은 목표인데 상황에 따라 다른 도구를 써야 할 때. 결정 트리를 스킬에 내장하는 패턴.

• 예: 파일 저장 (10MB 이상 → 클라우드, 협업 문서 → Notion, 코드 → GitHub, 임시 → 로컬)
• 핵심: 결정 기준을 명시하고, 왜 그 도구를 선택했는지 사용자에게 설명하게 할 것
• 이럴 때 써라: "이건 어디에 저장해야 하지?", "이건 어떤 도구로 해야 하지?" 같은 판단이 매번 필요할 때

 

Pattern 5: Domain-specific Intelligence (도메인 전문 지식): 전문가의 머릿속을 스킬에 담아

도구 접근 이상의 전문 지식이 필요한 작업. 규정 준수, 업계 관행, 내부 정책 같은 것들.

• 예: 금융 결제 처리 (제재 목록 확인 → 관할권 검증 → 리스크 평가 → 처리 or 보류)
• 핵심: 도메인 전문 지식을 로직에 내장, 행동 전에 규정 준수 확인, 감사 추적 생성
• 이럴 때 써라: "이거 법적으로 괜찮은 거야?", "이건 회사 정책상 어떻게 해야 해?" 같은 도메인 지식이 필요한 작업. 솔직히 개인 개발자보다는 팀/기업 환경에서 더 빛나는 패턴이다.

 

Skill 테스트: 3가지 영역

스킬을 만들었다고 끝이 아니다. 나도 처음에 만들었으니 됐지 하고 넘어갔다가, 스킬이 안 뜨거나 엉뚱할 때 뜨는 걸 보고 테스트의 중요성을 깨달았다. 따라서 공식 가이드가 강조하는 테스트 영역 3가지를 보면 좋을 것 같다.

1. Triggering Test (트리거 테스트)

• 의도한 질문에 스킬이 로딩되는가?
• 다르게 표현해도 트리거 되는가?
• 관계없는 질문에는 트리거 되지 않는가?

2. Functional Test (기능 테스트)

• 올바른 출력이 생성되는가?
• API 호출이 성공하는가?
• 에러 케이스가 처리되는가?

3. Performance Comparison (성능 비교)

• 스킬 없이 vs 스킬 있을 때 비교

# pdf 제시한 비교 예시
스킬 없이:
- 매번 사용자가 지시를 제공
- 15번의 왕복 대화
- 3번의 API 실패 후 재시도
- 12,000 토큰 소비

스킬 있을 때:
- 자동 워크플로우 실행
- 2번의 확인 질문만
- 0번의 API 실패
- 6,000 토큰 소비

Pro Tip: 하나의 작업에서 먼저 반복 개선하고, 성공한 접근법을 스킬로 추출하라. 넓게 테스트하기보다 하나를 완벽하게 만드는 것이 더 빠르다. 이건 직접 해보니까 정말 공감한다. /plan 스킬도 처음부터 스킬로 만든 게 아니라, 프로젝트를 몇 개 진행하면서 "요구사항 분석 → 아키텍처 설계 → 단계별 구현 계획" 흐름이 매번 반복되길래 그걸 모아서 스킬로 만든 거다.

 

트러블슈팅 : 이거 모르면 삽질한다

실제로 부딪히는 문제들과 해결법. 공식 가이드에서 정리한 건데, 결국 너무 모호하거나, 너무 길거나, 범위가 넓어도 문제라는 소리 같다.

Skill이 자동으로 로딩이 안 된다

• description이 너무 모호하지 않은지 확인
• 사용자가 실제로 말할 트리거 문구가 포함되어 있는지 확인
• 디버깅 방법: Claude에게 "When would you use the [스킬명] skill?"이라고 물어보면 description을 읽어준다

Skill이 너무 자주 로딩된다

• description에 negative trigger 추가 ("Do NOT use for simple data exploration")
• 범위를 더 좁게 명시

지시를 따르지 않는다

• 지시가 너무 길지 않은지 확인 (간결하게, 불릿 포인트 사용)
• 중요한 지시를 상단에 배치 (## Important 또는 ## Critical 헤더 사용)
• 모호한 표현 제거 ("validate things properly" → "CRITICAL: Before calling create_project, verify: - Project name is non-empty - At least one team member assigned")
• 모델이 단계를 건너뛰면 명시적으로 격려: "Take your time to do this thoroughly. Quality is more important than speed."

컨텍스트가 느려진다

• SKILL.md를 5,000 단어 이하로 유지
• 상세 문서는 references/로 분리하고 링크
• 동시에 활성화된 스킬이 20~50개 이상이면 선별적 활성화 고려

 

마무리

이것들을 이해하면 뭐가 달라지는가?

• "Claude한테 매번 같은 말 반복" → Rules로 해결
• "이 작업할 때마다 긴 프롬프트" → Skill로 해결
• "이거 알아서 해와" → Agent로 해결
• "매번 깜빡하는 포맷팅" → Hook으로 해결
• "외부 시스템 연동이 필요해" → MCP로 해결

결국 이 도구들의 본질은 AI한테 반복적으로 말하는 것을 구조화하는 것이다. 너무 모호하고 짧아서도 안 되고, 너무 길어서도 안 된다. 결국 얘네도 사람이라 생각하면 편하다. 사람도 너무 모호하거나 너무 많은 양을 한 번에 전달하면 이해를 다 못하듯이, 얘네도 그렇다. 최대한 문서를 정확하고 핵심적으로 구조화해서, 필요할 때 더 읽어서 쓸 수 있도록 만드는 것이 중요하다. 즉, 하나의 문서에 너무 짧게도 길게도 쓰지 말라는 소리다.

 

그리고 이전 편에서 말한 판단력이, 여기서는 뭘 Rules에 넣고, 뭘 Skill로 만들고, 뭘 Agent한테 맡기고, 뭘 Hook으로 자동화할지 결정하는 것으로 구체화된다. 도구를 아는 것과 적절히 쓰는 것 사이에는 간극이 있고, 그 간극을 메우는 게 결국 경험인 것 같다. 이 글에서 다룬 내용은 시작점에 가깝다. 각 기능의 세부 옵션이나 고급 패턴(팀 오케스트레이션, 플러그인 시스템 등)은 공식 문서에 훨씬 자세히 나와 있다.

 

그리고 쓰면서 느낀 건데, 이 중에서 Skill이 확실히 메인이다. Anthropic이 30페이지짜리 별도 가이드를 Skills에만 할애한 것도 그렇고, 실제로 커스터마이징의 대부분은 Skill로 수렴한다. Rules는 깔아놓고 잊으면 되고, Hooks는 한 번 설정하면 끝이고, MCP는 연결만 해두면 된다. 근데 Skill은 계속 만들고, 다듬고, 확장한다. "이것도 스킬로 만들면 편하겠는데?"라는 생각이 반복적으로 드는 순간이 온다. 그게 바로 시작점이다.

 

직접 만들어보면서 이건 Skill이 맞겠다, 이건 Agent로 빼야겠다 라는 감각이 생기기 시작하면, 그때부터 진짜 활용이 시작되는 것 같다. 사실 판단이 잘 안 되면 Claude한테 이런 기능 만들 건데 뭐가 좋냐고 추천받아도 된다. 너무 큰 부담 없이 .md 파일 하나 만들어서 활용해 보면 된다.

 

개인적으로는 요구사항 정의에 시간을 오래 쓰는 게 맞다고 생각한다. 여기서 대충 넘어가면 나중에 다 돌아온다. 따라서 나는 superpowers의 브레인스토밍을 기반으로 요구사항 정의를 하면서, 중간중간 /decision 으로 트레이드오프를 기록하면서 방향을 잡고, 병렬로 돌릴 수 있는 규모면 티켓으로 쪼개서 돌리고, 티켓을 기반으로 코드를 작성하도록 하며, 기본적으로는 테스트와 코드 리뷰를 빠뜨리지 않는 식으로 하고 있다. 이것도 언제 변할지 모르지만, 나보다 더 잘 만든 게 있으면 써보고 그걸 그대로 쓰든 커스텀해서 쓰든 할 생각이다.