Claude Code Extensions 활용 가이드

| 기능 | MD 파일만? | 추가 필요 | ai-rules 관리 현황 | |------|-----------|---------|-----------------| | **Skills** | ✅ | 없음 | 🟡 일부 (`commands/playwrig

guide docs/guide/CLAUDE_CODE_EXTENSIONS.md

ai-rules에서 관리하거나 연동 가능한 Claude Code 확장 기능 정리. Claude Code 업데이트 시 이 문서를 체크리스트로 사용.

빠른 요약

기능	MD 파일만?	추가 필요	ai-rules 관리 현황
Skills	✅	없음	🟡 일부 (`commands/playwright.md`)
Agents	✅	없음	✅ `agents/` 디렉토리
Hooks	❌	settings.json + .sh	✅ governance/tooling adapter
Permissions	❌	settings.json	🟡 일부 (수동)
Plugins	❌	plugin.json 필수	❌ 미구현
MCP servers	❌	.mcp.json 필수	❌ 미구현
Keybindings	❌	keybindings.json	❌ 미구현
Status line	❌	settings.json	❌ 미구현

1. Skills (Slash Commands)

MD 파일만으로 바로 사용 가능.

파일 위치

~/.claude/commands/skill-name.md   → /skill-name  (전역, 모든 프로젝트)
.claude/commands/skill-name.md     → /skill-name  (프로젝트 전용)

Frontmatter 옵션

---
description: 스킬 설명 (Claude가 자동 호출 판단용, 강력 권장)
allowed-tools: Read, Bash(git:*), Edit
model: claude-opus-4-6     # 이 스킬 실행 시 모델 변경
shell: bash                # bash (기본) 또는 powershell
---

특수 문법

문법	설명
`$ARGUMENTS`	`/skill arg1 arg2` 의 전체 인자
!`command`	셸 명령 실행 후 결과 삽입 (전처리)

예시

---
description: Toggle Playwright MCP tools on or off
allowed-tools: Read, Edit
---

Current settings: !`cat ~/.claude/settings.json`

Toggle playwright tools. User request: $ARGUMENTS
- "on" → add all mcp__playwright__browser_* to permissions.allow
- "off" → remove all mcp__playwright__browser_* from permissions.allow

ai-rules 연동 계획

ai-rules/
└── skills/
    ├── global/          → sync 시 ~/.claude/commands/ 에 배포
    │   ├── playwright.md
    │   └── permissions.md
    └── {project}/       → sync 시 {project}/.claude/commands/ 에 배포

구현 필요: adapters/claude-code.mjs에 skills 배포 로직 + profiles/*.yaml에 skills 섹션 추가.

2. Agents (Subagents)

MD 파일만으로 사용 가능.

파일 위치

.claude/agents/agent-name.md   → /agent-name 또는 Claude가 자동 위임

Frontmatter 옵션

---
name: reviewer
description: PR 생성 전 코드 리뷰. 수정 없이 읽기만.
model: claude-opus-4-6
tools: Read, Glob, Grep
---

ai-rules 현황

✅ 이미 agents/ 디렉토리에서 관리 중. adapters/claude-code.mjs가 .claude/agents/ 에 배포.

개선 여지: frontmatter(model, tools) 자동 생성을 profiles/*.yaml에서 제어.

3. Hooks

settings.json + 셸 스크립트 필요.

ai-rules 현황

✅ adapters/governance.mjs → .claude/hooks/*.sh + settings.json ✅ adapters/tooling.mjs → husky, lint-staged

Hook 이벤트 (주요)

이벤트	용도
`PreToolUse`	명령 검증, 차단 (guard-branch, guard-secrets)
`PostToolUse`	자동 포맷, 로깅
`SessionStart`	컨텍스트 주입
`Stop`	작업 완료 검증
`PermissionRequest`	자동 승인/거부
`FileChanged`	파일 변경 감지 → 자동 sync

활용 아이디어

// SessionStart: 세션 시작 시 ACTIVE_WORK.md 자동 주입
{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "cat ~/.claude/ACTIVE_WORK.md 2>/dev/null || true"
    }]
  }]
}

4. Plugins

plugin.json 매니페스트 필요. 현재 미구현.

구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 필수 매니페스트
├── skills/                  # 스킬 모음
├── agents/                  # 에이전트 모음
├── hooks/hooks.json         # 훅 설정
└── .mcp.json                # MCP 서버

plugin.json 최소 구조

{
  "name": "ai-rules-plugin",
  "description": "ai-rules team rules as a Claude Code plugin",
  "version": "1.0.0",
  "author": { "name": "your-org" }
}

ai-rules 연동 계획

ai-rules 자체를 플러그인으로 패키징하면:

npm install ai-rules-plugin 한 번으로 팀 전체에 규칙 배포
skills, agents, hooks 일괄 설치

구현 조건: Plugin API 안정화 확인 후 진행. 추적: Claude Code changelog에서 plugin 키워드 모니터링.

5. MCP Servers

.mcp.json 필요. 현재 미구현.

파일 위치

~/.claude/mcp.json          → 전역 (모든 프로젝트)
.mcp.json                   → 프로젝트 전용

구조

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

ai-rules 연동 계획

# profiles/aitem.yaml
mcp:
  servers:
    - name: playwright
      command: npx
      args: ["@playwright/mcp"]
    - name: github
      command: npx
      args: ["@modelcontextprotocol/server-github"]

sync 시 .mcp.json 자동 생성.

구현 필요: adapters/ 에 mcp.mjs 추가 또는 claude-code.mjs 확장.

6. Permissions (현재 수동 관리)

settings.json 필요. 현재 일부 수동.

관리 도구

웹 대시보드: npm run permissions → http://localhost:3333
슬래시 커맨드: /playwright on|off|status

ai-rules 연동 계획

# profiles/global.yaml
permissions:
  allow:
    - "mcp__playwright__browser_*류 전체"
    - "WebFetch(domain:*)"

sync 시 ~/.claude/settings.json의 permissions.allow에 병합.

구현 필요: adapters/claude-code.mjs에 global settings.json 배포 로직 추가.

7. Keybindings

keybindings.json 필요. 현재 미구현.

파일 위치

~/.claude/keybindings.json   → 전역 (유일한 위치)

구조

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+enter": "chat:submit"
      }
    }
  ]
}

ai-rules 연동 계획

개인 취향이 강해 global.yaml에서 관리하기보다 별도 파일로:

ai-rules/
└── personal/
    └── keybindings.json    → sync 시 ~/.claude/keybindings.json 에 배포

업데이트 체크리스트

Claude Code 업데이트 시 아래 항목 확인:

Plugin API 안정화 → ai-rules를 플러그인으로 패키징
MCP registry 확장 → 새 유용한 MCP 서버 추가
새 Hook 이벤트 → FileChanged, ConfigChange 등 활용
Skills 새 frontmatter → paths, context: fork 등 신규 옵션
Permissions 와일드카드 → mcp__playwright__* 패턴 지원 여부
Agent 새 기능 → preload-skills, teammate 패턴 업데이트

구현 우선순위 제안

우선순위	기능	이유
🔴 즉시	Permissions → global.yaml 연동	수동 관리 번거로움
🔴 즉시	Skills → sync 배포	MD만 있으면 되므로 쉬움
🟠 다음	MCP servers → profiles 연동	프로젝트별 MCP 관리 필요
🟡 나중	Plugin 패키징	API 안정화 후
🟡 나중	Keybindings	개인 취향, 낮은 우선순위