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를 입력할 필요가 없습니다. 시스템이 컨텍스트에 기반하여 관련 전문 지식을 주입합니다.³

---
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를 추가하는 것입니다.

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의 주요 장점입니다

참고 문헌