agentleFS
wisterx-specwisterx-spec/agent-rails/.agents/skills/proposal-review/SKILL.md

proposal-review

Skill2 starsChanged 7 months agoMITView on GitHub

在任何实现开始前,强制 Agent 将实现方案翻译成人类可判断的语言,输出方案评审文档并等待人工确认后才允许进入编码阶段

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Proposal Review Skill

目的:堵住方案层幻觉。Agent 必须在动任何代码之前,把实现思路翻译成用户能独立判断的语言。 红线:本文档未经人工确认,不允许执行 impact-analysis,不允许生成测试骨架,不允许写任何业务代码。


执行步骤

Step 1:读取上下文

按顺序读取以下内容,构建完整的决策背景:

  1. project.config.json — 获取技术栈、目录结构
  2. docs/decisions/README.md — 获取历史架构决策,本方案不得与已有决策冲突,冲突必须在 Step 2 中显式说明
  3. 需求规格说明书(来自 requirement-clarification 输出)

Step 2:生成方案评审文档

输出以下格式,所有字段必须填写,不允许留空,不允许用"暂无"敷衍:

## 方案评审文档

### 需求理解
用一句话复述:让__(谁)__能够__(做什么)__,结果是__(得到什么)__。

> 这句话必须和需求规格说明书对得上。如果对不上,停下来重新读需求。

---

### 实现思路
【用讲故事的方式描述,禁止使用代码,禁止使用技术术语】
【如果必须用术语,括号里给出大白话解释】

---

### 会动哪些东西

**现有文件**(不允许说"相关文件",必须列出具体路径):
- 修改:
- 新增:
- 确认不会动的:

**数据变化**:
- 新增字段:(字段名 / 类型 / 用途)
- 修改字段:(原来是什么 / 改成什么 / 原因)
- 删除字段:(字段名 / 影响范围)
- 无数据变化:(说明原因)

---

### 完整走一遍的例子
> 根据 task_type 选择对应格式,不允许用"示例数据"或类型描述代替。

**【新功能】用真实具体数据走完整个流程:**

**输入**:(一条真实的具体数据,例如:用户点击"提交订单",购物车里有3件商品,总价128元)

**发生了什么**:
1. (第一步,大白话)
2. (第二步,大白话)
3. ...

**输出**:(一个真实的具体结果)

**【Bug 修复】改动前后的行为对比:**

**触发条件**:(具体的操作步骤或数据条件)
**旧行为(Bug)**:(用户实际看到/遇到的问题)
**新行为(修复后)**:(修复后用户应该看到的正确结果)

**【重构】改动前后的结构对比:**

**改动前**:(当前结构的大白话描述)
**改动后**:(重构后结构的大白话描述)
**行为不变性证明**:(用户可观察的行为在改动前后完全一致的说明)

---

### 我考虑过但没选的方案

> 必须填。如果真的只有一种方案,解释为什么没有替代选项。

| 备选方案 | 不选的原因 |
|---------|-----------|
| {{方案A}} | {{原因}} |

---

### 我不确定的地方

> 必须填。填"无"时需要解释为什么这个需求完全没有不确定的地方。
> Agent 表达出不确定,比假装全部确定更有价值。

- {{不确定点1}}:{{当前的处理方式}}
- {{不确定点2}}:{{当前的处理方式}}

---

### 与现有架构决策的关系

> 对照 docs/decisions/README.md 逐条检查

- 冲突项:(列出冲突的决策编号和冲突原因,无冲突则说明为什么确认无冲突)
- 延续项:(本方案延续了哪些已有决策)

---

### 验收标准

> 用"当...时,应该..."格式,不用代码,不用技术描述

- 当 {{具体场景}} 时,应该 {{可观察的结果}}
- 当 {{边界情况}} 时,应该 {{可观察的结果}}
- 当 {{异常情况}} 时,应该 {{可观察的结果}}

Step 3:强制人工确认卡点

输出文档后,停止所有操作,显示以下提示: ─────────────────────────────────────── 方案评审文档已生成。 在继续之前,请逐字段检查: □ 需求理解:它说的是你想要的吗? □ 实现思路:你能用自己的话复述吗? □ 会动哪些东西:有没有它不该动的地方? □ 完整例子:这个例子符合你的预期吗? □ 没选的方案:它的理由你接受吗? □ 不确定的地方:它承认的不确定你能接受吗? □ 验收标准:这样验收够不够? 有任何一项不确定,回复你的问题,不要回复"继续"。 确认所有项目后,回复"确认,继续执行"。 ───────────────────────────────────────

在收到"确认,继续执行"之前,不执行任何后续操作。


约束

  • MUST 所有字段必须填写,字段为空视为文档不完整,需重新生成
  • MUST 实现思路禁止出现代码片段,禁止出现未解释的技术术语
  • MUST 完整例子必须使用具体数据,不允许用占位符或类型描述
  • MUST 文档写入 docs/proposals/ 目录,文件名格式:YYYYMMDD-{{feature-slug}}.md
  • NEVER 在人工回复"确认,继续执行"之前调用任何其他 skill 或修改任何文件
  • NEVER 在"不确定的地方"填写"无"而不提供解释
  • 若读取 docs/decisions/README.md 发现本方案与历史决策冲突,必须在文档中显式标注,不允许静默覆盖已有决策

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.