claude-code-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code 高级开发指南

Claude Code Advanced Development Guide

全面的 Claude Code 中文学习指南，涵盖从基础到高级的所有核心概念、工具使用、开发工作流和最佳实践。

A comprehensive learning guide for Claude Code, covering all core concepts from basics to advanced levels, tool usage, development workflows, and best practices.

何时使用此技能

When to Use This Skill

当需要以下帮助时使用此技能：

学习 Claude Code 的核心功能和工具
掌握 REPL 环境的高级用法
理解开发工作流和任务管理
使用 MCP 集成外部系统
实现高级开发模式
应用 Claude Code 最佳实践
解决常见问题和错误
进行大文件分析和处理

Use this skill when you need help with:

Learning Claude Code's core features and tools
Mastering advanced usage of the REPL environment
Understanding development workflows and task management
Integrating external systems using MCP
Implementing advanced development patterns
Applying Claude Code best practices
Resolving common issues and errors
Performing large file analysis and processing

快速参考

Quick Reference

Claude Code 核心工具（7个）

Claude Code Core Tools (7)

REPL - JavaScript 运行时环境
- 完整的 ES6+ 支持
- 预加载库：D3.js, MathJS, Lodash, Papaparse, SheetJS
- 支持 async/await, BigInt, WebAssembly
- 文件读取：
```
window.fs.readFile()
```
Artifacts - 可视化输出
- React, Three.js, 图表库
- HTML/SVG 渲染
- 交互式组件
Web Search - 网络搜索
- 仅美国可用
- 域名过滤支持
Web Fetch - 获取网页内容
- HTML 转 Markdown
- 内容提取和分析
Conversation Search - 对话搜索
- 搜索历史对话
- 上下文检索
Recent Chats - 最近对话
- 访问最近会话
- 对话历史
End Conversation - 结束对话
- 清理和总结
- 会话管理

REPL - JavaScript runtime environment
- Full ES6+ support
- Preloaded libraries: D3.js, MathJS, Lodash, Papaparse, SheetJS
- Supports async/await, BigInt, WebAssembly
- File reading:
```
window.fs.readFile()
```
Artifacts - Visual output
- React, Three.js, chart libraries
- HTML/SVG rendering
- Interactive components
Web Search - Web search
- US-only availability
- Domain filtering support
Web Fetch - Retrieve web content
- HTML to Markdown conversion
- Content extraction and analysis
Conversation Search - Conversation search
- Search historical conversations
- Context retrieval
Recent Chats - Recent conversations
- Access recent sessions
- Conversation history
End Conversation - End conversation
- Cleanup and summary
- Session management

大文件分析工作流

Large File Analysis Workflow

bash

undefined

bash

undefined

阶段 1：定量评估

Phase 1: Quantitative Assessment

wc -l filename.md # 行数统计 wc -w filename.md # 词数统计 wc -c filename.md # 字符数统计

wc -l filename.md # Line count wc -w filename.md # Word count wc -c filename.md # Character count

阶段 2：结构分析

Phase 2: Structural Analysis

grep "^#{1,6} " filename.md # 提取标题层次 grep "```" filename.md # 识别代码块 grep -c "keyword" filename.md # 关键词频率

grep "^#{1,6} " filename.md # Extract heading hierarchy grep "```" filename.md # Identify code blocks grep -c "keyword" filename.md # Keyword frequency

阶段 3：内容提取

Phase 3: Content Extraction

Read filename.md offset=0 limit=50 # 文件开头 Read filename.md offset=N limit=100 # 目标部分 Read filename.md offset=-50 limit=50 # 文件结尾

undefined

Read filename.md offset=0 limit=50 # File start Read filename.md offset=N limit=100 # Target section Read filename.md offset=-50 limit=50 # File end

undefined

REPL 高级用法

Advanced REPL Usage

javascript

// 数据处理
const data = [1, 2, 3, 4, 5];
const sum = data.reduce((a, b) => a + b, 0);

// 使用预加载库
// Lodash
_.chunk([1, 2, 3, 4], 2);  // [[1,2], [3,4]]

// MathJS
math.sqrt(16);  // 4

// D3.js
d3.range(10);  // [0,1,2,3,4,5,6,7,8,9]

// 读取文件
const content = await window.fs.readFile('path/to/file');

// 异步操作
const result = await fetch('https://api.example.com/data');
const json = await result.json();

javascript

// Data processing
const data = [1, 2, 3, 4, 5];
const sum = data.reduce((a, b) => a + b, 0);

// Use preloaded libraries
// Lodash
_.chunk([1, 2, 3, 4], 2);  // [[1,2], [3,4]]

// MathJS
math.sqrt(16);  // 4

// D3.js
d3.range(10);  // [0,1,2,3,4,5,6,7,8,9]

// Read file
const content = await window.fs.readFile('path/to/file');

// Async operation
const result = await fetch('https://api.example.com/data');
const json = await result.json();

斜杠命令系统

Slash Command System

内置命令：

```
/help
```
- 显示帮助
```
/clear
```
- 清除对话
```
/plugin
```
- 管理插件
```
/settings
```
- 配置设置

自定义命令： 创建

.claude/commands/mycommand.md

：

markdown

根据需求执行特定任务的指令

使用：

/mycommand

Built-in Commands:

```
/help
```
- Show help
```
/clear
```
- Clear conversation
```
/plugin
```
- Manage plugins
```
/settings
```
- Configure settings

Custom Commands: Create

.claude/commands/mycommand.md

markdown

Instructions to perform specific tasks based on requirements

Usage:

/mycommand

开发工作流模式

Development Workflow Patterns

1. 文件分析工作流

1. File Analysis Workflow

bash

undefined

bash

undefined

探索 → 理解 → 实现

Explore → Understand → Implement

ls -la # 列出文件 Read file.py # 读取内容 grep "function" file.py # 搜索模式

ls -la # List files Read file.py # Read content grep "function" file.py # Search patterns

然后实现修改

Then implement modifications

undefined

undefined

2. 算法验证工作流

2. Algorithm Validation Workflow

bash

undefined

bash

undefined

设计 → 验证 → 实现

Design → Validate → Implement

1. 在 REPL 中测试逻辑

1. Test logic in REPL

2. 验证边界情况

2. Verify edge cases

3. 实现到代码

3. Implement into code

undefined

undefined

3. 数据探索工作流

3. Data Exploration Workflow

bash

undefined

bash

undefined

检查 → 分析 → 可视化

Inspect → Analyze → Visualize

1. 读取数据文件

1. Read data file

2. REPL 中分析

2. Analyze in REPL

3. Artifacts 可视化

3. Visualize with Artifacts

undefined

undefined

核心概念

Core Concepts

工具权限系统

Tool Permission System

自动授予权限的工具：

REPL
Artifacts
Web Search/Fetch
Conversation Search

需要授权的工具：

Bash (读/写文件系统)
Edit (修改文件)
Write (创建文件)

Tools with Auto-Granted Permissions:

REPL
Artifacts
Web Search/Fetch
Conversation Search

Tools Requiring Authorization:

Bash (read/write file system)
Edit (modify files)
Write (create files)

项目上下文

Project Context

Claude 自动识别：

Git 仓库状态
编程语言（从文件扩展名）
项目结构
依赖配置

Claude automatically identifies:

Git repository status
Programming languages (from file extensions)
Project structure
Dependency configurations

内存系统

Memory System

对话内存：

存储在当前会话
200K token 窗口
自动上下文管理

持久内存（实验性）：

跨会话保存
用户偏好记忆
项目上下文保留

Conversation Memory:

Stored in current session
200K token window
Automatic context management

Persistent Memory (Experimental):

Saved across sessions
User preference memory
Project context retention

MCP 集成

MCP Integration

什么是 MCP？

What is MCP?

Model Context Protocol - 连接 Claude 到外部系统的协议。

Model Context Protocol - A protocol for connecting Claude to external systems.

MCP 服务器配置

MCP Server Configuration

配置文件：

~/.config/claude/mcp_config.json

json

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Configuration file:

~/.config/claude/mcp_config.json

json

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

使用 MCP 工具

Using MCP Tools

Claude 会自动发现 MCP 工具并在对话中使用：

"使用 my-server 工具获取数据"

Claude automatically discovers MCP tools and uses them in conversations:

"Use the my-server tool to retrieve data"

钩子系统

Hook System

钩子类型

Hook Types

在

.claude/settings.json

配置：

json

{
  "hooks": {
    "tool-pre-use": "echo 'About to use tool'",
    "tool-post-use": "echo 'Tool used'",
    "user-prompt-submit": "echo 'Processing prompt'"
  }
}

Configure in

.claude/settings.json

json

{
  "hooks": {
    "tool-pre-use": "echo 'About to use tool'",
    "tool-post-use": "echo 'Tool used'",
    "user-prompt-submit": "echo 'Processing prompt'"
  }
}

常见钩子用途

Common Hook Use Cases

自动格式化代码
运行测试
Git 提交检查
日志记录
通知发送

Automatic code formatting
Run tests
Git commit checks
Logging
Notification sending

高级模式

Advanced Patterns

多代理协作

Multi-Agent Collaboration

使用 Task 工具启动子代理：

"启动一个专门的代理来优化这个算法"

子代理特点：

独立上下文
专注单一任务
返回结果到主代理

Use the Task tool to start sub-agents:

"Start a specialized agent to optimize this algorithm"

Sub-agent features:

Independent context
Focused on single task
Returns results to main agent

智能任务管理

Intelligent Task Management

使用 TodoWrite 工具：

"创建任务列表来跟踪这个项目"

任务状态：

```
pending
```
- 待处理
```
in_progress
```
- 进行中
```
completed
```
- 已完成

Use the TodoWrite tool:

"Create a task list to track this project"

Task statuses:

```
pending
```
- Pending
```
in_progress
```
- In progress
```
completed
```
- Completed

代码生成模式

Code Generation Patterns

渐进式开发：

生成基础结构
添加核心功能
实现细节
测试和优化

验证驱动：

写测试用例
实现功能
运行测试
修复问题

Incremental Development:

Generate basic structure
Add core functionality
Implement details
Test and optimize

Validation-Driven:

Write test cases
Implement functionality
Run tests
Fix issues

质量保证

Quality Assurance

自动化测试

Automated Testing

bash

undefined

bash

undefined

运行测试

Run tests

npm test pytest

类型检查

Type checking

mypy script.py tsc --noEmit

代码检查

Code linting

eslint src/ flake8 .

undefined

eslint src/ flake8 .

undefined

代码审查模式

Code Review Pattern

使用子代理进行审查：

"启动代码审查代理检查这个文件"

审查重点：

代码质量
安全问题
性能优化
最佳实践

Use sub-agents for review:

"Start a code review agent to check this file"

Review focus areas:

Code quality
Security issues
Performance optimization
Best practices

错误恢复

Error Recovery

常见错误模式

Common Error Patterns

工具使用错误
- 检查权限
- 验证语法
- 确认路径
文件操作错误
- 确认文件存在
- 检查读写权限
- 验证路径正确
API 调用错误
- 检查网络连接
- 验证 API 密钥
- 确认请求格式

Tool Usage Errors
- Check permissions
- Validate syntax
- Confirm paths
File Operation Errors
- Verify file exists
- Check read/write permissions
- Validate path correctness
API Call Errors
- Check network connection
- Verify API key
- Confirm request format

渐进式修复策略

Incremental Fix Strategy

隔离问题
最小化复现
逐步修复
验证解决方案

Isolate the problem
Minimize reproduction
Fix incrementally
Validate solution

最佳实践

Best Practices

开发原则

Development Principles

清晰优先 - 明确需求和目标
渐进实现 - 分步骤开发
持续验证 - 频繁测试
适当抽象 - 合理模块化

Clarity First - Clearly define requirements and goals
Incremental Implementation - Develop in stages
Continuous Validation - Test frequently
Appropriate Abstraction - Reasonable modularization

工具使用原则

Tool Usage Principles

正确的工具 - 选择合适的工具
工具组合 - 多工具协同
权限最小化 - 只请求必要权限
错误处理 - 优雅处理失败

Right Tool for the Job - Choose appropriate tools
Tool Combination - Collaborate with multiple tools
Least Privilege - Request only necessary permissions
Error Handling - Gracefully handle failures

性能优化

Performance Optimization

批量操作 - 合并多个操作
增量处理 - 处理大文件
缓存结果 - 避免重复计算
异步优先 - 使用 async/await

Batch Operations - Combine multiple operations
Incremental Processing - Handle large files
Cache Results - Avoid redundant calculations
Async First - Use async/await

安全考虑

Security Considerations

沙箱模型

Sandbox Model

每个工具在隔离环境中运行：

REPL：无文件系统访问
Bash：需要明确授权
Web：仅特定域名

Each tool runs in an isolated environment:

REPL: No file system access
Bash: Requires explicit authorization
Web: Only specific domains

最佳安全实践

Security Best Practices

最小权限 - 仅授予必要权限
代码审查 - 检查生成的代码
敏感数据 - 不要共享密钥
定期审计 - 检查钩子和配置

Least Privilege - Grant only necessary permissions
Code Review - Inspect generated code
Sensitive Data - Do not share keys
Regular Audits - Check hooks and configurations

故障排除

Troubleshooting

工具无法使用

Tool Unavailable

症状： 工具调用失败

解决方案：

检查权限设置
验证语法正确
确认文件路径
查看错误消息

Symptom: Tool call fails

Solutions:

Check permission settings
Validate syntax correctness
Confirm file paths
Review error messages

REPL 性能问题

REPL Performance Issues

症状： REPL 执行缓慢

解决方案：

减少数据量
使用流式处理
优化算法
分批处理

Symptom: REPL execution is slow

Solutions:

Reduce data volume
Use streaming processing
Optimize algorithms
Process in batches

MCP 连接失败

MCP Connection Failure

症状： MCP 服务器无响应

解决方案：

检查配置文件
验证服务器运行
确认环境变量
查看服务器日志

Symptom: MCP server unresponsive

Solutions:

Check configuration files
Verify server is running
Confirm environment variables
Review server logs

实用示例

Practical Examples

示例 1：数据分析

Example 1: Data Analysis

javascript

// 在 REPL 中
const data = await window.fs.readFile('data.csv');
const parsed = Papa.parse(data, { header: true });
const values = parsed.data.map(row => parseFloat(row.value));
const avg = _.mean(values);
const std = math.std(values);
console.log(`平均值: ${avg}, 标准差: ${std}`);

javascript

// In REPL
const data = await window.fs.readFile('data.csv');
const parsed = Papa.parse(data, { header: true });
const values = parsed.data.map(row => parseFloat(row.value));
const avg = _.mean(values);
const std = math.std(values);
console.log(`Average: ${avg}, Standard Deviation: ${std}`);

示例 2：文件搜索

Example 2: File Search

bash

undefined

bash

undefined

在 Bash 中

In Bash

grep -r "TODO" src/ find . -name "*.py" -type f

undefined

grep -r "TODO" src/ find . -name "*.py" -type f

undefined

示例 3：网络数据获取

Example 3: Web Data Retrieval

"使用 web_fetch 获取 https://api.example.com/data 的内容，
然后在 REPL 中分析 JSON 数据"

"Use web_fetch to get content from https://api.example.com/data, then analyze the JSON data in REPL"

参考文件

Reference Files

此技能包含详细文档：

README.md (9,594 行) - 完整的 Claude Code 高级指南

包含以下主题：

核心工具深度解析
REPL 高级协同模式
开发工作流详解
MCP 集成完整指南
钩子系统配置
高级模式和最佳实践
故障排除和安全考虑

使用

view

命令查看参考文件获取详细信息。

This skill includes detailed documentation:

README.md (9,594 lines) - Complete Claude Code Advanced Guide

Covers the following topics:

In-depth analysis of core tools
Advanced REPL collaboration patterns
Detailed development workflows
Complete MCP integration guide
Hook system configuration
Advanced patterns and best practices
Troubleshooting and security considerations

Use the

view

command to access reference files for detailed information.

资源

Resources

GitHub 仓库: https://github.com/karminski/claude-code-guide-study
原始版本: https://github.com/Cranot/claude-code-guide
Anthropic 官方文档: https://docs.claude.com

GitHub Repository: https://github.com/karminski/claude-code-guide-study
Original Version: https://github.com/Cranot/claude-code-guide
Anthropic Official Documentation: https://docs.claude.com

注意事项

Notes

本指南结合了：

官方功能和公告
实际使用观察到的模式
概念性方法和最佳实践
第三方工具集成

请在使用时参考最新的官方文档。

使用这个技能深入掌握 Claude Code 的强大功能！

This guide combines:

Official features and announcements
Patterns observed in practical usage
Conceptual approaches and best practices
Third-party tool integrations

Please refer to the latest official documentation when using.

Use this skill to master the powerful features of Claude Code!