claude-skill

Claude Code 无头模式

你正在使用 Claude Code 无头模式——一种无需交互的自动化模式，可自动执行任务。

前提条件

使用此技能前，请确保已安装并配置 Claude Code CLI：

1. 验证安装：

   claude --version
   

2. 首次设置：如果尚未安装，请指导用户使用命令 npm install -g @anthropic-ai/claude-code 安装 Claude Code CLI。

核心原则

自主执行

• 从头到尾执行任务，无需为每项操作征求批准
• 根据最佳实践和任务要求果断做出决定
• 仅在确实缺少关键信息时提问
• 优先完成工作流，而不是逐步解释每个操作

输出行为

• 在执行过程中持续输出进度更新
• 完成后提供清晰、结构化的最终摘要
• 重点呈现可执行结果和指标，而非冗长解释
• 报告已完成的工作，而非本可完成的工作

权限模式

Claude Code 使用权限模式来控制允许执行的操作。通过 --permission-mode 标志设置：

模式	描述
default	标准行为——首次使用每个工具时会提示请求权限
acceptEdits	自动接受本次会话中的文件编辑权限 （此技能的默认模式）
plan	计划模式——Claude 可以分析，但不能修改文件或执行命令
bypassPermissions	跳过所有权限提示（需要安全环境——见下方警告）

接受编辑模式（--permission-mode acceptEdits）——默认模式

• 自动接受文件编辑，无需提示
• 执行 shell 命令仍需批准
• 推荐用于大多数编程任务
• 这是此技能的默认模式

默认模式（--permission-mode default）

• 文件编辑和命令执行均需批准
• 适用于探索和分析任务，安全性较高

计划模式（--permission-mode plan）

• 只读分析模式
• Claude 可以探索和分析，但不能修改文件
• 不能执行命令
• 适用于代码审查和架构分析

跳过权限模式（--permission-mode bypassPermissions）

• 跳过所有权限提示
• ⚠️ 警告：仅在外部沙箱环境中使用（容器、虚拟机）
• 在未进行适当隔离的开发计算机上切勿使用
• 配合 --allowedTools 使用，以限制特定工具，确保安全

Claude Code CLI 命令

注意：以下命令基于 Claude Code 无头模式的官方文档。

基本无头执行

使用 --print（或 -p）标志以非交互模式运行：

claude -p "analyze the codebase structure and explain the architecture"

工具权限

使用 --allowedTools 和 --disallowedTools 控制 Claude 可以使用哪些工具：

# Allow specific tools
claude -p "stage my changes and write commits" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

# Allow multiple tools (space-separated)
claude -p "implement the feature" \
  --permission-mode acceptEdits \
  --allowedTools Bash Read Write Edit

# Allow tools with restrictions (comma-separated string)
claude -p "run tests" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test),Read"

# Disallow specific tools
claude -p "analyze the code" \
  --disallowedTools "Bash,Write"

使用权限模式

控制权限的处理方式：

# Accept file edits automatically (recommended for programming)
claude -p "implement the user authentication feature" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

# Combine with allowed tools for safe automation
claude -p "fix the bug in login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

输出格式

文本输出（默认）

claude -p "explain file src/components/Header.tsx"
# Output: Plain text response

JSON 输出

返回包含元数据的结构化数据：

claude -p "how does the data layer work?" --output-format json

响应格式：

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

流式 JSON 输出

接收消息时逐条输出：

claude -p "build an application" \
  --permission-mode acceptEdits \
  --output-format stream-json

每段对话都以初始的 init 系统消息开始，接着是用户和助手消息，最后以包含统计信息的 result 系统消息结束。

多轮对话

对于多轮对话，你可以恢复或继续会话：

# Continue the most recent conversation
claude --continue --permission-mode acceptEdits "now refactor this for better performance"

# Resume a specific conversation by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000 \
  --permission-mode acceptEdits "update the tests"

# Resume in non-interactive mode
claude --resume 550e8400-e29b-41d4-a716-446655440000 -p \
  --permission-mode acceptEdits "fix all linting issues"

# Short flags
claude -c --permission-mode acceptEdits "continue with next step"
claude -r abc123 -p --permission-mode acceptEdits "implement the next feature"

自定义系统提示词

向系统提示词追加自定义指令：

claude -p "review this code" \
  --append-system-prompt "Focus on security vulnerabilities and performance issues"

MCP 服务配置

从 JSON 配置文件加载 MCP 服务：

claude -p "analyze the metrics" \
  --mcp-config monitoring-tools.json \
  --allowedTools "mcp__datadog,mcp__prometheus"

详细日志记录

启用详细输出以进行调试：

claude -p "debug this issue" --verbose

组合示例

组合多个标志以应对复杂场景：

# Full automation with JSON output
claude -p "implement authentication and output results" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit" \
  --output-format json

# Multi-turn with custom instructions
session_id=$(claude -p "start code review" --output-format json | jq -r '.session_id')
claude -r "$session_id" -p "now check for security issues" \
  --permission-mode acceptEdits \
  --append-system-prompt "Be thorough with OWASP top 10"

# Streaming with MCP tools
claude -p "deploy the application" \
  --permission-mode acceptEdits \
  --output-format stream-json \
  --mcp-config deploy-tools.json \
  --allowedTools "mcp__kubernetes,mcp__docker"

执行工作流

1. 解析请求：理解完整目标和范围
2. 高效规划：制定精简、聚焦的执行计划
3. 自主执行：有把握地实施解决方案
4. 验证结果：酌情运行测试、检查或验证
5. 清晰报告：以结构化摘要汇报完成情况

最佳实践

速度与效率

• 如果次要细节存在歧义，请做出合理假设
• 尽可能并行操作（读取多个文件、运行多个命令）
• 执行过程中避免冗长解释，专注于行动
• 对于常规操作，无需征求确认

范围管理

• 严格聚焦于请求的任务
• 不要添加未请求的功能或改进
• 避免重构与任务无关的代码
• 保持解决方案精简、直接

质量标准

• 遵循现有代码模式和约定
• 修改后运行相关测试
• 验证解决方案确实有效
• 报告遇到的错误或限制

错误处理

• 检查退出代码和 stderr 中的错误

• 对长时间运行的操作设置超时：

  timeout 300 claude -p "$complex_prompt" --permission-mode acceptEdits || echo "Timed out after 5 minutes"
  

• 多次请求时通过在调用之间添加延迟来遵守速率限制

何时中断执行

只有遇到以下情况时才暂停并征求用户意见：

• 破坏性操作：删除数据库、强制推送到 main、删除表
• 安全决策：暴露凭据、更改身份验证、开放端口
• 需求不明确：存在多种有效方案，且各有显著权衡
• 缺少关键信息：没有用户专属数据便无法继续

对于其他所有决策，请运用最佳判断自主继续。

最终输出格式

始终以结构化摘要结束：

✓ Task completed successfully

Changes made:
- [List of files modified/created]
- [Key code changes]

Results:
- [Metrics: lines changed, files affected, tests run]
- [What now works that didn't before]

Verification:
- [Tests run, checks performed]

Next steps (if applicable):
- [Suggestions for follow-up tasks]

使用场景示例

代码分析（只读）

用户：“按语言统计此项目的代码行数” 命令：

claude -p "count the total number of lines of code in this project, broken down by language" \
  --allowedTools "Read,Bash(find),Bash(wc)"

操作：搜索所有文件，按扩展名分类，统计行数并汇报总数

修复 Bug

用户：“修复登录流程中的身份验证 Bug” 命令：

claude -p "fix the authentication bug in the login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

操作：查找 Bug、实施修复并运行测试

功能实现

用户：“为 UI 实现深色模式支持” 命令：

claude -p "add dark mode support to the UI with theme context and style updates" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

操作：识别组件、添加主题上下文、更新样式，并在两种模式下进行测试

批量操作

用户：“将所有导入从 old-lib 更新为 new-lib” 命令：

claude -p "update all imports from old-lib to new-lib across the entire codebase" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

操作：查找所有导入、执行替换、验证语法并运行测试

生成 JSON 格式的报告

用户：“分析安全漏洞并以 JSON 输出” 命令：

claude -p "analyze the codebase for security vulnerabilities and provide a detailed report" \
  --allowedTools "Read,Grep" \
  --output-format json

操作：扫描代码、识别问题，并以结构化 JSON 输出发现结果

SRE 事件响应

用户：“调查支付 API 错误” 命令：

claude -p "Incident: Payment API returning 500 errors (Severity: high)" \
  --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
  --output-format json \
  --allowedTools "Bash,Read,mcp__datadog" \
  --mcp-config monitoring-tools.json

操作：分析日志、找出根本原因并提供行动项

PR 自动安全审查

用户：“审查当前 PR 中的安全问题” 命令：

gh pr diff | claude -p \
  --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
  --output-format json \
  --allowedTools "Read,Grep"

操作：分析差异、识别安全问题并输出结构化报告

多轮法律文档审查

用户：“审查合同的多个方面” 命令：

# Start session and capture ID
session_id=$(claude -p "start legal review session" --output-format json | jq -r '.session_id')

# Review in multiple steps
claude -r "$session_id" -p "review contract.pdf for liability clauses" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "check compliance with GDPR requirements" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "generate executive summary of risks" \
  --permission-mode acceptEdits

操作：在保留上下文的情况下进行多轮分析

错误处理

发生错误时：

1. 尽可能尝试自动恢复
2. 在输出中清楚记录错误
3. 如果错误不会阻止后续任务，则继续执行
4. 在最终摘要中报告所有错误
5. 只有错误导致无法继续时才停止

可恢复执行

如果执行中断：

• 清楚说明已完成的内容
• 提供用于恢复的会话 ID：claude --resume <session_id> -p "continue" --permission-mode acceptEdits
• 列出需要保留的状态
• 说明剩余待办事项