mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-16 12:28:06 +00:00
docs: skills - upgrade skill instructions
This commit is contained in:
tukuaiai
@@ -1,470 +1,106 @@
|
||||
---
|
||||
name: claude-code-guide
|
||||
description: Claude Code 高级开发指南 - 全面的中文教程，涵盖工具使用、REPL 环境、开发工作流、MCP 集成、高级模式和最佳实践。适合学习 Claude Code 的高级功能和开发技巧。
|
||||
description: "Claude Code guide skill: CLI workflows, project context, tool permissions, slash commands, hooks, MCP, large-file analysis, debugging, and advanced coding-agent operating patterns."
|
||||
---
|
||||
|
||||
# Claude Code 高级开发指南
|
||||
# claude-code-guide Skill
|
||||
|
||||
全面的 Claude Code 中文学习指南，涵盖从基础到高级的所有核心概念、工具使用、开发工作流和最佳实践。
|
||||
Use this skill to answer Claude Code workflow questions and to turn the long Chinese guide in `references/README.md` into focused operating steps.
|
||||
|
||||
## 何时使用此技能
|
||||
## When to Use This Skill
|
||||
|
||||
当需要以下帮助时使用此技能：
|
||||
- 学习 Claude Code 的核心功能和工具
|
||||
- 掌握 REPL 环境的高级用法
|
||||
- 理解开发工作流和任务管理
|
||||
- 使用 MCP 集成外部系统
|
||||
- 实现高级开发模式
|
||||
- 应用 Claude Code 最佳实践
|
||||
- 解决常见问题和错误
|
||||
- 进行大文件分析和处理
|
||||
Trigger when any of these applies:
|
||||
- Learning or explaining Claude Code CLI workflows, command habits, or project-context handling.
|
||||
- Designing slash commands, hooks, MCP integrations, memory/context conventions, or task workflows.
|
||||
- Debugging Claude Code permission, tool-use, file analysis, or large-context problems.
|
||||
- Comparing interactive coding-agent patterns such as explore-plan-edit-verify, review loops, or multi-agent coordination.
|
||||
- Extracting a compact answer from the full Claude Code guide in `references/README.md`.
|
||||
|
||||
## 快速参考
|
||||
## Not For / Boundaries
|
||||
|
||||
### Claude Code 核心工具（7个）
|
||||
- Not the source of truth for current Claude product availability, pricing, or model names; verify those with official Anthropic docs when exact current behavior matters.
|
||||
- Not for bypassing tool permissions, sandbox rules, repository policies, or higher-priority system/developer instructions.
|
||||
- Do not treat the long guide as automatically correct for every Claude Code version; use it as local project reference material.
|
||||
- Required inputs: target workflow, OS/shell, Claude Code version if relevant, current repository constraints, and the exact error or behavior observed.
|
||||
- If a command may mutate files or external systems, identify the blast radius and validation path before recommending it.
|
||||
|
||||
1. **REPL** - JavaScript 运行时环境
|
||||
- 完整的 ES6+ 支持
|
||||
- 预加载库：D3.js, MathJS, Lodash, Papaparse, SheetJS
|
||||
- 支持 async/await, BigInt, WebAssembly
|
||||
- 文件读取：`window.fs.readFile()`
|
||||
## Quick Reference
|
||||
|
||||
2. **Artifacts** - 可视化输出
|
||||
- React, Three.js, 图表库
|
||||
- HTML/SVG 渲染
|
||||
- 交互式组件
|
||||
### Common Patterns
|
||||
|
||||
3. **Web Search** - 网络搜索
|
||||
- 仅美国可用
|
||||
- 域名过滤支持
|
||||
|
||||
4. **Web Fetch** - 获取网页内容
|
||||
- HTML 转 Markdown
|
||||
- 内容提取和分析
|
||||
|
||||
5. **Conversation Search** - 对话搜索
|
||||
- 搜索历史对话
|
||||
- 上下文检索
|
||||
|
||||
6. **Recent Chats** - 最近对话
|
||||
- 访问最近会话
|
||||
- 对话历史
|
||||
|
||||
7. **End Conversation** - 结束对话
|
||||
- 清理和总结
|
||||
- 会话管理
|
||||
|
||||
### 大文件分析工作流
|
||||
**Start with project context**
|
||||
```text
|
||||
Read README/AGENTS/CONTRIBUTING, inspect git status, then search for local patterns before editing.
|
||||
```
|
||||
|
||||
**Large-file triage**
|
||||
```bash
|
||||
# 阶段 1：定量评估
|
||||
wc -l filename.md # 行数统计
|
||||
wc -w filename.md # 词数统计
|
||||
wc -c filename.md # 字符数统计
|
||||
|
||||
# 阶段 2：结构分析
|
||||
grep "^#{1,6} " filename.md # 提取标题层次
|
||||
grep "```" filename.md # 识别代码块
|
||||
grep -c "keyword" filename.md # 关键词频率
|
||||
|
||||
# 阶段 3：内容提取
|
||||
Read filename.md offset=0 limit=50 # 文件开头
|
||||
Read filename.md offset=N limit=100 # 目标部分
|
||||
Read filename.md offset=-50 limit=50 # 文件结尾
|
||||
wc -l path/to/file.md
|
||||
rg -n '^#{1,6} ' path/to/file.md
|
||||
sed -n '1,120p' path/to/file.md
|
||||
```
|
||||
|
||||
### REPL 高级用法
|
||||
|
||||
```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();
|
||||
**Slash command authoring shape**
|
||||
```text
|
||||
.claude/commands/<command-name>.md
|
||||
```
|
||||
|
||||
### 斜杠命令系统
|
||||
|
||||
**内置命令：**
|
||||
- `/help` - 显示帮助
|
||||
- `/clear` - 清除对话
|
||||
- `/plugin` - 管理插件
|
||||
- `/settings` - 配置设置
|
||||
|
||||
**自定义命令：**
|
||||
创建 `.claude/commands/mycommand.md`：
|
||||
```markdown
|
||||
根据需求执行特定任务的指令
|
||||
**Hook design checklist**
|
||||
```text
|
||||
event -> allowed command -> timeout -> logging -> rollback/disable path
|
||||
```
|
||||
|
||||
使用：`/mycommand`
|
||||
|
||||
### 开发工作流模式
|
||||
|
||||
#### 1. 文件分析工作流
|
||||
```bash
|
||||
# 探索 → 理解 → 实现
|
||||
ls -la # 列出文件
|
||||
Read file.py # 读取内容
|
||||
grep "function" file.py # 搜索模式
|
||||
# 然后实现修改
|
||||
**MCP integration checklist**
|
||||
```text
|
||||
server name -> command/env -> auth source -> minimal permission -> smoke test
|
||||
```
|
||||
|
||||
#### 2. 算法验证工作流
|
||||
```bash
|
||||
# 设计 → 验证 → 实现
|
||||
# 1. 在 REPL 中测试逻辑
|
||||
# 2. 验证边界情况
|
||||
# 3. 实现到代码
|
||||
**Debug a Claude Code failure**
|
||||
```text
|
||||
Capture: command, working directory, permission mode, exact error, relevant config, and smallest reproduction.
|
||||
```
|
||||
|
||||
#### 3. 数据探索工作流
|
||||
```bash
|
||||
# 检查 → 分析 → 可视化
|
||||
# 1. 读取数据文件
|
||||
# 2. REPL 中分析
|
||||
# 3. Artifacts 可视化
|
||||
**Context hygiene rule**
|
||||
```text
|
||||
Keep entry prompts short; move long references to files and load only the needed section.
|
||||
```
|
||||
|
||||
## 核心概念
|
||||
## Examples
|
||||
|
||||
### 工具权限系统
|
||||
### Example 1: Add a Custom Slash Command
|
||||
|
||||
**自动授予权限的工具：**
|
||||
- REPL
|
||||
- Artifacts
|
||||
- Web Search/Fetch
|
||||
- Conversation Search
|
||||
- Input: user wants a repeatable `/review-pr` workflow.
|
||||
- Steps:
|
||||
1. Create or update `.claude/commands/review-pr.md` with scope, required inputs, and output format.
|
||||
2. Reference repository review rules instead of duplicating stale policy text.
|
||||
3. Test the command on a small diff and refine ambiguous steps.
|
||||
- Expected output / acceptance: command is discoverable, deterministic, and does not bypass repo review constraints.
|
||||
|
||||
**需要授权的工具：**
|
||||
- Bash (读/写文件系统)
|
||||
- Edit (修改文件)
|
||||
- Write (创建文件)
|
||||
### Example 2: Diagnose a Permission Problem
|
||||
|
||||
### 项目上下文
|
||||
- Input: Claude Code refuses to run or edit a file.
|
||||
- Steps:
|
||||
1. Identify whether the blocker is tool permission, filesystem sandbox, repository policy, or OS permissions.
|
||||
2. Capture the exact path, command, and error.
|
||||
3. Propose the least-permissive fix and a smoke test.
|
||||
- Expected output / acceptance: user gets a concrete unblock path without granting broad unnecessary access.
|
||||
|
||||
Claude 自动识别：
|
||||
- Git 仓库状态
|
||||
- 编程语言（从文件扩展名）
|
||||
- 项目结构
|
||||
- 依赖配置
|
||||
### Example 3: Summarize a Long Guide Section
|
||||
|
||||
### 内存系统
|
||||
- Input: need the MCP section from `references/README.md`.
|
||||
- Steps:
|
||||
1. Use heading search to locate the section.
|
||||
2. Read only the relevant slice.
|
||||
3. Return a short operator checklist plus links back to the local reference file.
|
||||
- Expected output / acceptance: answer is actionable and avoids dumping the full long document.
|
||||
|
||||
**对话内存：**
|
||||
- 存储在当前会话
|
||||
- 200K token 窗口
|
||||
- 自动上下文管理
|
||||
## References
|
||||
|
||||
**持久内存（实验性）：**
|
||||
- 跨会话保存
|
||||
- 用户偏好记忆
|
||||
- 项目上下文保留
|
||||
- `references/index.md`: structured navigation for the guide.
|
||||
- `references/README.md`: long-form Claude Code Chinese guide.
|
||||
|
||||
## MCP 集成
|
||||
## Maintenance
|
||||
|
||||
### 什么是 MCP？
|
||||
|
||||
Model Context Protocol - 连接 Claude 到外部系统的协议。
|
||||
|
||||
### MCP 服务器配置
|
||||
|
||||
配置文件：`~/.config/claude/mcp_config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["path/to/server.js"],
|
||||
"env": {
|
||||
"API_KEY": "your-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 MCP 工具
|
||||
|
||||
Claude 会自动发现 MCP 工具并在对话中使用：
|
||||
|
||||
```
|
||||
"使用 my-server 工具获取数据"
|
||||
```
|
||||
|
||||
## 钩子系统
|
||||
|
||||
### 钩子类型
|
||||
|
||||
在 `.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'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 常见钩子用途
|
||||
|
||||
- 自动格式化代码
|
||||
- 运行测试
|
||||
- Git 提交检查
|
||||
- 日志记录
|
||||
- 通知发送
|
||||
|
||||
## 高级模式
|
||||
|
||||
### 多代理协作
|
||||
|
||||
使用 Task 工具启动子代理：
|
||||
|
||||
```
|
||||
"启动一个专门的代理来优化这个算法"
|
||||
```
|
||||
|
||||
子代理特点：
|
||||
- 独立上下文
|
||||
- 专注单一任务
|
||||
- 返回结果到主代理
|
||||
|
||||
### 智能任务管理
|
||||
|
||||
使用 TodoWrite 工具：
|
||||
|
||||
```
|
||||
"创建任务列表来跟踪这个项目"
|
||||
```
|
||||
|
||||
任务状态：
|
||||
- `pending` - 待处理
|
||||
- `in_progress` - 进行中
|
||||
- `completed` - 已完成
|
||||
|
||||
### 代码生成模式
|
||||
|
||||
**渐进式开发：**
|
||||
1. 生成基础结构
|
||||
2. 添加核心功能
|
||||
3. 实现细节
|
||||
4. 测试和优化
|
||||
|
||||
**验证驱动：**
|
||||
1. 写测试用例
|
||||
2. 实现功能
|
||||
3. 运行测试
|
||||
4. 修复问题
|
||||
|
||||
## 质量保证
|
||||
|
||||
### 自动化测试
|
||||
|
||||
```bash
|
||||
# 运行测试
|
||||
npm test
|
||||
pytest
|
||||
|
||||
# 类型检查
|
||||
mypy script.py
|
||||
tsc --noEmit
|
||||
|
||||
# 代码检查
|
||||
eslint src/
|
||||
flake8 .
|
||||
```
|
||||
|
||||
### 代码审查模式
|
||||
|
||||
使用子代理进行审查：
|
||||
|
||||
```
|
||||
"启动代码审查代理检查这个文件"
|
||||
```
|
||||
|
||||
审查重点：
|
||||
- 代码质量
|
||||
- 安全问题
|
||||
- 性能优化
|
||||
- 最佳实践
|
||||
|
||||
## 错误恢复
|
||||
|
||||
### 常见错误模式
|
||||
|
||||
1. **工具使用错误**
|
||||
- 检查权限
|
||||
- 验证语法
|
||||
- 确认路径
|
||||
|
||||
2. **文件操作错误**
|
||||
- 确认文件存在
|
||||
- 检查读写权限
|
||||
- 验证路径正确
|
||||
|
||||
3. **API 调用错误**
|
||||
- 检查网络连接
|
||||
- 验证 API 密钥
|
||||
- 确认请求格式
|
||||
|
||||
### 渐进式修复策略
|
||||
|
||||
1. 隔离问题
|
||||
2. 最小化复现
|
||||
3. 逐步修复
|
||||
4. 验证解决方案
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 开发原则
|
||||
|
||||
1. **清晰优先** - 明确需求和目标
|
||||
2. **渐进实现** - 分步骤开发
|
||||
3. **持续验证** - 频繁测试
|
||||
4. **适当抽象** - 合理模块化
|
||||
|
||||
### 工具使用原则
|
||||
|
||||
1. **正确的工具** - 选择合适的工具
|
||||
2. **工具组合** - 多工具协同
|
||||
3. **权限最小化** - 只请求必要权限
|
||||
4. **错误处理** - 优雅处理失败
|
||||
|
||||
### 性能优化
|
||||
|
||||
1. **批量操作** - 合并多个操作
|
||||
2. **增量处理** - 处理大文件
|
||||
3. **缓存结果** - 避免重复计算
|
||||
4. **异步优先** - 使用 async/await
|
||||
|
||||
## 安全考虑
|
||||
|
||||
### 沙箱模型
|
||||
|
||||
每个工具在隔离环境中运行：
|
||||
- REPL：无文件系统访问
|
||||
- Bash：需要明确授权
|
||||
- Web：仅特定域名
|
||||
|
||||
### 最佳安全实践
|
||||
|
||||
1. **最小权限** - 仅授予必要权限
|
||||
2. **代码审查** - 检查生成的代码
|
||||
3. **敏感数据** - 不要共享密钥
|
||||
4. **定期审计** - 检查钩子和配置
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 工具无法使用
|
||||
|
||||
**症状：** 工具调用失败
|
||||
|
||||
**解决方案：**
|
||||
- 检查权限设置
|
||||
- 验证语法正确
|
||||
- 确认文件路径
|
||||
- 查看错误消息
|
||||
|
||||
### REPL 性能问题
|
||||
|
||||
**症状：** REPL 执行缓慢
|
||||
|
||||
**解决方案：**
|
||||
- 减少数据量
|
||||
- 使用流式处理
|
||||
- 优化算法
|
||||
- 分批处理
|
||||
|
||||
### MCP 连接失败
|
||||
|
||||
**症状：** MCP 服务器无响应
|
||||
|
||||
**解决方案：**
|
||||
- 检查配置文件
|
||||
- 验证服务器运行
|
||||
- 确认环境变量
|
||||
- 查看服务器日志
|
||||
|
||||
## 实用示例
|
||||
|
||||
### 示例 1：数据分析
|
||||
|
||||
```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}`);
|
||||
```
|
||||
|
||||
### 示例 2：文件搜索
|
||||
|
||||
```bash
|
||||
# 在 Bash 中
|
||||
grep -r "TODO" src/
|
||||
find . -name "*.py" -type f
|
||||
```
|
||||
|
||||
### 示例 3：网络数据获取
|
||||
|
||||
```
|
||||
"使用 web_fetch 获取 https://api.example.com/data 的内容，
|
||||
然后在 REPL 中分析 JSON 数据"
|
||||
```
|
||||
|
||||
## 参考文件
|
||||
|
||||
此技能包含详细文档：
|
||||
|
||||
- **README.md** (9,594 行) - 完整的 Claude Code 高级指南
|
||||
|
||||
包含以下主题：
|
||||
- 核心工具深度解析
|
||||
- REPL 高级协同模式
|
||||
- 开发工作流详解
|
||||
- MCP 集成完整指南
|
||||
- 钩子系统配置
|
||||
- 高级模式和最佳实践
|
||||
- 故障排除和安全考虑
|
||||
|
||||
使用 `view` 命令查看参考文件获取详细信息。
|
||||
|
||||
## 资源
|
||||
|
||||
- **GitHub 仓库**: https://github.com/karminski/claude-code-guide-study
|
||||
- **原始版本**: https://github.com/Cranot/claude-code-guide
|
||||
- **Anthropic 官方文档**: https://docs.claude.com
|
||||
|
||||
## 注意事项
|
||||
|
||||
本指南结合了：
|
||||
- 官方功能和公告
|
||||
- 实际使用观察到的模式
|
||||
- 概念性方法和最佳实践
|
||||
- 第三方工具集成
|
||||
|
||||
请在使用时参考最新的官方文档。
|
||||
|
||||
---
|
||||
|
||||
**使用这个技能深入掌握 Claude Code 的强大功能！**
|
||||
- Sources: local `references/README.md` and `references/index.md`.
|
||||
- Last updated: 2026-04-28
|
||||
- Known limits: Claude Code behavior can change; verify current CLI flags, hooks, and MCP details against official docs when precision matters.
|
||||
|
||||
Reference in New Issue
Block a user