Claude Code, 설치만 해놓고 채팅만 하고 있다면 — CLAUDE.md, Hooks, MCP 설정법

Source: Dev.to

Claude Code를 깔았다. claude를 치면 대화창이 뜬다. 거기서 “이 버그 고쳐줘”, “테스트 짜줘”를 한다.
하지만 많은 사람이 여기서 멈춰 있다. Claude Code의 진짜 힘은 채팅창이 아니라 설정 파일 3개에 있다.

• CLAUDE.md
• Hooks 설정
• MCP 서버 연결

이 셋만 잡아도 체감이 완전히 달라진다.

CLAUDE.md — 세션이 바뀌어도 기억이 남는다

Claude Code는 세션이 끝나면 전부 잊는다. 어제 “pytest에 -v 옵션 써”라고 가르쳐줬어도 오늘 다시 말해야 한다. CLAUDE.md가 이 문제를 해결한다.

프로젝트 루트에 CLAUDE.md를 만들어두면 Claude Code가 세션 시작 시 자동으로 읽는다. 명시적으로 “이거 읽어”라고 할 필요가 없다. Claude는 이 파일을 “개발자가 나를 위해 남겨둔 지시사항” 으로 인식한다.

# Project Guide

## 개발 규칙
- 테스트는 항상 `pytest tests/ -v`로 실행
- DB 작업 전 반드시 백업 생성
- 커밋 메시지는 feat/fix/docs 접두사 사용

## 기술 스택
- Python 3.11, FastAPI, PostgreSQL
- 프론트는 Next.js 14 App Router

핵심은 처음부터 완벽하게 쓸 필요가 없다는 점이다. Claude가 실수할 때마다 교정 사항을 하나씩 추가하면 된다. 세션 중에 #으로 시작하는 라인을 바로 CLAUDE.md에 추가할 수 있다.

# API 응답은 항상 snake_case로 보낼 것

CLAUDE.md는 계층 구조로 동작한다.

• ~/.claude/CLAUDE.md – 전역 설정
• ./CLAUDE.md – 프로젝트 설정
• ./.claude/CLAUDE.md – 프로젝트 로컬(개인) 설정

하위 디렉터리에도 넣을 수 있다. 예: src/ui/CLAUDE.md.

Hooks — “항상” 실행되는 자동화

Hook은 도구 실행 전/후에 셸 명령을 강제로 거는 방식이다. 설정 파일은 .claude/settings.local.json에 위치한다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; if echo \"$f\" | grep -qE '\\.(ts|tsx)$'; then npx prettier --write \"$f\" 2>/dev/null; fi; }"
          }
        ]
      }
    ]
  }
}

차단 Hook 예시

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json,sys; d=json.load(sys.stdin); p=d.get('tool_input',{}).get('file_path',''); sys.exit(2 if '.env' in p else 0)\""
          }
        ]
      }
    ]
  }
}

PreToolUse 훅이 종료 코드 2를 반환하면 해당 도구 실행이 차단된다.

MCP — Claude Code에 플러그인을 꽂는다

MCP 서버를 연결하면 외부 시스템까지 다룰 수 있다. 아래 예시는 여러 플러그인을 추가하는 방법이다.

# GitHub
claude mcp add github -s user \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token \
  -- npx -y @modelcontextprotocol/server-github

# Context7
claude mcp add context7 -s user -- npx -y @upstash/context7-mcp@latest

# Playwright
claude mcp add playwright -s project -- npx -y @playwright/mcp@latest

# PostgreSQL
claude mcp add postgres -s project \
  -e DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" \
  -- npx -y @modelcontextprotocol/server-postgres

요약

1. CLAUDE.md 로 규칙을 가르치고 기억하게 만든다.
2. Hook 으로 코드 품질과 보안을 자동으로 강제한다.
3. MCP 로 기능을 확장해 외부 시스템과 연동한다.

설정에 30분만 투자하면 매일 시간을 크게 절약할 수 있다. Claude Code의 진짜 힘은 대화가 아니라 설정에 있다.