Claude Code
바이블

비유 하나로 전부 설명한다

ChatGPT에게 코드를 물어보는 건 요리 레시피 검색이다. 레시피를 알려주면 내가 직접 재료 사고, 요리하고, 설거지까지 해야 한다.

Claude Code는 다르다. 이건 셰프를 고용한 것이다. "오늘 저녁 파스타 만들어줘"라고 하면 셰프가 냉장고 열어보고, 재료 파악하고, 요리하고, 상까지 차려준다. 내가 할 일은 "맛있네, 조금 짜다"라고 피드백하는 것뿐이다.

핵심 차이 — 4가지

구분	ChatGPT / Claude.ai 웹	Claude Code CLI
파일 접근	붙여넣기만 가능	직접 읽고 쓰고 실행
기억	대화 끝나면 리셋	CLAUDE.md로 영구 기억
행동	답변 생성	계획 → 실행 → 검증
확장	없음	MCP로 DB·GitHub 직접 제어

결정적인 차이는 파일 시스템 직접 접근이다. Claude Code는 당신 컴퓨터의 폴더를 직접 열고, 파일을 읽고, 수정하고, 터미널 명령어를 실행한다. AI가 개발자처럼 일하는 게 아니라, AI가 실제로 개발자처럼 일한다.

에이전트가 뭔가요

요즘 "AI 에이전트"라는 말이 많이 나온다. 쉽게 말하면 이렇다.

Claude Code는 코딩 에이전트다. "이 API에 유닛 테스트 추가해줘"라고 하면, 코드 읽고, 테스트 작성하고, 실행해서 통과하는지 확인하고, 실패하면 고치는 과정을 알아서 반복한다.

할 수 있는 것 vs 못 하는 것

사전 준비 (5분)

설치 (1분)

npm install -g @anthropic-ai/claude-code

로그인 (2분)

claude

처음 실행하면 브라우저가 열린다. Anthropic 계정으로 로그인하고 "허용" 버튼 누르면 끝. 토큰이 내 컴퓨터에 저장된다.

첫 대화 (2분)

cd 내-프로젝트-폴더
claude

이게 전부다. Claude Code가 현재 폴더를 자동으로 읽고 대화 모드로 진입한다.

이 폴더 구조를 파악하고 어떤 프로젝트인지 설명해줘.

Claude가 실제로 파일들을 열어보고 설명한다. 마법처럼 느껴지는 첫 순간이다.

꼭 외울 명령어 5개

명령어	역할
/clear	대화 컨텍스트 초기화 (새 작업 시작 전)
/help	사용 가능한 명령어 전체 목록
/context	현재 컨텍스트 윈도우 사용량 확인
Ctrl+C	Claude 응답 즉시 중단
Shift+Enter	줄바꿈 (Enter는 전송)

"Claude Code한테 바로 코딩 시키면 왜 이상한 게 나오냐고? 셰프한테 뭘 원하는지도 말 안 하고 '요리해'라고 하는 거랑 같다."

왜 순서가 중요한가

처음 Claude Code를 쓸 때 저지르는 실수 1위: "버그 고쳐줘"라고 바로 시킨다. 그러면 Claude가 코드를 뜯어보지도 않고 추측으로 고친다. 틀린다. 다시 고친다. 더 망가진다.

4단계 황금 워크플로우

실제 프롬프트 — 복붙해서 써라

Step 1: 탐색 프롬프트

[파일명 또는 기능명]이 어떻게 동작하는지 파악해줘.
관련 파일들 읽어보고 현재 구조 설명해줘.
지금은 코드 건드리지 마, 분석만.

Step 2: 계획 확인 프롬프트

[원하는 변경사항] 구현하려면 어떻게 할 거야?
어떤 파일을 어떻게 바꿀 건지 계획 먼저 알려줘.
코드 수정은 내가 OK 하면 시작해.

Step 3: 구현 프롬프트

OK, 진행해. [파일명]부터 시작해.
각 파일 수정 후에 잘 돌아가는지 확인하면서 해줘.

/plan 모드 — 더 안전하게

복잡한 작업에는 /plan 모드를 쓴다. 이 모드에서 Claude는 파일을 수정할 수 없다. 계획만 세울 수 있다.

/plan
# 이제 Claude는 읽기만 가능, 수정 불가
# "좋아, 시작해" 하면 일반 모드로 전환

"CLAUDE.md 없이 Claude Code 쓰는 건, 직원을 고용했는데 회사 설명은 안 해주는 것과 같다. 매번 처음부터 설명해야 한다."

CLAUDE.md가 뭔가

Claude Code가 시작할 때 가장 먼저 찾는 파일이 CLAUDE.md다. 여기에 쓰인 내용은 매 세션마다 자동으로 읽힌다. 한 번 써두면 다시 설명할 필요가 없다.

CLAUDE.md 황금 템플릿

# 프로젝트명 — Claude 행동 지침

## 프로젝트 개요
- **목적**: [한 줄로 설명]
- **스택**: Python 3.11 / FastAPI / PostgreSQL
- **포트**: 8766 (로컬), Render 배포

## 폴더 구조 핵심
- `api_server/` — 백엔드
- `frontend/` — React SPA
- `MASTER.env` — 환경변수 (절대 커밋 금지!)

## 코딩 규칙
- 주석보다 명확한 함수명 우선
- try/except 있으면 반드시 로깅
- 새 기능 전에 기존 테스트 먼저 통과 확인

## ⛔ 금지 사항 (Claude 필독)
- git push --force 절대 금지
- .env 파일 내용 출력 금지
- rm -rf 실행 전 반드시 확인 요청

## 자주 쓰는 명령어
- 서버 시작: `python local_agent_server.py`
- 테스트: `pytest tests/ -v`
- 보안 체크: `python git_security_check.py`

## 과거 실수 — 똑같은 실수 금지
- [2026-05] 한국어 경로 subprocess 인코딩 오류
  → 해결: PYTHONUTF8=1 항상 설정
- [2026-05] MCP 204 빈 응답 파싱 오류
  → 해결: content 길이 먼저 체크

CLAUDE.md 배치 전략

MCP란 뭐냐

Model Context Protocol. 복잡하게 생각할 것 없다. 한 줄 요약:

MCP 설치 — 명령어 하나로

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase@latest \
  --access-token 내_Supabase_토큰 \
  --project-ref 내_프로젝트_ref

claude mcp add github -- npx @modelcontextprotocol/server-github \
  --token 내_GitHub_토큰

claude mcp list

주요 MCP 서버 목록

서버	주요 기능
Supabase	PostgreSQL 쿼리, 마이그레이션, Edge Function 배포
GitHub	PR 생성, 이슈 조회, 코드 검색, 브랜치 관리
Playwright	실제 브라우저 조작, 스크린샷, 스크래핑
Figma	디자인 읽기, Code Connect, 목업 자동 생성
Context7	최신 라이브러리 공식 문서 실시간 조회
Linear	이슈 생성, 스프린트 관리, 작업 추적

설정 파일로 관리하는 법

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token", "sbp_XXXXXXXXXX",
        "--project-ref", "XXXXXXXXXX"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"]
    }
  }
}

Hooks가 뭔가

Claude가 파일을 수정할 때, Bash 명령어를 실행할 때, 응답을 완료할 때 — 이 시점에 내가 원하는 셸 명령어를 자동으로 실행할 수 있다. 이게 Hooks다.

Hook 이벤트 5가지

이벤트	언제 실행되나	활용
PreToolUse	도구 실행 직전	위험 명령어 차단, 로그 기록
PostToolUse	도구 실행 직후	테스트 자동 실행, 린트 체크
Notification	알림 발생 시	Slack/텔레그램 전송
Stop	Claude 응답 완료	소리 알림, 자동 커밋
SubagentStop	하위 에이전트 완료	파이프라인 다음 단계 트리거

설정 방법

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pytest tests/ -x -q 2>&1 | tail -8"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \"[console]::beep(880, 400)\""
          }
        ]
      }
    ]
  }
}

복붙 레시피 5개

① 파일 수정 후 자동 테스트

"command": "python -m pytest tests/ -x -q 2>&1 | tail -5"

② 작업 완료 시 소리 알림 (Windows)

"command": "powershell -c \"[console]::beep(800,300)\""

③ 텔레그램 알림 전송

"command": "python /tools/telegram_notify.py \"Claude 작업 완료!\""

④ rm -rf 차단 (PreToolUse)

"command": "python /tools/bash_safety_check.py"

⑤ 파일 수정 후 git auto-stage

"command": "git add -u"

"시황 AGI의 26라운드 루프를 Claude 하나가 처리하면 몇 시간이 걸린다. 멀티에이전트로 병렬화하니까 1시간 안에 끝난다."

오케스트레이터 패턴

Claude A (오케스트레이터)가 전체 목표를 이해하고 작업을 나눠서 여러 Claude B, C, D에게 위임한다. 각 서브에이전트는 독립된 컨텍스트에서 자기 일만 한다. 다 끝나면 오케스트레이터가 결과를 종합한다.

Claude Code에서 병렬 작업 시키는 법

다음 3가지를 병렬로 처리해줘:
1. api_server/ 보안 취약점 검토 (에이전트 1)
2. frontend/ 성능 최적화 포인트 분석 (에이전트 2)
3. tests/ 커버리지 분석 (에이전트 3)

각각 독립적으로 분석하고, 끝나면 종합 보고서 만들어줘.

Agent SDK — 코드로 팀 구성

Anthropic Agent SDK를 쓰면 멀티에이전트 시스템을 코드로 만들 수 있다. 이게 JANDA 시황 AGI의 핵심이다.

import anthropic

client = anthropic.Anthropic()

# 순차 파이프라인: 진단 결과를 다음 에이전트에 넘긴다
def run_pipeline(task: str):
    # 에이전트 1: 코드 리뷰 (Haiku — 빠르고 저렴)
    review = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=1024,
        system="코드 리뷰 전문가. 버그와 보안 취약점만 찾아.",
        messages=[{"role": "user", "content": task}]
    )

    # 에이전트 2: 리뷰 결과 받아서 개선안 작성 (Sonnet)
    solution = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="개선안 작성 전문가. 구체적 코드 제시.",
        messages=[
            {"role": "user", "content": task},
            {"role": "assistant", "content": review.content[0].text},
            {"role": "user", "content": "위 리뷰를 바탕으로 개선된 코드를 작성해줘"}
        ]
    )
    return solution.content[0].text

# ── 독립 작업을 실제로 병렬 실행하려면 asyncio 사용 ──
import asyncio, anthropic

async def run_parallel(tasks: list[str]):
    client = anthropic.AsyncAnthropic()
    async def call(t):
        r = await client.messages.create(
            model="claude-haiku-4-5-20251001", max_tokens=512,
            messages=[{"role": "user", "content": t}]
        )
        return r.content[0].text
    return await asyncio.gather(*[call(t) for t in tasks])

SDK 설치

pip install anthropic python-dotenv

기본 메시지 전송

import anthropic
import os
from dotenv import load_dotenv

load_dotenv("MASTER.env")

client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

response = client.messages.create(
    model="claude-sonnet-4-6",     # 기본 모델
    max_tokens=1024,
    system="한국어로만 답해.",
    messages=[
        {"role": "user", "content": "오늘 블로그 제목 3개 만들어줘. JSON 배열로."}
    ]
)

print(response.content[0].text)

모델 선택 — 언제 뭘 쓸까

모델	언제 쓰나	비용
claude-haiku-4-5-20251001	분류, 스코어링, 짧은 응답, 고속 처리	가장 저렴
claude-sonnet-4-6	일반 개발, 분석, 긴 응답 (기본값)	중간
claude-opus-4-7	전략적 판단, 복잡한 추론	가장 비쌈

스트리밍 응답

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{"role": "user", "content": "긴 보고서 작성해줘"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Tool Use — Claude에게 함수 주기

tools = [{
    "name": "search_naver_local",
    "description": "네이버 지역 검색 API로 업체 정보 검색",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "검색어 (예: 강남 스터디카페)"}
        },
        "required": ["query"]
    }
}]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    tools=tools,
    messages=[{"role": "user", "content": "강남 필라테스 업체 찾아줘"}]
)

# Claude가 tool_use 블록 반환하면 실제 함수 실행
for block in response.content:
    if block.type == "tool_use":
        result = search_naver_local(block.input["query"])
        # 결과를 다시 Claude에게 전달해서 요약시킴

"외주 개발비로 월 300만 원 썼다. Claude Code 도입 후 API 비용은 월 5만 원. 생산량은 3배다."

우리가 만든 것들

시황 AGI — 자가코딩의 구현

시황 AGI는 매일 밤 00:30에 혼자 시작해서 스스로 코드를 개선하고 07:00에 끝난다. 사람은 아무것도 안 해도 된다.

CLAUDE.md가 전부를 가능케 했다

## 시황 AGI 파일 안전 규칙 (v3.3 — 2026-05-14)

| 규칙 | 내용 |
|------|------|
| confidence < 55 | 스킵 — 스코프 축소 재시도 1회 |
| 쿨다운 기준 | 마지막 시도 기준 1시간 (반복 방지) |
| import 검증 | subprocess 실행 후 반영 |
| overnight 수정 | code_patcher 통해서만, 직접 수정 금지 |
| 목표 성공률 | 100% — 모든 유효 시도는 patched=True

이 규칙들이 CLAUDE.md에 있어서 매 세션마다 Claude에게 주입된다. AI가 AI 코드를 수정할 때 지켜야 할 안전 프로토콜이다.

핵심 교훈 — 6개월 후 돌아보며

이 책을 읽었다면 이미 준비는 됐다. 이제 실제로 해보는 것만 남았다. 아는 것과 해본 것 사이의 간격을 채우는 데는 첫 번째 프로젝트가 제일 빠르다.

지금 당장 시작할 3가지 프로젝트

책 읽는 것과 실제로 써보는 건 완전히 다르다. 읽을 때는 다 이해된 것 같다. 막상 터미널 열면 멍해진다. 그 간격을 메우는 데는 작은 프로젝트 하나가 제일 빠르다. 아래 순서대로 하나씩 해봐라.

Claude Code 생태계 — 앞으로

---

저자가 Claude Code로 직접 만든 서비스

Claude Code 바이블 2026 — 저자 김화현 · 공동저자 로드
AI사냥꾼 채널 · dev@stayjanda.com
협업 및 제안 · ceo@stayjanda.com

🐛 버그 수정 패턴

아래 에러가 나. 원인 찾아서 고쳐줘.
코드 건드리기 전에 원인 먼저 설명해.

[에러 메시지 전체 붙여넣기]

파일: [파일명]

[함수명] 함수에서 [증상]이 발생해.
입력값: [예시 입력]
기대 결과: [기대하는 출력]
실제 결과: [실제 나오는 출력]

관련 코드 읽고 원인 찾아줘. 수정 전에 가설 말해줘.

[기능명]이 가끔 안 된다. 매번은 아니고 [빈도/조건].
로그 보면 이렇게 나와:
[로그 내용]

race condition이나 타이밍 문제인지 확인해줘.
관련 코드 전체 읽어보고 의심 포인트 찾아줘.

🔨 새 기능 추가 패턴

현재 [모듈명] 코드 읽어봐.
[기능 설명]을 추가하려는데
기존 구조에서 어디에 어떻게 붙이면 자연스러울지 말해줘.
계획만 먼저. 코드 수정은 내가 OK 하면 시작해.

FastAPI에 [엔드포인트 경로] 엔드포인트 추가해줘.
- 메서드: [GET/POST/PUT]
- 입력: [파라미터 설명]
- 출력: [반환값 설명]
- 인증: [있음/없음]

기존 라우터 파일 [파일명] 읽고 같은 스타일로 만들어줘.

[테이블명] 테이블에서 [조건] 데이터를 가져오는 쿼리 짜줘.
현재 DB 접속 방식은 [파일명] 참고해.
기존 쿼리 함수들이랑 스타일 맞춰줘.

♻️ 리팩터링 패턴

[파일명]의 [함수명] 함수가 너무 길어.
읽어보고 어떻게 나누면 좋을지 제안해줘.
나누기 전후로 기존 기능 동일하게 유지해야 해.

[파일명A]랑 [파일명B]에 비슷한 코드가 있어.
둘 다 읽어보고 공통 함수로 뽑아낼 수 있는 부분 찾아줘.
변경 최소화로.

[파일명] 읽어봐. 기능은 바꾸지 말고
변수명, 함수명만 더 명확하게 바꿔줘.
바꿀 이름들 목록 먼저 보여주고 내가 확인하면 적용해줘.

✅ 테스트 작성 패턴

[파일명]의 [함수명] 함수에 대한 pytest 테스트 작성해줘.
- 정상 케이스 3개
- 엣지 케이스 2개 (None 입력, 빈 값 등)
- 예외 케이스 1개

기존 테스트 파일 [tests/파일명] 읽고 같은 스타일로.

[파일명] 전체 읽어봐.
이 파일에서 가장 중요한 함수 3개 골라서
각각 최소 테스트 케이스 2개씩 작성해줘.
테스트 먼저 작성하고, 통과되는지 실행해봐.

🔍 코드 이해 패턴

이 프로젝트의 [기능명] 부분이 어떻게 동작하는지 모르겠어.
[관련 폴더/파일명] 읽어보고
데이터 흐름을 순서대로 설명해줘. 코드는 건드리지 마.

[파일명] [라인번호]~[라인번호] 이 부분이 뭐 하는 건지 모르겠어.
왜 이렇게 짰는지 이유까지 설명해줘.
비개발자도 이해할 수 있게.

[파일명/함수명]을 수정하면 어디에 영향 가?
이 파일을 import하거나 호출하는 파일들 찾아줘.
영향 범위 파악 후에 수정 들어갈게.

🚀 성능 최적화 패턴

[파일명]의 [함수명]이 느려. 평균 [시간]ms 걸림.
코드 읽어보고 병목 원인 찾아줘.
인덱스, N+1 쿼리, 불필요한 루프 위주로 봐줘.

[파일명]의 [함수명]이 순차 처리라 느려.
비동기/병렬로 바꿀 수 있는지 봐줘.
현재 코드 읽고 asyncio 또는 ThreadPoolExecutor로 개선안 제시해줘.

📝 문서화 패턴

이 프로젝트 전체 읽어봐.
GitHub README.md 작성해줘.
- 프로젝트 설명 (1~2줄)
- 설치 방법
- 사용법 (예시 포함)
- 환경변수 목록
개발자가 아닌 사람도 읽을 수 있게.

[파일명] 읽어봐.
docstring 없는 public 함수들 찾아서
Args/Returns/Raises 형식으로 docstring 추가해줘.
함수 로직은 건드리지 마.

🔐 보안 패턴

[파일명] 읽어봐.
SQL injection, XSS, 인증 우회, 민감정보 노출
이 4가지 관점에서 취약점 있는지 점검해줘.
발견하면 심각도(상/중/하)랑 수정 방법 같이 알려줘.

이 프로젝트에서 하드코딩된 API 키나 비밀번호가 있는지 찾아줘.
os.getenv()로 대체 가능한 것들 목록 만들어줘.
실제 값은 출력하지 마.

🤝 협업 패턴

git diff [브랜치명]..HEAD 결과야:
[diff 내용]

이 변경사항으로 GitHub PR 설명 작성해줘.
- Summary (무엇을 왜 바꿨나)
- 테스트 방법
- 주의사항
마크다운 형식으로.

git diff --staged 결과야:
[diff 내용]

Conventional Commits 형식으로 커밋 메시지 써줘.
feat/fix/refactor/docs 중 맞는 타입 골라서.

🐍 Python 특화 패턴

[파일명] 읽어봐.
타입 힌트 없는 함수들에 Python typing 모듈로 타입 추가해줘.
함수 동작은 바꾸지 말고 타입만.

[파일명]의 [함수명]에 에러 핸들링이 부족해.
어떤 예외가 발생할 수 있는지 분석하고
try/except + 로깅 추가해줘. silent fail은 금지.

⚡ 자동화 패턴

매일 [작업 설명]을 수동으로 하고 있어.
이걸 자동화하는 Python 스크립트 만들어줘.
- 입력: [데이터 소스]
- 처리: [로직]
- 출력: [결과물]
MASTER.env에서 키 읽는 방식으로.

[스크립트 경로]를 매일 [시간]에 자동 실행하고 싶어.
Windows 작업 스케줄러 또는 Linux cron 설정 방법 알려줘.
실패 시 텔레그램 알림 오게 하려면 어떻게 해?

🔧 디버깅 패턴

아래 로그야. 뭐가 문제인지 찾아줘.
[로그 내용]

타임스탬프 패턴, 에러 패턴, 이상한 값 위주로 봐줘.

[명령어]를 실행하면 이렇게 나와:
[실행 결과]

로컬에서는 되는데 서버에서 안 돼.
환경 차이 원인 찾아줘. OS, 파이썬 버전, 패키지 버전 차이 위주로.

📊 데이터 패턴

이 JSON 구조야:
[JSON 샘플]

[원하는 데이터]만 뽑아서 [출력 형식]으로 변환하는 코드 짜줘.

[파일명]에서 받아오는 데이터가 가끔 이상해.
[예상 스키마]대로 오는지 검증하는 코드 추가해줘.
이상한 값 들어오면 로그 찍고 건너뛰도록.

---

⌨️ 슬래시 명령어 전체 목록

Claude Code 대화 중 언제든 입력할 수 있는 명령어들이다. 이 표 하나면 다 된다.

명령어	언제 쓰나	설명
/help	처음 쓸 때	사용 가능한 명령어 전체 목록 보기
/clear	새 작업 시작 전	대화 컨텍스트 완전 초기화 (비용·품질 리셋)
/compact	대화가 길어질 때	대화를 요약본으로 압축. 흐름 유지하면서 토큰 절약
/context	컨텍스트 확인	현재 남은 컨텍스트 윈도우 사용량 확인
/model	모델 바꿀 때	Opus / Sonnet / Haiku 전환
/config	설정 확인	현재 설정 상태 표시
/cost	비용 확인	현재 세션 토큰 사용량 및 비용 확인
/quit · /exit	종료	Claude Code 종료

"내가 저지른 실수를 당신이 반복할 필요 없다. 이미 충분히 비쌌다."

실수 #1 — 탐색 없이 바로 "고쳐줘"

실수 #2 — /clear 안 하고 새 작업 시작

실수 #3 — 너무 큰 작업을 한 번에 던지기

실수 #4 — .env 파일 git에 커밋

.env
*.env
MASTER.env
.env.local
.env.production
secrets.json
*_credentials.json
token*.pickle

실수 #5 — CLAUDE.md 없이 개발 시작

실수 #6 — 성공 기준 없이 "잘 만들어줘"

실수 #7 — 실패 기록 안 하기

실수 #8 — 검증 없이 바로 배포

실수 #9 — 토큰 낭비

실수 #11 — Claude가 루프에 빠졌을 때 방치하기

실수 #12 — 컨텍스트 창 고갈 모르고 계속하기

실수 #10 — Claude 말을 100% 믿기

💰 Part A — 비용 절약 실전 가이드

Claude Code는 claude.ai Pro 플랜($20/월)으로 CLI를 쓰면 별도 API 비용이 없다. 하지만 API를 직접 호출하는 봇을 만들면 토큰 비용이 쌓인다. 이걸 관리하는 법이다.

모델별 비용 & 적합한 용도

모델	상대 비용	쓸 때	쓰지 말 때
Haiku 4.5	★☆☆ 저렴	스코어링, 분류, 짧은 응답, 반복 루프	긴 코드 생성, 복잡한 추론
Sonnet 4.6	★★☆ 중간	일반 개발, 분석, 코드 생성 (기본값)	단순 분류, 짧은 요약
Opus 4.7	★★★ 비쌈	전략 판단, 아키텍처 설계	일상적인 코딩 작업

컨텍스트 관리로 비용 줄이기

import anthropic

client = anthropic.Anthropic()

# ✅ 스코어링: Haiku + max_tokens 제한
def score_lead(item: dict) -> int:
    resp = client.messages.create(
        model="claude-haiku-4-5-20251001",  # 저렴한 모델
        max_tokens=50,                        # 숫자만 반환하면 됨
        system="숫자만 반환. 0~100.",
        messages=[{"role": "user", "content": f"이 업체 구독 가능성: {item}"}]
    )
    return int(resp.content[0].text.strip())

# ✅ 코드 생성: Sonnet + 적절한 토큰
def generate_code(spec: str) -> str:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,          # 코드 생성은 넉넉하게
        messages=[{"role": "user", "content": spec}]
    )
    return resp.content[0].text

---

🖥️ Part B — VS Code 통합 완전 가이드

터미널에서만 쓰는 것보다 VS Code에서 함께 쓰면 훨씬 빠르다.

설치 & 실행

VS Code에서만 되는 것들

추천 VS Code 설정

{
  "editor.formatOnSave": true,
  "terminal.integrated.defaultProfile.windows": "PowerShell",
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "git.autofetch": true,
  "editor.minimap.enabled": false  // 화면 넓게 쓰기
}

---

🌿 Part C — Claude Code + Git 실전

Claude가 직접 git 작업하게 하는 법

새 기능 [기능명] 개발 시작할게.
git checkout -b feature/[기능명] 브랜치 만들어줘.
개발 완료 후에는 커밋 메시지 Conventional Commits 형식으로 작성해줘.

지금까지 바꾼 내용 git diff로 확인하고
의미 있는 단위로 나눠서 커밋해줘.
각 커밋 메시지는 feat/fix/refactor 중 맞는 걸로.

자동 보안 체크 → 커밋 연결

#!/bin/bash
# 커밋 전 .env 파일 포함 여부 자동 체크
if git diff --cached --name-only | grep -E "\.env$|MASTER\.env|secrets\."; then
  echo "❌ 보안 파일이 staged 되어 있습니다. git reset HEAD <파일> 로 제외하세요."
  exit 1
fi
echo "✅ 보안 체크 통과"

GitHub Actions + Claude (고급)

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Claude Code Review
        run: |
          # PR diff를 Claude API로 보내서 리뷰 코멘트 자동 생성
          # anthropic SDK + GitHub API 조합
          python scripts/ai_review.py

---

🔒 Part D — 보안 실전 가이드

Claude Code를 많이 쓸수록 보안 실수 확률도 올라간다. .env를 조심하는 건 기본이고, 이것들도 챙겨라.

이 프로젝트 전체 스캔해줘.
하드코딩된 API 키, 비밀번호, 토큰 있는지 찾아줘.
실제 값은 출력하지 마, 파일명과 라인 번호만 알려줘.

---

👥 Part E — 팀 협업 가이드

혼자 쓸 때랑 팀에서 쓸 때는 다르다. CLAUDE.md를 공유하면 팀 전체가 같은 컨텍스트로 작업할 수 있다.

# 팀 프로젝트 CLAUDE.md

## 코딩 원칙
- Python 함수는 snake_case
- API 응답은 항상 TypedDict로 타입 명시
- 에러는 반드시 로깅 후 raise

## 절대 건드리지 말 것
- db/migrations/ — DBA만 수정
- auth/jwt.py — 보안팀 승인 후 수정

## PR 규칙
커밋 메시지: feat/fix/refactor/docs 중 선택
PR 단위: 기능 1개, 파일 변경 5개 이하

## 환경변수
모든 키는 .env.example 참고. 실제 값은 팀 노션에서 발급.

---

🪟 Part F — Windows 특화 팁

Claude Code 튜토리얼 대부분이 Mac/Linux 기준이다. Windows에서 쓰다 보면 예상치 못한 곳에서 막힌다. 국내 사용자라면 반드시 알아야 할 것들이다.

# 한글 깨짐 방지
$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# Node.js 버전 확인 (v18 이상 필요)
node --version

# Claude Code 실행
claude

* text=auto
*.py text eol=lf
*.js text eol=lf
*.json text eol=lf