Claude Code를 일상 도구로 쓰기: Claude.md, Skills, Subagents, Plugins, MCP 완벽 가이드

Claude Code 확장 포인트: Claude.md, Skills, Subagents, Plugins, MCP

Claude Code를 일상 도구로 쓰기: Claude.md, Skills, Subagents, Plugins, MCP 완벽 가이드

Claude Code는 단순한 CLI 도구가 아니다. 개발자가 매일 마주하는 반복 작업을 자동화하고, 팀 전체의 컨벤션을 공유하며, 외부 서비스와 유기적으로 연동할 수 있는 확장성 높은 플랫폼이다. 핵심은 Claude Code의 5대 확장 포인트인 Claude.md, Skills, Subagents, Plugins, MCP를 어떻게 조합하느냐에 있다.

이 글에서는 각 확장 포인트의 용도를 정리하고, 실제로 바로 적용할 수 있는 워크플로우를 다룬다.

---

1. Claude.md — 프로젝트 컨벤션의 뿌리

Claude.md는 Claude Code가 매 세션마다 자동으로 로드하는 마크다운 파일이다. 프로젝트 루트에 두면 Claude는 대화 시작부터 프로젝트의 규칙과 conventions을 인식한다.

Claude.md 기본 구조

# 프로젝트 컨벤션## 항상 적용되는 규칙- pnpm 사용, npm 절대 사용 금지- 커밋 전에 항상 테스트 실행- API 변경 시상응 문서 업데이트## 코드 스타일- 들여쓰기: 2칸- 세미콜론 사용- JSDoc 주석 필수## 디렉토리 구조- src/: 소스 코드- tests/: 테스트 코드- docs/: 문서

효과적인 Claude.md 작성 원칙

1. 구체적으로 쓰기: "코드 스타일 지켜라"보다 "component 파일은 PascalCase"가 명확하다.

2. 실패 패턴 기반: Claude가 반복적으로 잘못한 것을 기록한다. 매번 동일한 교정을 하는라면, 그것은 Claude.md에 넣어야 할 규칙이다.

3. 적극적용: 이미 작성된 Claude.md가 있다면 그것을 개선하는 것이 첫 번째 액션이다.

Claude.md는 team이 공유하는 프로젝트의 약속이다. 새 팀원이 들어와서 Claude Code를 실행하면, 별도 설명 없이도 프로젝트의 규칙을 이해할 수 있다.

---

2. Skills — 반복 작업의 재사용 가능한 지식

Skills는 Claude Code가 명령어로 호출하거나 자동으로 로드하는 마크다운 파일이다. /deploy처럼 슬래시 명령으로 실행하거나, 특정 상황에 자동으로 triggered 되도록 설정할 수 있다.

Skill 파일 구조

# Skill: deploy## 목적프로덕션 배포 워크플로우를 자동화한다.## 실행 조건- main 브랜치에 병합되었을 때- 태그가 v* 패턴일 때## 워크플로우1. 빌드 확인: npm run build2. 테스트 실행: npm test3. Docker 이미지 빌드: docker build -t myapp:${GIT_TAG} .4. 레지스트리에 푸시: docker push myapp:${GIT_TAG}5. 쿠버네티스에 배포: kubectl set image deployment/myapp myapp=myapp:${GIT_TAG}## 확인 체크리스트- [ ] 빌드 성공- [ ] 모든 테스트 통과- [ ] 이미지 레지스트리 푸시 완료- [ ] 프로덕션 Pod 교체 완료

Skill 호출 방법

방법	설명	예시
/명령어	사용자가 직접 호출	/deploy
자동 로드	특정 상황 시 Claude가 자동 로드	대형 파일 refactoring 시
Subagent	격리된 컨텍스트에서 실행	백그라운드 태스크용

Reference Skill vs Action Skill

Reference Skill은 Claude가 세션 전반에 걸쳐 참조하는 지식이다. API 스타일 가이드, 디자인 패턴 문서 등이 해당한다. Claude가 코드를 작성할 때 이 지식을 자동으로 참고한다.

Action Skill은 특정 작업을 실행하는 절차다. /deploy, /deploy-production 같은 슬래시 명령으로 호출하면, Claude가 step-by-step으로 워크플로우를 수행한다.

둘의 차이는 명확하다. Reference Skill은 "지식"이고, Action Skill은 "작업"이다.

---

3. Subagents — 격리된 컨텍스트에서의 작업

Subagent는 독립적인 컨텍스트에서 자체 루프를 실행하고, 완료 후 요약만 메인 세션에 반환하는 기능이다. 복잡한 작업을 메인 대화 창에서 처리하면 컨텍스트가 복잡해지고 토큰 소모가 커진다. Subagent를 사용하면 백그라운드에서 병렬 작업이 가능하다.

Subagent 활용 시나리오

# 메인 세션에서 subagent 호출/subagent research:- 전체 코드베이스 분석- 보안 취약점 탐지- 성능 병목 지점 식별

Subagent가 적합한 경우

1. 컨텍스트 격리가 필요할 때: Subagent는 메인 세션과 별도의 컨텍스트를 사용한다. 따라서 대규모 리팩토링이나 코드 분석 작업이 메인 대화를 오염시키지 않는다.

2. 병렬 작업이 필요할 때: 여러 Subagent를 동시에spawn하여 각각 다른 작업을 병렬로 수행하고, 결과만 취합할 수 있다.

3. 토큰 소모를 줄여야 할 때: Subagent가 읽은 파일의 세부 내용은 메인 세션에 돌아오지 않고, 요약만 반환된다.

Subagent vs Skill — 언제 무엇을 선택할까

상황	선택
문서나 패턴을 Claude가 참고하게	Reference Skill
반복적인 작업 절차 실행	Action Skill
대규모 파일 분석 or 백그라운드 태스크	Subagent
여러 전문 분야가 동시에 협업	Agent Teams

Subagent를 잘못 사용하면 불필요한 복잡성이 추가된다. 간단한 조회의 경우 Skill이나 Claude.md로 충분한 경우가 많다.

---

4. Plugins — 다중 기능의 패키지화

Plugin은 Skills, Hooks, Subagents, MCP 서버를 하나의 설치 단위로 묶는 packaging 계층이다. 복수의 확장을 하나의 plugin으로하면 다른 저장소나 팀에 배포하기 쉽다.

Plugin의 네 가지 구성 요소

구성 요소	설명
Skills	plugin namespace로 구분됨 (예: /my-plugin:review)
Hooks	특정 이벤트에_triggered되는 스크립트
Subagents	격리된 작업 실행 단위
MCP servers	외부 서비스 연동 서버

Plugin 설치 예시

# Plugin 설치claude plugin install claude-code/plugin-name# 설치된 plugin 확인claude plugin list# namespace로 호출/my-plugin:review/my-plugin:deploy

Plugin의 핵심 가치는 재사용성이다. 여러 프로젝트에서 동일한 개발 워크플로우를 적용하고 싶다면, 그것을 Plugin으로하면 된다. 팀원 모두가 동일한 규칙으로 개발할 수 있다.

---

5. MCP — 외부 서비스와 도구 연동

MCP(Model Context Protocol)는 Claude Code를 외부 서비스와 도구에 연결하는 프로토콜이다. 데이터베이스 쿼리, Slack 알림발, 브라우저 제어 등 Claude가 원래 할 수 없는 작업을 MCP 서버를 통해 확장할 수 있다.

MCP 활용 예시

// MCP 서버 설정 예시{"mcpServers": {"database": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-postgres"],"env": {"DATABASE_URL": "postgres://localhost/mydb"}},"slack": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-slack"],"env": {"SLACK_BOT_TOKEN": "xoxb-..."}}}}

MCP가 적합한 작업

1. 데이터베이스 연동: 쿼리 실행, 스키마 확인, 마이그레이션 관리

2. 메신저 연동: Slack 채널에 알림 전송, Teams 메시지 발송

3. 브라우저 자동화: 웹 스크래핑, UI 테스트, 폼 자동 입력

4. 파일 시스템 외 작업: 클라우드 스토리지 읽기/쓰기, CI/CD은

MCP 서버는 Claude Code와 외부 시스템 사이에 위치하며, Claude가 할 수 없던 작업을 가능하게 한다. 그러나 모든 작업을 MCP로 처리할 필요는 없다. 간단한 bash 명령으로 가능한 것을 MCP 서버로 처리하면 불필요한 복잡성이 추가된다.

---

6. Hooks — 이벤트 기반 자동화

Hook은 특정 이벤트가 발생할 때마다 자동으로 실행되는 스크립트다. 파일 저장, 커밋, 브랜치 생성 등 개발Workflow의 특정 시점에hook을 걸어서 자동화를 구현한다.

Hook 활용 예시

# .claude/hooks.json{"hooks": [{"event": "post-commit","actions": [{"type": "script","command": "npm test"},{"type": "subagent","goal": "코드 리뷰 자동 실행"}]},{"event": "post-merge","actions": [{"type": "http","url": "https://api.example.com/deploy","method": "POST"}]}]}

Hook 액션 타입

타입	설명	사용 사례
script	로컬 스크립트 실행	lint, 테스트 실행
http	HTTP 요청 전송	CI/CD, 알림
prompt	프롬프트 주입	자동 문서화, 컨벤션 체크
subagent	백그라운드 작업 실행	코드 리뷰, 보안 스캔

Hook을 잘못 설정하면 개발 workflow가 예기치 않게중단될 수 있다. 실행 시간이 긴 스크립트를 hook에 등록하거나, 실패 시 롤백 로직이 없으면생산환경에 문제가 발생할 수 있다. Hook은 항상 idempotent하게 작성해야 한다.

---

7. 확장 포인트 조합 전략

이제 다섯 가지 확장 포인트를 살펴봤으니, 이를 어떻게 조합하는지가 핵심이다.

권장 확장 순서

Claude Code 공식 문서에서 제시하는 순서는 다음과 같다:

1. 컨벤션 반복 오류 → Claude.md에 추가

2. 같은 프롬프트 반복 입력 → User-invocable Skill으로 저장

3. 플레이북/절차를 반복 붙여넣기 → Action Skill으로 캡처

4. 브라우저 탭의 데이터를 Claude가 볼 수 없음 → 해당 시스템을 MCP 서버로 연결

5. 심볼 정의 위치 찾는 데 시간 소요 → 코드 인텔리전스 플러그인 설치

6. 사이드 태스크가 대화를 flooding → Subagent로 라우팅

7. 매번 자동으로 발생해야 하는 작업 → Hook 등록

8. 두 번째 저장소에 동일한 설정 필요 → Plugin으로 패키징

실제 워크플로우 예시

상황: 새 기능 개발 시작1. Claude.md 확인 → 프로젝트 컨벤션 로드2. /start-feature [기능명] → Action Skill 호출3. Subagent가 관련 파일 분석 → 격리된 컨텍스트에서 작업4. Hook이 파일 저장마다 lint 실행 → 자동 품질 관리5. 커밋 시 MCP가 Slack 채널에 알림 → 팀 공유

각 확장 포인트는 독립적으로도 강력하지만, 서로 연결될 때 비약적인 시너지가 발생한다. 처음부터 모든 것을 설정할 필요 없이, 필요할 때마다 하나씩 추가해나가면 된다.

---

8. Agent Teams — 다중 에이전트 협력

Agent Teams은 여러 독립적인 Claude Code 세션을 coordinated하여 동시에 작업하게 하는 기능이다. 병렬 리서치, 새 기능 개발, 복수 가설 검증 등 단일 에이전트로는 처리하기 어려운 대규모 작업에 사용한다.

Agent Teams 활용 시나리오

# 보안 리뷰어, 성능 리뷰어, 테스트 리뷰어를 동시에spawn/team-review:- security: 보안 취약점 스캔- performance: 성능 병목 분석- tests: 테스트 커버리지 검토

각 리뷰어는 독립적인 세션에서 동시에 작업하고, 결과는 메인 세션에 보고된다. 이렇게 하면 세 가지 관점을 병렬로 확보하고, 전체 검토 시간을 단축할 수 있다.

Agent Teams vs Subagents

측면	Agent Teams	Subagent
세션 수	복수 독립 세션	단일 격리 세션
조정	명시적 리더십/공유 태스크	단방향 요약
비용	높음 (복수 세션)	중간
적합한 상황	병렬 전문 분야 검토	대규모 단일 작업

단순히 병렬화가 목적이라면 Subagent로 충분하다. Agent Teams는 여러 전문 분야가 peer-to-peer로 통신하며 협업해야 하는 상황에 적합하다.

---

실용 체크리스트: 오늘부터 적용하기

Claude Code 확장을 구체적으로 시작하고 싶다면, 아래 순서대로 진행해보자.

1. 프로젝트에 Claude.md 생성: 디렉토리 구조, 코드 스타일, 커밋 규칙 등 기본 컨벤션 기록

2. 가장 반복적인 작업 1개 Skill로 만들기: 배포, 빌드, 테스트 실행 등 매일 하는 작업을 Skill으로 정의

3. MCP 서버 1개 연결: 데이터베이스나 Slack 등 가장 필요한 외부 서비스와 연동

4. Hook 1개 등록: 파일 저장 시 lint 실행처럼즉 효과 볼 수 있는 것부터 시작

한 번에 모든 것을 설정하지 않아도 된다. 위 순서는 필요할 때마다 확장해나가는 로드맵이다. 각 확장 포인트를 알아둠으로써, 문제 상황이 왔을 때 "이건 MCP로 연결하면 되겠구나"처럼 올바른 도구를 선택할 수 있다.

---

요약

Claude Code의 힘은 확장성에 있다. 핵심 5가지 포인트를 정리하면 다음과 같다:

확장 포인트	핵심 용도
Claude.md	프로젝트 전반의 컨벤션과 규칙
Skills	반복 작업의 절차와 지식 재사용
Subagents	격리된 컨텍스트에서의 대규모 작업
Plugins	복수 확장의 패키지화 및 배포
MCP	외부 서비스 및 도구 연동
Hooks	이벤트 기반 자동화
Agent Teams	다중 에이전트 협력

이 확장 포인트들은 서로 조합될 때 비로소 진정한 가치를 발휘한다. 하지만 모든 것을 처음부터 설정할 필요는 없다. 필요할 때 하나씩 추가하며, 반복되는 작업이 보이면 그것을 자동화하는 것이 핵심이다.

Claude Code를 단순한 코드 작성 도구로만 사용한다면, 이미 가진 잠재력의 일부만 활용하는 것이다. 위 확장 포인트를 적극 활용해, 자신의 개발 workflow에 맞는 강력한 도구로 만들어갈 것을 권한다.

---

📚 출처

• Extend Claude Code - Claude Code Docs

• Understanding Claude Code's Full Stack: MCP, Skills, Subagents

• Claude Code Daily Driver: Skills, Subagents & MCP

• Claude Code: Plugins vs Skills vs Subagents

---

📚 출처

• https://news.hada.io/topic?id=29957