claude-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code

Summary

摘要

Goal: Help users install, configure, troubleshoot, and extend Claude Code CLI (skills, hooks, MCP, slash commands).

Step	Action	Key Notes
1	Identify problem category	Setup, Hook Issues, MCP Issues, Context, Extensibility, Configuration
2	Execute category-specific diagnosis	Check prerequisites, configs, scripts, settings
3	Apply fix	Step-by-step solution with verification
4	Output report	Problem, Solution, Files Changed, Verification

Key Principles:

Load reference files on-demand per topic (10 reference docs available)
Never modify settings without user approval
For app code use
```
feature
```
/
```
debug
```
skills, not this one

目标： 帮助用户安装、配置、排查故障并扩展Claude Code CLI（skills、hooks、MCP、斜杠命令）。

步骤	操作	关键说明
1	识别问题类别	安装、Hook问题、MCP问题、上下文、可扩展性、配置
2	执行对应类别的诊断	检查前置依赖、配置项、脚本、设置
3	应用修复方案	附带验证环节的分步解决方案
4	输出报告	问题、解决方案、变更文件、验证结果

核心原则：

按需加载对应主题的参考文件（共10份参考文档可用）
未经用户许可绝不修改任何设置
应用代码相关问题请使用
```
feature
```
/
```
debug
```
skill，不要使用本指南

Purpose

用途

Help users install, configure, troubleshoot, and extend Claude Code CLI -- Anthropic's agentic coding tool with skills, hooks, MCP servers, and slash commands.

帮助用户安装、配置、排查故障并扩展Claude Code CLI——Anthropic出品的具备skills、hooks、MCP服务器和斜杠命令能力的智能Agent编程工具。

When to Use

适用场景

Setting up Claude Code for the first time
Troubleshooting hooks that don't fire or produce errors
Diagnosing MCP server connection failures
Understanding or resolving context window limits
Creating or modifying slash commands and agent skills
Configuring settings (model, allowed tools, output style)

首次设置Claude Code
排查Hook不触发或报错问题
诊断MCP服务器连接失败问题
理解或解决上下文窗口限制问题
创建或修改斜杠命令和Agent skill
配置设置（模型、允许使用的工具、输出样式）

When NOT to Use

不适用场景

Writing application code -- use
```
feature
```
,
```
debug
```
, or
```
refactoring
```
skills
Creating MCP servers from scratch -- use
```
mcp-builder
```
skill
Managing existing MCP connections -- use
```
mcp-management
```
skill

编写应用代码——请使用
```
feature
```
、
```
debug
```
或
```
refactoring
```
skill
从零创建MCP服务器——请使用
```
mcp-builder
```
skill
管理现有MCP连接——请使用
```
mcp-management
```
skill

Workflow

工作流程

Step 1: Identify Problem Category

步骤1：识别问题类别

User Says	Category	Go To
"install", "set up", "authenticate"	Setup	Step 2A
"hook not firing", "hook error"	Hook Issues	Step 2B
"MCP not connecting", "MCP error"	MCP Issues	Step 2C
"context too long", "compaction", "token limit"	Context Issues	Step 2D
"create skill", "create command"	Extensibility	Step 2E
"configure", "settings", "model"	Configuration	Step 2F

用户话术	类别	跳转至
"install", "set up", "authenticate"	安装	步骤2A
"hook not firing", "hook error"	Hook问题	步骤2B
"MCP not connecting", "MCP error"	MCP问题	步骤2C
"context too long", "compaction", "token limit"	上下文问题	步骤2D
"create skill", "create command"	可扩展性	步骤2E
"configure", "settings", "model"	配置	步骤2F

Step 2A: Setup

步骤2A：安装

Check prerequisites: Node.js 18+, npm
Verify authentication:
```
claude auth status
```
Verify project detection: check for
```
CLAUDE.md
```
in project root

检查前置依赖：Node.js 18+、npm
验证身份认证状态：
```
claude auth status
```
验证项目识别：检查项目根目录是否存在
```
CLAUDE.md
```

Step 2B: Hook Issues

步骤2B：Hook问题

Read the hook file causing issues
Check hook event type matches expected trigger
Verify hook script is executable with correct shebang
Check
```
.claude/settings.json
```
for hook registration
Test hook in isolation with mock input

Common fixes:

Hook not firing: wrong event name or tool matcher pattern
Hook errors: script not finding dependencies (check relative paths)
Hook blocks unexpectedly: PreToolUse returning
```
{ "decision": "block" }
```
incorrectly

读取出现问题的Hook文件
检查Hook事件类型是否与预期触发条件匹配
验证Hook脚本具备可执行权限且shebang正确
检查
```
.claude/settings.json
```
中是否完成Hook注册
使用模拟输入单独测试Hook运行状态

常见修复方案：

Hook不触发：事件名称错误或工具匹配模式不正确
Hook报错：脚本找不到依赖（检查相对路径）
Hook意外阻塞：PreToolUse错误返回
```
{ "decision": "block" }
```

Step 2C: MCP Issues

步骤2C：MCP问题

Check
```
.mcp.json
```
for server configuration
Verify the MCP server process can start manually
Check environment variables (API keys in
```
.env.local
```
)
Test connectivity:
```
claude mcp list
```

检查
```
.mcp.json
```
中的服务器配置
验证MCP服务器进程可手动启动
检查环境变量（
```
.env.local
```
中的API密钥）
测试连通性：
```
claude mcp list
```

Step 2D: Context Issues

步骤2D：上下文问题

Check current context usage
Suggest
```
/compact
```
command if approaching limit
Review if large files are being read unnecessarily
Verify
```
session-resume.cjs
```
hook for session continuity

检查当前上下文使用量
接近限制时建议使用
```
/compact
```
命令
排查是否存在不必要的大文件读取
验证
```
session-resume.cjs
```
Hook的会话连续性配置

Step 2E: Extensibility

步骤2E：可扩展性

For skills: read
```
references/agent-skills.md
```
for structure
For commands: create
```
.claude/skills/{name}.md
```
Verify SKILL.md frontmatter has required fields (name, version, description)

技能开发：参考
```
references/agent-skills.md
```
了解结构规范
命令创建：生成
```
.claude/skills/{name}.md
```
文件
验证SKILL.md头部元数据包含必填字段（名称、版本、描述）

Step 2F: Configuration

步骤2F：配置

Settings locations:

.claude/settings.json

(project),

~/.claude/settings.json

(user)

IMPORTANT: Never modify settings without user approval

配置文件位置：
```
.claude/settings.json
```
（项目级）、
```
~/.claude/settings.json
```
（用户级）
重要提示：未经用户许可绝不修改任何配置

Output Format

输出格式

markdown

undefined

markdown

undefined

Claude Code: [Issue/Task Summary]

Problem

[What was wrong or what was requested]

Solution

[Step-by-step fix or setup instructions]

Files Changed

[List any config files modified]

Verification

[How to confirm the fix works]

undefined

[How to confirm the fix works]

undefined

Reference Guide

参考指南

Load references as needed for specific topics:

Topic	Reference File
Installation & setup	`references/getting-started.md`
Creating skills	`references/agent-skills.md`
Hooks system	`references/hooks-comprehensive.md`
Configuration	`references/configuration.md`
Troubleshooting	`references/troubleshooting.md`
IDE integration	`references/ide-integration.md`
CI/CD	`references/cicd-integration.md`
Advanced features	`references/advanced-features.md`
API reference	`references/api-reference.md`
Best practices	`references/best-practices.md`

按需加载对应主题的参考文件：

主题	参考文件
安装与设置	`references/getting-started.md`
技能创建	`references/agent-skills.md`
Hooks系统	`references/hooks-comprehensive.md`
配置说明	`references/configuration.md`
故障排查	`references/troubleshooting.md`
IDE集成	`references/ide-integration.md`
CI/CD	`references/cicd-integration.md`
高级功能	`references/advanced-features.md`
API参考	`references/api-reference.md`
最佳实践	`references/best-practices.md`

claude-code

Original

Translation

Claude Code

Claude Code

Summary

摘要

Purpose

用途

When to Use

适用场景

When NOT to Use

不适用场景

Workflow

工作流程

Step 1: Identify Problem Category

步骤1：识别问题类别

Step 2A: Setup

步骤2A：安装

Step 2B: Hook Issues

步骤2B：Hook问题

Step 2C: MCP Issues

步骤2C：MCP问题

Step 2D: Context Issues

步骤2D：上下文问题

Step 2E: Extensibility

步骤2E：可扩展性

Step 2F: Configuration

步骤2F：配置

Output Format

输出格式

Claude Code: [Issue/Task Summary]

Claude Code: [Issue/Task Summary]

Problem

Problem

Solution

Solution

Files Changed

Files Changed

Verification

Verification

Reference Guide

参考指南

Related Skills

相关Skill