Claude Code Goal 命令编写指南
本文档面向开发团队，介绍如何编写高质量的 Goal 命令（结构化指令），让 AI 助手高效、可靠地执行批量代码修改任务。
一、什么是 Goal 命令
1.1 官方定义
/goal 是 Claude Code 的内置命令。官方文档描述如下：
/goal [condition|clear]— 设置一个目标：Claude 在多个轮次中继续工作，直到满足条件。不带参数时，显示当前或最近实现的目标。clear、stop、off、reset、none或cancel会提前移除活跃目标。
简单说：你用 /goal 设一个目标条件，Claude 就会持续工作直到条件达成。这跟普通对话"问一句答一句"不同 —— Goal 模式下 Claude 会自主推进多轮操作。
版本要求：/goal 命令自 Claude Code v2.1.139 起引入（2025 年 5 月发布）。使用前请确认你的 Claude Code 版本 ≥ 2.1.139，可通过 claude --version 查看当前版本。如果版本过低，运行 claude update 升级。
1.2 使用方式
/goal
（你的完整目标描述，包含步骤、规则、约束等）Claude 收到后会持续执行，直到你描述的目标完成。你可以用 /goal clear 随时终止。
1.3 和其他命令的协作
Goal 命令常和以下命令配合使用：
| 命令 | 配合场景 |
|---|---|
/compact | Goal 执行过程中对话变长时压缩上下文 |
/diff | Goal 完成后查看改动 |
/review | Goal 产出代码后做审查 |
/plan | 复杂任务先用 Plan 规划，再用 Goal 执行 |
二、核心原则
1. 步骤化 —— 告诉 AI "做什么" 和 "怎么做"
差的写法：
把所有 Sonar 问题修一下好的写法：
对每个问题类别：
1. 读取对应文件
2. 按规则修复（如：删除空 CSS 块）
3. 更新分析文档标记为已修复
4. 验证 diff 确认改动正确
5. 提交，commit message: "fix: sonar问题修复"2. 验证闭环 —— 不信任，要验证
每一步操作后都要验证。尤其是：
- CSS/SCSS 改动后检查括号闭合
- 正则修改后检查语法正确
- 函数提取后检查调用方完整
血的教训：删除 CSS 空块 .el-icon {} 时，删了内容但留下了多余的 }，导致整个文件语法报错。如果当时验证了 diff 再提交，一眼就能发现。
3. 边界清晰 —— 什么该做、什么不该做
明确告诉 AI：
注意事项：
- 不要提交分析文档，只提交代码文件
- 不要修改 .gitignore
- 不要顺便格式化其他代码
- 每个类别单独一个 commit4. 输出格式固定 —— 方便检查进度
每完成一个类别输出：
✅ 类别号 | 文件数 | 通过
❌ 类别号 | 失败 — 问题描述三、Goal 命令的结构模板
一个完整的 Goal 命令建议包含以下部分：
/goal
【一句话目标描述】
按以下步骤执行：
1. 【准备阶段】
- 列出所有待处理的条目
- 读取参考文档，确认规则
2. 【执行阶段】
- 逐条处理的具体操作步骤
- 每条处理完的验证方法
3. 【验证阶段】
- 逐条回查 diff
- 检查语法完整性
- 确认无多余改动
4. 【收尾阶段】
- 输出汇总报告
注意事项：
- 明确的约束条件
- 什么不能做
- 出错时怎么处理四、实战案例：批量代码质量修复
以下是一个脱敏后的真实案例，展示了如何用 Goal 命令批量修复代码扫描工具发现的问题。
4.1 执行阶段的 Goal 命令
/goal
逐个修复代码扫描发现的 N 个问题类别（编号 #1 ~ #N），每个类别按以下步骤处理：
1. 用 `git log --oneline` 确认当前分支状态
2. 对照分析文档（analysis.md），读取该类别的规则描述和涉及文件
3. 对每个文件进行修复：
a. 先 Read 文件，定位问题行
b. 按规则修改（具体修复方式见下表）
c. 确认修改后代码语法正确
4. 更新 analysis.md 中该类别的状态为"已修复"（仅本地，不提交）
5. 用 `git diff` 验证改动：
- 只有目标修复，没有多余改动
- CSS/SCSS 文件括号闭合正确
- Vue 文件标签闭合正确
6. `git add` 相关代码文件（不包括 analysis.md）
7. `git commit -m "fix: 代码质量修复@scan"`
修复方式对照表：
| 类别 | 问题 | 修复方式 |
|------|------|---------|
| #1 | 正则中单字符类 | `[x]` → `x` |
| #2 | 无效语句 | 补充 return 或内联表达式 |
| #3 | 重复函数 | 提取公共函数或 NOSONAR 注释 |
| #4 | 冗余赋值 | 删除被覆盖的赋值行 |
| #5 | 子表达式赋值 | 拆为独立的赋值 + 判断 |
| #6 | else-if 可合并 | `else { if }` → `else if` |
| #7 | Object.assign | 替换为展开语法 |
| #8 | reject 字面量 | 包裹 `new Error()` |
| #9 | HTML5 废弃属性 | 替换为 CSS 等效写法 |
| #10 | 不必要转义 | 移除多余反斜杠 |
| #11 | indexOf 判断首尾 | 替换为 startsWith/endsWith |
| #12 | 字体缺泛型回退 | 追加 `, sans-serif` |
| #13 | 重复字体名 | 去重，用 sans-serif 替代 |
| #14 | 重复 CSS 属性 | 删除先定义的那个 |
| #15 | 空 CSS 块 | 整个块删除（含大括号）|
| #16 | 空 style 标签 | 整个 `<style>...</style>` 删除 |
| #17 | 重复 CSS 选择器 | 合并到同一个块 |
| #18 | 嵌套三元 | 改为 if-else 或 Map 查找 |
| #19 | 嵌套模板字符串 | 提取为变量 |
| #20 | 复杂正则 | 添加 NOSONAR 注释抑制 |
| #21 | 正则类重复字符 | 去重 |
| #22 | th 缺 scope | 添加 scope="col" 或 scope="row" |
注意事项：
- 分析文档 analysis.md 只留在本地，永远不要提交到 git
- 每个类别一个独立 commit
- 不要修改无关代码，不要顺手格式化
- CSS/SCSS 删除空块时，确保删除完整的 `selector { }`，不要遗留多余的 `}`
- 量大时（如 #16 涉及 100+ 文件），可以用脚本处理，但必须逐文件验证 diff
- 如果某条修复拿不准，先问用户再动手4.2 验证阶段的 Goal 命令
修复完成后，用独立的 Goal 命令逐条验证：
/goal
逐个验证分支上最近的 N 个代码修复 commit，每个 commit 按以下步骤检查：
1. 用 `git log --oneline -N` 列出所有 commit
2. 对每个 commit：
- `git show <hash> --stat` 查看改动文件
- `git show <hash> --format="" -- .` 查看具体 diff
3. 验证内容：
a. 语法完整性：括号匹配、标签闭合、CSS 块完整
b. 修复正确性：改动确实解决了对应问题
c. 无多余改动：没有无关的格式化或 import 变动
4. 对 CSS/SCSS/Less 改动特别检查：
- 删除空块后无遗留多余大括号
- 合并选择器后属性未丢失
- font-family 补充后语法正确
5. 对 Vue 文件特别检查：
- template 标签闭合正确
- style 标签删除后无孤儿内容
6. 对 JS/TS 文件特别检查：
- 正则语法正确
- 函数提取后调用方和定义都完整
- return 语句无遗漏
每个 commit 验证完输出：
- ✅ commit hash | 类别号 | 通过 — 简述
- ❌ commit hash | 类别号 | 失败 — 具体问题
全部完成后输出汇总报告。
注意事项：
- 不修改任何代码，纯验证任务
- 发现问题记录到 analysis.md
- 每次只看一个 commit五、踩坑记录
以下是实际执行中遇到的问题，编写 Goal 命令时应提前规避：
1. 删除 CSS 空块遗留多余括号
现象：删除 .el-icon {} 时只删了内容行，留下了外层的 }，导致整个 SCSS 文件语法错误。
预防：Goal 命令中明确写 "删除完整的 selector { } 包含大括号"，并在验证阶段特别检查括号闭合。
2. 分析文档被误提交
现象：本应只留在本地的分析文档被 git add 带进了 commit。
预防：注意事项中明确写 "分析文档不提交"。用 git add 指定文件而非 git add -A。
3. 脚本批量处理后未验证
现象：用 sed 批量删除空 style 标签，结果工作目录不对，改了 0 个文件却以为成功了。
预防：脚本处理后必须用 git diff --stat 确认改动数量，数量为 0 说明有问题。
4. git add -A 带入了无关改动
现象：git add -A 把 IDE 自动格式化的 600+ 行变更一起提交了。
预防：永远用 git add <指定文件> 而非 git add -A。提交前用 git diff --cached --stat 检查暂存区。
5. 量大时偷懒用脚本跳过验证
现象：涉及 179 个文件的修改，想用脚本一步到位，结果引入了语法错误。
预防：可以用脚本处理，但必须抽样验证。Goal 命令中写 "量大可用脚本，但必须用 git diff --numstat 过滤出纯删除行并逐文件确认"。
六、编写 Checklist
写完 Goal 命令后，对照以下清单检查：
目标明确：一句话能说清最终要干什么
步骤有序：按 1、2、3 编号，有先后依赖关系
操作具体：告诉 AI 用什么工具/命令（如
git show、Read）验证闭环：每个关键步骤后有验证检查点
边界清晰：写了 "不要做 X" 的约束
输出格式：规定了 AI 的输出格式，方便追踪进度
异常处理：写了出错时怎么办（问用户 / 跳过 / 记录）
脱敏：如果是模板，确保没有真实的路径、IP、密钥