prose-style

Prose style — Agent 报告写作规范

great_cto 的报告由忙碌的 CTO 在周二下午 3 点阅读。他们会快速浏览事实、决策以及需要他们关注的事项。营销腔和模棱两可的措辞会浪费他们的时间。

五条规则

1. 开门见山，先说结论

反例：

审阅架构文档并考虑了各种权衡因素（包括但不限于可扩展性、安全性和可维护性）后，我们认为所提方案总体上可以接受，但有些方面可能还有改进空间。

正例：

批准，但需完成 2 项修改：（a）将 PII 加密迁移到 KMS；（b）在 webhook 处理程序中添加幂等键。详情如下。

2. 提供具体证据，不用形容词

反例：“性能可以接受。” 正例：“在 50K 次请求中，p99 延迟为 142ms（k6 测试时间：2026-05-12 14:00 UTC，tests/load/<your-scenario>.js）。SLO 为 200ms。”

反例：“安全性看起来不错。” 正例：“未发现严重或高危问题。发现 2 个中危问题：src/logger.ts:14 中日志级别硬编码，src/middleware/cors.ts:8 中缺少 CORS 标头。”

3. 不要使用模棱两可的措辞

禁用词：总体上、有些、相当、大多、算是、有点、差不多、在某些情况下、经常、有时、偶尔、可能、也许、或许、可以考虑。

请用具体内容替代，或直接省略。如果确实不知道，就说“因 而无法确定”——这也是有用的信息。

4. 不要用填充性开场白

禁用：

• “本文将讨论……”
• “需要指出的是……”
• “首先，也是最重要的……”
• “归根结底……”
• “不言而喻……”

如果删掉一句话不会损失信息，就删掉它。

5. 最后一行必须是判定行

每份最终报告都必须以下列内容之一结尾：

VERDICT: APPROVED — <one-line summary>
VERDICT: DONE — <one-line summary>
VERDICT: BLOCKED reason="<specific blocker>"
VERDICT: FAIL reason="<specific failure>"

此内容由 board 的 readVerdicts() 函数解析。格式必须机器可读，不要添加修饰。

模板

审阅者报告

# REVIEW-<feature> — <reviewer name>

Reviewed: <commit-sha or file paths>
Standard: <regulation / framework you applied>

## Findings
- [Critical|High|Med|Low] <one-sentence finding>
  - location: <path:line>
  - rationale: <why this matters in this domain>
  - remediation: <specific fix>

## Verdict
VERDICT: APPROVED|BLOCKED reason="<short>"

架构 / ADR

# ARCH-<feature> | ADR-<NNN>

Date: <ISO>
Status: proposed | accepted | superseded

## Context
2-4 sentences. What problem, what constraint.

## Decision
Imperative single sentence: "Use X for Y."

## Consequences
- Positive: <bullets>
- Negative: <bullets>
- Reversible? yes/no — if no, document migration cost

## Alternatives considered
<bullets with one-line dismissal reason each>

需要通过 grep 查找的反模式

写判定行之前，请搜索草稿中的：

\b(generally|somewhat|fairly|mostly|kind of|sort of|possibly|perhaps|maybe)\b

如果命中内容位于非引用句子中，请将其改写为具体表述，或直接删除。

为什么这很重要

board 的 readVerdicts() 会解析每份报告。营销腔会破坏解析器。充斥模棱两可措辞的报告会浪费读者时间。具体信息能让 CTO 信任 Agent 的判断。