claude-code

@rules/routing.md

Claude Code 技能

<output_language>

默认将所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明设为韩语，即使此规范技能文件以英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、软件包名称、专有名称和引用的源文本片段，并使用其规定语言或原始语言。

只有在用户明确要求使用其他语言、现有目标产物必须保持其他语言以确保一致性，或机器可读的契约要求使用精确的英文标记时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），则优先将其用于面向用户的产物。

</output_language>

事实来源：https://code.claude.com/docs/en/cli-reference。

<instruction_contract>

字段	契约
意图	当用户明确要求使用 Claude Code 时，构建或说明安全的 claude CLI 调用。
范围	负责 claude 的命令构建、恢复/会话标记、权限模式选择、工具限制、身份验证指导和结果摘要。
权威依据	优先遵循用户意图和本地项目规则；所链接的 Claude Code CLI 参考文档是 CLI 标记的事实来源。
依据	根据命令形式、CLI 输出、支持文件指导以及观察到的警告/错误来组织回答。
工具	只有在用户要求运行 CLI 时才执行 shell；否则提供命令或转交处理。
输出	返回实际使用或建议使用的精确命令，总结输出/警告，并原样保留 CLI 标记。
验证	检查非交互式运行是否使用 -p、权限模式是否符合所要求的权限，以及危险的绕过操作是否受到限制。
停止条件	构建或运行所请求的命令，并报告结果、警告或阻碍后即停止。

</instruction_contract>

默认设置

参数	默认值
模型选择	使用 Claude Code CLI 默认模型，除非用户明确要求使用 --model
努力程度	使用 CLI 默认值，除非用户明确要求使用 --effort
权限模式	--permission-mode default
无头模式	-p / --print
CI / 脚本运行	添加 --bare，使调用忽略本地钩子、插件、MCP 和 CLAUDE.md
恢复目标	使用 claude --continue (-c) 恢复当前目录中的最新会话；使用 claude --resume (-r) 按 ID 或显示名称恢复会话

除非用户明确要求，否则不要询问用户选择模型或努力程度。

路由

仅在请求确实需要使用 claude CLI 或单独的 Claude Code 会话时使用此技能。

• 如果请求可能超出范围，在构建命令前阅读 rules/routing.md。
• 如果用户需要的是通用写作、文档整理或无需 claude CLI 本身的本地编辑，则转交直接编辑或其他技能处理。

示例

正面示例：

• “使用 Claude Code 审查此代码库并总结风险。”
• “以打印模式运行 claude 并分析此架构。”
• “继续上一个 Claude Code 会话，并让它完成补丁。”
• “恢复 auth-refactor claude 会话并应用下一项修复。”
• “使用 claude --bare -p，确保此 CI 步骤不会加载本地钩子。”

反面示例：

• “为提高可读性，重写此运行手册。”
• “为我们的代码库创建一个新技能。”

边界示例：

• “研究 Claude Code 的权限，并告诉我它们的作用。” 只有在用户希望调用 claude CLI 时才使用此技能；否则转交研究或直接文档处理。

重要：打印模式

非交互式 Claude Code 运行时，务必使用 -p / --print。不带 -p 的位置参数提示词会启动交互式 REPL，因此，省略 -p 的脚本会挂起并等待 TTY。

# 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 是标准的 SDK/CI 入口。CLI 之前称为“无头模式”；-p 标志没有变化。

CI 和脚本的裸模式

对于任何脚本或 CI 调用，都添加 --bare。它会跳过钩子、技能、插件、MCP 服务、自动记忆和 CLAUDE.md 的自动发现，从而确保每台机器上的调用都返回相同结果。裸模式还会跳过 OAuth 密钥链，因此需要 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN，或通过 --settings 传入的 apiKeyHelper。

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

对于需要长期有效的 OAuth 令牌而非 API 密钥的管道，请使用 claude setup-token 生成令牌，并将其导出为 CLAUDE_CODE_OAUTH_TOKEN（注意：裸模式不会读取 CLAUDE_CODE_OAUTH_TOKEN — 设置 --bare 时，请使用 ANTHROPIC_API_KEY 或 apiKeyHelper）。

运行任务

在更改权限模式、恢复会话、限制工具或添加额外目录之前，请阅读 references/recipes.md 了解具体的命令示例。

权限模式选择

支持六种模式。选择任务安全允许的最宽松模式。

标志	适用场景
--permission-mode default	常规 Claude Code 使用场景，带有常规审批提示
--permission-mode plan	只读分析或规划，不更改文件，也不执行 shell 命令
--permission-mode acceptEdits	用户明确要求 Claude Code 写入文件（也会自动批准常见的文件系统命令，例如 mkdir、mv、cp）
--permission-mode auto	长时间自主执行的任务，适用于需要减少提示疲劳的场景；服务端分类器会阻止高风险操作，但不能取代审查
--permission-mode dontAsk	锁定的 CI：仅可运行 permissions.allow 规则允许的操作和只读命令集；其他操作都会自动拒绝
--permission-mode bypassPermissions	仅限容器 / VM — 等同于 --dangerously-skip-permissions，需要用户明确批准，且无法防范提示注入

自动模式需要 Claude Code v2.1.83+，并受计划、管理员策略、模型和提供方限制；如果 CLI 报告该模式不可用，请勿重试。

命令规范

• 从 claude --permission-mode default -p "your prompt here" 开始。
• 仅在用户明确要求时，才添加 --model <model> 或 --effort <level>。
• 仅在用户需要 text 以外的内容时，才使用 --output-format。支持的值：text（默认）、json、stream-json。
• 对于经过架构验证的结构化输出，将 --output-format json 与 --json-schema '<JSON Schema>' 搭配使用。
• 对于不得无限循环的自主打印模式运行，添加 --max-turns <N> 和／或 --max-budget-usd <dollars>。
• 在打印模式下，如果优雅降级优于因过载而硬性失败，请使用 --fallback-model <name>。
• 如果任务需要访问启动目录以外的文件，请使用 --add-dir <path>。（--add-dir 会授予文件访问权限；它不会加载所添加目录中的 .claude/ 配置，但 .claude/skills/ 除外。）
• 使用 --allowedTools、--disallowedTools 或 --tools 限制工具（使用 --tools "" 禁用所有内置工具，使用 --tools "default" 启用全部工具，或使用逗号分隔的列表，例如 "Bash,Edit,Read"）。
• 使用 --append-system-prompt、--append-system-prompt-file、--system-prompt 或 --system-prompt-file，向系统提示词追加内容或替换系统提示词。
• 使用 --mcp-config <file-or-json> 加载 MCP 服务；添加 --strict-mcp-config 可忽略所有其他 MCP 来源。
• 使用 --dangerously-skip-permissions 前请先征求同意。常规文件编辑优先使用 --permission-mode acceptEdits。

恢复会话

# 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"

使用 --continue 继续当前目录中的最新对话。 使用 --resume 恢复指定会话，可按 ID 或显示名称 指定（通过 --name / -n 设置，或在会话中途通过 /rename 设置）。 仅将 --session-id 用于真实 UUID——CLI 会拒绝其他字符串。 恢复会话时，除非用户明确要求更改模型、effort 或权限模式，否则保持现有会话的行为不变。 只有当用户希望从现有会话分支，而不是复用它时，才添加 --fork-session。

完成后

• 总结结果，包括任何警告或部分输出。
• 告知用户可以通过 claude --continue（-c）、claude --resume <id-or-name>（-r）或 claude --from-pr <pr> 恢复会话。
• 询问用户是要继续、调整提示词，还是切回直接工作。

关键评估

将 Claude Code 视为同事，而非权威。

• 有把握时，相信自己基于事实的知识。
• 如有分歧，在接受某项说法前，先查阅最新文档或一手资料进行核实。
• 请记住，另一个 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（--bare 不会读取此令牌）。
• 直接调用 API：设置 ANTHROPIC_API_KEY，用于 X-Api-Key；设置 ANTHROPIC_AUTH_TOKEN，用于通过网关传递的 Authorization: Bearer。

错误处理

• command not found: claude：告知用户尚未安装 Claude Code CLI；完成设置后可运行 claude install stable。
• 身份验证错误：先确认上述优先顺序（例如，订阅处于激活状态时可能需要取消设置 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。
• 自动模式不可用：该模式受计划、管理员策略、模型和提供商限制；这不是暂时性故障，应改用 default 或 acceptEdits。
• 标志或模型无效：检查 claude --help，然后使用受支持的选项重新运行。claude --help 不会列出所有标志——完整列表请参阅 CLI 参考文档。

<validation_checklist>

• 请求明确需要 claude CLI 或单独的 Claude Code 会话。
• 非交互式运行使用 -p / --print；自动化时不使用位置参数形式的提示词。
• 权限模式与任务匹配：只读使用 plan，仅在明确要求编辑文件时使用 acceptEdits；只有在隔离环境中获得明确批准后，才绕过权限限制。
• 脚本或 CI 运行在需要确保可复现性并隔离本地钩子时使用 --bare。
• 最终输出包括命令格式、观察到的结果、警告，以及任何身份验证、会话或权限方面的阻碍。

</validation_checklist>