소속팀: AI플랫폼엔지니어링 작성자: 손재홍
안녕하세요. AI 플랫폼 엔지니어링팀 손재홍입니다.
최근 Claude Code의 Skills, MCP, Hooks 체계를 다시 정리했습니다. PDP에는 Claude Code Skills, MCP, Hooks를 활용해 팀 단위 AI 코딩 표준 워크플로우를 설계하고 적용하는 목표로 기록해두었습니다. 이전에 Claude Code 기본 사용법, CLAUDE.md, 고급 워크플로우, Cursor MCP를 각각 정리했기 때문에 이번 글은 개인 생산성보다는 팀 표준화 관점으로 봤습니다.
Claude Code를 개인이 혼자 쓰면 빠른 코드 수정이나 문서 정리에 도움이 됩니다. 하지만 팀 단위로 쓰려면 다른 문제가 생깁니다. 사람마다 prompt 방식이 다르고, 프로젝트 실행 방법을 매번 다시 설명하고, 어떤 MCP server를 써야 하는지 헷갈리고, 수정 후 어떤 검증을 해야 하는지도 달라질 수 있습니다. 결국 AI 도구를 쓰는데도 작업 방식은 개인별로 흩어질 수 있습니다.
이번 학습에서 본 핵심은 이 흩어짐을 어떻게 줄일 것인가였습니다. Skills는 반복 절차를 문서화하고, MCP는 공통 도구와 데이터 source를 연결하고, Hooks는 특정 시점에 검증을 자동 실행합니다. 여기에 settings scope를 이해하면 무엇을 개인 설정으로 둘지, 무엇을 project 설정으로 공유할지 구분할 수 있습니다.
Skills는 반복 지시를 절차로 빼는 방식
Claude Code 공식 문서에서는 Skills를 Claude의 capability를 확장하는 방법으로 설명합니다. `SKILL.md` 파일에 지시를 작성하면 Claude가 필요할 때 해당 skill을 toolkit에 추가합니다. 같은 지시, checklist, multi-step procedure를 계속 Chat에 붙여 넣고 있다면 skill로 만들 수 있다고 설명합니다.
이 설명이 실무적으로 좋았습니다. AI 도구를 쓰다 보면 처음에는 prompt로 시작합니다. 예를 들어 “변경사항 요약해줘”, “위험한 부분 찾아줘”, “테스트 기준 확인해줘”, “배포 전 점검해줘” 같은 요청을 매번 씁니다. 그런데 이런 요청이 반복되면 Chat에 계속 붙여 넣는 것보다 skill로 빼는 편이 낫습니다.
Skill과 CLAUDE.md의 차이도 중요합니다. CLAUDE.md는 프로젝트의 상시 context에 가깝습니다. coding convention, 금지 작업, 테스트 명령, repository 구조처럼 거의 모든 작업에 필요한 사실을 넣는 것이 맞습니다. 반면 skill은 특정 작업을 할 때만 필요한 절차입니다. 공식 문서에서도 skill body는 사용될 때만 load되기 때문에 긴 reference material은 필요할 때까지 거의 비용이 들지 않는다고 설명합니다.
팀 기준으로 보면 이것은 context 관리 문제입니다. 모든 절차를 CLAUDE.md에 넣으면 Claude가 매번 너무 많은 규칙을 읽게 됩니다. 반대로 아무것도 넣지 않으면 매번 같은 설명을 해야 합니다. 그래서 상시 규칙은 CLAUDE.md, 반복 작업 절차는 Skills로 나누는 것이 좋아 보였습니다.
예를 들어 데이터 플랫폼 프로젝트라면 다음과 같은 skills를 생각해볼 수 있습니다.
- `/summarize-changes`: 현재 변경사항을 요약하고 위험 요소를 확인
- `/review-pipeline`: 데이터 파이프라인 변경사항을 운영 관점으로 검토
- `/prepare-release-note`: 배포 변경사항을 릴리즈 노트 형식으로 정리
- `/check-data-quality-change`: DQ rule이나 schema 변경의 영향 확인
- `/incident-note`: 장애 대응 메모 초안 작성
중요한 것은 skill을 너무 크게 만들지 않는 것입니다. “모든 것을 다 해주는 skill”보다 특정 반복 업무를 안정적으로 처리하는 skill이 좋습니다. 공식 문서에서도 complex skill의 경우 supporting files를 둘 수 있지만, main skill은 focused하게 유지하라고 설명합니다.
Skill 위치는 공유 범위를 결정한다
Claude Code 문서에서는 skill을 어디에 두는지에 따라 적용 범위가 달라진다고 설명합니다. Personal skill은 `~/.claude/skills/`에 두고 모든 project에서 쓸 수 있습니다. Project skill은 `.claude/skills/`에 두고 해당 project에서만 씁니다. Enterprise skill은 조직 전체에 적용될 수 있고, plugin skill은 plugin이 enabled된 곳에서 동작합니다.
팀 표준화 관점에서는 Project skill이 중요합니다. 특정 repository에서 모두가 같은 방식으로 리뷰하고, 같은 방식으로 검증하고, 같은 방식으로 배포 메모를 만들려면 `.claude/skills/`에 넣고 git으로 관리하는 방식이 자연스럽습니다. 반대로 개인 메모 정리나 개인 선호 prompt는 user scope에 두는 것이 맞습니다.
공식 문서에는 skill name conflict의 우선순위도 나옵니다. Enterprise가 personal보다 우선하고, personal이 project보다 우선합니다. Plugin skill은 namespace를 사용하기 때문에 일반 skill과 충돌하지 않습니다. 팀에서 같은 이름의 skill을 만들 때 이런 우선순위를 알아야 합니다. 개인 skill이 project skill을 덮어쓰면 팀 표준이 기대한 대로 동작하지 않을 수 있습니다.
또 하나 중요한 것은 automatic discovery입니다. Claude Code는 시작 directory와 상위 디렉터리의 `.claude/skills/`를 찾고, subdirectory에서 작업할 때 nested `.claude/skills/`도 on-demand로 발견할 수 있습니다. monorepo에서는 package별 skill을 둘 수 있다는 뜻입니다. 데이터 플랫폼에서도 ingestion, transformation, serving, monitoring 같은 하위 영역마다 다른 skill이 필요할 수 있습니다.
제가 보기에는 팀 표준을 만들 때 아래처럼 나누는 것이 현실적입니다.
- Repository root: 공통 review, release note, test guide skill
- `pipelines/`: pipeline 변경 검토 skill
- `infra/`: IaC, permission, network 검토 skill
- `docs/`: 문서 요약과 B-Brain 초안 skill
- 개인 scope: 개인 보고, 개인 학습 메모 skill
이렇게 하면 모든 것을 하나의 거대한 prompt로 넣지 않고, 작업 위치에 따라 필요한 절차만 불러올 수 있습니다.
MCP는 공통 도구와 데이터 source를 연결한다
MCP는 Model Context Protocol의 약자입니다. Claude Code 공식 문서는 MCP server가 Claude Code에 tools, databases, APIs 접근을 제공한다고 설명합니다. Issue tracker, monitoring dashboard, database, design tool, Slack 같은 외부 시스템의 데이터를 Chat에 복사해서 붙여 넣고 있다면 MCP server 연결을 고려할 수 있습니다.
개인 작업에서는 복사해서 붙여 넣는 방식도 충분할 수 있습니다. 하지만 팀 단위에서는 문제가 됩니다. 어떤 사람은 issue를 붙여 넣고, 어떤 사람은 log 일부만 붙여 넣고, 어떤 사람은 dashboard 수치를 말로 설명합니다. 그러면 Claude가 보는 context가 매번 다릅니다. MCP는 이런 부분을 표준화할 수 있습니다.
예를 들어 데이터 플랫폼 팀에서는 다음 MCP server가 유용할 수 있습니다.
- GitHub 또는 GitLab: issue, PR, diff, review comment 조회
- Monitoring: error, alert, trace, job 상태 조회
- Database read-only endpoint: schema, sample count, metadata 조회
- Documentation: 내부 runbook, 운영 문서, API 문서 검색
- Ticket system: 작업 요구사항과 acceptance criteria 조회
공식 문서에서는 MCP server를 연결하면 Claude에게 “JIRA issue 기반으로 기능 구현하고 GitHub PR을 만들어줘”, “Sentry와 Statsig를 확인해줘”, “PostgreSQL에서 사용자를 조회해줘” 같은 요청을 할 수 있다고 예시를 듭니다. 데이터 플랫폼 업무에 맞추면 “최근 실패한 job의 log를 보고 원인 후보를 정리해줘”, “이 PR이 어떤 pipeline에 영향을 주는지 확인해줘” 같은 방향이 됩니다.
다만 MCP는 편한 만큼 조심해야 합니다. 공식 문서도 server를 연결하기 전에 신뢰할 수 있는지 확인하라고 안내합니다. 외부 content를 가져오는 server는 prompt injection 위험에 노출될 수 있다고 설명합니다. 특히 monitoring log, issue, 문서, comment는 외부 입력이 섞일 수 있습니다. AI가 읽는 context가 곧 지시처럼 작동할 수 있기 때문에, MCP server는 권한과 source를 신중하게 봐야 합니다.
팀 기준으로는 MCP server를 아무나 각자 추가하는 방식보다 project 또는 managed 설정으로 관리하는 편이 좋습니다. 읽기 전용으로 충분한 server는 write 권한을 주지 않고, 운영 DB는 sample과 metadata 조회만 허용하고, 민감정보가 섞인 로그는 masking 후 제공하는 식의 기준이 필요합니다.
Hooks는 검증을 자동화하는 장치
Hooks는 Claude Code session lifecycle의 특정 시점에 자동으로 실행되는 user-defined shell command, HTTP endpoint, LLM prompt입니다. 공식 문서에 따르면 hook은 `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` 같은 event에서 실행될 수 있습니다. 특히 `PreToolUse`는 tool 실행 전에 block할 수 있고, `PostToolUse`는 tool 성공 후 실행됩니다.
이 기능은 팀 표준화에서 중요합니다. AI가 코드를 수정한 뒤 사람이 매번 “테스트 돌렸어?”, “포맷 맞췄어?”, “민감정보 확인했어?”라고 물어보는 것은 비효율적입니다. 자주 확인해야 하는 것은 hook으로 옮길 수 있습니다.
예를 들어 공식 문서에는 `Write|Edit` 후 style check script를 실행하는 예시가 나옵니다. 데이터 플랫폼 프로젝트에서는 아래 같은 hook을 생각할 수 있습니다.
- `PostToolUse` with `Write|Edit`: formatting, lint, unit test 후보 실행
- `PreToolUse` with `Bash`: 위험한 command block 또는 확인 요청
- `Stop`: 변경 요약, 미검증 항목, 다음 action 출력
- `SessionStart`: project 상태, branch, 주요 지침 표시
- `PostToolBatch`: 여러 tool call 이후 한번에 consistency check
Hooks는 자동화지만 만능은 아닙니다. 잘못 만들면 작업을 방해하거나 너무 자주 실행되어 비용과 시간이 늘 수 있습니다. 그래서 모든 검증을 hook으로 넣기보다, 짧고 확실한 것부터 넣는 것이 맞습니다. 예를 들어 포맷 검사, 금지 문자열 검사, 민감정보 패턴 검사, 특정 directory 수정 시 테스트 안내 정도가 첫 후보입니다.
Claude Code 문서는 hooks가 settings file, plugin, skill, subagent에 정의될 수 있다고 설명합니다. Skill이나 agent frontmatter에 hook을 넣으면 해당 component가 active일 때만 hook이 동작합니다. 이 점도 중요합니다. 모든 작업에 전체 hook을 걸지 않고, 배포 skill이 실행될 때만 배포 전 검증 hook을 돌리거나, secure operation skill에서만 Bash command security check를 수행할 수 있습니다.
Settings scope를 알아야 팀 공유가 가능하다
Claude Code settings 문서는 configuration scope를 Managed, User, Project, Local로 나눕니다. Managed는 조직이나 IT가 강제하는 설정이고, User는 개인 전체 project에 적용되는 설정입니다. Project는 repository의 `.claude/`에 들어가고 팀과 공유되며, Local은 `.claude/settings.local.json`처럼 개인의 repository별 override에 가깝습니다.
팀 단위 표준화에서는 Project scope가 핵심입니다. 공식 문서에서도 Project scope는 team-shared settings, permissions, hooks, MCP servers, plugins처럼 collaborators across repository에 표준화해야 하는 도구에 적합하다고 설명합니다. 반대로 API key, 개인 theme, 개인 preference는 User나 Local로 가야 합니다.
이 구분이 없으면 보안과 협업이 모두 꼬일 수 있습니다. 예를 들어 project settings에 개인 token을 넣으면 안 됩니다. 반대로 팀이 모두 써야 하는 hook이나 MCP server를 local에만 넣으면 다른 사람은 같은 workflow를 재현할 수 없습니다.
제가 정리한 기준은 아래와 같습니다.
- Managed: 조직 보안 정책, 금지 도구, 필수 permission rule
- Project: 팀 공통 hooks, project MCP server, 공통 skills, repository 규칙
- User: 개인 도구, 개인 skill, 개인 인증 정보
- Local: 실험 중인 설정, 개인 machine path, 임시 override
결국 팀 표준은 project에 있어야 하고, 개인 비밀은 project에 있으면 안 됩니다. 이 단순한 기준만 지켜도 사고 가능성을 줄일 수 있습니다.
팀 표준 워크플로우로 묶는 방법
Skills, MCP, Hooks, Settings를 따로 보면 기능이 많아 보입니다. 하지만 팀 표준 워크플로우로 묶으면 역할이 분명해집니다.
첫째, CLAUDE.md에는 항상 필요한 규칙을 둡니다. 예를 들어 repository 구조, coding convention, 테스트 명령, 금지 작업, 민감정보 처리 기준입니다.
둘째, Skills에는 반복 작업 절차를 둡니다. 예를 들어 PR review, pipeline 변경 검토, release note 작성, incident note 작성입니다.
셋째, MCP에는 Claude가 직접 확인해야 하는 외부 context를 연결합니다. Issue, PR, monitoring, docs, read-only metadata가 후보입니다.
넷째, Hooks에는 자동으로 확인해야 하는 검증을 둡니다. Formatting, lint, test, secret scan, 위험 command check가 후보입니다.
다섯째, Settings scope로 공유 범위를 정합니다. 팀 공통은 project, 개인 설정은 user/local, 조직 보안은 managed에 둡니다.
이 구조가 있으면 Claude Code를 쓰는 방식이 개인별로 덜 흔들립니다. 신규 참여자도 “이 repository에서는 어떤 skill을 쓰고, 어떤 MCP가 연결되어 있고, 수정 후 어떤 hook이 돌고, 어떤 규칙을 지켜야 하는지”를 빠르게 이해할 수 있습니다.
데이터 플랫폼 업무에 적용해보기
데이터 플랫폼 프로젝트에서 AI 코딩 표준을 만든다면 처음부터 거창하게 만들 필요는 없어 보입니다. 작은 workflow 하나부터 시작하는 것이 좋습니다. 예를 들어 pipeline 변경 검토 workflow입니다.
이 workflow는 아래처럼 구성할 수 있습니다.
- CLAUDE.md: pipeline directory 구조, naming rule, 테스트 명령, 금지 작업을 적습니다.
- Skill: `/review-pipeline-change`를 만들고 schema, source, target, partition, retry, monitoring 관점으로 검토하게 합니다.
- MCP: issue와 PR diff, 가능하면 read-only metadata를 조회하게 합니다.
- Hook: 파일 수정 후 lint나 simple validation을 실행합니다.
- Stop hook: 변경 요약, 검증 여부, 남은 확인 사항을 출력합니다.
이 정도만 해도 AI가 하는 작업이 훨씬 예측 가능해집니다. 매번 “이 부분도 확인해줘”라고 말하는 대신 skill과 hook이 기본 확인 항목을 챙깁니다. 사람은 더 중요한 판단, 예를 들어 운영 영향이나 배포 시점, 고객 커뮤니케이션을 봅니다.
또 다른 후보는 incident note workflow입니다. 장애 대응 후 log와 변경사항을 바탕으로 원인 후보, 조치, 재발 방지, 추가 확인 사항을 정리하는 skill을 만들 수 있습니다. 여기에 monitoring MCP가 연결되면 log나 alert 정보를 직접 가져올 수 있습니다. 단, 이 경우 민감정보 masking과 read-only 권한이 반드시 필요합니다.
주의할 점
팀 표준화는 편하지만 잘못하면 오히려 복잡해질 수 있습니다. Skill이 너무 많으면 어떤 것을 써야 하는지 모릅니다. MCP server가 너무 많으면 권한과 보안 관리가 어려워집니다. Hook이 너무 많으면 매 작업마다 시간이 오래 걸리고, 작은 수정도 번거로워집니다.
그래서 처음 기준은 작게 잡는 것이 좋습니다.
- Skill은 자주 반복되는 3개 업무부터 만든다.
- MCP는 read-only 위주로 시작한다.
- Hook은 빠르고 확실한 검증만 넣는다.
- Project settings에는 팀 공통만 넣는다.
- 민감정보와 token은 절대 repository에 넣지 않는다.
또 하나 중요한 점은 “AI가 자동으로 하게 만들기”보다 “AI가 같은 기준으로 일하게 만들기”가 먼저라는 것입니다. 모든 것을 자동화하려고 하면 실패했을 때 원인을 찾기 어렵습니다. 먼저 사람의 기준을 skill과 hook으로 옮기고, 그 다음 반복 가능한 부분만 자동화하는 순서가 좋아 보입니다.
마무리
Claude Code Skills, MCP, Hooks를 정리하면서 느낀 것은, 팀 단위 AI 코딩 표준은 하나의 기능으로 완성되지 않는다는 점입니다. Skills는 절차를 담고, MCP는 context를 연결하고, Hooks는 검증을 자동화하고, Settings는 공유 범위를 정합니다. 이 네 가지가 같이 있어야 팀 workflow가 안정됩니다.
개인 생산성 도구로 Claude Code를 쓰는 것과 팀 표준으로 쓰는 것은 다릅니다. 개인은 빠르게 시도하고 수정하면 됩니다. 팀은 재현성, 권한, 검증, onboarding을 같이 봐야 합니다. 그래서 prompt만 잘 쓰는 것보다 project 안에 어떤 규칙과 도구를 남길지가 중요합니다.
이번 학습은 Claude Code를 단순 AI 코딩 도구가 아니라 팀 개발 환경을 표준화하는 도구로 보는 계기가 되었습니다. 다음 단계에서는 실제 프로젝트에서 가장 반복되는 작업 하나를 골라 skill과 hook 형태로 작게 만들어보는 것이 좋겠습니다.
참고 자료
- Claude Code Docs: Extend Claude with skills
- Claude Code Docs: Connect Claude Code to tools via MCP
- Claude Code Docs: Hooks reference
- Claude Code Docs: Claude Code settings
- Model Context Protocol official documentation