공식 문서 밖의 숨은 팁

1. 환경 변수 — 알면 바뀌는 것들

Claude Code 는 공식 환경 변수 레퍼런스에 수십 개의 변수를 문서화하고 있지만, 조합법은 안 알려줘요.

opusplan — 비용 최적화 내장 모델

# Plan Mode 에서는 Opus, 실행에서는 Sonnet
/model opusplan

/model 피커에서 선택 한 번이면 끝. 설계는 비싼 모델로, 구현은 저가 모델로 자동 분기합니다. 환경 변수로 고정하려면 ANTHROPIC_MODEL=opusplan.

settings.json 의 env 블록

환경 변수를 쉘 프로필이 아니라 설정 파일 안에 넣을 수 있습니다:

{
  "model": "claude-sonnet-4-6",
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16000"
  }
}

env 블록이 없으면 /model 에서 "Default" 를 선택했을 때 최신 릴리즈로 풀려요. env 블록은 settings 파일에서 모든 세션에 걸쳐 모델을 고정하는 방법입니다.

자동 compaction 시점 조절

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60

기본값은 약 83% 로 알려져 있는데 (GitHub #31806), 그때는 이미 품질이 떨어지기 시작한 후예요. 60%로 낮추면 Compact 활용법에서 설명한 "60% 룰"이 자동으로 적용됩니다.

2. CLI 플래그 — 잘 안 알려진 것들

CLI 레퍼런스에 있지만 눈에 띄지 않는 플래그들:

스크립트 파이프라인 예시:

claude -p "린트 돌리고 결과 요약해줘" \
  --output-format stream-json \
  --max-budget-usd 0.50 \
  --bare

3. Hook 심화 — 공식 문서에 묻힌 패턴

Hooks 가이드는 길어서 핵심이 묻힙니다. 실전에서 차이를 만드는 세 가지:

if 필드로 정밀 필터링

matcher 는 도구 이름만 걸러요. if 필드는 인자까지 봅니다:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "if": "Bash(git push *)",
        "command": "echo 'push 전 확인: 브랜치가 main 이 아닌지 체크' && git branch --show-current | grep -v '^main$'"
      }]
    }]
  }
}

agent 타입 Hook — 멈추기 전 테스트 자동 실행

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "agent",
        "prompt": "테스트 스위트를 실행하고 결과를 보고해. 실패하면 block.",
        "timeout": 120
      }]
    }]
  }
}

type: agent 는 subagent 가 최대 50턴 동안 도구를 쓸 수 있어요. type: command 보다 훨씬 유연합니다.

stop_hook_active 가드

Stop hook 이 실패하면 Claude 가 다시 작업하고, 또 Stop 하고, 또 hook 실패하고 — 무한 루프. 이걸 막으려면:

INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # 이미 한 번 실행됨 — 통과
fi
npm test --silent 2>/dev/null || exit 2

4. CLAUDE.md 고급 패턴

RFC 2119 언어 사용

"TypeScript strict mode 를 선호합니다" → 무시당함. "TypeScript strict mode 를 MUST 사용합니다" → 따름.

커뮤니티 분석에 따르면, MUST / MUST NOT / SHOULD 같은 RFC 2119 키워드를 쓰면 준수율이 눈에 띄게 올라갑니다.

경로별 규칙 분리

.claude/rules/ 디렉토리에 frontmatter 로 glob 패턴을 지정하면, 해당 디렉토리의 파일을 읽을 때만 규칙이 로드됩니다:

---
paths:
  - "src/api/**"
---
# API Rules
MUST version all endpoints (/v1/, /v2/)

하위 디렉토리 CLAUDE.md 는 세션 시작 시 로드되지 않아요 — Claude 가 해당 디렉토리의 파일을 읽는 순간 lazy-load 됩니다. 큰 레퍼런스 파일을 넣어도 초기 컨텍스트 비용이 0입니다.

다음에 읽을 글

• Session & Context — Compact 활용법 — 컨텍스트 관리 전략 상세
• Slash Commands — Claude Code 카탈로그 — 모든 네이티브 커맨드 레퍼런스

참고 자료

• Claude Code — Environment Variables — 전체 환경 변수 레퍼런스
• Claude Code — CLI Reference — 전체 플래그 목록
• Claude Code — Hooks Guide — Hook 이벤트, 타입, if 필드
• Claude Code — Model Config — opusplan, effort, env 블록
• Claude Code — Best Practices — CLAUDE.md, subagent, 컨텍스트
• CLAUDE.md Maturity Model (DEV Community) — L0-L6 프레임워크
• Enterprise Proxy Model Mapping — 프록시 ID 매칭 주의사항