10개월간 매일 사용하며 정리한 Claude Code 전체 세팅: 스킬, 훅, 서브에이전트, MCP, 플러그인, 그리고 실제로 효과 있었던 것들.
URL: https://x.com/affaanmustafa/status/2012378465664745795?s=46&t=mcSRNjoGZpvK980s1LdaWA
Title: X의 cogsec: “클로드 코드(Claude Code) 모든 것의 축약 가이드” / X
10개월간 매일 사용하며 정리한 제 전체 세팅입니다: 스킬, 훅, 서브에이전트, MCP, 플러그인, 그리고 실제로 효과 있었던 것들.
2월 실험적 롤아웃 때부터 Claude Code를 열성적으로 써 왔고, Anthropic x Forum Ventures 해커톤에서
그리고
Claude Code만으로
와 함께 우승했습니다.
cogsec
@affaanmustafa
NYC에서 열린
x
해커톤에서 우승했습니다. 주최해줘서 고마워요. 정말 좋은 이벤트였습니다(그리고 Anthropic 크레딧 15k도요).
그리고 저는 PMFProbe를 만들어 창업가들이 0 -> 1로 가도록 돕고, 프리 MVP 단계에서 아이디어를 검증하게 합니다. 곧 더 많은 소식을 공유할게요.
스킬(Skills)은 규칙처럼 동작하며, 특정 스코프와 워크플로에 제한됩니다. 특정 워크플로를 실행해야 할 때 쓰는 프롬프트의 축약형입니다.
Opus 4.5로 긴 코딩 세션을 마친 뒤, 죽은 코드와 느슨하게 흩어진 .md 파일을 정리하고 싶나요?
/refactor-clean을 실행하세요. 테스트가 필요하면? /tdd, /e2e, /test-coverage. 스킬과 커맨드는 한 프롬프트에서 서로 체이닝할 수 있습니다.
커맨드 체이닝
저는 체크포인트마다 코드맵(codemap)을 업데이트하는 스킬을 만들 수 있습니다. Claude가 탐색에 컨텍스트를 소모하지 않고도 코드베이스를 빠르게 탐색하게 해주는 방법이죠.
~/.claude/skills/codemap-updater.md
커맨드(Commands)는 슬래시 커맨드로 실행되는 스킬입니다. 겹치는 부분이 있지만 저장 위치가 다릅니다:
스킬(Skills): ~/.claude/skills - 더 넓은 워크플로 정의
커맨드(Commands): ~/.claude/commands - 빠르게 실행 가능한 프롬프트
bash
# Example skill structure
~/.claude/skills/
pmx-guidelines.md # Project-specific patterns
coding-standards.md # Language best practices
tdd-workflow/ # Multi-file skill with README.md
security-review/ # Checklist-based skill
훅(Hooks)은 특정 이벤트에서 발화되는 트리거 기반 자동화입니다. 스킬과 달리, 툴 호출(tool calls)과 라이프사이클 이벤트에 제한됩니다.
훅 유형(Hook Types)
PreToolUse - 툴이 실행되기 전(검증, 리마인더)
PostToolUse - 툴이 끝난 뒤(포맷팅, 피드백 루프)
UserPromptSubmit - 메시지를 보낼 때
Stop - Claude가 응답을 끝냈을 때
PreCompact - 컨텍스트 압축(compaction) 전에
Notification - 권한 요청
예시: 장시간 실행되는 커맨드 전 tmux 리마인더
json
{
"PreToolUse": [
{
"matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"",
"hooks": [
{
"type": "command",
"command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for session persistence' >&2; fi"
}
]
}
]
}
PostToolUse 훅을 실행할 때 Claude Code에서 받는 피드백 예시
프로 팁: JSON을 수동으로 쓰는 대신 hookify 플러그인을 사용하면 대화로 훅을 만들 수 있습니다. /hookify를 실행하고 원하는 것을 설명하세요.
서브에이전트(Subagents)는 오케스트레이터(메인 Claude)가 제한된 스코프로 작업을 위임할 수 있는 프로세스입니다. 백그라운드 또는 포그라운드로 실행할 수 있어 메인 에이전트의 컨텍스트를 절약할 수 있습니다.
서브에이전트는 스킬과 잘 어울립니다. 일부 스킬을 실행할 수 있는 서브에이전트에 작업을 위임하면, 그 스킬을 자율적으로 사용해 작업할 수 있습니다. 또한 특정 툴 권한으로 샌드박싱할 수도 있습니다.
bash
# Example subagent structure
~/.claude/agents/
planner.md # Feature implementation planning
architect.md # System design decisions
tdd-guide.md # Test-driven development
code-reviewer.md # Quality/security review
security-reviewer.md # Vulnerability analysis
build-error-resolver.md
e2e-runner.md
refactor-cleaner.md
적절한 스코핑을 위해 서브에이전트별로 허용 툴, MCP, 권한을 구성하세요.
.rules 폴더에는 Claude가 항상 따라야 하는 베스트 프랙티스를 담은 .md 파일이 들어갑니다. 두 가지 접근이 있습니다:
.md 파일들bash
~/.claude/rules/
security.md # No hardcoded secrets, validate inputs
coding-style.md # Immutability, file organization
testing.md # TDD workflow, 80% coverage
git-workflow.md # Commit format, PR process
agents.md # When to delegate to subagents
performance.md # Model selection, context management
규칙 예시:
코드베이스에서 이모지 금지
프론트엔드에서 보라색 계열 색상 지양
배포 전 항상 코드 테스트
거대한 단일 파일보다 모듈형 코드 우선
console.log를 커밋하지 않기
MCP는 Claude를 외부 서비스에 직접 연결합니다. API를 대체하는 것은 아니라, 프롬프트 기반 래퍼로서 더 유연하게 정보를 탐색할 수 있게 해줍니다.
예: Supabase MCP는 Claude가 특정 데이터를 가져오고, 복사/붙여넣기 없이 상류(Upstream)에서 직접 SQL을 실행하게 해줍니다. DB나 배포 플랫폼 등도 마찬가지입니다.
Supabase MCP가 public 스키마 내 테이블을 나열하는 예시
Claude 안의 Chrome: Claude가 브라우저를 자율적으로 조작(클릭 등)해 동작을 확인할 수 있게 해주는 내장 플러그인 MCP입니다.
중요(CRITICAL): 컨텍스트 윈도우 관리
MCP를 엄선하세요. 저는 모든 MCP를 유저 설정에 넣되, 쓰지 않는 건 전부 비활성화합니다. /plugins로 들어가 아래로 스크롤하거나 /mcp를 실행하세요.
압축(compacting) 전 200k 컨텍스트 윈도우가, 너무 많은 툴을 켜면 70k 정도로 줄어들 수 있습니다. 성능이 크게 저하됩니다.
/plugins로 MCP로 이동해 현재 설치된 것과 상태를 확인하는 모습
경험칙: 설정에는 MCP를 20~30개 넣되, 활성화는 10개 미만 / 활성 툴은 80개 미만으로 유지하세요.
플러그인(Plugins)은 번거로운 수동 설정 대신, 툴을 쉽게 설치할 수 있도록 패키징해줍니다. 플러그인은 스킬 + MCP 조합이 될 수도 있고, 훅/툴 번들을 포함할 수도 있습니다.
플러그인 설치:
bash
# Add a marketplace
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
# Open Claude, run /plugins, find new marketplace, install from there
새로 설치된 Mixedbread-Grep 마켓플레이스를 표시하는 화면
LSP 플러그인: 에디터 밖에서 Claude Code를 자주 실행한다면 특히 유용합니다. LSP(Language Server Protocol)는 IDE를 열지 않아도 실시간 타입 체크, 정의로 이동(go-to-definition), 지능형 완성 기능을 제공합니다.
bash
# Enabled plugins example
typescript-lsp@claude-plugins-official # TypeScript intelligence
pyright-lsp@claude-plugins-official # Python type checking
hookify@claude-plugins-official # Create hooks conversationally
mgrep@Mixedbread-Grep # Better search than ripgrep
MCP와 같은 경고가 적용됩니다. 컨텍스트 윈도우를 주시하세요.
키보드 단축키(Keyboard Shortcuts)
Ctrl+U - 전체 줄 삭제(백스페이스 연타보다 빠름)
! - 빠른 bash 커맨드 접두어
@ - 파일 검색
/ - 슬래시 커맨드 시작
Shift+Enter - 여러 줄 입력
Tab - thinking 표시 토글
Esc Esc - Claude 중단 / 코드 복구
병렬 워크플로(Parallel Workflows)
/fork - 큐에 메시지를 쌓아두는 대신, 겹치지 않는 작업은 대화(컨버세이션)를 포크해 병렬로 처리
Git Worktrees - 충돌 없이 겹치는 병렬 Claude를 돌리기 위함. 각 worktree는 독립 체크아웃
bash
git worktree add ../feature-branch feature-branch
# Now run separate Claude instances in each worktree
tmux로 장시간 실행 커맨드 관리: Claude가 실행하는 로그/bash 프로세스를 스트리밍하며 모니터링.
Claude Code가 프론트엔드/백엔드 서버를 띄우게 하고 tmux로 세션에 붙어 로그를 모니터링하는 모습
bash
tmux new -s dev
# Claude runs commands here, you can detach and reattach
tmux attach -t dev
mgrep > grep: mgrep는 ripgrep/grep보다 크게 개선된 도구입니다. 플러그인 마켓플레이스로 설치한 뒤 /mgrep 스킬을 사용하세요. 로컬 검색과 웹 검색 모두 동작합니다.
bash
mgrep "function handleSubmit" # Local search
mgrep --web "Next.js 15 app router changes" # Web search
기타 유용한 커맨드(Other Useful Commands)
/rewind - 이전 상태로 되돌리기
/statusline - 브랜치, 컨텍스트 %, TODO 등을 커스터마이즈
/checkpoints - 파일 단위 undo 포인트
/compact - 컨텍스트 압축 수동 트리거
GitHub Actions CI/CD
GitHub Actions로 PR 코드 리뷰를 설정하세요. 구성만 해두면 Claude가 PR을 자동으로 리뷰할 수 있습니다.
버그 수정 PR을 승인하는 Claude
샌드박싱(Sandboxing)
위험한 작업은 샌드박스 모드를 사용하세요. Claude가 제한된 환경에서 실행되어 실제 시스템에 영향을 주지 않습니다. (반대로 --dangerously-skip-permissions를 쓰면 Claude가 제한 없이 돌아다니게 됩니다. 주의하지 않으면 파괴적일 수 있습니다.)
에디터는 필요하진 않지만, Claude Code 워크플로에 긍정적/부정적으로 영향을 줄 수 있습니다. Claude Code는 어떤 터미널에서도 동작하지만, 괜찮은 에디터와 함께 쓰면 실시간 파일 추적, 빠른 내비게이션, 통합 커맨드 실행이 가능해집니다.
Zed(제 선호)
저는
Zed가 Claude Code와 잘 맞는 이유:
에이전트 패널 통합 - Zed의 Claude 통합은 Claude가 편집하는 파일 변경을 실시간으로 추적할 수 있게 해줍니다. Claude가 참조하는 파일 사이를 에디터를 떠나지 않고 이동할 수 있습니다.
성능 - Rust로 작성되어 즉시 열리고, 큰 코드베이스도 버벅임 없이 처리합니다.
CMD+Shift+R 커맨드 팔레트 - 커스텀 슬래시 커맨드, 디버거, 툴을 검색 가능한 UI에서 빠르게 접근. 터미널로 전환하지 않고도 빠른 커맨드를 실행할 수 있습니다.
최소 리소스 사용 - 무거운 작업 중 Claude와 시스템 리소스를 두고 경쟁하지 않습니다.
Vim 모드 - 원한다면 완전한 vim 키바인딩 제공
CMD+Shift+R로 커스텀 커맨드 드롭다운을 띄운 Zed 에디터.
팔로잉 모드는 오른쪽 아래의 과녁(bullseye)으로 표시됩니다.
화면 분할 - 한쪽은 Claude Code 터미널, 다른 쪽은 에디터로
Ctrl + G - Zed에서 Claude가 현재 작업 중인 파일을 빠르게 열기
자동 저장 - Claude의 파일 읽기가 항상 최신이 되도록 autosave 활성화
Git 통합 - 커밋 전 에디터의 git 기능으로 Claude 변경사항 리뷰
파일 워처 - 대부분의 에디터는 변경된 파일을 자동 리로드. 이것이 활성화됐는지 확인
VSCode / Cursor
이 또한 유효한 선택지이며 Claude Code와 잘 맞습니다. 터미널 형태로 사용하면서 \ide로 에디터 자동 동기화를 활성화해 LSP 기능을 사용할 수 있습니다(지금은 플러그인으로 다소 중복). 또는 에디터에 더 통합되고 UI가 맞춰진 확장(extension)을 선택할 수도 있습니다.
문서에서 직접 발췌
플러그인
설치됨: (저는 보통 한 번에 4~5개만 활성화해 둡니다)
markdown
ralph-wiggum@claude-code-plugins # Loop automation
frontend-design@claude-code-plugins # UI/UX patterns
commit-commands@claude-code-plugins # Git workflow
security-guidance@claude-code-plugins # Security checks
pr-review-toolkit@claude-code-plugins # PR automation
typescript-lsp@claude-plugins-official # TS intelligence
hookify@claude-plugins-official # Hook creation
code-simplifier@claude-plugins-official
feature-dev@claude-code-plugins
explanatory-output-style@claude-code-plugins
code-review@claude-code-plugins
context7@claude-plugins-official # Live documentation
pyright-lsp@claude-plugins-official # Python types
mgrep@Mixedbread-Grep # Better search
MCP 서버
구성됨(유저 레벨):
json
{
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
"firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] },
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"]
},
"memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
},
"vercel": { "type": "http", "url": "https://mcp.vercel.com" },
"railway": { "command": "npx", "args": ["-y", "@railway/mcp-server"] },
"cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" },
"cloudflare-workers-bindings": {
"type": "http",
"url": "https://bindings.mcp.cloudflare.com/mcp"
},
"cloudflare-workers-builds": { "type": "http", "url": "https://builds.mcp.cloudflare.com/mcp" },
"cloudflare-observability": {
"type": "http",
"url": "https://observability.mcp.cloudflare.com/mcp"
},
"clickhouse": { "type": "http", "url": "https://mcp.clickhouse.cloud/mcp" },
"AbletonMCP": { "command": "uvx", "args": ["ableton-mcp"] },
"magic": { "command": "npx", "args": ["-y", "@magicuidesign/mcp@latest"] }
}
프로젝트별 비활성화(컨텍스트 윈도우 관리):
markdown
# In ~/.claude.json under projects.[path].disabledMcpServers
disabledMcpServers: [
"playwright",
"cloudflare-workers-builds",
"cloudflare-workers-bindings",
"cloudflare-observability",
"cloudflare-docs",
"clickhouse",
"AbletonMCP",
"context7",
"magic"
]
이게 핵심입니다. MCP를 14개 구성해두되, 프로젝트마다 약 5~6개만 활성화합니다. 컨텍스트 윈도우를 건강하게 유지해줘요.
핵심 훅(Key Hooks)
json
{
"PreToolUse": [
// tmux reminder for long-running commands
{ "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux reminder"] },
// Block unnecessary .md file creation
{ "matcher": "Write && .md file", "hooks": ["block unless README/CLAUDE"] },
// Review before git push
{ "matcher": "git push", "hooks": ["open editor for review"] }
],
"PostToolUse": [
// Auto-format JS/TS with Prettier
{ "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] },
// TypeScript check after edits
{ "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] },
// Warn about console.log
{ "matcher": "Edit", "hooks": ["grep console.log warning"] }
],
"Stop": [
// Audit for console.logs before session ends
{ "matcher": "*", "hooks": ["check modified files for console.log"] }
]
}
커스텀 상태줄(Custom Status Line)
사용자, 디렉터리, dirty 표시 포함 git 브랜치, 남은 컨텍스트 %, 모델, 시간, TODO 개수를 표시:
Mac 루트 디렉터리에서의 statusline 예시
Rules 구조(Rules Structure)
markdown
~/.claude/rules/
security.md # Mandatory security checks
coding-style.md # Immutability, file size limits
testing.md # TDD, 80% coverage
git-workflow.md # Conventional commits
agents.md # Subagent delegation rules
patterns.md # API response formats
performance.md # Model selection (Haiku vs Sonnet vs Opus)
hooks.md # Hook documentation
서브에이전트(Subagents)
markdown
~/.claude/agents/
planner.md # Break down features
architect.md # System design
tdd-guide.md # Write tests first
code-reviewer.md # Quality review
security-reviewer.md # Vulnerability scan
build-error-resolver.md
e2e-runner.md # Playwright tests
refactor-cleaner.md # Dead code removal
doc-updater.md # Keep docs synced
과하게 복잡하게 만들지 말 것 - 설정은 아키텍처가 아니라 파인튜닝으로 다뤄라
컨텍스트 윈도우는 귀중하다 - 쓰지 않는 MCP와 플러그인은 비활성화
병렬 실행 - 대화 포크, git worktrees 사용
반복을 자동화 - 포맷팅, 린팅, 리마인더에 훅 사용
서브에이전트 스코프를 제한 - 제한된 툴 = 집중된 실행
[
]
]
참고: 이 내용은 상세 중 일부입니다. 사람들이 관심 있다면 세부 주제로 더 많은 글을 올릴 수도 있어요.