Goal Workflow 使用指南

Goal Workflow 是一套基于 Claude Code / Codex 的 AI 研发工作流技能集，将软件开发的完整生命周期拆分为标准化步骤，每一步都由一个专属 Skill 驱动。

它让 AI Agent 能够像一个有经验的工程师一样——从理解需求、拆解任务、编写代码、审查质量，到最终提交合入——全流程自主完成。你只需描述功能想法，剩下的交给工作流。

通过 npx skills CLI 一键安装所有技能：

# 安装本仓库所有 skills
npx skills add smallnest/goal-workflow

# 或安装指定 skill
npx skills add smallnest/goal-workflow --skill prd
npx skills add smallnest/goal-workflow --skill prd-to-spec
npx skills add smallnest/goal-workflow --skill to-issues
npx skills add smallnest/goal-workflow --skill review-it
npx skills add smallnest/goal-workflow --skill ship-it
npx skills add smallnest/goal-workflow --skill humanize-it
npx skills add smallnest/goal-workflow --skill listenhub-tts
npx skills add smallnest/goal-workflow --skill insight-diagram
npx skills add smallnest/goal-workflow --skill refactor
npx skills add smallnest/goal-workflow --skill modern-go
npx skills add smallnest/goal-workflow --skill note-it
npx skills add smallnest/goal-workflow --skill code-to-spec
npx skills add smallnest/goal-workflow --skill smell

# 全局安装（所有项目可用）
npx skills add smallnest/goal-workflow -g

# 安装到指定 agent
npx skills add smallnest/goal-workflow -a claude-code

前置要求

六步闭环，从需求到交付：

/prd 将一个模糊的功能想法转化为结构化的产品需求文档，并拆解为可独立实施的 Issue 卡片。

触发方式

# 在 Claude Code 中直接输入
/prd 给我们的任务管理系统加一个优先级功能

# 或使用触发词
写PRD：用户注册功能，支持邮箱和手机号
需求分析：为 API 增加限流能力

工作流程

• Agent 提出 3-5 个澄清问题（带字母选项，可快速回复 "1A, 2C, 3B"）
• 根据回答生成结构化 PRD（用户故事、功能需求、非目标、验收标准）
• 展示 PRD 供审阅，确认或调整
• 保存 PRD 到 tasks/prd-[feature-name].md
• 拆解 PRD 为 Issue 列表，展示供确认
• 选择创建模式（GitHub / Local / Baidu iCafe）并创建 Issue

输出示例

# 生成的 Issue 列表
📋 Generated 4 Issues from PRD:

#1: Add priority field to database (backend, high)
#2: Display priority indicator (frontend, high) — depends on #1
#3: Add priority selector (frontend, medium) — depends on #1
#4: Filter tasks by priority (frontend, medium) — depends on #1, #2

/prd-to-spec 将产品需求文档（PRD）转化为可实施的技术设计方案（SPEC）。PRD 说明"做什么"，SPEC 说明"怎么做"。

触发方式

# 在 Claude Code 中直接输入
/prd-to-spec tasks/prd-priority-system.md

# 或使用触发词
需求转设计：将优先级 PRD 转为技术方案
技术方案：基于 prd-user-auth.md 生成 SPEC

PRD → SPEC 映射

SPEC 输出结构（11 章节）

工作流程

• 定位 PRD 文件（自动扫描 tasks/ 或手动指定）
• （可选）分析现有代码库：架构、技术栈、模式、约定（无代码库时跳过，从零提出架构）
• 提出 3-5 个技术澄清问题（带选项）
• 生成完整 SPEC 文档
• 展示供审阅，确认或迭代
• 保存到 tasks/spec-[feature-name].md

/to-issues 将 PRD 和/或 SPEC 拆解为可独立实施的 Issue，并创建到你选择的平台。可独立使用，不需要先运行 /prd。

触发方式

# 在 Claude Code 中直接输入
/to-issues

# 或使用触发词
创建issue：基于 prd-user-auth.md 创建 Issue
拆解issue：从 SPEC 拆解可实施的卡片
生成卡片：将 PRD 和 SPEC 一起拆成 Issue

输入来源

创建平台

工作流程

• 定位输入文件（自动检测或手动指定 PRD/SPEC）
• 拆解为 Issue 列表，展示供用户审阅（可增删改合并）
• 选择创建平台（GitHub / Local / Baidu iCafe）
• 逐条创建并输出汇总报告

/goal 是 Claude Code 内置的目标驱动开发模式。选择一个 Issue 卡片，Agent 会理解验收标准并端到端实现。

使用方式

# Claude Code: 指定 GitHub Issue 编号
/goal #42

# Claude Code: 指定本地 Issue 文件
/goal tasks/issues/issue-001-add-priority-field.md

# Codex: 使用 --goal 参数
codex --goal "Implement issue #42: Add priority field to database"

Agent 行为

• 读取 Issue 描述和验收标准
• 分析代码库结构，理解上下文
• 编写实现代码
• 运行测试和类型检查
• 对 UI 变更在浏览器中验证
• 逐条确认验收标准满足

/review-it 在代码提交前进行自动化审查，发现潜在问题并迭代修复，直到审查通过。

触发方式

# 审查未提交的变更（默认模式）
/review-it

# 审查整个分支 vs main
/review-it --mode branch

# 审查 + 测试并行执行
/review-it --parallel-tests "npm test"

审查原则

审查模式

/ship-it 是实现完成后的标准收尾流程：提交代码、创建 PR、合入、添加实现总结、关闭 Issue。

触发方式

# 在 Claude Code 中调用
/ship-it

# 或使用触发词
提交代码
创建PR并合入

完整流程

# Step 1: 提交代码（关联 Issue）
git add <related files>
git commit -m "Add priority field to database (#42)"

# Step 2: 推送分支
git push -u origin feat/issue-42-priority-field

# Step 3: 创建 PR（body 包含 Closes #42）
gh pr create --title "Add priority field" \
  --body "Closes #42 ..."

# Step 4: 合入
gh pr merge --squash --delete-branch

# Step 5: 关闭 Issue（如未自动关闭）
gh issue close 42 --reason completed

错误处理

/humanize-it 对指定文档进行去 AI 味的改写。根据文档类型自动选择最合适的人性化策略，迭代改写直到效果达标。

触发方式

# 在 Claude Code 中直接输入
/humanize-it docs/architecture.md

# 或使用触发词
去AI味：把这篇文档改成人话
降AIGC：humanize docs/blog-draft.md

子 Skill 能力矩阵

自动策略选择

迭代机制

• 自动检测文档类型，选择第一个改写 skill
• 改写后按 5 个维度评分（AI 痕迹去除 / 自然度 / 信息完整 / 风格一致 / 可读性）
• 评分 ≥ 80 分则通过，输出结果
• 不达标则切换到下一个 skill，在上次改写基础上继续优化
• 同一 skill 连续 3 次无提升则自动切换
• 所有 skill 用完一轮后从头开始新一轮组合
• 最多迭代 42 轮，输出当前最佳结果

/listenhub-tts 使用 ListenHub API 将文本转换为语音。支持三种合成模式，覆盖从短文本到长文本的全场景。

触发方式

# 在 Claude Code 中直接输入
/listenhub-tts 把这段文字转成语音

# 或使用触发词
语音合成：将 README.md 朗读出来
生成音频：用晓曼的声音读这篇文章

三种合成模式

音色选择

前置要求

/insight-diagram 为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型，渲染为 HTML+SVG 并保存到 docs/ 目录。

触发方式

# 在 Claude Code 中直接输入
/insight-diagram

# 或使用触发词
生成架构图：分析项目结构并生成架构图
画流程图：为这个模块绘制调用流程图
生成UML图：生成类图和时序图

支持的图表类型

共支持 17 种图表类型，分为结构性图形和行为性图形两大类：

结构性图形（静态）

行为性图形（动态）

★ 标注为最常用的图表类型。默认推荐组合：架构图 + 序列图 + 流程图。

工作流程

• 分析项目代码库，识别关键组件和依赖关系
• 展示可选的图表类型列表，用户选择需要生成的类型
• 使用 architecture-diagram skill 渲染为 HTML+SVG
• 保存输出到 docs/ 目录

/refactor 基于 Martin Fowler《重构》第 2 版的完整目录，提供专家级代码重构能力。通过识别代码坏味道并应用经过验证的重构手法，在不改变外部行为的前提下改善代码的可维护性、可读性和结构。

触发方式

# 在 Claude Code 中直接输入
/refactor

# 或使用触发词
重构：重构 UserManager 类，它太大了
code smell：这个函数有 Feature Envy，修复它
extract method：把这个长方法拆分成更小的函数

代码坏味道目录

共识别 22 种代码坏味道，按五大类别组织：

重构手法目录

40+ 种重构手法，分 6 大类，每种附带机械步骤和对比示例：

安全协议

• 准备阶段：编写特征测试 → 提交当前状态 → 创建重构分支
• 每一步：一次仅做一处变更 → 编译通过 → 所有测试通过 → 提交
• 验证阶段：全部测试通过 → 手动冒烟测试 → 自审 diff → 最终提交
• 铁律：不改变外部行为，不混杂功能变更，每一步都有测试保障

语言专属指南

/modern-go 自动将 Go 代码升级为现代写法和 API，类似 go fix。扫描 go.mod 检测 Go 版本，对 Go 源文件批量应用版本适配的转换规则，覆盖从 Go 1.0 到 1.26+ 的 35+ 条规则。

触发方式

# 在 Claude Code 中直接输入
/modern-go

# 或使用触发词
modernize：现代化改造这个项目的 Go 代码
升级Go代码：更新到 Go 1.22 的写法
gofix：扫描 pkg/ 目录并应用转换

工作流程

• 读取 go.mod 获取 Go 版本
• 在目标范围内（指定文件/目录/整个项目）查找 .go 文件
• 逐个文件扫描 "Before" 模式，应用所有版本 ≤ 项目版本的转换
• 每条转换附带简洁对照表和代码示例（before/after）
• 编辑完成后运行 goimports -w 清理 import
• 输出改造报告：文件数、应用转换数、已跳过的规则

转换规则目录（按 Go 版本）

安全规则

• omitzero 仅建议不自动应用（可能改变 JSON 序列化行为）
• SplitSeq 仅在循环体不需要索引或完整切片时应用
• strings.Builder 仅当拼接发生在循环内时应用
• 每次转换若需要新 import，自动添加并运行 goimports 清理

/note-it 在代码实现和审查完成后，为当前 Issue 生成一份结构化实现笔记，记录设计决策、偏离、权衡和待确认问题，输出为 HTML 格式保存到 docs/ 目录。

触发方式

# 在 Claude Code 中直接输入
/note-it

# 或使用触发词
记录笔记：为 Issue #42 生成实现笔记
implementation notes：记录本次实现的决策和偏离

笔记内容

输出

• 自动检测 Issue 编号（从分支名或 /goal 上下文）
• 生成 HTML 格式笔记文件
• 保存到 docs/issue#XXXX.html
• 如已存在该 Issue 笔记，提示是否追加或覆盖

定位

/note-it 位于工作流中 /review-it 和 /ship-it 之间，作为提交前最终检查点——确保实现意图被完整记录，方便后续维护者理解代码背后的决策逻辑。

/code-to-spec 分析一个既有项目的代码、配置、测试和结构，反向生成一份完整的 SPEC（规格）文档。输出可用于重建项目、新人入职或对比实际实现与预期设计。

触发方式

# 在 Claude Code 中直接输入
/code-to-spec

# 或使用触发词
生成设计文档：分析当前项目并生成 SPEC
reverse spec：逆向工程这个项目的规格
生成规格文档：为 src/ 目录生成技术规格

分析深度

SPEC 文档结构（12 章节）

工作流程

• 确认分析范围（整个仓库 / 指定目录 / 特定方面）和深度级别
• 扫描项目：识别入口点、目录结构、依赖图、API 路由、数据模型
• 提取业务规则：从校验函数、Guard Clauses、测试断言中推导
• 合成生成 12 章节 SPEC 文档
• 展示供审阅，根据反馈迭代调整
• 保存到 docs/SPEC.md 或用户指定位置

/smell 分析代码库中的架构反模式、代码坏味道和算法复杂度热点。输出详细的 Markdown 报告，包含严重级别、证据和重构路线图。

如何调用

# 在 Claude Code 中直接输入
/smell

# 或使用触发短语
代码坏味道检测：找出代码坏味道
架构审计：检测架构反模式
复杂度扫描：分析代码复杂度

检测类别（8 大类，50+ 坏味道）

报告结构

• 执行摘要与整体健康评估
• 检测到的架构风格 vs. 期望风格
• 按严重级别分类的发现（严重 / 警告 / 建议）
• 依赖图分析与模块健康评分卡
• 8 大类坏味道分布统计
• 重构路线图（立即可做 / 短期 / 长期）

Goal Workflow 的技能可在多个 AI Coding Agent 中使用：

Issue 创建平台

Q: 必须按顺序使用所有步骤吗？

不必。每个 Skill 都是独立的，可以单独使用。比如你已经有 Issue 了，可以直接从 /goal 开始；代码已经写好，可以直接用 /review-it 审查。但完整走一遍流程能获得最好的效果。

Q: /goal 是哪里来的？为什么没有在 skills 目录中？

/goal 是 Claude Code 的内置功能，不需要额外安装。本工作流的 /prd 生成的 Issue 格式与 /goal 的期望输入完全匹配。

Q: 可以在非 GitHub 项目中使用吗？

可以。/prd 支持将 Issue 保存为本地 Markdown 文件或创建到百度 iCafe。/review-it 只需要本地 git 仓库。/ship-it 目前依赖 GitHub（gh CLI）。

Q: /review-it 和手动 code review 的区别？

/review-it 是自动化的自查（self-review），在提交前发现明显问题。它不替代团队 code review，而是在 PR 创建前提升代码质量，减少 reviewer 需要指出的低级问题。

Q: Issue 粒度应该多大？

每个 Issue 应该是一个 Agent 在单次会话中可以完成的工作量——通常是 1-3 个文件的变更，有明确的验收标准。/prd 会自动按这个粒度拆解，但你可以在确认前调整。

Q: 如何在 Codex 中使用？

通过 npx skills add 安装时选择 -a codex。在 Codex 中使用 codex --goal "..." 替代 /goal，/review-it 在各 Agent 中通用。

Q: /prd-to-spec 是必需的吗？什么时候可以跳过？

不是必需的。/prd-to-spec 是一个可选步骤。PRD 说的是"做什么"，SPEC 说的是"怎么做"。区别在于：AI agent 在执行 /goal 时本身就具备"怎么做"的能力——它会自动分析代码库、理解现有架构和约定、在实现过程中做出合理的技术决策。换句话说，AI agent 就是一个活的 SPEC 引擎，不需要在纸面上先画一遍。

大多数中小型功能只靠 PRD → /goal 就能很好地跑通。以下场景才值得多写一步 /prd-to-spec：

• 多人/多 agent 并行开发——需要共享技术约定，避免各自按不同方式实现
• 跨多个服务/模块的改动——架构决策影响面大，返工成本高
• 后期需要维护文档——需要一份正式的技术参考供团队查阅
• 合规/评审要求——组织流程强制要求设计文档
• PRD 写得太模糊——SPEC 可以用技术细节补足，降低 agent 的理解偏差

如果你的项目是单人开发、功能边界清晰、agent 已经能稳定理解项目结构的，跳过 /prd-to-spec 完全合理，甚至更高效。把它当成工具包里的可选武器，需要时再拿出来。

Q: /humanize-it 的 42 次迭代上限是怎么来的？

数字 42 并非迭代次数有特殊要求，而是向经典科幻小说《银河系漫游指南》（The Hitchhiker's Guide to the Galaxy）致敬的极客文化。在该书中，超级计算机经过 750 万年计算，得出了"生命、宇宙及一切的终极答案"就是 42。在编程界，这个数字非常流行，原因有二：

• 致敬科幻：作为程序员群体中广为人知的彩蛋，代表了终极的解答。
• ASCII 巧合：在 ASCII 编码中，42 对应的是星号 *。在计算机科学中，* 经常被用作通配符，表示"任何事物"或"一切皆有可能"。因此，"终极答案是 42（*）"刚好契合了"任何你想要的答案"这一哲学梗。

实际使用中，大多数文档在 3-5 轮迭代后就能达标。迭代的核心是智能切换策略——当一种改写方式效果停滞时，自动换用另一种，三种策略组合使用可以互补覆盖不同类型的 AI 痕迹。

Q: /humanize-it 支持英文文档吗？

目前 /humanize-it 的三个子 skill 主要针对中文文本优化。humanizer-zh 的模式检测规则对英文也部分适用，但改写效果以中文为最佳。

Q: /listenhub-tts 如何获取 API Key？

前往 listenhub.ai 注册并获取 API Key，然后设置为环境变量：export LISTENHUB_API_KEY=your_key。

Q: /listenhub-tts 支持哪些语言？

ListenHub 支持中文（zh）和英文（en）等多种语言的音色。调用音色列表 API 时可通过 ?language=zh 参数筛选。

Q: /insight-diagram 支持哪些图表类型？

/insight-diagram 支持 17 种图表类型，包括系统架构图、14 种 UML 图（类图、对象图、组件图、部署图、包图、复合结构图、剖面图、用例图、活动图、状态机图、序列图、通信图、定时图、交互概览图）、流程图和泳道图。输出为 HTML+SVG 格式，保存到 docs/ 目录。适用于任何软件项目。