나의 실제 Claude Code 환경 셋팅을 정리한 문서. 설치부터 플러그인, MCP 서버, Hooks, 커스텀 스킬까지 전체 구성을 다룬다. 2026년 2월 기준.
| 항목 | 값 |
|---|---|
| OS | macOS (Darwin) |
| Terminal | Ghostty |
| Shell | zsh |
| Node.js | v24.13.0 |
| npm | 11.6.2 |
| pnpm | 10.28.0 |
| Claude Code | v2.1.44 |
| Theme | dark-daltonized |
curl -fsSL https://claude.ai/install.sh | bash
설치 후 터미널에서 claude 명령어로 실행할 수 있다.
Claude Code의 설정은 ~/.claude/ 디렉토리에 모여 있다.
~/.claude/
├── CLAUDE.md # 글로벌 지시사항 (모든 프로젝트에 적용)
├── settings.json # CLI 설정 (권한, 플러그인, HUD, Hooks 등)
├── keybindings.json # 키 바인딩 커스터마이징 (선택)
├── skills/ # 커스텀 스킬 (Git 저장소 심볼릭 링크)
├── plugins/ # 설치된 플러그인
│ └── marketplaces/
│ ├── claude-plugins-official/ # 공식 플러그인 마켓플레이스
│ └── omc/ # OMC 플러그인
├── hooks/ # 이벤트 훅 스크립트
│ └── peon-ping/ # 알림 사운드 훅
├── hud/ # HUD 스크립트
├── projects/ # 프로젝트별 메모리 및 설정
└── transcripts/ # 세션 기록
~/.claude.json은 별도 파일로, MCP 서버 등록에 사용된다.~/.claude/디렉토리 안이 아님에 주의.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"permissions": {
"allow": [
"Bash(./gradlew build)",
"Bash(./gradlew test)",
"Bash(yarn install)",
"Bash(yarn test)",
"Bash(yarn lint)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(git push --force)",
"Read(.env)"
],
"ask": [
"Bash(git push:*)"
],
"defaultMode": "dontAsk"
},
"enableAllProjectMcpServers": true,
"hooks": { ... },
"statusLine": {
"type": "command",
"command": "node ~/.claude/hud/omc-hud.mjs"
},
"enabledPlugins": {
"oh-my-claudecode@omc": true,
"typescript-lsp@claude-plugins-official": true,
"kotlin-lsp@claude-plugins-official": true
},
"language": "Korean",
"autoUpdatesChannel": "latest",
"skipDangerousModePermissionPrompt": true
}
| 설정 | 설명 |
|---|---|
permissions.defaultMode |
dontAsk로 설정하면 허용/거부 목록 외의 작업도 자동 실행 |
permissions.allow |
빌드, 테스트, lint 등 자주 쓰는 안전한 명령어를 자동 허용 |
permissions.deny |
위험한 명령어(rm -rf /, git push --force)와 .env 파일 읽기를 차단 |
permissions.ask |
git push는 항상 사용자 확인 후 실행 |
enableAllProjectMcpServers |
프로젝트 .mcp.json의 MCP 서버를 자동 활성화 |
enabledPlugins |
OMC, TypeScript LSP, Kotlin LSP 플러그인 활성화 |
statusLine |
OMC HUD를 상태 표시줄에 표시 |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS |
실험적 Agent Teams 기능 활성화 |
language |
응답 언어를 한국어로 설정 |
skipDangerousModePermissionPrompt |
위험한 모드 전환 시 확인 프롬프트 건너뛰기 |
Claude Code는 특정 이벤트 발생 시 커스텀 스크립트를 실행할 수 있다. 현재 peon-ping을 사용하여 사운드 알림을 설정 중이다.
| 이벤트 | 설명 |
|---|---|
SessionStart |
세션 시작 시 사운드 재생 |
UserPromptSubmit |
사용자 프롬프트 제출 시 사운드 재생 |
Stop |
에이전트 작업 완료 시 사운드 재생 |
Notification |
알림 발생 시 사운드 재생 |
PermissionRequest |
권한 요청 시 사운드 재생 |
settings.json의 hooks 필드에 이벤트별 훅을 등록한다:
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/peon-ping/peon.sh",
"timeout": 10
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/peon-ping/peon.sh",
"timeout": 10
}
]
}
]
}
}
모든 이벤트에 동일한
peon.sh스크립트를 등록하면 peon-ping이 이벤트 유형에 따라 자동으로 다른 사운드를 재생한다.
Claude Code의 기능을 대폭 확장하는 커뮤니티 플러그인.
Claude Code에서 아래 프롬프트 입력:
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode
이후 OMC 셋업:
/oh-my-claudecode:omc-setup 출력은 한글로 해줘
/autopilot # 아이디어에서 완성 코드까지 자율 실행
/ralph # 아키텍트 검증 루프 방식 자율 실행
/plan # 전략적 계획 수립
/code-review # 종합 코드 리뷰
/security-review # 보안 리뷰
/team # 멀티 에이전트 팀 협업
/note # 메모 저장 (컨텍스트 압축 대비)
/deepsearch # 코드베이스 심층 검색
/tdd # 테스트 주도 개발 모드
/build-fix # 빌드/타입 에러 최소 변경 수정
/git-master # Git 전문가 모드
Claude Code 공식 마켓플레이스에서 설치 가능한 LSP 플러그인으로, 코드 자동완성, 진단, 정의 이동 등 IDE 수준의 코드 분석 기능을 Claude Code에 추가한다.
| 플러그인 | 설명 |
|---|---|
typescript-lsp@claude-plugins-official |
TypeScript/JavaScript 언어 서버 연동 |
kotlin-lsp@claude-plugins-official |
Kotlin 언어 서버 연동 |
/plugin install typescript-lsp
/plugin install kotlin-lsp
중요: Claude Code는
~/.claude.json파일에서 MCP 서버를 로드한다.~/.claude/.mcp.json이나~/.claude/settings.json의mcpServers필드는 무시된다.
MCP(Model Context Protocol) 서버를 등록하면 Claude Code가 외부 도구와 연동할 수 있다.
~/.claude.json잘못된 위치 (작동하지 않음):
~/.claude/.mcp.json~/.claude/settings.json의 mcpServers 필드~/.claude/claude_desktop_config.json올바른 위치:
~/.claude.json의 mcpServers 필드| 서버 | 방식 | 용도 |
|---|---|---|
| Context7 | npx / Docker | 라이브러리 최신 공식 문서 실시간 참조 |
| Chrome DevTools | npx | 브라우저 디버깅, 콘솔 로그, 네트워크 모니터링 |
| WikiJS | npx | wiki.yowu.dev 페이지 검색/생성/수정/삭제 |
| Atlassian | Docker | Confluence 위키 + Jira 이슈 연동 (사내용) |
| GitHub Enterprise | Docker | GitHub Enterprise 저장소 연동 (사내용) |
Docker 기반 MCP 서버는 사내 서비스(Atlassian, GitHub Enterprise 등)처럼 인증이 필요한 도구에 적합하다. 오픈소스 도구는 npx로 실행하는 것이 편리하다.
~/.claude.json 파일을 열고 mcpServers 필드를 추가:
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
},
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
},
"wikijs": {
"command": "npx",
"args": ["-y", "@yowu-dev/requarks-wiki-mcp@latest"],
"env": {
"WIKI_BASE_URL": "https://your-wiki.example.com",
"WIKI_API_TOKEN": "<YOUR_API_TOKEN>",
"WIKI_MUTATIONS_ENABLED": "true"
}
},
"atlassian": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_PERSONAL_TOKEN",
"-e", "JIRA_URL",
"-e", "JIRA_PERSONAL_TOKEN",
"<ATLASSIAN_MCP_IMAGE>"
],
"env": {
"CONFLUENCE_URL": "https://your-confluence.example.com",
"CONFLUENCE_PERSONAL_TOKEN": "<YOUR_TOKEN>",
"JIRA_URL": "https://your-jira.example.com",
"JIRA_PERSONAL_TOKEN": "<YOUR_TOKEN>"
}
},
"github-enterprise": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
"-e", "GITHUB_HOST",
"<GITHUB_MCP_IMAGE>"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
"GITHUB_HOST": "https://your-github-enterprise.example.com"
}
}
}
}
~/.claude.json은 Claude Code가 자동으로 생성하는 파일이므로 기존 필드를 유지하고mcpServers필드만 추가하면 된다.
라이브러리/프레임워크의 최신 공식 문서를 실시간으로 참조할 수 있는 MCP 서버. React, Next.js, Kotlin 등 거의 모든 주요 라이브러리를 지원한다.
브라우저 개발자 도구와 연동하여 웹 페이지 디버깅, 콘솔 로그 확인, 네트워크 모니터링, 스크린샷 촬영을 지원하는 MCP 서버.
WikiJS 기반 위키의 페이지를 검색, 생성, 수정, 삭제할 수 있는 MCP 서버. 자세한 내용은 requarks-wiki-mcp 상세 문서를 참고.
Docker 이미지로 실행하며, Confluence 위키 검색/읽기와 Jira 이슈 조회/생성/변경을 지원한다. 사내 On-Premise 환경에서도 동작한다.
Docker 이미지로 실행하며, GitHub Enterprise 저장소의 코드 검색, PR 리뷰, 이슈 관리를 지원한다. GITHUB_HOST 환경변수로 Enterprise 서버 주소를 지정한다.
~/.claude.json에 있는지 확인cat ~/.claude.json | jq . 실행하여 문법 오류 확인tail -500 ~/.claude/debug/latest | grep -E "MCP server.*Starting connection".claude/.mcp.json 파일이 로드되지 않는 문제 (GitHub).mcp.json 파일이 읽히지 않는 문제 (GitHub)settings.json의 mcpServers 필드가 무시되는 문제 (GitHub)~/.claude/CLAUDE.md 파일로 Claude Code의 모든 세션에 적용되는 행동 지침을 설정한다.
현재 Andrej Karpathy의 LLM 코딩 가이드라인을 기반으로, 추가적인 글로벌 규칙을 결합하여 사용 중이다.
Karpathy 가이드라인 위에 추가로 설정한 규칙들:
## Language Rules
- Internal thinking must be in English
- User-facing output should be in Korean whenever possible
Claude Code의 내부 사고(thinking)는 영어로, 사용자에게 보여주는 출력은 한국어로 작성하도록 강제한다.
## User Changes Protection Rules
- NEVER delete or modify code, comments, TODOs, or any changes that the user has manually added
- Before running git checkout, git restore, or any file revert command, ALWAYS check if the file contains user's separate work mixed in
- When reverting is needed, preserve user changes and selectively revert only unintended AI-generated changes
AI가 사용자의 수동 변경사항을 실수로 덮어쓰는 것을 방지하는 규칙이다. git checkout이나 git restore 실행 전에 반드시 diff를 확인하도록 강제한다.
글로벌 ~/.claude/CLAUDE.md 외에 프로젝트별 .claude/CLAUDE.md도 작성할 수 있다.
project-root/
└── .claude/
└── CLAUDE.md # 이 프로젝트에만 적용되는 추가 지침
프로젝트 CLAUDE.md는 글로벌 CLAUDE.md와 병합되어 적용된다.
커스텀 스킬은 Claude Code의 기능을 확장하는 프롬프트 기반 확장 모듈이다. ~/.claude/skills/ 디렉토리에 Git 저장소를 심볼릭 링크하여 관리한다.
# Git 저장소를 skills 디렉토리에 심볼릭 링크
ln -s ~/git/ai-prompts-skills ~/.claude/skills
~/.claude/skills/
├── wiki-knowledge-manager/ # WikiJS 지식 관리
├── frontend-design/ # 프론트엔드 디자인 생성
├── find-skills/ # 스킬 검색 및 설치
├── skill-creator/ # 스킬 제작 가이드
├── pdf/ # PDF 처리 (읽기, 병합, 분할 등)
├── seo-audit/ # SEO 감사
├── web-design-guidelines/ # 웹 디자인 가이드라인 리뷰
├── marketing-psychology/ # 마케팅 심리학 멘탈 모델
├── vercel-react-best-practices/ # React/Next.js 최적화
├── vercel-composition-patterns/ # React 컴포지션 패턴
├── peon-ping-toggle/ # 알림 사운드 토글
├── peon-ping-config/ # 알림 사운드 설정
├── pr-review-espresso/ # PR 코드 리뷰 (프로젝트별)
├── devly-start/ # 프로젝트 팀 시작
└── devly-status/ # 프로젝트 상태 대시보드
Claude Code 프롬프트에서 /skill-name 형태로 호출한다:
/wiki-knowledge-manager 코루틴 관련 문서 검색해줘
/frontend-design 랜딩 페이지 만들어줘
/pdf resume.pdf에서 텍스트 추출해줘
/seo-audit https://example.com 감사해줘
| 스킬 | 용도 |
|---|---|
wiki-knowledge-manager |
wiki.yowu.dev 지식 CRUD, WikiJS MCP 연동 |
frontend-design |
고품질 프론트엔드 UI/컴포넌트 코드 생성 |
find-skills |
필요한 스킬 검색 및 설치 안내 |
skill-creator |
새 스킬 제작 가이드 |
pdf |
PDF 읽기, 병합, 분할, 워터마크, OCR 등 |
seo-audit |
기술 SEO, 메타태그, 접근성 감사 |
web-design-guidelines |
Web Interface Guidelines 준수 여부 리뷰 |
marketing-psychology |
70+ 마케팅 심리학 멘탈 모델 |
vercel-react-best-practices |
Vercel 엔지니어링 기반 React 성능 최적화 |
vercel-composition-patterns |
React 컴포지션 패턴 (React 19 포함) |
peon-ping-toggle |
알림 사운드 on/off 토글 |
peon-ping-config |
알림 사운드 볼륨, 팩, 카테고리 설정 |
| 도구 | 설치 | 용도 |
|---|---|---|
| OpenAI Codex CLI | npm i -g @openai/codex |
OMC에서 Codex 엔진으로 활용 |
| Google Gemini CLI | npm i -g @google/gemini-cli |
OMC에서 Gemini 엔진으로 활용 |
| gh (GitHub CLI) | brew install gh |
GitHub 관련 CLI 작업 |
| tig | brew install tig |
Git 히스토리 TUI 뷰어 |
| TypeScript | npm i -g typescript |
타입 체크, LSP 연동 |
| TS Language Server | npm i -g typescript-language-server |
TypeScript LSP 서버 |
brew install --cask ghosttycurl -fsSL https://claude.ai/install.sh | bashbrew install gh~/.claude.json 파일에 mcpServers 필드 추가/plugin install oh-my-claudecode/plugin install typescript-lsp, /plugin install kotlin-lspln -s 로 스킬 Git 저장소 심볼릭 링크