shape · diff
git:20260910.4546a3c to git:20260923.8eb4b09
38 added, 22 removed. Audit A to A.
---
name: shape
- description: 在方向、任务承诺或关键系统前提尚不可信，用户预期可能与真实对象不符，或新证据推翻现有方向时使用。显式 Shape 新 Task 建立或修订 `context.md`；明确只讨论或查看、宿主自动路由但未启动 Task、方向清楚的低风险行动不触发落盘。
+ description: 用户要求 Shape、输入 /shape，或想先对齐方案、由自己做关键决定再动手时使用。先调查现实，摆出选项和代价，逐轮只问现在能决定的问题，用户做出关键决定后再进入实现。用户没有提出时不用，即使目标还不确定，也只建议用户用 Shape。
---
+
# shape
- ## 先让领地说话，再决定形状
+ Shape 是规划里最深的一档。目标或关键前提还靠不住时，先让现实把事实、矛盾、可选方案和代价摆出来，再收敛方向。现实指代码、运行现场、数据和用户的实际使用；用户的描述和已有文档是线索，不能代替它们。
- 把 Shape 当作一次模拟退火：先提高探索温度，接触真实代码、运行现场、用户行为和约束，让事实、矛盾、可能性与代价浮出来；结论不再随合理调查实质变化时再降温收敛。用户描述和已有文档是意图与线索，不能替代真实对象。
+ ## 调查：事实自己查，决定交给用户
- 能自行查明的事实先调查。价值、偏好、代价接受、范围和授权由用户裁决；证据推翻原方向时明确说明影响，不替用户悄悄改写承诺。调查可以看宽，执行范围不能随之静默扩大。
+ 能从代码、运行现场、文档和工具查明的事实，自己查清，不拿去问用户。价值、偏好、范围、能接受的风险和授权由用户决定。
- 实现路径在当前请求与 `AGENTS.md` 的边界内自行收敛。发现超出承诺的范围、风险或长期成本时，把事实与代价交给用户；技术必要性不能反向创造授权。
+ 开始时放开看：多看几种可能，不急着定形，也不要让最先发现的问题框住后面的调查。继续合理调查已经不会改变结论时，再开始收敛。调查可以看得宽，做事的范围不跟着扩大。证据推翻了原来的方向时，直接说出影响，不悄悄改写用户的目标。
- ## 建立可信 Context
+ ## 提问：只问现在能决定的
- 处理 Context 前先判断这次请求是否真正启动或继续 Task：
+ 把未决事项看成有先后依赖的决策树。前置决定还没定的分支先不问；现在就能决定、又会改变方向的问题，放在同一轮问。每个问题讲清背景，给出你的推荐和各个选项的代价，默认用户没读过相关代码。
- - 明确只讨论或查看时，无论是否已有 Task，都不创建也不修改 Context。宿主自动路由到 Shape、但尚未启动 Task 时同样只在对话中处理。
- - 用户显式用 Shape 启动新 Task 时，在任务工作区根目录创建 `context.md`。忠实保存 Original Request 与已查明的 Reality Coordinates，依据用户请求和调查形成 Goal、Scope、Non-goals 与 Acceptance Evidence；尚不能确定的内容写 `unresolved`。
- - 对已有 Task 使用 Shape 时，先读取同一份 `context.md` 和 Current Artifacts，再只更新受影响内容。事实变化可以更新 Reality Coordinates；承诺变化必须先让用户看见变化与代价，并取得用户决定后再修订；没有受影响内容时不写。
+ 用户回答后，重新看哪些问题因此消失、哪些新出现，不按旧的问题清单往下走。用户说"不知道"不等于同意，把它记成一个明确的未知，并说明它影响什么。
- 目的地或责任范围已经成为另一项工作时新建 Task，不覆盖原 Task；同一目的下由新证据推动的修正继续更新当前 Task。
+ ## 收敛：让下一步不用猜
- Context 生命周期、Current Artifacts 权限和可选产物见 [产物与权威来源](references/artifacts.md)，固定结构见 [Context Demo](references/templates/context.demo.md)。创建其他持久产物前，按该 reference 选择并读取对应 Demo。
+ 方向可以承诺时，这几件事都能写成具体的句子：目标（完成后能观察到什么）、范围、不做什么、验收标准，以及还没决定的问题。把它们简短地给用户看；关键决定由用户做出后进入实现，按工作模式选的执行档继续。不依赖未决问题的工作可以先做。
- ## 自主展开候选
+ 只要实现时还得猜需求、系统设计、公共契约或迁移路线，就把对应的部分补完。局部、结构清楚的任务不为形式写文档。
- 用户没有在 Shape 开始时参与，不等于把事实调查或方案探索停在等待提问。先从真实对象补齐能够自行查明的部分；默认由主 Shape 沿事实单路收敛，不自行增加候选代理。
+ ## 保存：shape.md
- 用户以 `--ponytail`、`--bold` 或 `--contrast` 调用 Shape 时，把参数从 Original Request 中剥离，再读取 [自主候选探索](references/contrastive-exploration.md)。主 Shape 先调查并冻结共享 brief：`--ponytail` 只增加最小化视角，`--bold` 只增加扩展探索视角，`--contrast` 同时运行两个相互隔离的视角。显式选择的视角即使判断方向已经足够，也只能以“无需独立候选”结束，不能被主 Shape 提前跳过；`--contrast` 在没有并行子代理能力时可以顺序执行，但后一个视角不能看到前一个的答案。三个参数互斥；同时出现时先请用户选择，不猜测优先级。
+ Shape 的产出是一份 `shape.md`，写到 `.agents/tasks/<日期>-<主题>/shape.md`，调查开始后就建立，随调查和用户的决定持续更新。只有用户明确说只想讨论时，才只在对话里进行。这个任务后续的测试报告等文件也放在同一个目录，实现、test 和 review 都以它为准。
- 子代理负责扩大证据和候选空间，不拥有综合裁决、Context、任务承诺或用户授权。主代理抽查承重出处、处理冲突，只向用户交付一份有推荐、有代价、有未决事项的当前提案；不能用多数票、折中方案或子代理共识替代判断。
+ ```markdown
+ # <任务>
- ## 收敛到下游不用猜
+ ## 原始请求
+ 用户的原话，或不增加意图的整理，注明来源。
- 方向成立时，关键事实和代价已经清楚，目标、边界、不能破坏的关系与验收证据足以让下一位继续。具体实现路径仍可由执行者根据现场调整；新证据推翻关键前提时，重新 Shape 受影响的承诺和专业产物。
+ ## 现状
+ 已查明的代码、运行状态、环境和约束。没查的写"未查"，查过确认不存在的才写"无"。
- 进入 Dev 前，把 Goal、Scope、Non-goals 与 Acceptance Evidence 简洁地展示给用户，使实施范围与完成标准可审阅。
+ ## 目标
+ 完成后能观察到什么。
- Shape 不停在一句建议上。只要下游仍会被迫猜需求、系统模型、公共契约、迁移或执行路线，就继续完成其中必要部分；局部且结构清楚的任务可以直接交给 Dev，不为形式制造文档套件。
+ ## 范围
+ 做什么，不做什么。
- ## 边界
+ ## 验收标准
+ 要观察到的结果，以及证明它需要的证据。
- Shape 负责方向、任务承诺和为其成立所需的 Diagnosis、Requirements、Design、Contract、Migration 与 Plan。它不实现代码，不承担完整 Test，也不把自己的论证当作独立 Review；调查中的复现和验证只用于让当前判断有事实基础。
+ ## 决定
+ 用户已经做出的决定和理由；仍未决定的问题，以及它影响什么。
+
+ ## 方案
+ 实现时需要、上面几节写不下的内容，例如根因诊断、需求细节、设计、接口契约、迁移步骤或执行计划。只写这次用得上的部分，按需加小标题。
+ ```
+
+ 已有 shape.md 时先读它，只改受影响的部分，始终写当前结论，不在末尾追加修改记录。现状随证据直接更新；目标、范围和验收标准要变时，先让用户看到变化和代价，由用户决定后再改。目的变成另一件事时新建任务目录，不覆盖原来的。任务完成后，值得长期留下的决定按 `writing-notes` 写成 Note。
+
+ ## 候选探索（可选）
+
+ 用户在 `/shape` 后加 `--ponytail`、`--bold` 或 `--contrast` 时，先把参数从请求中去掉，再读 [候选探索](references/contrastive-exploration.md)。`--ponytail` 增加一个最小方案视角，`--bold` 增加一个扩展方案视角，`--contrast` 让两个视角互相隔离地各跑一遍再综合。子代理只负责扩大证据和候选；核实、综合和向用户提出的推荐由你负责。三个参数互斥，同时出现时请用户选。