claude-code

어떤 스킬인가요?

[Hyper] Use when the user explicitly wants Anthropic Claude Code CLI (`claude`) for an isolated session, non-interactive (`-p`) run, session resume by ID or name, or a CI-friendly `--bare` invocation. Trigger phrases: \"use claude code\", \"ask claude\", \"run claude\", \"continue the last claude session\", \"resume the auth-refactor claude session\", or \"use Anthropic's CLI to inspect or fix this repo\".

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# 명령 예시

이 예시들은 라우팅 판단이 끝난 뒤에만 사용한다. 모든 플래그는 공식 CLI 레퍼런스(<https://code.claude.com/docs/en/cli-reference>) 기준이다.

## 기본 비대화형 분석

`-p` / `--print` 는 SDK 루프를 한 번 돌고 종료한다.

```bash
claude --permission-mode default \
  -p "이 저장소의 최신 diff를 검토하고 주요 위험을 요약해줘."
```

## CI / 스크립트용 Bare 모드

`--bare` 는 훅·스킬·플러그인·MCP·auto memory·CLAUDE.md 자동 발견을 모두 끈다. 어느 머신에서도 같은 결과를 보장한다. OAuth 키체인도 건너뛰므로 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, 혹은 `--settings` 의 `apiKeyHelper` 가 필요하다.

```bash
ANTHROPIC_API_KEY=$KEY claude --bare -p "이 파일 요약해줘" \
  --allowedTools "Read"
```

Bare 모드 없이 CI 용 장기 토큰을 쓰려면:

```bash
# 한 번만: claude setup-token   (출력된 토큰을 시크릿 저장소로 옮긴다)
export CLAUDE_CODE_OAUTH_TOKEN=...
claude -p "diff 요약해줘" --output-format json
```

## 명시적 파일 수정

사용자가 Claude Code 가 파일을 수정하길 명시적으로 요청했을 때만 사용한다. `acceptEdits` 는 `mkdir`, `touch`, `mv`, `cp`, `rm`, `rmdir`, `sed` 같은 일반 파일 시스템 명령도 자동 승인한다.

```bash
claude --permission-mode acceptEdits \
  -p "src/app.ts 를 패치해서 failing build를 고치고 변경 이유를 설명해줘."
```

## 읽기 전용 계획

파일 변경이나 셸 실행 없이 분석/계획만 원할 때 사용한다.

```bash
claude --permission-mode plan \
  -p "이 아키텍처를 분석하고 주요 위험을 정리해줘."
```

## `dontAsk` 로 잠긴 CI

`dontAsk` 는 프롬프트가 뜰 만한 모든 호출을 자동 거부한다. 필요한 도구만 사전 허용한다.

```bash
claude --permission-mode dontAsk \
  --allowedTools "Read" "Bash(git diff *)" "Bash(git log *)" \
  -p "스테이징된 변경만 요약해줘."
```

## 장시간 작업용 Auto 모드

Auto 모드는 액션마다 묻지 않고 진행하며, 서버측 분류기가 위험 행위를 차단한다. v2.1.83+ 와 지원 모델, 관리자 활성화된 플랜이 필요하다.

```bash
claude --permission-mode auto \
  -p "MIGRATION.md 의 마이그레이션 계획을 실행하되 절대 main 에 push 하지 마."
```

분류기는 프롬프트 안의 경계 선언("절대 main 에 push 하지 마") 도 차단 신호로 읽는다.

## 최근 세션 계속하기

현재 디렉터리의 가장 최근 대화에 이어서 붙는다. `-c` 는 단축형이다.

```bash
claude --continue \
  -p "이전 작업을 계속하고 다음 의사결정을 요약해줘."
```

## 이름 또는 ID 로 특정 세션 재개

`--resume` 은 표시 이름(`--name` / `-n`, 또는 `/rename` 으로 지정) 또는 세션 ID 를 받는다.

```bash
claude --resume "auth-refactor" \
  -p "이 세션에서 이어서 후속 요청을 처리해줘."

claude --resume <session-id> \
  -p "이 세션에서 이어서 후속 요청을 처리해줘."
```

## 재현 스크립트용 UUID 고정

`--session-id` 는 유효한 UUID 만 받는다. 같은 UUID 로 다시 실행하면 같은 대화에 이어붙는다.

```bash
claude --session-id 550e8400-e29b-41d4-a716-446655440000 \
  -p "이 턴을 안정된 대화에 추가해줘."
```

## PR 에 연결된 세션 재개

```bash
claude --from-pr 123 \
  -p "최근 리뷰 코멘트 반영해줘."
```

## 기존 세션에서 분기

원래 세션을 재사용하지 않고 갈라서 시도하고 싶을 때 사용한다.

```bash
claude --resume <session-id> \
  --fork-session \
  -p "이 시점부터 이어가되, 다른 수정 방안을 탐색해줘."
```

## 추가 디렉터리 포함

`--add-dir` 은 파일 접근 권한만 부여한다. `.claude/skills/` 외의 다른 `.claude/` 설정은 추가 디렉터리에서 로드되지 않는다.

```bash
claude --add-dir ../shared \
  --permission-mode default \
  -p "이 저장소와 shared 디렉터리를 함께 보고 통합 지점을 요약해줘."
```

## 구조화된 JSON 출력

```bash
claude --permission-mode default \
  --output-format json \
  -p "이 diff를 기준으로 summary, risks, next_steps 키를 가진 JSON 객체를 반환해줘."
```

스키마 검증된 출력이 필요하면 `--output-format json` 과 `--json-schema` 를 함께 쓴다. 검증된 결과는 JSON envelope 의 `structured_output` 필드에 들어온다.

```bash
claude -p "auth.py 의 함수 이름을 추출해줘" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
```

## 실시간 스트리밍

`stream-json` 은 줄 단위 JSON 이벤트를 내보낸다. 토큰 델타를 보려면 `--verbose` 와 `--include-partial-messages` 를 함께 쓴다.

```bash
claude -p "재귀를 설명해줘" \
  --output-format stream-json --verbose --include-partial-messages
```

## 한정된 자율 실행

턴 수와 달러 한도를 정해 자율 실행이 무한 반복되지 않게 한다. 폴백 모델을 추가하면 한 번의 과부하로 작업이 죽지 않는다.

```bash
claude -p "오픈 이슈를 분류하고 답변 초안을 작성해줘." \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --fallback-model sonnet
```

## 도구 제한 또는 추가

```bash
# 빌트인만 사용, Bash 금지
claude -p "이 모듈 리팩터링 해줘." --tools "Read,Edit"

# 필요한 것만 사전 허용
claude -p "스테이징하고 커밋해줘." \
  --allowedTools "Bash(git add *)" "Bash(git commit *)" "Bash(git status *)"

# 특정 도구만 차단
claude -p "이 모듈 리팩터링 해줘." --disallowedTools "Bash"
```

## 시스템 프롬프트 조정

기본값을 유지하려면 append 계열을 우선한다.

```bash
claude -p "이 PR 리뷰해줘." \
  --append-system-prompt "너는 보안 엔지니어다. 인젝션과 인가 결함을 먼저 표시해."

claude -p "이 PR 리뷰해줘." \
  --append-system-prompt-file ./prompts/security-reviewer.txt
```

전체 교체가 필요할 때만 replacement 계열을 쓴다.

```bash
claude -p "..." --system-prompt "너는 Python 전문가다."
claude -p "..." --system-prompt-file ./prompts/full-prompt.md
```

## MCP 서버 로드

```bash
claude --mcp-config ./mcp.json \
  -p "데이터베이스 MCP 서버로 스키마 요약해줘."

# 재현성을 위해 다른 MCP 소스를 모두 무시
claude --strict-mcp-config --mcp-config ./mcp.json -p "..."
```

## 위험한 권한 우회는 명시적 승인 후에만

`--dangerously-skip-permissions` 는 `--permission-mode bypassPermissions` 와 같다. 사용자의 명시적 승인 후, 그리고 네트워크가 차단된 컨테이너/VM 처럼 격리된 환경에서만 사용한다. prompt injection 보호가 없으므로 "프롬프트가 적었으면" 이라는 목적이라면 `auto` 모드를 우선 검토한다.

```bash
claude --dangerously-skip-permissions \
  -p "요청된 패치를 적용하고 필요한 검증을 실행해줘."
```

# Command Recipes

Use these recipes after the routing decision is already clear. All flags follow the official CLI reference at <https://code.claude.com/docs/en/cli-reference>.

## Default Headless Analysis

`-p` / `--print` runs the SDK loop and exits.

```bash
claude --permission-mode default \
  -p "Review the latest diff in this repository and summarize the main risks."
```

## Bare Mode for CI / Scripts

`--bare` skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so the same command produces the same result on every machine. It also skips the OAuth keychain — supply credentials via `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or an `apiKeyHelper` in `--settings`.

```bash
ANTHROPIC_API_KEY=$KEY claude --bare -p "Summarize this file" \
  --allowedTools "Read"
```

For a long-lived CI token without bare mode:

```bash
# One-time: claude setup-token   (prints a token; copy it to your secret store)
export CLAUDE_CODE_OAUTH_TOKEN=...
claude -p "Summarize the diff" --output-format json
```

## Explicit File Edit

Only use this when the user explicitly asked Claude Code to modify files. `acceptEdits` also auto-approves common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, `rm`, `rmdir`, `sed`).

```bash
claude --permission-mode acceptEdits \
  -p "Patch src/app.ts to fix the failing build and explain the change."
```

## Read-Only Planning

Use this when the user wants planning or analysis without file changes or shell execution.

```bash
claude --permission-mode plan \
  -p "Analyze this architecture and list the main risks."
```

## Locked-Down CI with `dontAsk`

`dontAsk` auto-denies anything that would otherwise prompt. Pre-approve exactly the tools the run needs.

```bash
claude --permission-mode dontAsk \
  --allowedTools "Read" "Bash(git diff *)" "Bash(git log *)" \
  -p "Summarize the staged changes only."
```

## Auto Mode for Long Tasks

Auto mode lets Claude work without per-action prompts; a server-side classifier blocks risky actions. Requires v2.1.83+, a supported model, and an admin-enabled plan.

```bash
claude --permission-mode auto \
  -p "Run the migration plan in MIGRATION.md, but never push to main."
```

State boundaries in the prompt itself ("never push to main") — the classifier reads them as block signals.

## Continue the Latest Session

Use this for the most recent conversation in the current directory. `-c` is the short form.

```bash
claude --continue \
  -p "Continue the previous task and summarize the next decision."
```

## Resume a Specific Session by Name or ID

`--resume` accepts a display name (set with `--name` / `-n`, or `/rename`) or a session ID.

```bash
claude --resume "auth-refactor" \
  -p "Continue from this session and apply the follow-up request."

claude --resume <session-id> \
  -p "Continue from this session and apply the follow-up request."
```

## Pin a UUID Session for Reproducible Scripts

`--session-id` requires a valid UUID. The same UUID across runs reuses the same conversation.

```bash
claude --session-id 550e8400-e29b-41d4-a716-446655440000 \
  -p "Append this turn to a stable conversation."
```

## Resume Sessions Linked to a Pull Request

```bash
claude --from-pr 123 \
  -p "Address the latest review comments."
```

## Fork From an Existing Session

Use this when the user wants to branch instead of reusing the original session.

```bash
claude --resume <session-id> \
  --fork-session \
  -p "Continue from this point, but explore an alternative fix."
```

## Additional Directories

`--add-dir` grants file access; it does NOT load `.claude/` configuration from added directories (except `.claude/skills/`).

```bash
claude --add-dir ../shared \
  --permission-mode default \
  -p "Inspect this repo and the shared directory, then summarize the integration points."
```

## Structured JSON Output

```bash
claude --permission-mode default \
  --output-format json \
  -p "Return a JSON object with keys summary, risks, and next_steps for this diff."
```

For schema-validated output, pair `--output-format json` with `--json-schema`. The validated result lands in the `structured_output` field of the JSON envelope.

```bash
claude -p "Extract the function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
```

## Real-Time Streaming

`stream-json` emits newline-delimited events; pair with `--verbose` and `--include-partial-messages` to see token deltas.

```bash
claude -p "Explain recursion" \
  --output-format stream-json --verbose --include-partial-messages
```

## Bounded Autonomous Run

Cap turns and dollars so an autonomous run cannot drift forever. Add a fallback model so a single overload does not abort the job.

```bash
claude -p "Triage open issues and draft replies." \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --fallback-model sonnet
```

## Restrict or Augment Tools

```bash
# Built-ins only, no Bash
claude -p "Refactor this module." --tools "Read,Edit"

# Pre-approve just what is needed
claude -p "Stage and commit the change." \
  --allowedTools "Bash(git add *)" "Bash(git commit *)" "Bash(git status *)"

# Block specific tools instead
claude -p "Refactor this module." --disallowedTools "Bash"
```

## Custom System Prompt

Prefer the append flags so Claude Code's defaults stay in place.

```bash
claude -p "Review this PR." \
  --append-system-prompt "You are a security engineer. Flag injection and authz bugs first."

claude -p "Review this PR." \
  --append-system-prompt-file ./prompts/security-reviewer.txt
```

Use the replacement flags only when total control of the system prompt is needed:

```bash
claude -p "..." --system-prompt "You are a Python expert."
claude -p "..." --system-prompt-file ./prompts/full-prompt.md
```

## Load MCP Servers

```bash
claude --mcp-config ./mcp.json \
  -p "Use the database MCP server to summarize the schema."

# Ignore every other MCP source for reproducibility
claude --strict-mcp-config --mcp-config ./mcp.json -p "..."
```

## Dangerous Bypass Only With Explicit Approval

`--dangerously-skip-permissions` is equivalent to `--permission-mode bypassPermissions`. Only use it after explicit user approval, and only in isolated environments such as containers or VMs without network access. It offers no protection against prompt injection — prefer `auto` mode when "fewer prompts" is the actual goal.

```bash
claude --dangerously-skip-permissions \
  -p "Apply the requested patch and run the requested checks."
```

# 라우팅 규칙

사용자가 `claude` CLI 자체, 별도 Claude Code 세션, 비대화형(`-p`) 실행, `--bare` 호출, 또는 세션 재개 플로우 중 하나를 명시적으로 원할 때만 이 스킬을 사용한다.

요청이 실제로 `claude` CLI를 필요로 하지 않으면 다른 경로로 전환한다.

## 범위 안

- 분석·검토·계획·구조화 출력(`json`, `stream-json`, `--json-schema`) 등을 위해 `claude -p` 를 실행해야 할 때
- `--continue` (`-c`), `--resume` (`-r`) (ID 또는 표시 이름), `--from-pr`, `--session-id` (UUID), `--fork-session` 으로 Claude Code 세션을 이어가야 할 때
- 사용자가 `claude` CLI 를 워크플로 일부로 명시했고 Claude Code 에게 코드 점검·패치를 맡기려 할 때 (`--allowedTools` / `--disallowedTools` / `--tools` 로 사전 허용 도구 집합 지정 포함)
- 로컬 훅·플러그인·MCP·auto memory·CLAUDE.md 를 끌어오면 안 되는 CI / 스크립트 실행에 `--bare` 를 써야 할 때
- 추가 저장소 경로가 필요한 Claude Code 실행에 `--add-dir` 을 써야 할 때 (파일 접근만 부여하며, `.claude/skills/` 를 제외한 다른 `.claude/` 설정은 로드되지 않음)
- 권한 모드 선택: `default`, `plan`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`
- `claude auth login`, `claude auth status`, `claude auth logout`, `claude setup-token` (CI 용 장기 OAuth) 로 인증 또는 자격 증명 회전이 필요할 때

## 범위 밖

- `claude` CLI 없이도 가능한 스킬 생성 또는 스킬 리팩터링
- 일반 문서 작성, 문서 정리, 런북 수정
- 사용자가 Claude Code를 요청하지 않았고 직접 로컬 편집이 더 단순한 작업
- Claude Code 실행보다 Anthropic 제품 조사 자체가 주목적인 리서치 작업

요청이 실제로 `claude` CLI 를 필요로 하지 않으면 다른 스킬이나 직접 편집으로 넘긴다.

일반 글쓰기, 스킬 생성, 직접 하는 편이 더 쉬운 로컬 편집을 위해 Claude Code 명령을 만들지 않는다.
Claude Code 가 맡을 일이 아닌데 억지로 실행하려고 `--dangerously-skip-permissions` 또는 `--permission-mode bypassPermissions` 까지 올리지 않는다 — 두 옵션 모두 사용자의 명시적 승인과 컨테이너/VM 같은 격리된 환경이 필요하다.
Claude Code 가 맞지 않는 작업이면 깔끔하게 다른 경로로 전환한다.

# Routing Rules

Use Claude Code when the user explicitly wants the `claude` CLI, a separate Claude Code session, or one of Claude Code's non-interactive (`-p`), `--bare`, or session-resume flows.

Route away when the request does not actually need the `claude` CLI.

## In Scope

- Run `claude -p` for analysis, review, planning, or structured (`json` / `stream-json` / `--json-schema`) output.
- Resume or continue a Claude Code session with `--continue` (`-c`), `--resume` (`-r`) by ID or display name, `--from-pr`, `--session-id` (UUID), or `--fork-session`.
- Ask Claude Code to inspect or patch code when the `claude` CLI is part of the requested workflow, including pre-approved tool sets via `--allowedTools` / `--disallowedTools` / `--tools`.
- Use `--bare` for a CI / scripted run that must not pick up local hooks, plugins, MCP servers, auto memory, or CLAUDE.md.
- Use `--add-dir` when the requested Claude Code run needs extra repository paths (file access only — `.claude/` config beyond `.claude/skills/` is not loaded from added directories).
- Choose a permission mode: `default`, `plan`, `acceptEdits`, `auto`, `dontAsk`, or `bypassPermissions`.
- Authenticate or rotate credentials with `claude auth login`, `claude auth status`, `claude auth logout`, or `claude setup-token` (long-lived OAuth for CI).

## Route Away

- Create or refactor a skill without needing the `claude` CLI.
- Rewrite generic prose, docs, or runbooks.
- Perform direct local edits when the user did not ask for Claude Code and it adds no clear value.
- Do Anthropic product research when the main job is fact-finding rather than running Claude Code.

Use another skill or direct editing when the request does not actually need the `claude` CLI.

Do not build a Claude Code command for generic writing, skill creation, or local edits that are easier to do directly.
Do not escalate to `--dangerously-skip-permissions` (or `--permission-mode bypassPermissions`) just to force Claude Code into a task it does not own; both require explicit user approval and an isolated environment such as a container or VM.
When Claude Code is the wrong tool, route away cleanly instead of running it anyway.

---
name: claude-code
description: >-
  사용자가 Anthropic Claude Code CLI(`claude`) 자체를 명시적으로 원할 때 사용.
  격리된 세션 실행, 비대화형(`-p`) 실행, ID 또는 이름 기반 세션 재개,
  CI 친화적인 `--bare` 호출이 대상이다. 트리거 문구 예시:
  "claude code 써줘", "claude한테 물어봐", "claude 실행해",
  "지난 claude 세션 이어줘", "auth-refactor claude 세션 재개해",
  "Anthropic CLI로 이 저장소를 점검하거나 수정해줘".
compatibility: Claude Code CLI(`claude`)가 필요하며, 해당 CLI가 설치된 환경에서만 동작합니다.
---

@rules/routing.ko.md

# Claude Code 스킬

<output_language>

사용자에게 보이는 모든 산출물, 저장 아티팩트, 리포트, 계획서, 생성 문서, 요약, 인수인계 메모, 커밋/메시지 초안, 검증 메모는 기본적으로 한국어로 작성합니다.

소스 코드 식별자, CLI 명령, 파일 경로, 스키마 키, JSON/YAML 필드명, API 이름, 패키지명, 고유명사, 인용한 원문 발췌는 필요한 언어 또는 원문 그대로 유지합니다.

사용자가 명시적으로 다른 언어를 요청했거나, 기존 대상 산출물의 언어 일관성을 맞춰야 하거나, 기계 판독 계약상 정확한 영어 토큰이 필요한 경우에만 다른 언어를 사용합니다. 사용자-facing 산출물에 쓸 로컬라이즈된 템플릿/참조(`*.ko.md`, `*.ko.json` 등)가 있으면 우선 사용합니다.

</output_language>

진실 공급원: <https://code.claude.com/docs/en/cli-reference>

<instruction_contract>

| 항목 | 계약 |
|---|---|
| Intent | 사용자가 Claude Code를 명시적으로 요청했을 때 안전한 `claude` CLI 호출을 만들거나 설명합니다. |
| Scope | `claude`의 명령 구성, 세션 재개 플래그, 권한 모드 선택, 도구 제한, 인증 안내, 결과 요약을 담당합니다. |
| Authority | 사용자 의도와 로컬 프로젝트 규칙이 우선하며, CLI 플래그는 링크된 Claude Code CLI 레퍼런스를 진실 공급원으로 삼습니다. |
| Evidence | 명령 형태, CLI 출력, support-file 지침, 관찰된 경고/오류에 근거합니다. |
| Tools | 사용자가 실제 CLI 실행을 원할 때만 셸 실행을 사용하고, 그 외에는 명령을 제안하거나 라우팅을 전환합니다. |
| Output | 사용했거나 권장하는 정확한 명령, 출력/경고 요약, CLI 토큰을 원문 그대로 제공합니다. |
| Verification | 비대화형 실행이 `-p`를 쓰는지, 권한 모드가 요청 권한과 맞는지, 위험 우회가 gate되어 있는지 확인합니다. |
| Stop condition | 요청된 명령을 구성하거나 실행한 뒤 결과, 경고, blocker를 보고하면 멈춥니다. |

</instruction_contract>

## 기본값

| 항목 | 기본값 |
|------|--------|
| 모델 선택 | 사용자가 `--model` 을 명시적으로 요구하지 않으면 Claude Code CLI 기본 모델 사용 |
| 추론 강도 | 사용자가 `--effort` 를 명시적으로 요구하지 않으면 CLI 기본값 사용 |
| 권한 모드 | `--permission-mode default` |
| 헤드리스 모드 | `-p` / `--print` |
| CI / 스크립트 실행 | `--bare` 를 추가해 로컬 훅·플러그인·MCP·CLAUDE.md 자동 발견을 끈다 |
| 재개 대상 | 현재 디렉터리 최근 세션은 `claude --continue` (`-c`), 특정 세션은 ID 또는 표시 이름으로 `claude --resume` (`-r`) |

사용자가 명시적으로 요청하지 않는 한 모델이나 `--effort` 를 묻지 않는다.

## 라우팅

이 스킬은 실제로 `claude` CLI 또는 별도 Claude Code 세션이 필요한 요청에만 사용한다.

- 요청이 범위를 벗어날 수 있으면 먼저 [rules/routing.ko.md](rules/routing.ko.md)를 읽고 커맨드를 만들지 말지 결정한다.
- `claude` CLI 자체가 필요 없는 일반 문서 작성, 문서 정리, 직접 로컬 편집은 다른 스킬이나 직접 작업으로 전환한다.

## 예시

긍정 예시:

- "Claude Code로 이 저장소를 리뷰하고 위험 요소를 요약해줘."
- "`claude` print 모드로 실행해서 이 아키텍처를 분석해줘."
- "지난 Claude Code 세션 이어서 패치를 마무리하게 해줘."
- "`auth-refactor` 라는 이름의 claude 세션을 재개해서 다음 수정을 적용해줘."
- "이 CI 단계가 로컬 훅을 끌어오지 않게 `claude --bare -p` 로 돌려줘."

부정 예시:

- "이 런북을 읽기 쉽게 다시 써줘."
- "우리 저장소용 새 스킬을 만들어줘."

경계 예시:

- "Claude Code 권한 모드를 조사해서 설명해줘."
  사용자가 `claude` CLI 실행까지 원할 때만 이 스킬을 쓰고, 그렇지 않으면 리서치나 직접 문서 작업으로 전환한다.

## 핵심: 비대화형 실행은 `-p`

비대화형 Claude Code 실행에는 항상 `-p` / `--print` 를 사용한다. `-p` 없이 위치 인수 프롬프트만 주면 대화형 REPL이 시작되어 스크립트가 TTY 를 기다리며 멈춘다.

```bash
# 비대화형 (헤드리스 / SDK)
claude --permission-mode default -p "프롬프트"

# 대화형 REPL (초기 프롬프트만 - 종료되지 않음)
claude "프롬프트"
```

`-p` 가 SDK/CI 의 표준 진입점이다. 이전에 "headless mode" 라고 부르던 것이 이 플래그이며, 동작은 동일하다.

## CI / 스크립트용 Bare 모드

스크립트나 CI 호출에는 `--bare` 를 같이 쓴다. 훅, 스킬, 플러그인, MCP 서버, auto memory, CLAUDE.md 자동 발견을 모두 건너뛰어 어느 머신에서도 같은 결과를 보장한다. Bare 모드는 OAuth 키체인도 건너뛰므로 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, 혹은 `--settings` 에 들어 있는 `apiKeyHelper` 가 필요하다.

```bash
ANTHROPIC_API_KEY=$KEY claude --bare -p "diff 요약해줘" --allowedTools "Read"
```

장기 OAuth 토큰이 필요한 파이프라인에서는 `claude setup-token` 으로 발급한 뒤 `CLAUDE_CODE_OAUTH_TOKEN` 으로 export 한다. 단, `--bare` 는 `CLAUDE_CODE_OAUTH_TOKEN` 을 읽지 않으므로 `--bare` 와 함께 쓸 때는 `ANTHROPIC_API_KEY` 또는 `apiKeyHelper` 를 사용한다.

## 작업 실행

권한 모드를 바꾸거나, 세션을 재개하거나, 도구를 제한하거나, 추가 디렉터리를 넣기 전에는 [references/recipes.ko.md](references/recipes.ko.md)를 먼저 읽는다.

### 권한 모드 선택

지원되는 모드는 6 종이다. 작업이 안전하게 허용하는 가장 느슨한 모드를 선택한다.

| 플래그 | 사용 시점 |
|--------|-----------|
| `--permission-mode default` | 일반적인 Claude Code 사용, 기본 승인 프롬프트 유지 |
| `--permission-mode plan` | 파일 변경이나 셸 실행 없는 읽기 전용 분석/계획 |
| `--permission-mode acceptEdits` | 사용자가 Claude Code 가 파일을 수정하길 명시적으로 원할 때 (`mkdir`, `mv`, `cp` 같은 일반 파일 시스템 명령도 자동 승인) |
| `--permission-mode auto` | 프롬프트 피로가 큰 장시간 자율 작업; 서버측 분류기가 위험 행위를 차단하지만 검토를 대체하지는 않는다 |
| `--permission-mode dontAsk` | 잠긴 CI: `permissions.allow` 규칙과 읽기 전용 명령만 허용, 그 외는 자동 거부 |
| `--permission-mode bypassPermissions` | 컨테이너/VM 전용. `--dangerously-skip-permissions` 와 같은 효과이며, 사용자의 명시적 승인이 필요하고 prompt injection 보호가 없다 |

Auto 모드는 Claude Code v2.1.83+ 가 필요하며 플랜·관리자 정책·모델·공급자 조합으로 게이팅된다. CLI 가 사용 불가라고 보고하면 일시적 장애가 아니므로 재시도하지 않는다.

### 명령 작성 규칙

- 시작점은 `claude --permission-mode default -p "프롬프트"` 다.
- 사용자가 명시적으로 원할 때만 `--model <model>` 또는 `--effort <level>` 을 추가한다.
- `--output-format` 은 사용자가 `text` 외 형식을 원할 때만 쓴다. 지원 값: `text`(기본), `json`, `stream-json`.
- 스키마 검증된 구조화 출력이 필요하면 `--output-format json` 과 `--json-schema '<JSON Schema>'` 를 함께 쓴다.
- 무한 루프를 피해야 하는 자율 print 모드 실행에는 `--max-turns <N>` 또는 `--max-budget-usd <달러>` 를 추가한다.
- 과부하 시 즉시 실패 대신 우아한 폴백이 낫다면 print 모드에서 `--fallback-model <name>` 을 사용한다.
- 시작 디렉터리 밖의 파일이 필요할 때만 `--add-dir <path>` 를 추가한다. (`--add-dir` 은 파일 접근 권한만 부여하며, `.claude/skills/` 를 제외한 다른 `.claude/` 설정은 자동 로드되지 않는다.)
- 도구는 `--allowedTools`, `--disallowedTools`, `--tools` 로 제한한다 (`--tools ""` 는 모든 빌트인 비활성, `--tools "default"` 는 전체, `"Bash,Edit,Read"` 같은 콤마 목록도 가능).
- 시스템 프롬프트는 `--append-system-prompt`, `--append-system-prompt-file`, `--system-prompt`, `--system-prompt-file` 로 추가하거나 교체한다.
- MCP 서버는 `--mcp-config <file-or-json>` 으로 로드하고, 다른 MCP 소스를 무시하려면 `--strict-mcp-config` 를 추가한다.
- `--dangerously-skip-permissions` 는 반드시 명시적 승인 후에만 쓰고, 일반 파일 수정은 `--permission-mode acceptEdits` 를 우선한다.

### 세션 재개

```bash
# 현재 디렉터리의 최근 세션
claude --continue -p "이전 작업 계속해줘"   # 단축: claude -c -p "..."

# ID 또는 표시 이름으로 특정 세션 재개
claude --resume "auth-refactor" -p "이 후속 요청으로 이어가줘"   # 단축: -r
claude --resume <session-id> -p "이 후속 요청으로 이어가줘"

# 스크립트가 항상 같은 세션을 쓰도록 UUID 고정
claude --session-id 550e8400-e29b-41d4-a716-446655440000 -p "..."   # 반드시 유효한 UUID

# PR 에 연결된 세션 재개
claude --from-pr 123 -p "리뷰 코멘트 반영해줘"
```

현재 디렉터리의 최근 대화는 `--continue` 를 사용한다.
특정 세션은 **ID 또는 표시 이름**(`--name` / `-n` 으로 지정하거나 세션 도중 `/rename` 으로 변경) 으로 `--resume` 한다.
`--session-id` 는 실제 UUID 만 받는다 — 다른 문자열은 거절된다.
재개할 때는 기존 세션 동작을 유지하고, 사용자가 모델, `--effort`, 권한 모드 변경을 명시적으로 요청할 때만 그 설정을 바꾼다.
기존 세션을 덮지 않고 갈라서 이어가고 싶을 때만 `--fork-session` 을 추가한다.

### 완료 후

- 결과와 함께 경고나 부분 출력이 있으면 같이 요약한다.
- 사용자가 `claude --continue` (`-c`), `claude --resume <id-or-name>` (`-r`), `claude --from-pr <pr>` 로 이어갈 수 있다고 알려준다.
- 계속할지, 프롬프트를 조정할지, 직접 작업으로 돌아갈지 묻는다.

## 비판적으로 사용하기

Claude Code를 권위자가 아니라 동료로 다룬다.

- 근거가 분명하면 자신의 판단을 유지한다.
- 이견이 생기면 최신 문서나 1차 자료로 검증한다.
- 별도 Claude Code 세션도 틀리거나 오래된 판단을 할 수 있음을 기억한다.
- 실제로 애매할 때만 사용자에게 결정을 맡긴다.

## 인증

CLI 는 다음 우선순위로 자격 증명을 읽는다: 클라우드 공급자 환경 변수(`CLAUDE_CODE_USE_BEDROCK` / `_VERTEX` / `_FOUNDRY`) → `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `apiKeyHelper` → `CLAUDE_CODE_OAUTH_TOKEN` → `/login` 의 구독 OAuth.

- 브라우저 로그인: `claude` 를 한 번 실행해 안내를 따르거나 `claude auth login` (Console 과금은 `--console`, SSO 강제는 `--sso`) 을 쓴다.
- 상태 확인 / 로그아웃: `claude auth status` 또는 세션 안의 `/status`; `claude auth logout` 또는 `/logout` 으로 자격 증명을 지운다.
- CI 용 장기 OAuth: `claude setup-token` 이 토큰을 출력하며, 이를 `CLAUDE_CODE_OAUTH_TOKEN` 으로 export 한다 (`--bare` 는 이 변수를 읽지 않음).
- 직접 API: `ANTHROPIC_API_KEY` 는 `X-Api-Key` 헤더, `ANTHROPIC_AUTH_TOKEN` 은 게이트웨이용 `Authorization: Bearer`.

## 오류 처리

- `command not found: claude`: Claude Code CLI 설치가 필요하다고 안내한다. 설치 후 `claude install stable` 로 재설치할 수 있다.
- 인증 오류: 위 우선순위를 확인하고 (구독이 활성인데도 막히면 `unset ANTHROPIC_API_KEY` 가 필요할 수 있음), `claude auth login` 또는 `claude auth status` 로 다시 점검한다.
- 권한 차단: 작업 성격에 맞는 `--permission-mode` (`plan` 은 읽기 전용, `acceptEdits` 는 파일 수정) 로 재시도하거나 `--allowedTools` / `--disallowedTools` 를 조정한다. 사용자의 명시적 승인 없이 `--dangerously-skip-permissions` 로 올리지 않는다.
- 세션을 찾지 못함: 인수 없이 `claude --resume` 으로 목록에서 선택하거나 현재 디렉터리 최근 세션이면 `claude --continue` 로 전환한다. `--session-id` 는 UUID 만 허용한다.
- Auto 모드 사용 불가: 플랜·관리자 정책·모델·공급자 조합으로 게이팅된 것이며 일시적 장애가 아니다. `default` 나 `acceptEdits` 로 폴백한다.
- 잘못된 플래그나 모델 오류: `claude --help` 로 옵션을 확인 후 재시도한다. `--help` 가 모든 플래그를 보여주지는 않으므로 전체 목록은 CLI 레퍼런스를 참고한다.

<validation_checklist>

- [ ] 요청이 `claude` CLI 또는 별도 Claude Code 세션을 명시적으로 필요로 합니다.
- [ ] 비대화형 실행은 `-p` / `--print`를 사용하고, 자동화에 위치 인수 프롬프트를 쓰지 않습니다.
- [ ] 권한 모드는 작업 성격과 맞습니다: 읽기 전용은 `plan`, 명시적 파일 편집만 `acceptEdits`, 우회는 격리 환경에서 명시적 승인 후에만 사용합니다.
- [ ] 스크립트나 CI 실행은 재현성과 로컬 훅 격리가 필요할 때 `--bare`를 사용합니다.
- [ ] 최종 출력에는 명령 형태, 관찰된 결과, 경고, 인증/세션/권한 blocker가 포함됩니다.

</validation_checklist>

---
name: claude-code
description: "[Hyper] Use when the user explicitly wants Anthropic Claude Code CLI (`claude`) for an isolated session, non-interactive (`-p`) run, session resume by ID or name, or a CI-friendly `--bare` invocation. Trigger phrases: \"use claude code\", \"ask claude\", \"run claude\", \"continue the last claude session\", \"resume the auth-refactor claude session\", or \"use Anthropic's CLI to inspect or fix this repo\"."
compatibility: Requires Claude Code CLI (`claude`) and works only in environments where that CLI is installed.
---

@rules/routing.md

# Claude Code Skill

<output_language>

Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.

Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.

Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example `*.ko.md` or `*.ko.json`), prefer it for user-facing artifacts.

</output_language>

Source of truth: <https://code.claude.com/docs/en/cli-reference>.

<instruction_contract>

| Field | Contract |
|---|---|
| Intent | Build or explain a safe `claude` CLI invocation when the user explicitly asks for Claude Code. |
| Scope | Owns command construction, resume/session flags, permission mode choice, tool restrictions, auth guidance, and result summarization for `claude`. |
| Authority | User intent and local project rules come first; the linked Claude Code CLI reference is the source of truth for CLI flags. |
| Evidence | Ground the answer in the command shape, CLI output, support-file guidance, and any warnings/errors observed. |
| Tools | Use shell execution only when the user wants the CLI run; otherwise provide the command or route away. |
| Output | Return the exact command used or recommended, summarize output/warnings, and preserve CLI tokens verbatim. |
| Verification | Check that non-interactive runs use `-p`, permission mode matches the requested authority, and dangerous bypass is gated. |
| Stop condition | Stop after the requested command is constructed or run and its result, warnings, or blocker are reported. |

</instruction_contract>

## Defaults

| Parameter | Default |
|-----------|---------|
| Model selection | Use Claude Code CLI default unless the user explicitly asks for `--model` |
| Effort | Use CLI default unless the user explicitly asks for `--effort` |
| Permission mode | `--permission-mode default` |
| Headless mode | `-p` / `--print` |
| CI / scripted run | Add `--bare` so the call ignores local hooks, plugins, MCP, and CLAUDE.md |
| Resume target | `claude --continue` (`-c`) for the latest session in the current directory; `claude --resume` (`-r`) for a session by ID or display name |

Do NOT ask the user for model or effort unless explicitly requested.

## Routing

Use this skill when the request actually needs the `claude` CLI or a separate Claude Code session.

- Read [rules/routing.md](rules/routing.md) before building a command when the request might be out of scope.
- Route away to direct editing or another skill when the user wants generic writing, documentation cleanup, or local edits without needing the `claude` CLI itself.

## Examples

Positive examples:

- "Use Claude Code to review this repository and summarize the risks."
- "Run `claude` in print mode and analyze this architecture."
- "Continue the last Claude Code session and ask it to finish the patch."
- "Resume the `auth-refactor` claude session and apply the next fix."
- "Use `claude --bare -p` so this CI step does not pick up local hooks."

Negative examples:

- "Rewrite this runbook for readability."
- "Create a new skill for our repo."

Boundary examples:

- "Research Claude Code permissions and tell me what they do."
  Use this skill only if the user wants the `claude` CLI involved; otherwise route to research or direct documentation work.

## Critical: Print Mode

Always use `-p` / `--print` for non-interactive Claude Code runs. Positional prompts without `-p` start the interactive REPL instead, so a script that omits `-p` will hang waiting for a TTY.

```bash
# Non-interactive (headless / SDK)
claude --permission-mode default -p "your prompt here"

# Interactive REPL (initial prompt only — does NOT exit)
claude "your prompt here"
```

`-p` is the canonical SDK/CI entrypoint. The CLI was previously called "headless mode"; the `-p` flag is unchanged.

## Bare Mode for CI and Scripts

Add `--bare` for any scripted or CI invocation. It skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so the call returns the same result on every machine. Bare mode also skips the OAuth keychain, so it requires `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or an `apiKeyHelper` passed through `--settings`.

```bash
ANTHROPIC_API_KEY=$KEY claude --bare -p "Summarize the diff" --allowedTools "Read"
```

For pipelines that need a long-lived OAuth token instead of an API key, generate one with `claude setup-token` and export it as `CLAUDE_CODE_OAUTH_TOKEN` (note: bare mode does NOT read `CLAUDE_CODE_OAUTH_TOKEN` — use `ANTHROPIC_API_KEY` or `apiKeyHelper` when `--bare` is set).

## Running a Task

Read [references/recipes.md](references/recipes.md) for concrete command recipes before changing permission modes, resuming a session, restricting tools, or adding extra directories.

### Permission Mode Selection

Six modes are supported. Pick the loosest mode the task safely allows.

| Flag | When to use |
|------|-------------|
| `--permission-mode default` | General Claude Code usage with normal approval prompts |
| `--permission-mode plan` | Read-only analysis or planning with no file changes or shell execution |
| `--permission-mode acceptEdits` | The user explicitly wants Claude Code to write files (also auto-approves common filesystem commands like `mkdir`, `mv`, `cp`) |
| `--permission-mode auto` | Long autonomous tasks where prompt fatigue matters; a server-side classifier blocks risky actions but does not replace review |
| `--permission-mode dontAsk` | Locked-down CI: only `permissions.allow` rules and the read-only command set may run; everything else is auto-denied |
| `--permission-mode bypassPermissions` | Containers / VMs only — equivalent to `--dangerously-skip-permissions`, requires explicit user approval, and offers no protection against prompt injection |

Auto mode requires Claude Code v2.1.83+ and is gated by plan, admin policy, model, and provider; if the CLI reports it as unavailable, do not retry.

### Command Discipline

- Start from `claude --permission-mode default -p "your prompt here"`.
- Add `--model <model>` or `--effort <level>` only when the user explicitly asks.
- Use `--output-format` only when the user wants something other than `text`. Supported values: `text` (default), `json`, `stream-json`.
- For schema-validated structured output, pair `--output-format json` with `--json-schema '<JSON Schema>'`.
- Add `--max-turns <N>` and/or `--max-budget-usd <dollars>` for autonomous print-mode runs that must not loop forever.
- Use `--fallback-model <name>` in print mode when a graceful degrade beats a hard failure on overload.
- Use `--add-dir <path>` when the task needs files outside the launch directory. (`--add-dir` grants file access; it does NOT load `.claude/` configuration from the added directory, except for `.claude/skills/`.)
- Restrict tools with `--allowedTools`, `--disallowedTools`, or `--tools` (use `--tools ""` to disable all built-ins, `--tools "default"` for all, or a comma list like `"Bash,Edit,Read"`).
- Add to / replace the system prompt with `--append-system-prompt`, `--append-system-prompt-file`, `--system-prompt`, or `--system-prompt-file`.
- Load MCP servers with `--mcp-config <file-or-json>`; add `--strict-mcp-config` to ignore every other MCP source.
- Ask before using `--dangerously-skip-permissions`. Prefer `--permission-mode acceptEdits` for normal file edits.

### Resuming a Session

```bash
# Latest session in the current directory
claude --continue -p "continue the previous task"   # short: claude -c -p "..."

# Specific session by ID or by display name
claude --resume "auth-refactor" -p "continue with this follow-up"   # short: -r
claude --resume <session-id> -p "continue with this follow-up"

# Pin a UUID so a script always reuses the same session
claude --session-id 550e8400-e29b-41d4-a716-446655440000 -p "..."   # must be a valid UUID

# Resume sessions linked to a pull request
claude --from-pr 123 -p "address review comments"
```

Use `--continue` for the latest conversation in the current directory.
Use `--resume` for a specific session by **ID or by display name** (set with `--name` / `-n`, or by `/rename` mid-session).
Use `--session-id` only with a real UUID — the CLI rejects other strings.
When resuming, keep the existing session's behavior unless the user explicitly asks to change the model, effort, or permission mode.
Add `--fork-session` only when the user wants to branch from the existing session instead of reusing it.

### After Completion

- Summarize the result, including any warnings or partial output.
- Tell the user they can resume with `claude --continue` (`-c`), `claude --resume <id-or-name>` (`-r`), or `claude --from-pr <pr>`.
- Ask whether to continue, adjust the prompt, or switch back to direct work.

## Critical Evaluation

Treat Claude Code as a colleague, not an authority.

- Trust your own grounded knowledge when you are confident.
- Verify disagreements with current docs or primary sources before accepting a claim.
- Remember that a separate Claude Code session can still be wrong or stale.
- Let the user decide when there is genuine ambiguity.

## Authentication

The CLI reads credentials in this precedence order: cloud provider env vars (`CLAUDE_CODE_USE_BEDROCK` / `_VERTEX` / `_FOUNDRY`) → `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `apiKeyHelper` → `CLAUDE_CODE_OAUTH_TOKEN` → subscription OAuth from `/login`.

- Browser login: run `claude` once and follow the prompt, or `claude auth login` (use `--console` for Console billing, `--sso` to force SSO).
- Inspect / sign out: `claude auth status` or `/status` from inside a session; `claude auth logout` or `/logout` to clear credentials.
- Long-lived OAuth for CI: `claude setup-token` prints a token; export it as `CLAUDE_CODE_OAUTH_TOKEN` (not read by `--bare`).
- Direct API: set `ANTHROPIC_API_KEY` for `X-Api-Key`, `ANTHROPIC_AUTH_TOKEN` for `Authorization: Bearer` through a gateway.

## Error Handling

- `command not found: claude`: tell the user Claude Code CLI is not installed; they can run `claude install stable` after setup.
- Auth errors: confirm precedence above (e.g. an unset `unset ANTHROPIC_API_KEY` may be needed when a subscription is active), then re-run `claude auth login` or `claude auth status` to confirm.
- Permission blocks: retry with an appropriate `--permission-mode` (`plan` for read-only, `acceptEdits` for file edits) or adjust `--allowedTools` / `--disallowedTools`. Do not escalate to `--dangerously-skip-permissions` without explicit user approval.
- Session not found: run `claude --resume` without an argument to pick from a list, or switch to `claude --continue` for the current directory; `--session-id` requires a UUID.
- Auto-mode unavailable: this is gated by plan, admin policy, model, and provider — it is not a transient outage; fall back to `default` or `acceptEdits`.
- Invalid flag or model errors: check `claude --help`, then re-run with supported options. `claude --help` does not list every flag — consult the CLI reference for the full list.

<validation_checklist>

- [ ] The request explicitly needs the `claude` CLI or a separate Claude Code session.
- [ ] Non-interactive runs use `-p` / `--print`; positional prompts are not used for automation.
- [ ] Permission mode matches the task: `plan` for read-only, `acceptEdits` only for explicit file edits, and bypass only after explicit approval in an isolated environment.
- [ ] Scripted or CI runs use `--bare` when reproducibility and local-hook isolation are required.
- [ ] Final output includes the command shape, observed result, warnings, and any auth/session/permission blocker.

</validation_checklist>