manifest-dev-help

manifest-dev-help

人们来到这里，询问任何他们不了解的 manifest-dev 内容，以及它为何如此运作。回答每个问题时，请说明该部分是什么，以及它为何存在。每个答案都应尽量符合 ASD-STE100：句子简短，每句话只讲一个主题，并使用含义明确的简单词语。

如何回答

1. 当问题提到某个术语，或询问某个部分、文件或行为时，请阅读 references/GLOSSARY.md。
2. 当用户询问所有术语时，请完整提供 references/GLOSSARY.md。
3. 当用户没有提出问题时，请提供 manifest-dev 的用途、工作流 和 自主性阶梯。
4. 当用户指出某项内容时，请先阅读它：Manifest、日志、拉取请求或文件。
5. 当问题涉及用户的项目时，也请阅读其 Project Surfaces。
6. 如果此技能没有说明答案或原因，请阅读负责该行为的技能。
7. 在此技能所在文件夹旁边的文件夹中查找该技能：阅读其 SKILL.md 和 references/ 文件夹。 manifest-dev-tools 插件的技能位于该插件的 skills/ 文件夹中。该插件与此技能分开安装。请按技能名称搜索其文件夹。
8. 只回答问题。
9. 说明每个部分的原因，而不只是它是什么。
10. 当答案来自此技能以外的文件时，请注明该文件。
11. 如果没有文件提供答案，请如实说明，不要猜测。

manifest-dev 的用途

Agent 现在几乎可以编写所有代码，但项目仍会偏离方向。每次会话都必须重新弄清项目的用途、下一步要做什么，以及“完成”的标准。于是，Agent 的速度会带来超出人们审查能力的工作量。

manifest-dev 将这三项内容保存在项目中，而不是某个人的脑海里。Agent 会读取这些内容，依据它们开展工作，并在宣告完成前检查结果。它的承诺是：你把一项复杂任务交给 Agent，并足够信任结果，从而只需少量审查就能发布。几周后，项目仍然清楚自己的用途、下一步工作，以及“完成”的标准。与之前相比，代码也更容易正确修改。

你可以在指定的限制范围内分配项目成果。/orchestrate 可以调查、规划工作、交付成果并阅读结果。你可以保留自己想做的决策。可靠的持续运行仍是一个目标；完成一项任务并不能证明这一目标已经实现。

manifest-dev 面向希望获得可信结果的开发者。他们愿意在开始时投入更多 token 和工作，以换取这些结果。他们可以独自工作，也可以在任何规模的团队中工作，包括同事不使用 manifest-dev 的代码库。它不适合只追求最快或最便宜结果的人。

问题	答案所在位置	有效时长
这个项目的用途是什么？	North Star，项目中的一个文件	直到授权裁定对其作出更改
接下来要做什么？	Ticket，位于你的跟踪工具或文件中	直到该工作完成
这项工作的“完成”标准是什么？	当这项工作需要时，使用一份有明确范围的 Manifest	一次运行

工作流

1. 使用 /figure-out <topic> 在修改之前了解问题。
2. 使用 /define 编写一份 Manifest：明确什么样的结果才算完成。
3. 使用 /do <manifest-path> 开展工作，并为每个关卡提供证据。

/auto 会连续完成这三个步骤，中间不会暂停。每项技能也可以单独使用，而且没有任何项目必须遵循这一流程。你可以从 Read 直接进入 /ticket-up，也可以直接分配任务。如果你和 Agent 对问题尚未达成共识，/define 会先启动 /figure-out。若要逐轮改进现有产物，使其逐步接近目标，请使用 tools 插件中的 /hillclimb。它会运行相同的三个步骤。

如果你的工具可以将问题显示为选项列表，/figure-out 和 /define 就会以这种方式向你提问。第一个选项是它们推荐的答案。你也可以用自己的话回答。

/do 会假定你暂时离开。它会代为作出已委派的决定，并向你汇报。你保留的决定仍需等待你处理。在 /do 运行期间发送的消息会修改 Manifest，运行也会继续。只有在每个关卡都有证据，或必须由人来采取行动时，运行才会停止。

如果工作进入拉取请求，其描述会展示变更的实际效果。开头会说明变更内容及原因、运行如何证明变更有效、作出的决定，以及尚未偿还的 Debt；还会列出运行过程中解决的问题。一个简短示例会说明变更前后你做了什么、得到了什么。截图则会展示可见的变更。

自主性阶梯

你可以在五个层级使用 manifest-dev。每个层级都可以独立于更高层级运行。团队中的其他人不必使用任何层级。选择适合项目的层级即可。

层级	你要做什么	你会得到什么	代价
1. 单项技能	单独使用一项技能，例如用 /figure-out 处理一个问题。	获得更好的答案或审查，无需设置。	对项目没有任何影响。
2. 单项工作	使用 /figure-out、/define 和 /do，或使用 /auto。	每个关卡都有证据的结果。	开始时会多花一些令牌和时间。Manifest 及其日志保留在仓库之外。
3. 项目上下文	使用一次 /setup-project。	每次会话都会基于项目的方向、术语、决定和检查开始。	仓库中会增加团队可见的文件。
4. 共享队列	使用 /ticket-up 编写工作，并用 /next-ticket 领取。	后续工作存放在工作区中，而非某个人的脑海里。	需要一个 Ticket Store：GitHub Issues、文件或你自己的追踪系统。
5. 协调	使用队列或明确的目标启动 /orchestrate。批准其计划，或在你设定的限制内使用 --autonomous。	独立的调查和交付任务会作为 Tickets 运行。结果会指导下一步行动。保留的决定和尚缺的证据都会清晰可见。	需要与任务相符的权限和证据来源。只有在你希望自动继续时，才需要现有的宿主唤醒机制。

逐步提升层级：

1. 先使用当前层级，直到你信任其结果。
2. 如果当前层级无法满足需求，就增加下一层级。
3. 只有在所有必要决定都已敲定或委派，且没有待你接受的事项或缺失的访问权限时，才授予 Auto。

任务分配与权限

任务分配说明要做什么。委派则说明执行者在该活动中可以作出哪些决定。长期委派不会启动任何工作，模式标志也不会授予更广泛的权限。

使用 /setup-project 在项目指令中记录所需的调整。个人规则请保留在私有指令中。设置流程会先显示拟定的文本，再保存新的选择；它不会启动任何操作。

例如，你可以委派视觉方向的决定，但保留对渲染结果的验收权。执行者可以构建并提出建议，然后在等待验收处暂停。批准仅适用于该产物及其版本；若发生实质性变更，则需要再次验收。

其他技能

技能	用途
/setup-project	为项目设定北极星、术语表和决策记录规范，并添加验证工具，除非你选择退出。再次运行可查找遗漏。
/ticket-up	将工作作为 Ticket 写入你的 Ticket Store。
/next-ticket	选择下一个 Ticket、认领它，并查看它为何排在首位。
/run-ticket	调查问题或交付已成形的工作，并将结果和进度记录在同一个 Ticket 上。
/orchestrate	协调队列或指定的成果，并提供状态页和待你处理的事项列表。
/figure-out-team	在 Slack 频道或线程中与团队一起执行 /figure-out 的工作。
/review-code	从一个质量维度审查变更。Manifest 门禁会使用它。
/audit-state-machines	找出代码库中的每个状态机，用模型逐一检查，并获取它发现的 Bug。它不会更改代码。
/create-principles-skill	创建或更新项目技能，记录团队希望如何完成某一领域的工作，例如设计。它会利用团队已有的表述。
/review-writing	根据风格规范审查文本。
/design	为页面、应用、文档或其他视觉作品获取设计方向。
/review-design	在设计所针对的媒介中审查设计。
/check-pr	检查拉取请求是否已准备好合并。它不会合并。
/manifest-dev-help	阅读本指南，或向它提问。

工具插件

manifest-dev-tools 插件会添加以下技能。在一次只能安装一个插件的宿主环境中，也请安装此插件。未安装时，无法使用这些技能。

技能	用途
/babysit-pr	推进你尚未关闭的拉取请求，处理 CI、审查评论和冲突，直到它可以合并。它不会合并。
/review-pr	审查拉取请求，并以你的账号发表评论。
/walk-pr	与 Agent 一起逐部分查看拉取请求或大型差异。
/hillclimb	朝着目标逐轮改进现有成果。
/prompt-engineering	编写、修改或讨论提示词、技能或 Agent。
/review-prompt	审查提示词并获取发现的问题。它不会更改文件。
/write-goal	编写一条简短目标，说明“完成”的含义，以便粘贴到目标字段中。
/handoff	为新会话或其他 Agent 提供继续工作所需的上下文。
/teach-me	一步一步了解某项变更、拉取请求或主题。
/eli5	用图片获取某个主题的简单易懂解释。

/review-pr 会调用三个你不会直接使用的技能：review-pr-holistic、 review-pr-judgment 和 review-pr-thread-verify。

本指南将每个技能写作 /name。你的宿主环境可能使用不同的前缀，例如 $name 或 /skill:name。

各部分之间的关系

• 一个 Manifest 包含一个或多个 Deliverable。每个 Deliverable 包含一个或多个 Acceptance Criterion。
• Global Invariants 适用于所有 Deliverable。Process Guidance 仅为建议，不具约束力。
• 每个 Acceptance Criterion 和 Global Invariant 都是一道关卡。关卡分为 Judgment Gate 或 Deterministic Gate。
• /do 通过提供证据让每道关卡都通过。关卡未通过时，/do 会修复工作成果并重新检查关卡。
• 一个项目会保留 North Star、术语表和决策记录，也可以保留验证测试框架。/setup-project 会安装这些内容，常规运行会使它们保持最新。
• 验证测试框架会为每项功能、技能、文档检查或评估套件配置一个 Recipe。它还会为整个项目的检查（例如 lint 和测试）配置一个 Recipe。/do 会运行变更涉及的 Recipe。项目可以选择不使用测试框架，改用自己的检查；此时，/do 会使用这些检查。
• 一个 Ticket 包含一个工作单元。/ticket-up 编写 Ticket，/next-ticket 选择 Ticket，/run-ticket 执行 Ticket。/orchestrate 会运行多个 Ticket 并将其合并。
• 运行过程中纠正错误时，会添加一条 Lock。运行过程中发现但无法在拉取请求中修复的问题，则记为 Debt。之后修改到相关代码的下一次运行会提出修复 Debt。

这样设计的原因

• 工作开始前就要写明“完成”的标准。Agent 无法根据一个不存在的目标来检查结果。
• 关卡只有在有证据时才算通过。声称“完成”的摘要可能有误。
• /do 的工作方式就像你不在场一样，因此它可以在没有你的情况下完成任务。它会汇报自己替你做出的每项决定。
• 每次纠正都会变成一项检查，避免再次犯同样的错误。
• 方向、术语和决策都保存在代码库中。每次新会话都会以这些内容为起点，而不是从零开始。
• 有成本的检查会先询问，免费的检查则会经常运行。运行时间本身不算成本。
• 每个层级都可以独立工作。因此，你可以在一个不使用 manifest-dev 的团队中开始使用。

良好实践

• 从真实问题入手，使用 /figure-out。先让它阅读代码，再让它向你提问。
• 在 /do 开始前阅读 Outcome 和关卡。确认哪些内容不可变，以及 Agent 可以修改哪些内容。
• 让 /do 发现并修复小问题，不要因此打断它。
• 通过消息向 /do 说明方向变更，使其记录到 Manifest 中。运行期间不要自己修改代码。
• 相信证据，而不是摘要。
• 在运行有成本的检查前先同意。带有 ask-first 标记的 Recipe 会消耗资金、配额，或占用共享系统的资源。
• 运行一次 /setup-project 来安装 Project Surfaces。
• 让每次纠正都变成一项检查，确保之后每个人遇到同样的问题时都会失败。
• 阅读每个拉取请求中的“Debt left”部分。下次修改涉及相关代码时，修复 Debt。
• 预计开始阶段会消耗更多令牌，也需要投入更多工作。作为回报，你得到的是可以检查的结果，而不是只能相信的结果。