goal-crafter

Goal Crafter

将模糊的任务转化为可验证的目标，让 AI Agent 能够无人值守地执行。

首要原则：没有可检查完成标准的目标，只是一个愿望。Agent 必须能够在不询问人类的情况下回答“我完成了吗？”

调用模式

遵循流程前，请先选择模式：

• 独立模式：用户提出模糊任务或直接要求制定目标。运行阶段 1，并一次只问一个问题来明确任务。
• 编译交接模式：已批准的规划证据中已包含答案。**不要再次询问用户。**仅应用此技能的可验证性规则和目标运行环境格式。证据可以来自对话、规范、问题单、文档或其他技能。

在编译交接模式下，如果来源中确实缺少必需的产品决策或完成条件，请说明来源尚未达到 Agent 可用状态，并指出缺少的证据。不要在目标编译过程中重新开始规划访谈。

流程

阶段 1 — 明确任务

仅在独立模式下运行此阶段。在编译交接模式下，从上游证据中提取五项答案，不要提问。

请按以下形式，一次只问一个问题（仅限独立模式访谈——编译交接模式中不要使用表情符号）：

❓ **QN** - **<short title>**
<body>

💡 <your recommended answer, when you have one>

按顺序询问以下五项：

1. Agent 具体要做什么？ 用一句话描述任务。如果描述含糊（“优化代码”“改进 UI”），请进一步询问细节。

2. 任务在哪个环境中运行？ 是哪个项目 / 仓库 / 工作区？是否有指定分支或文件区域？

3. 怎样才算完成？ 这是最重要的问题。请尽量明确可观测、可由机器检查的条件：

   ❌ 含糊（不佳）	✅ 可验证（良好）
   “提高代码质量”	"tsc --noEmit 0 errors + eslint 0 warnings"
   “让 UI 更好看”	“页面在 375px / 768px / 1440px 三个断点下视觉一致，无溢出”
   “修复所有 bug”	"npm test 全部通过，且 git diff 只包含修复相关改动"
   “写好文档”	“README.md 包含安装/使用/API 三个章节，每个章节都有代码示例”
   “优化性能”	“Lighthouse Performance 分数 ≥ 90，LCP < 2.5s”

4. 有哪些约束？ 是否不能修改某些文件？是否必须使用特定工具？是否有预算或时间限制？

5. 使用什么 Agent / 运行环境？ Claude Code (/goal)、Codex（Automations）、Pi，还是通用格式？

当你已获得全部 5 项答案时，阶段 1 即告完成。如果用户无法回答第 3 项，请协助其构思可验证条件——这是最常见的失败点。

阶段 2 — 起草目标

使用目标 Agent 的格式编写目标。请遵循以下规则：

以下三种格式是本技能专门为最常用的运行环境维护的格式。它们是当前快照，而非标准：如果目标运行环境的文档规定了不同格式，请遵循该运行环境的要求，并将此处的内容视为后备格式。未列出的运行环境均使用通用格式块。

适用于 Claude Code /goal：

Goal: [one-line task description]

Completion criteria:
- [ ] [checkable condition 1]
- [ ] [checkable condition 2]
- [ ] [checkable condition 3]

Constraints:
- [file/area restrictions]
- [tool/approach restrictions]
- [budget/time limits]

Context:
- [key files to read first]
- [relevant docs/specs]
- [related issues/PRs]

适用于 Codex Automations：

Task: [one-line description]
Frequency: [once / on push / on schedule]
Verification: [checkable condition]
Workspace: [project path]

适用于 Pi / 通用格式：

任务：[一句话]
完成标准：
- [ ] [可验证条件 1]
- [ ] [可验证条件 2]
限制：[约束条件]

阶段 3 — 验证目标

在给出最终目标之前，进行自检：

• Agent 能否阅读完成标准，并明确判断“已完成”还是“未完成”？
• 每项标准是否都能客观观察，无需人类判断？（不要使用“看起来不错”“感觉合适”之类的表述）
• 约束是否足够具体，能够防止范围蔓延？
• 上下文是否充分，能让 Agent 无需询问“在哪里”或“怎么做”就开始工作？

如果独立模式下有任何一项检查未通过，请返回阶段 1，要求用户澄清相应内容。在编译交接模式下，请指出来源尚未达到 Agent 可用状态，并列出缺少的证据，而不是提出新的规划问题。

阶段 4 — 交付

在独立模式下，给出最终目标，并以此结束：

🎯 把这个 goal 粘贴到 [agent 名称] 里，它就会自己跑到完成。如果中途卡住，告诉我哪条完成标准没达到，我帮你调。

在编译交接模式下，由上游技能负责交付包装。请按要求的运行环境格式返回目标，不要添加这句独立模式结尾语。

---

示例

下面两个示例里的仓库名、目录结构和文件路径都是占位符，不代表任何真实项目的约定。真正产出的目标必须写目标仓库当前的真实路径，不要照抄这里的形状。

示例 1：代码审查自动化

用户：“帮我写个目标，自动审查 PR”

澄清后：

• 任务：审查当前分支相对于 main 的所有改动
• 位置：当前工作仓库
• 完成标准：输出一份审查报告，列出所有 P0/P1 问题，每个问题标注文件和行号
• 约束：只读，不改文件
• Agent：Claude Code

输出：

Goal: 审查当前分支相对于 origin/main 的 diff

Completion criteria:
- [ ] 已读取完整的 git diff
- [ ] 已检查安全漏洞（SQL 注入、XSS、密钥泄露）
- [ ] 已检查逻辑错误（空指针、竞态条件、边界条件）
- [ ] 已检查代码规范（命名、结构、重复代码）
- [ ] 输出审查报告，每个问题标注：严重度 + 文件:行号 + 问题描述 + 修复建议

Constraints:
- 只读，不修改任何文件
- 只关注当前分支的改动，不审查已有代码

Context:
- 项目背景：<一句话说明这个仓库是什么>
- 设计 spec：<仓库内的设计文档>

示例 2：UI 重新设计

用户：“帮我写个目标，重做这个页面”

澄清后：

• 任务：用 shadcn 组件库重做目标页面
• 完成标准：页面在 3 个断点下视觉一致，所有交互有 hover/focus/active 状态，通过 tsc 类型检查
• 约束：不改变现有 API 接口，使用项目已有的 Tailwind 配置
• Agent：Claude Code

输出：

Goal: 用 shadcn/ui 组件库重做目标页面

Completion criteria:
- [ ] 所有组件替换为 shadcn/ui 等价组件
- [ ] 页面在 375px / 768px / 1440px 断点下无溢出、无错位
- [ ] 所有可交互元素有 hover、focus、active 状态
- [ ] `tsc --noEmit` 0 errors
- [ ] 页面加载后无 console error

Constraints:
- 不修改 API 客户端目录下的任何文件
- 使用项目已有的 Tailwind 主题配置
- 不引入新的 npm 依赖（shadcn 除外）

Context:
- 当前页面：<页面组件文件>
- UI 组件：<组件库入口文件>
- 样式：<全局样式入口>

---

特殊规则

• 独立模式下绝不能跳过阶段 1 的第 3 个问题。 如果用户无法定义“完成”，目标就会失败。请帮助他们集思广益。
• 编译交接模式下绝不重复访谈。 已批准的证据已包含澄清结果和产品决策；缺少证据意味着源材料尚未达到 Agent 可用状态。
• 每个复选框只能包含一个可验证条件。 不要在一行中合并多个条件。
• 约束是你的帮手。 它们可以避免 Agent“优化”无关文件或引入破坏性变更。
• **如果任务对于一个目标来说太大，**建议拆分成 2-3 个较小的目标，并明确交接内容。
• 对于研究/分析类目标（不修改代码），完成标准是“输出一份包含特定章节的报告”。