Claude Code 설치 후 반드시 해야 할 기본 세팅

Claude Code를 설치하고 claude를 실행하면 바로 사용할 수 있습니다. 하지만 날것의 상태로 쓰는 것과, 제대로 세팅한 후 쓰는 것 사이에는 생산성 차이가 수배에서 수십 배까지 납니다.

이 글에서는 설치 직후 반드시 진행해야 할 기본 세팅을 메모리 → MCP → Oh My Claude → 자동화 순서로 정리합니다. 한 번만 세팅해두면 이후 모든 프로젝트에서 레버리지가 됩니다.

1. 메모리 체계 구축: CLAUDE.md

Claude Code를 쓰면서 가장 먼저 해야 할 일은 메모리 체계를 잡는 것입니다. 아무리 좋은 모델이라도 내 프로젝트의 맥락을 모르면 정확한 코드를 짤 수 없습니다.

메모리 계층 이해하기

Claude Code의 메모리는 5단계 계층으로 구성됩니다. 범위가 넓을수록 우선순위가 낮고, 구체적일수록 우선순위가 높습니다.

글로벌 CLAUDE.md 세팅

먼저 전역 메모리를 설정합니다. 어떤 프로젝트에서든 적용되는 개인 코딩 스타일입니다.

mkdir -p ~/.claude && touch ~/.claude/CLAUDE.md

# Global Preferences
- 한국어로 응답
- TypeScript strict mode 준수
- 함수는 const 화살표 함수로 작성
- 커밋 메시지는 Conventional Commits 형식
- 변수명과 함수명은 camelCase
- Early return 패턴 사용

프로젝트 CLAUDE.md 생성

프로젝트 디렉토리에서 /init을 실행하면 자동으로 생성됩니다. 하지만 자동 생성된 내용은 범용적이므로, 반드시 프로젝트에 맞게 커스터마이징해야 합니다.

# CLAUDE.md
## 프로젝트 개요
- Next.js 16 App Router 기반 포트폴리오 + 기술 블로그
- TypeScript strict, Tailwind CSS v4 (dark theme only)
- MDX 기반 콘텐츠 시스템

## 핵심 명령어
- npm run dev: 개발 서버
- npm run build: 프로덕션 빌드
- npm run lint: ESLint 검사

## 아키텍처 원칙
- @/* 경로 별칭 사용 (./src/*)
- Server Component 우선, Client Component 최소화
- content/ 폴더에 MDX 콘텐츠 관리

자동 메모리 활성화

Claude가 세션 중 학습한 패턴, 디버깅 해결책, 선호도를 자동으로 저장하는 기능입니다. 최초 200줄까지 자동으로 로드됩니다.

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

쉘 설정 파일(~/.zshrc 등)에 추가해두면 항상 활성화 상태를 유지합니다.

2. 필수 MCP 설치

MCP(Model Context Protocol)는 Claude Code의 능력을 확장하는 플러그인 시스템입니다. 올바른 MCP 조합이 곧 생산성의 차이입니다.

① Memory MCP — 세션 간 기억 유지

Claude Code의 가장 큰 한계는 세션이 끝나면 맥락을 잃는다는 점입니다. Memory MCP는 로컬 지식 그래프를 통해 세션 간 지속적인 기억을 제공합니다.

claude mcp add memory \
  -e MEMORY_FILE_PATH=~/.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

설치 후 Claude에게 "이 프로젝트는 Next.js 16 기반이고, Tailwind v4를 사용해. 기억해줘"라고 말하면 지식 그래프에 엔티티로 저장됩니다. 다음 세션에서도 이 맥락을 참조할 수 있습니다.

Memory MCP가 제공하는 도구:

• create_entities — 프로젝트, 기술, 사람 등 엔티티 생성
• create_relations — 엔티티 간 관계 설정
• add_observations — 기존 엔티티에 정보 추가
• search_nodes — 지식 그래프 검색
• read_graph — 전체 그래프 조회

② Sequential Thinking — 구조적 사고 강제

복잡한 아키텍처 설계나 디버깅에서 Claude가 성급하게 결론을 내리는 것을 방지합니다. 단계별로 사고 과정을 외부화하여 추론의 정확도를 높입니다.

claude mcp add sequential-thinking \
  -- npx -y @modelcontextprotocol/server-sequential-thinking

사용할 때는 프롬프트에 "Sequential Thinking을 사용해서 분석해줘"라고 명시하면 단계별 추론이 시작됩니다.

③ Context7 — 실시간 문서 참조

Claude의 학습 데이터는 특정 시점에서 끊깁니다. Context7은 라이브러리의 최신 공식 문서를 실시간으로 가져와 할루시네이션을 차단합니다. GitHub 스타 46,000개 이상으로 검증된 MCP입니다.

claude mcp add context7 -- npx -y @upstash/context7-mcp

프롬프트에 "use context7"을 추가하면 자동으로 관련 문서를 가져옵니다. Next.js, React, Tailwind 등 50개 이상의 프레임워크를 지원합니다.

④ GitHub MCP — Git 워크플로우 통합

PR 생성, 이슈 관리, 코드 리뷰를 터미널 안에서 처리합니다.

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your_token> \
  -- npx -y @modelcontextprotocol/server-github

⑤ Fetch MCP — 웹 콘텐츠 접근

API 문서, 웹페이지 분석, 외부 리소스 참조가 필요할 때 사용합니다.

claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch

설치 확인

모든 MCP를 설치한 후 정상적으로 등록되었는지 확인합니다.

claude mcp list

3. Claude-Mem — 영구 메모리 시스템

Claude Code의 가장 큰 약점이었던 **"세션 종료 시 맥락 소실"**을 완전히 해결하는 플러그인입니다. 앞서 설치한 Memory MCP가 수동으로 엔티티를 저장하는 지식 그래프라면, Claude-Mem은 자동으로 작업 기록을 캡처 → AI 요약 → SQLite 저장 → 다음 세션에 자동 주입하는 영구 메모리 시스템입니다. GitHub 스타 29,000개 이상으로, 가장 널리 사용되는 Claude Code 플러그인 중 하나입니다.

설치

# Claude Code 내에서 실행
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

설치 후 Claude Code를 재시작하면 이전 세션의 맥락이 자동으로 새 세션에 주입됩니다.

동작 원리

Claude-Mem은 5개의 라이프사이클 훅(SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd)을 통해 작동합니다. 개발자가 별도로 "기억해줘"라고 말할 필요가 없습니다.

작업 수행 → 도구 사용 관찰 캡처 → AI 시맨틱 요약 → SQLite + Chroma 저장
                                                          ↓
다음 세션 시작 → 관련 컨텍스트 자동 검색 → 프롬프트에 주입

핵심 기능

• 자동 캡처 — 모든 도구 사용과 작업 결과를 자동으로 기록
• 시맨틱 검색 — 자연어로 과거 작업 이력 검색 가능
• Progressive Disclosure — 토큰 효율을 위해 3단계(인덱스 → 타임라인 → 상세)로 나눠 조회
• 웹 뷰어 — http://localhost:37777에서 실시간 메모리 스트림 시각화
• 프라이버시 제어 — <private> 태그로 민감한 내용을 저장에서 제외

MCP 검색 도구

Claude-Mem은 5개의 MCP 도구를 제공하여 토큰을 절약하는 3단계 워크플로우를 지원합니다.

1단계: search → 컴팩트 인덱스 조회 (~50-100 토큰/결과)
2단계: timeline → 시간순 맥락 확인
3단계: get_observations → 필터링된 ID만 상세 조회 (~500-1,000 토큰/결과)

이 방식으로 전체를 한 번에 가져오는 것 대비 약 10배의 토큰 절감 효과가 있습니다.

Memory MCP vs Claude-Mem

두 도구는 상호 보완적입니다. Memory MCP로 핵심 아키텍처 결정사항을 기록하고, Claude-Mem으로 일상적인 작업 맥락을 자동 보존하는 조합이 가장 효과적입니다.

4. Oh My Claude (OMC) — 멀티 에이전트 오케스트레이션

Oh My Claude(oh-my-claudecode)는 Claude Code를 멀티 에이전트 오케스트레이션 시스템으로 탈바꿈시키는 도구입니다. 한국인 개발자 허예찬 님이 개발했으며, "코드를 직접 짜지 말고 지휘하라"는 철학을 기반으로 합니다.

설치

# Claude Code 내에서 실행
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode
/oh-my-claudecode:omc-setup

핵심 개념: 지휘자(Conductor) 철학

OMC의 황금률은 직접 코드를 수정하지 않는 것입니다. 대신 28개의 전문화된 에이전트(아키텍트, 실행자, 검증자 등)에게 작업을 위임합니다.

매직 키워드

OMC는 자연어 기반의 매직 키워드로 동작합니다. 별도의 명령어 체계를 외울 필요가 없습니다.

autopilot — 아이디어에서 완성 코드까지 자율 실행

autopilot build a REST API for user management

기획 → 설계 → 구현 → 테스트 → 검증까지 자동으로 진행됩니다.

ralph — "바위는 멈추지 않는다" 지속 실행 모드

ralph refactor the entire authentication module

아키텍트가 검증을 완료할 때까지 계속 작업합니다.

ulw (Ultrawork) — 최대 병렬 실행

ulw fix all TypeScript errors in the project

5개 이상의 에이전트가 동시에 병렬로 작업합니다.

team — 네이티브 팀 모드

team 5:executor refactor backend services

지정된 수의 에이전트가 파이프라인(plan → prd → exec → verify → fix)으로 협업합니다.

스마트 모델 라우팅

OMC는 작업 복잡도에 따라 모델을 자동 선택하여 비용을 30~50% 절감합니다.

메모리와 상태 관리

OMC는 자체 메모리 시스템도 갖추고 있습니다.

• .omc/notepad.md — 컨텍스트 정리(pruning)에서도 살아남는 메모
• .omc/project-memory.json — 프로젝트 기술 스택, 컨벤션 저장
• .omc/plans/ — 기획 문서
• .omc/logs/ — 실행 로그

5. Hooks: 코드 품질을 자동화하는 안전장치

Hooks는 Claude의 작업 생명주기 특정 시점에 자동으로 실행되는 명령입니다. CLAUDE.md와 달리 Claude가 무시할 수 없으며, 항상 결정론적으로 실행됩니다.

설정 위치

~/.claude/settings.json      # 전역 (모든 프로젝트)
.claude/settings.json         # 프로젝트별

파일 저장 시 자동 포맷팅

Claude가 파일을 수정할 때마다 Prettier가 자동으로 실행됩니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$(jq -r '.tool_input.file_path')\"",
            "blocking": true
          }
        ]
      }
    ]
  }
}

위험한 명령어 차단

rm -rf 같은 파괴적 명령이 실행되는 것을 방지합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf' && exit 1 || exit 0",
            "blocking": true
          }
        ]
      }
    ]
  }
}

주요 Hook 이벤트

6. 권한 설정: bypassPermissions

Claude Code는 기본적으로 파일 수정, 명령어 실행 등 민감한 작업마다 승인을 요청합니다. 작업 흐름이 자주 끊기므로, 개인 개발 환경에서는 권한 승인을 건너뛰는 설정이 생산성에 큰 영향을 줍니다.

CLI 플래그로 실행

가장 간단한 방법은 실행 시 플래그를 추가하는 것입니다.

claude --dangerously-skip-permissions

기본값으로 영구 활성화

매번 플래그를 붙이기 번거롭다면 설정 파일에 직접 추가합니다.

// ~/.claude/settings.json
{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": ["*"],
    "deny": [],
    "ask": []
  }
}

이 설정은 ~/.claude/settings.json(전역)이나 .claude/settings.json(프로젝트별) 어디에든 적용할 수 있습니다.

쉘 별칭으로 간편하게

설정 파일을 건드리지 않고 별칭만으로 해결하는 방법도 있습니다.

# ~/.zshrc 또는 ~/.bashrc에 추가
alias clauded="claude --dangerously-skip-permissions"

이후 clauded만 입력하면 권한 승인 없이 바로 작업이 시작됩니다.

안전한 대안: 세분화된 권한 제어

전체 권한을 열기 부담스럽다면, 특정 도구만 허용하는 allow 리스트를 활용하세요.

// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm run *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

이렇게 하면 파일 읽기/쓰기와 npm, git 명령은 자동 승인되지만, rm -rf나 sudo 같은 위험한 명령은 차단됩니다. 전체를 열어두는 것보다 훨씬 안전하면서도 작업 흐름이 끊기지 않습니다.

주의: bypassPermissions는 모든 안전장치를 해제합니다. Docker 컨테이너, VM, 또는 중요한 데이터가 없는 개발 전용 환경에서만 사용하세요. 프로덕션 서버나 민감한 데이터가 있는 환경에서는 절대 사용하지 마세요.

7. 커스텀 슬래시 명령어

반복하는 작업이 있다면 커스텀 명령어로 만들어두면 됩니다.

설정 방법

mkdir -p .claude/commands

.claude/commands/ 안에 마크다운 파일을 만들면 곧바로 슬래시 명령어로 사용할 수 있습니다.

코드 리뷰 명령어 예시

.claude/commands/review.md:

---
description: 변경된 코드를 리뷰합니다
allowed-tools: Bash, Read
---

git diff로 변경된 파일을 확인하고 다음 관점에서 리뷰해주세요:
1. 버그 가능성
2. 타입 안전성
3. 성능 이슈
4. 보안 취약점

$ARGUMENTS 에 대한 추가 지시가 있으면 반영해주세요.

이제 /review 또는 /review 인증 로직 중심으로처럼 사용할 수 있습니다.

테스트 명령어 예시

.claude/commands/test-check.md:

---
description: 테스트를 실행하고 결과를 분석합니다
allowed-tools: Bash
---

npm test를 실행하고, 실패한 테스트가 있다면 원인을 분석해주세요.
수정이 필요한 경우 수정안을 제시해주세요.

8. 파워 유저를 위한 필수 명령어

일상적으로 활용하면 효율이 크게 올라가는 명령어들입니다.

세션 관리

실행 모드

작업 효율 팁

최종 세팅 체크리스트

설치 직후 이 순서대로 세팅하면 됩니다.

✅ 1. 글로벌 CLAUDE.md 작성 (~/.claude/CLAUDE.md)
✅ 2. 프로젝트 CLAUDE.md 작성 (/init 후 커스터마이징)
✅ 3. Memory MCP 설치 (세션 간 기억 유지)
✅ 4. Sequential Thinking MCP 설치 (구조적 추론)
✅ 5. Context7 MCP 설치 (최신 문서 참조)
✅ 6. GitHub MCP 설치 (Git 워크플로우 통합)
✅ 7. Fetch MCP 설치 (웹 리소스 접근)
✅ 8. Claude-Mem 설치 (영구 메모리 자동 캡처)
✅ 9. Oh My Claude 설치 (멀티 에이전트 오케스트레이션)
✅ 10. Hooks 설정 (자동 포맷팅, 보안 규칙)
✅ 11. 권한 설정 (bypassPermissions 또는 세분화된 allow/deny)
✅ 12. 커스텀 명령어 작성 (반복 작업 자동화)

마치며

도구의 성능은 도구 자체가 아니라 세팅의 깊이에서 결정됩니다. Claude Code는 설치만으로 끝이 아닙니다. 메모리 체계를 잡고, MCP로 능력을 확장하고, Hooks로 품질을 자동화하고, OMC로 멀티 에이전트 오케스트레이션을 구축했을 때 비로소 진정한 '레버리지'가 됩니다.

한 번 투자한 세팅 시간은 이후 수백 시간의 생산성으로 돌아옵니다. 오늘 바로 시작해보세요.