shape git:20260923.8eb4b09A

Immutable. This exact content never changes and is served at /api/v1/blob/5d07b699efa33715.

---
name: shape
description: 用户要求 Shape、输入 /shape，或想先对齐方案、由自己做关键决定再动手时使用。先调查现实，摆出选项和代价，逐轮只问现在能决定的问题，用户做出关键决定后再进入实现。用户没有提出时不用，即使目标还不确定，也只建议用户用 Shape。
---

# shape

Shape 是规划里最深的一档。目标或关键前提还靠不住时，先让现实把事实、矛盾、可选方案和代价摆出来，再收敛方向。现实指代码、运行现场、数据和用户的实际使用；用户的描述和已有文档是线索，不能代替它们。

## 调查：事实自己查，决定交给用户

能从代码、运行现场、文档和工具查明的事实，自己查清，不拿去问用户。价值、偏好、范围、能接受的风险和授权由用户决定。

开始时放开看：多看几种可能，不急着定形，也不要让最先发现的问题框住后面的调查。继续合理调查已经不会改变结论时，再开始收敛。调查可以看得宽，做事的范围不跟着扩大。证据推翻了原来的方向时，直接说出影响，不悄悄改写用户的目标。

## 提问：只问现在能决定的

把未决事项看成有先后依赖的决策树。前置决定还没定的分支先不问；现在就能决定、又会改变方向的问题，放在同一轮问。每个问题讲清背景，给出你的推荐和各个选项的代价，默认用户没读过相关代码。

用户回答后，重新看哪些问题因此消失、哪些新出现，不按旧的问题清单往下走。用户说"不知道"不等于同意，把它记成一个明确的未知，并说明它影响什么。

## 收敛：让下一步不用猜

方向可以承诺时，这几件事都能写成具体的句子：目标（完成后能观察到什么）、范围、不做什么、验收标准，以及还没决定的问题。把它们简短地给用户看；关键决定由用户做出后进入实现，按工作模式选的执行档继续。不依赖未决问题的工作可以先做。

只要实现时还得猜需求、系统设计、公共契约或迁移路线，就把对应的部分补完。局部、结构清楚的任务不为形式写文档。

## 保存：shape.md

Shape 的产出是一份 `shape.md`，写到 `.agents/tasks/<日期>-<主题>/shape.md`，调查开始后就建立，随调查和用户的决定持续更新。只有用户明确说只想讨论时，才只在对话里进行。这个任务后续的测试报告等文件也放在同一个目录，实现、test 和 review 都以它为准。

```markdown
# <任务>

## 原始请求
用户的原话，或不增加意图的整理，注明来源。

## 现状
已查明的代码、运行状态、环境和约束。没查的写"未查"，查过确认不存在的才写"无"。

## 目标
完成后能观察到什么。

## 范围
做什么，不做什么。

## 验收标准
要观察到的结果，以及证明它需要的证据。

## 决定
用户已经做出的决定和理由；仍未决定的问题，以及它影响什么。

## 方案
实现时需要、上面几节写不下的内容，例如根因诊断、需求细节、设计、接口契约、迁移步骤或执行计划。只写这次用得上的部分，按需加小标题。
```

已有 shape.md 时先读它，只改受影响的部分，始终写当前结论，不在末尾追加修改记录。现状随证据直接更新；目标、范围和验收标准要变时，先让用户看到变化和代价，由用户决定后再改。目的变成另一件事时新建任务目录，不覆盖原来的。任务完成后，值得长期留下的决定按 `writing-notes` 写成 Note。

## 候选探索（可选）

用户在 `/shape` 后加 `--ponytail`、`--bold` 或 `--contrast` 时，先把参数从请求中去掉，再读 [候选探索](references/contrastive-exploration.md)。`--ponytail` 增加一个最小方案视角，`--bold` 增加一个扩展方案视角，`--contrast` 让两个视角互相隔离地各跑一遍再综合。子代理只负责扩大证据和候选；核实、综合和向用户提出的推荐由你负责。三个参数互斥，同时出现时请用户选。