공식 문서 링크 모음

이 페이지에서 다루는 모든 항목은 다음 Anthropic 공식 문서로 거슬러 올라갑니다. 이 사이트의 정리 내용과 공식 문서가 어긋나면 항상 공식 문서를 우선 따르시면 됩니다.

• Claude Code 개요 ↗
• 메모리 (CLAUDE.md) ↗
• 설정 ↗
• 권한 ↗
• Skills ↗
• Subagents ↗
• Hooks ↗
• Slash 명령 ↗
• MCP ↗
• Plugin 마켓 ↗
• 베스트 프랙티스 ↗

Codex 짝 페이지는 /playbook/setup-codex 에서 같은 사상을 OpenAI Codex 쪽으로 옮긴 형태로 확인하실 수 있습니다.

0. 설치와 로그인

Node 18 이상이 설치돼 있어야 합니다. 회사 결제로 쓰실 때는 SSO 가 적용된 워크스페이스로 로그인하시는 것이 가장 안전합니다.

# Node 18+ 가 필요합니다
npm install -g @anthropic-ai/claude-code

# 로그인 (브라우저 OAuth 로 진행됩니다)
claude login

# 버전 확인
claude --version

개인 구독(Pro / Max) 또는 팀 구독(Team / Enterprise) 어느 쪽이든 같은 CLI 가 동작합니다.

빠른 시작 — 스크립트 또는 플러그인

Claude Code 는 세 가지 빠른 시작 경로가 있습니다. 하나는 이 저장소가 제공하는 starter 스크립트로 최소 표면을 한 번에 복사하는 방식이고, 다른 하나는 revfactory/harness 처럼 자연어 프롬프트로 하네스 골격을 생성하는 검증된 plugin 을 쓰는 방식이며, 나머지 하나는 oh-my-claudecode 처럼 Team 중심 오케스트레이션 레이어를 Claude Code 위에 얹는 방식입니다.

A. starter 스크립트로 복사

bash scripts/setup-claude-harness.sh /path/to/your-project

이 프로젝트 주제에 맞춰서 하네스를 구성해줘.
현재 있는 CLAUDE.md 와 .claude/ 를 기준으로
이 프로젝트에 필요한 agents, skills, rules, hooks 를 최소 구조부터 보강해줘.
검증 명령과 운영 안전선도 같이 정리해줘.

B. revfactory/harness plugin 사용

하네스 자체를 자연어로 생성하는 검증된 plugin 입니다. 프로젝트 도메인을 분석해 .claude/agents/ 와 .claude/skills/ 골격을 자동 생성합니다.

# 1) 마켓플레이스 등록
/plugin marketplace add revfactory/harness

# 2) 플러그인 설치
/plugin install harness@harness

하네스 구성해줘
이 프로젝트에 맞는 에이전트 팀 구축해줘
풀스택 웹사이트 개발 하네스를 구성해줘

C. oh-my-claudecode plugin 사용

Team 중심 오케스트레이션, 매직 키워드, tmux 기반 Codex · Gemini worker 까지 함께 쓰고 싶다면 OMC 경로가 더 맞습니다. README.ko.md 확인 기준으로는 Team이 표준 이고, swarm 은 레거시 호환 으로 읽으시면 됩니다.

# 1) 마켓플레이스 등록
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# 2) 플러그인 설치
/plugin install oh-my-claudecode

# 3) 설정 반영
/omc-setup

/deep-interview "I want to build an internal admin portal"
/team 3:executor "fix all TypeScript errors"
autopilot: build a task management API

1. 프로젝트 메모리 — CLAUDE.md

프로젝트 루트에 CLAUDE.md 파일을 두십시오. 모든 Claude Code 세션이 시작 시점에 자동으로 읽습니다. 다음 세 가지만 지키시면 됩니다.

• 200줄 이하로 유지하십시오. 그 이상은 컨텍스트만 차지하고 모델이 자주 무시합니다.
• 짧고 검증 가능한 문장만 두십시오. “좋게 잘 작성하세요” 같은 표현은 모델이 거의 활용하지 못합니다.
• 긴 규칙은 @AGENTS.md 또는 @.claude/rules/security.md 처럼 inline import 로 끌어오십시오. CLAUDE.md 본문은 항상 가벼워야 합니다.

# 프로젝트 메모리

## 빌드와 검증
- 빌드: pnpm build
- 검증: pnpm lint && pnpm build && pnpm test
- 한국어 콘텐츠는 모두 존댓말로 작성합니다

## 안전 기본값
- 운영 계정에 영향이 가는 명령은 반드시 사용자 확인 후 실행
- .env 와 *.pem 파일은 읽지 않습니다
- 마이그레이션은 staging 에서 한 번 확인 후 main 에 머지합니다

## 자세한 규칙
@AGENTS.md
@.claude/rules/security.md

2. 권한과 훅 — .claude/settings.json

모든 권한과 훅은 .claude/settings.json 한 파일에 둡니다. 위험 명령은 deny, 자주 쓰는 명령은 allow, 그 사이는 ask 로 둡니다. 평가 순서는 항상 deny > ask > allow 이므로, 한 번 deny 에 들어간 명령은 어떤 allow 매처로도 풀리지 않습니다.

{
  "$schema": "https://schemas.anthropic.com/claude-code/settings.json",
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(./gradlew test)",
      "Bash(./gradlew ktlintCheck)",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Read(**/*.md)",
      "Read(**/*.kt)",
      "Read(**/*.tsx)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git commit *)",
      "Bash(gh pr create *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(kubectl delete *)",
      "Bash(terraform apply)",
      "Bash(terraform destroy)",
      "Read(.env*)",
      "Read(**/*.pem)",
      "Read(**/secrets/**)"
    ]
  },
  "hooks": {
    "SessionStart": [
      {
        "command": "/usr/bin/python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session_start_context.py\""
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/usr/bin/python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre_bash_guard.py\""
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/post_kt_lint.sh\""
      }
    ]
  }
}

훅 스크립트 안에서 사용 가능한 환경 변수는 다음과 같습니다.

• $CLAUDE_PROJECT_DIR — 현재 프로젝트 루트 절대경로
• $CLAUDE_TOOL_INPUT — PreToolUse / PostToolUse 에서 도구 인자가 JSON 으로 들어옵니다 (stdin 도 동일)
• $CLAUDE_HOOK_EVENT — 이벤트 이름 (SessionStart, PreToolUse, PostToolUse 등)

3. Skills 와 Subagents

Skills — 반복 워크플로 자동화

스킬은 .claude/skills/<name>/SKILL.md 에 둡니다. frontmatter 의 description 이 사용자 메시지와 매칭되면 자동 활성화되고, /skill-name 으로 명시 호출도 가능합니다.

---
name: verify
description: 저장소 전체 검증을 한 번에 실행합니다 (lint + test + build). 사용자가 "검증해줘", "verify", "test all" 같은 표현을 쓰면 자동 활성화됩니다.
allowed-tools:
  - Bash
  - Read
model: sonnet
---

# /verify

이 스킬은 저장소 전체 회귀 검증을 실행합니다.

## 절차
1. `pnpm lint` 를 실행합니다
2. `pnpm test` 를 실행합니다
3. `pnpm build` 를 실행합니다
4. 실패한 항목이 있으면 그대로 출력하고 중단합니다
5. 모두 통과하면 한 줄 요약과 함께 종료합니다

## 출력 계약
- 마지막 줄은 항상 "검증 통과" 또는 "검증 실패: <원인>" 으로 끝납니다

스킬을 만들 때 가장 중요한 것은 description 한 문장 입니다. 이 한 줄로 자동 활성화 정확도가 결정됩니다.

Subagents — 좁은 역할의 병렬 일꾼

서브에이전트는 .claude/agents/<name>.md 에 두십시오. 메인 세션과 별도의 컨텍스트로 동작하므로 reviewer · verifier · docs-researcher 같은 좁은 read-only 역할에 가장 효과적입니다.

---
name: kotlin-reviewer
description: Kotlin 코드 변경에 대한 정확성·테스트 누락·동시성 문제 중심 리뷰. 사용자가 "리뷰", "review", "검토" 같은 표현을 쓰면 자동 활성화됩니다.
model: haiku
tools:
  - Read
  - Grep
  - Glob
---

당신은 Kotlin 코드 리뷰 전문가입니다. 다음 우선순위로 리뷰를 진행합니다.

1. 회귀 가능성: 변경이 기존 테스트를 깨지 않는가
2. 테스트 누락: 새 분기·예외 경로에 테스트가 있는가
3. 동시성: coroutine, mutex, suspend 함수 순서가 안전한가
4. 포맷 드리프트: ktlint 가 통과하는가
5. 명명 일관성: 기존 코드 베이스와 같은 패턴인가

각 항목은 한 문단으로 정리하시고, 마지막에 "OK" 또는 "수정 필요: <항목>" 한 줄로 끝내십시오.

4. Path-specific 규칙 — .claude/rules/

특정 디렉터리에만 적용되는 규칙은 .claude/rules/<name>.md 로 분리해 두십시오. 모듈별로 다른 안전 기준을 적용할 수 있고, CLAUDE.md 본문이 무거워지는 것을 막습니다.

---
glob:
  - "src/api/**/*.kt"
  - "src/api/**/*.tsx"
---

# API 계층 보안 규칙

- 모든 라우트에는 인증 미들웨어가 적용되어야 합니다
- 외부 입력은 zod 또는 jakarta validation 으로 한 번 더 검증합니다
- DB 쿼리는 raw SQL 대신 jOOQ 빌더를 사용합니다
- 응답에는 PII 가 포함되지 않는지 직접 확인합니다
- 새 엔드포인트를 추가하면 같은 이름의 통합 테스트도 함께 추가합니다

5. Hook 스크립트 패턴

훅 스크립트는 짧고 결정적이어야 합니다. 다음 두 개가 가장 자주 쓰이는 패턴입니다.

#!/usr/bin/env python3
"""
PreToolUse hook — 위험한 Bash 명령을 사전에 차단합니다.
exit 2 = 차단, exit 0 = 통과
"""
import json, os, re, sys

DENY_PATTERNS = [
    r"rm\s+-rf\s+/",
    r"git\s+push\s+--force",
    r"git\s+reset\s+--hard",
    r"DROP\s+TABLE",
    r"kubectl\s+delete",
    r"terraform\s+(apply|destroy)",
    r"helm\s+uninstall",
    r"mlflow\s+models\s+delete",
]

payload = json.loads(sys.stdin.read() or "{}")
command = payload.get("tool_input", {}).get("command", "")

for pattern in DENY_PATTERNS:
    if re.search(pattern, command, re.IGNORECASE):
        print(f"BLOCKED: 위험 명령 감지 — {pattern}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

#!/usr/bin/env python3
"""
SessionStart hook — 세션 시작 시 저장소 컨텍스트를 주입합니다.
출력 텍스트는 모델 컨텍스트에 그대로 들어갑니다.
"""
import os, subprocess, sys

root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())

# 마지막 commit hash + 메시지
last_commit = subprocess.run(
    ["git", "-C", root, "log", "-1", "--format=%h %s"],
    capture_output=True, text=True
).stdout.strip()

print(f"## 세션 컨텍스트 (자동 주입)")
print(f"- 저장소 루트: {root}")
print(f"- 최근 커밋: {last_commit}")
print(f"- 검증 명령: pnpm lint && pnpm test && pnpm build")
print(f"- 위험 명령은 .claude/hooks/pre_bash_guard.py 가 차단합니다")
sys.exit(0)

6. MCP 서버 등록과 Plugin 마켓

MCP 서버 등록

MCP 서버는 글로벌(~/.claude/settings.json) 또는 프로젝트(.claude/settings.json) 둘 다에서 등록할 수 있습니다. Playwright 와 Context7 은 거의 모든 프로젝트에 가치가 있어서 글로벌에 두시는 것을 권장드립니다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Plugin 마켓 활용

Claude Code 의 강점 중 하나는 plugin 마켓입니다. 좋은 플러그인 하나가 잘 만든 스킬 5개를 대체합니다. 세션 안에서 /plugin marketplace add 과 /plugin install 명령으로 설치하시면 됩니다.

가장 자주 쓰이는 plugin 묶음은 다음과 같습니다.

• obra/superpowers — Anthropic 공식 마켓에 등재된 skill 프레임워크. brainstorm, write-plan, execute-plan, verification-before-completion 같은 슬래시 명령과 자동 활성화 스킬을 묶어 제공합니다.
• affaan-m/everything-claude-code (ECC) — 30+ 전문 에이전트, 100+ 스킬, 60+ 슬래시 명령을 한 묶음으로 제공하는 멀티 도구 하네스 시스템입니다.
• codex 통합 plugin — Claude 세션 안에서 Codex 로 작업을 위임하실 수 있습니다.
• oh-my-claudecode — Team 중심 오케스트레이션 레이어. README 기준으로 Team이 표준이며, Codex · Gemini 는 `omc team` tmux worker 로 붙입니다.
• notebooklm-mcp — NotebookLM 노트북 자동화. 자료 조사 흐름에 강합니다.

OMC를 설치하셨다면 업데이트는 /plugin marketplace update omc 다음 /omc-setup 순서로 보시는 편이 맞습니다. 업데이트 후 꼬였을 때는 /omc-doctor 로 상태를 점검하는 흐름이 README에 정리돼 있습니다.

더 깊게 보고 싶으시면 인기 GitHub 하네스 레포 10선 과 oh-my-claudecode 읽기 가이드 페이지에 stars · license · 적용 가이드를 함께 정리해 두었습니다.

7. 모델 선택 가이드

• Opus 4.6 — 메인 세션, 어려운 리팩터링, 다단계 설계 결정. 비싸지만 가장 정확합니다.
• Sonnet 4.6 — 일반 구현, 코드 리뷰, 문서 작성. Opus 의 80% 품질을 약 1/5 비용에.
• Haiku 4.5 — 서브에이전트, 분류, 단순 검색, 빠른 보조. Sonnet 의 1/3 비용.

8. 권장 도입 순서

9. 자주 묻는 운영 이슈

Q. 같은 명령을 매번 ask 하는 게 너무 잦습니다.

허용해도 되는 명령은 allow 매처를 더 구체적으로 잡으십시오. 예를 들어 Bash(pnpm test:*) 처럼 prefix 를 좁히면 ask 빈도를 크게 줄일 수 있습니다. 단, deny 와 충돌하지 않게 평가 순서를 다시 확인하셔야 합니다.

Q. CLAUDE.md 가 너무 길어집니다.

본문은 200줄 안쪽으로 두시고, 긴 규칙은 .claude/rules/<name>.md 또는 AGENTS.md 로 분리한 다음@ 로 import 하십시오. 본문이 무거우면 모델이 마지막에 적힌 규칙만 보고 앞 규칙을 무시합니다.

Q. 훅 스크립트가 동작하지 않습니다.

먼저 실행 권한(chmod +x)을 확인하시고, 절대경로로 셸을 명시하시는 것이 가장 안전합니다(예 /usr/bin/python3 ...). 훅이 입력을 어떻게 받는지 모를 때는 stdin 으로 cat >/tmp/payload.json 를 한 번 흘려서 페이로드를 직접 보는 것이 가장 빠릅니다.

Q. 토큰 비용이 예상보다 빠르게 늘어납니다.

거의 모든 경우 메인 세션이 Opus 인 채로 단순 작업까지 다 처리하기 때문입니다. 분류·검색·문서 확인은 Haiku 서브에이전트로, 일반 구현은 Sonnet 으로 분리하시는 것만으로도 비용이 절반 이하로 떨어지는 경우가 많습니다. 더 깊은 비용 패턴은 /reference/token-economics 에 정리돼 있습니다.

Q. Team 이나 omc team 이 기대대로 동작하지 않습니다.

Claude Code 네이티브 Team 을 쓰실 때는 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 이 설정돼 있는지 먼저 보십시오. 반대로 omc team 은 tmux 와 외부 CLI 설치가 전제입니다. Codex · Gemini worker 까지 붙이실 때는 해당 CLI 가 실제로 PATH 에 잡히는지까지 같이 확인하셔야 합니다.