Commands, Skills, Subagents, Rules: 139개 확장 기능을 정리하며 배운 것

Claude Code를 위해 95개의 hooks, 44개의 skills, 85개의 commands, 11개의 rule 파일을 구축한 후, 잘못된 추상화를 선택하는 것이 잘못된 기능을 만드는 것보다 더 많은 시간을 낭비한다는 것을 깨달았습니다. Skill이어야 할 것을 Rule로 만들어 컨텍스트가 40% 비대해졌습니다. Skill이어야 할 것을 Command로 만들어 API 엔드포인트를 작업할 때마다 /fastapi를 직접 입력해야 했습니다.¹

TL;DR

Claude Code는 동작을 확장하는 네 가지 방법을 제공합니다: Commands(사용자가 직접 실행하는 프롬프트), Skills(자동으로 호출되는 컨텍스트), Subagents(위임된 작업 실행기), Rules(항상 적용되는 제약 조건). 139개의 확장 기능을 정리한 후, 의사결정 프레임워크는 단순하다는 것을 알게 되었습니다: 불변 조건에는 Rules, 도메인 전문 지식에는 Skills, 워크플로우에는 Commands, 격리가 필요한 작업에는 Subagents. 어려운 부분은 잘못된 선택을 인식하고 마이그레이션하는 것입니다.

네 가지 추상화 (실제 사례 포함)

Commands: “/commit”과 나머지 84개

Commands는 /command-name을 입력하면 활성화됩니다. 각 Command는 프롬프트 템플릿으로 확장됩니다.²

85개의 Commands에는 /commit(스마트 git 커밋), /review(코드 리뷰 에이전트 실행), /deploy(배포 체크리스트), /publish-check(블로그 게시 전 검증), /deliberate(멀티 에이전트 리서치)가 포함되어 있습니다.

제가 저지른 실수: /fastapi를 필요할 때 FastAPI 패턴을 주입하는 Command로 만들었습니다. 문제는 절반 정도의 경우에 입력하는 것을 잊어버렸다는 것입니다. 호출을 잊을 때마다 에이전트가 제가 적용하고 싶었던 패턴을 놓쳤습니다. 해결책은 /fastapi를 자동 활성화되는 Skill로 마이그레이션하는 것이었습니다.

Skills: 44개의 자동 활성화 지식 모듈

Skills는 대화 내용이 Skill의 설명과 일치할 때 자동으로 활성화됩니다. Command를 입력할 필요가 없습니다. 시스템이 컨텍스트에 기반하여 관련 전문 지식을 주입합니다.³ 직접 Skill을 만드는 단계별 과정은 커스텀 Skill 구축하기에서 다룹니다.

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

44개의 Skills는 다음과 같이 분류됩니다: - 도메인 지식 (8개): FastAPI, SwiftUI, HTMX/Alpine, database, testing, debugging, architecture, security - 블로그 인프라 (7개): blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - 철학/품질 (5개): Shokunin (Jiro), No Shortcuts, Rubin essence, design principles - 멀티 에이전트 (3개): deliberation, review, content creation - 프로젝트별 (4개): 개인 사이트 콘텐츠, ResumeGeni 블로그, Obsidian 캡처

40% 컨텍스트 비대화 사건: 초기에 전체 FastAPI 패턴 가이드(800줄)를 Rule 파일에 넣었습니다. Rules는 모든 세션에 로드됩니다. iOS 앱, CSS, 블로그 콘텐츠를 작업할 때 관련 없는 800줄의 FastAPI 패턴이 컨텍스트 토큰을 소비했습니다. 해당 내용을 “FastAPI backend development”라는 설명의 Skill로 옮기자 문제가 해결되었습니다: API 작업 시에만 Skill이 로드되었습니다.⁴

Subagents: 격리된 리뷰어

Subagents는 자체 컨텍스트 윈도우에서 제한된 도구 접근 권한과 독립적인 권한으로 실행됩니다.⁵

Subagents에는 security-reviewer(읽기 전용 접근, OWASP 취약점 스캔), test-runner(테스트 실행, 실패 분석), conventions-reviewer(프로젝트 표준 검사)가 포함됩니다.

격리가 중요한 이유: 코드 리뷰 중에 리뷰어는 파일을 편집할 수 없어야 합니다. Skill은 리뷰 지식을 주입할 수 있지만, 리뷰는 여전히 전체 쓰기 권한이 있는 메인 컨텍스트에서 이루어집니다. Subagent는 아키텍처 수준에서 읽기 전용 접근을 강제합니다.

Rules: 11개의 항상 적용되는 제약 파일

Rules는 모든 대화에 자동으로 로드됩니다. 11개의 Rule 파일은 다음을 다룹니다:⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

크기 조절의 교훈: Rules의 총량은 11개 파일에 걸쳐 약 180줄입니다. 모든 줄이 모든 세션에 로드됩니다. 원래는 주제별 콘텐츠를 Skills로 마이그레이션하기 전에 400줄 이상이었습니다. 180줄의 Rule 세트는 진정한 불변 조건(보안 제약, git 워크플로우, 수정 사항)을 다룹니다. 그 외의 모든 것은 Skills에 속합니다.

의사결정 프레임워크

마이그레이션 패턴

.claude/ 구조는 세 단계를 거쳐 발전했습니다:

1단계 (1-2개월차): 모든 것을 Rules에 넣었습니다. 항상 로드되는 400줄 이상의 컨텍스트. iOS 패턴, FastAPI 패턴, 디자인 가이드라인, 테스트 표준. 모든 세션에서 컨텍스트가 비대해졌습니다.

2단계 (3-4개월차): 주제별 콘텐츠를 Skills로 마이그레이션했습니다. Rules가 200줄로 줄었습니다. Skills가 20개 이상의 디렉토리로 증가했습니다. 컨텍스트 비대화가 40% 감소했습니다.

3단계 (5개월차 이후): 격리가 필요한 작업(코드 리뷰, 보안 감사)에 Subagents를 추가했습니다. Commands는 명시적 워크플로우용으로 85개에서 안정화되었습니다. 도메인별 전문 지식을 추가하면서 Skills가 44개로 증가했습니다.⁷

교훈: Rules로 시작하고(비용이 낮고, 항상 사용 가능), 주제별로 특화된 것을 발견하면 Skills로 마이그레이션하고, 격리가 필요할 때만 Subagents를 추가하는 것입니다. 컨텍스트가 곧 아키텍처다는 이 마이그레이션 패턴이 더 깊은 원칙을 반영한다는 점을 다룹니다. 컨텍스트 구조 자체가 모든 에이전트 동작을 형성하는 아키텍처적 결정입니다. hooks 튜토리얼은 이 네 가지 추상화를 보완하는 라이프사이클 이벤트 핸들러를 설명합니다. 이 확장 유형들을 모두 합치면 인프라로서의 Claude Code의 토대가 되며, 전체 패턴은 Claude Code 가이드에 정리되어 있습니다.

Skills로 Subagents 강화하기

강력한 패턴: skills frontmatter 필드를 사용하여 Subagent 컨텍스트에 Skills를 주입합니다:

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

security와 testing-philosophy Skills가 Subagent의 시스템 프롬프트에 내용을 주입합니다. 리뷰어는 격리된 읽기 전용 컨텍스트 내에서 전문 지식을 활용합니다.⁸

리뷰 파이프라인은 이 패턴을 사용합니다: 세 개의 Subagents(correctness-reviewer, security-reviewer, conventions-reviewer)가 각각 다른 Skill 주입을 받습니다. correctness reviewer는 debugging-philosophy를 받습니다. security reviewer는 보안 Rule 세트를 받습니다. conventions reviewer는 프로젝트의 코딩 표준을 받습니다.

프로덕션 아키텍처

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

핵심 요점

개인 개발자를 위한 조언: - 프로젝트별 표준을 위해 Rules로 시작하세요 (총 200줄 이하로 유지) - 가장 많이 사용하는 기술 스택에 Skills를 추가하세요. 자동 활성화는 “호출을 잊어버리는” 문제를 해결합니다 - 가장 자주 사용하는 세 가지 워크플로우에 대해 먼저 Commands를 만드세요 - 도구 제한이나 컨텍스트 격리가 필요할 때만 Subagents를 추가하세요

팀을 위한 조언: - 팀 전체의 일관성을 위해 프로젝트 수준에서 Rules를 표준화하세요 - 공통 저장소를 통해 Skills를 공유하세요. 프로젝트 간 이식성이 프로젝트 수준 설정 대비 Skills의 주요 장점입니다

자주 묻는 질문

Claude Code의 commands, skills, rules, subagents는 어떻게 다릅니까?

Commands는 /command-name을 입력하여 사용자가 직접 실행하는 프롬프트입니다. Skills는 대화 내용이 설명과 일치할 때 자동으로 활성화되는 컨텍스트 모듈입니다. Rules는 모든 세션에 로드되는 항상 적용되는 제약 조건입니다. Subagents는 제한된 도구 접근 권한과 독립적인 컨텍스트 윈도우를 가진 격리된 작업 실행기입니다. 의사결정 프레임워크는 다음과 같습니다: 불변 조건에는 Rules, 도메인 전문 지식에는 Skills, 워크플로우에는 Commands, 격리에는 Subagents.

Claude Code 확장 기능은 몇 개부터 너무 많은 것입니까?

개수보다 분류가 더 중요합니다. 제 시스템은 95개 hooks, 44개 skills, 85개 commands, 11개 rule 파일을 성능 문제 없이 운영하고 있는데, 각 유형이 서로 다른 방식으로 로드되기 때문입니다. Rules(항상 적용)는 총 200줄 이내로 유지해야 합니다. Skills는 관련 있을 때만 로드되므로 자유롭게 늘릴 수 있습니다. Commands는 필요할 때만 활성화됩니다. 문제는 양이 아니라 잘못된 분류입니다. 주제별 콘텐츠를 Skills가 아닌 Rules에 넣어 컨텍스트가 40% 비대해지는 문제가 발생했고, 올바른 추상화로 마이그레이션하자 즉시 해결되었습니다.

Claude Code를 설정할 때 rules와 skills 중 무엇으로 시작해야 합니까?

주제와 관계없이 모든 세션에 적용되는 진짜 불변 조건(보안 제약, git 워크플로우, 수정 사항)을 담은 Rules로 시작하세요. 총 200줄 이내로 유지하세요. 그다음 가장 자주 사용하는 기술 스택에 Skills를 추가하면 자동 활성화 덕분에 “호출을 잊어버리는” 문제가 사라집니다. 이어서 가장 흔한 세 가지 워크플로우에 Commands를 추가하세요. Subagents는 마지막입니다. 코드 리뷰처럼 도구 제한이나 컨텍스트 격리가 필요한 작업에만 추가하세요.

Claude Code 세션에서 컨텍스트 비대화를 어떻게 방지합니까?

주제별 콘텐츠를 Rules에서 Skills로 옮기면 됩니다. Rules는 모든 세션에 로드되지만, Skills는 대화 주제가 일치할 때만 로드됩니다. FastAPI 패턴, iOS 패턴, 디자인 가이드라인을 설명이 담긴 frontmatter를 갖춘 Skills로 옮겨 Rules를 400줄 이상에서 180줄로 줄였습니다. 40%의 컨텍스트 감소는 즉시 나타났습니다. 원칙은 이렇습니다: 모든 세션과 관련이 없는 콘텐츠라면 Rules에 있어서는 안 됩니다.

Claude Code의 skills를 여러 프로젝트에서 공유할 수 있습니까?

가능합니다. ~/.claude/skills/에 저장한 Skills는 모든 프로젝트에서 사용할 수 있습니다. 프로젝트 전용 Skills는 프로젝트 디렉토리 안의 .claude/skills/에 넣습니다. 프로젝트 간 이식성이 프로젝트 수준 설정 대비 Skills의 주요 장점입니다. 팀은 공통 저장소를 통해 Skills를 공유하여 모든 구성원이 동일한 도메인 전문 지식과 품질 기준을 사용하도록 할 수 있습니다.

참고 문헌