claude_guide

Claude Code 新手使用指导手册

一、基本概念

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，可以直接在你的终端中工作。它能够读写文件、执行命令、搜索代码库、操作 Git，像一个经验丰富的同事一样与你协作。

工作模式

• 对话模式：直接输入自然语言指令，Claude Code 会理解你的意图并执行

• Plan 模式：复杂任务先出方案，你审核后再动手实现（自动触发或手动进入）

• 权限控制：涉及文件修改、命令执行等操作时，会请你确认（可按需调整）

核心能力

| 能力 | 说明 |

|------|------|

| 读写文件 | 读取、创建、编辑项目中的任何文件 |

| 执行命令 | 在终端中运行 shell 命令 |

| 搜索代码 | 跨文件搜索函数、变量、关键词 |

| Git 操作 | 提交、分支管理、PR 创建 |

| 网页搜索 | 获取最新技术文档和信息 |

---

二、常用命令

2.1 内置命令

在对话中直接输入 / 开头的命令即可调用。

| 命令 | 说明 |

|------|------|

| /help | 查看帮助信息 |

| /clear | 清空当前对话上下文，重新开始 |

| /compact | 压缩对话上下文，释放 token 空间，保留关键摘要 |

| /context | 查看当前上下文使用情况（token 用量、模型信息） |

| /init | 在当前项目生成 CLAUDE.md 项目说明文件 |

| /config | 配置主题、模型等基本设置 |

| /cost | 查看当前会话的 API 费用 |

2.2 项目自定义命令

本工作区配置了以下专用命令（定义在 CLAUDE.md 和 custom_cmd.md 中）：

| 命令 | 说明 |

|------|------|

| /blog-publish | 发布博客文章到 MyWeb（自动 md→html） |

| /blog-unpublish | 下架已发布的博客文章 |

| /format | Verilog/SystemVerilog 代码格式化 |

| /md2html | Markdown → HTML 转换 |

| /md2pdf | Markdown → PDF/DOCX 转换 |

| /实验指导书Skill | 生成 FPGA 实验指导书 |

| /技术文档生成Skill | 生成/重写技术文档 |

| /git-push | 推送项目到 GitHub（自动忽略中间文件） |

| /git-pull | 从 GitHub 拉取项目到本地 |

2.3 终端 Shell 别名

这些是 Shell 别名（定义在 ~/.bashrc 中），在终端直接输入即可：

| 命令 | 说明 |

|------|------|

| chrome | 启动 Chrome 浏览器（自动走代理） |

| wechat | 启动微信客户端 |

| folder | 在文件管理器中打开当前目录 |

| lockd | 锁定屏幕 |

| gedit | 文本编辑器（GNOME 图形界面） |

| ll / la / l | 列出文件（详细信息 / 含隐藏文件 / 短格式） |

---

三、使用技巧

3.1 任务描述技巧

好的任务描述 = 清晰的目标 + 必要的上下文 + 约束条件

# 不推荐
帮我改一下那个文件

# 推荐
在 FPGA_Prj/linkreal_common/bfm/i2c_bfm.v 中，
把 SCL 的下降沿触发改成上升沿触发，不要改动其他地方。

关键原则：

• 指定文件路径或目录范围，不要只说"那个文件"

• 说明约束条件："不要改接口"、"保持向后兼容"、"不要引入新依赖"

• 描述预期结果："改完后 I2C 读时序应该符合 spec 图 3-2"

3.2 复杂任务先让 Claude Code 出方案

对于跨文件、有多个实现路径的任务，先让 Claude Code 探索代码库再出方案，避免盲目执行。

请先看一下 FPGA_Prj/linkreal_common/bfm/ 下的 I2C 相关模块，
然后给出一个添加多字节连续读功能的设计方案。

Claude Code 会自动进入 Plan 模式，探索代码、给出方案，等你确认后才动手修改。

3.3 善用 @ 符号引用

在对话中可以用 @ 引用文件或目录，帮助 Claude Code 精准定位：

@FPGA_Prj/linkreal_common/bfm/i2c_bfm.v 把这个模块的时钟域处理改成异步 FIFO 方案

3.4 /compact 和 /context 管理上下文

Claude Code 的对话上下文有容量限制。当讨论变长、token 接近上限时：

• /context — 查看当前 token 使用情况

• /compact — 压缩上下文（保留对话摘要，释放空间）

• 不要在一个超长对话中解决所有问题，适时 /clear 开始新话题

经验值：一般对话保持在 token 使用率 50% 以下体验最佳。

3.5 让 Claude Code 检查自己的工作

代码修改完成后，追加一句验证：

检查一下改动有没有引入语法错误，跑一下相关测试

Claude Code 会自动执行编译、lint 或测试命令来验证。

3.6 随时中断和重试

• 如果 Claude Code 走错方向，直接说"停，换一种思路"

• 用 Ctrl+C 可以中断正在执行的操作

• 不满意可以回退：让 Claude Code git diff 查看改动，或用 git checkout 恢复

---

四、高阶方法

4.1 CLAUDE.md — 项目级指令

项目根目录下的 CLAUDE.md 是项目级别的"使用说明书"。Claude Code 每次启动都会自动读取它。你可以在里面定义：

• 自定义斜杠命令

• 项目目录结构说明

• 编码规范和约定

• 特殊的工作流程

# 项目名称

## 自定义命令
| 命令 | 说明 |
|------|------|
| `/build` | 编译当前项目 |

## 编码规范
- Verilog 文件使用 Tab 缩进
- 模块名和文件名一致

4.2 Skills — 可复用的自动化技能

Skills 是预定义的自动化流程，存放在项目 .claude/skills/ 目录中。每个 skill 是一个 Markdown 文件，定义了触发条件、执行步骤和工具调用。

使用场景：

• 重复性的文档生成（如实验指导书、技术文档）

• 标准化的发布流程（如博客发布、代码推送）

• 代码格式化等通用操作

调用方式：直接输入 /skill名称或自然语言描述需求。

4.3 Memory 系统 — 跨会话持久记忆

Claude Code 支持持久化记忆，将用户偏好、项目背景等信息保存到 ~/.claude/projects/<project>/memory/ 目录。

适用场景：

• 记录你的技术背景和偏好（如"我是 FPGA 工程师，习惯 Verilog 风格 XX"）

• 记录项目的长期背景信息（如"这个模块的接口不能改，因为和硬件绑定"）

• 记录可复用的配置和账号信息

注意：不要记录代码模式、文件路径、Git 历史等可以随时从代码库派生出来的信息。

4.4 Git 工作流集成

Claude Code 可以直接操作 Git。

查看改动：

git diff

创建提交：

请帮我提交这些改动，commit message 简洁描述做了什么

Claude Code 会自动分析改动、生成合适的 commit message。

注意：不要用 --amend、--force、--no-verify 等破坏性 Git 操作，除非你明确要求。

4.5 并行处理多个独立任务

Claude Code 可以并行执行互不依赖的操作，提高效率。

请同时做三件事：
1. 把 bfm/ 下所有 .v 文件的 Tab 替换成空格
2. 在 document/ 下生成一份 I2C 接口说明文档
3. 检查 ip/ 目录下哪些模块缺少 testbench

4.6 用 Claude Code 生成文档

Claude Code 擅长从代码生成文档。

从代码生成 Markdown 文档：

请读取 FPGA_Prj/linkreal_common/bfm/ 下的所有 Verilog 文件，
生成一份模块接口说明文档，包含端口列表、时序图和波形说明。

转格式：

• /md2html — Markdown → HTML

• /md2pdf — Markdown → PDF/DOCX

4.7 在 Claude Code 中直接运行命令

以 ! 前缀发送消息，可以直接在当前终端执行命令而无需等待 Claude Code 响应：

! make sim TESTCASE=i2c_read

等价于在终端中直接输入 make sim TESTCASE=i2c_read，输出会直接返回到对话中。

4.8 调试协助

让 Claude Code 参与调试：

编译报错了，帮我看看错误日志

然后粘贴错误信息，Claude Code 会自动定位相关源文件并提出修复建议。

波形分析：

我用 Verdi 跑了一个仿真，波形截图放在 figures/wave.png，
帮我分析 I2C 时序有没有问题。

Claude Code 支持读取图片（PNG、JPG），可以分析波形截图、时序图等。

4.9 大文件处理技巧

处理大文件（如大型 Verilog 模块、长日志文件）时：

• 告诉 Claude Code 具体要修改的位置（行号、功能块名称）

• 先让 Claude Code 搜索关键词定位，再精确读取

• 日志文件太大时，先 grep 过滤再分析

/tmp/sim.log 有 500MB，帮我 grep 出所有 ERROR 和 WARNING 行，然后分析

4.10 上下文窗口利用策略

• 短期任务（单文件修改、简单问答）：直接描述，不担心上下文

• 中期任务（5-10 步操作）：任务开始前用 /context 确认余量，中间适时 /compact

• 长期任务（重构、大规模开发）：拆分成多个独立对话，每个对话用 /clear 重置上下文

4.11 多模型切换

Claude Code 支持多种模型。对于不同复杂度的任务可以选择不同模型以平衡速度和质量：

| 场景 | 推荐模型 |

|------|---------|

| 简单问答、文件搜索 | Haiku（最快） |

| 代码修改、文档生成 | Sonnet（均衡） |

| 复杂重构、架构设计 | Opus（最强） |

用 /config 或对话中直接要求切换模型。

---

快速参考卡片

| 操作 | 命令/方法 |

|------|----------|

| 查看帮助 | /help |

| 查看上下文用量 | /context |

| 清空对话 | /clear |

| 压缩上下文 | /compact |

| 直接执行命令 | ! <命令> |

| 生成文档 | 自然语言描述 + /md2html 或 /md2pdf |

| 发布博客 | /blog-publish |

| 推送代码 | /git-push <项目名> |

| 拉取代码 | /git-pull <项目名> |

| 中断操作 | Ctrl+C |

| 回退改动 | git checkout <文件> |

| 验证改动 | "检查改动是否正确" |