Files
lpt-meta/.agents/skills/write-notes-like-deepseek/references/prose-checklist.md
T
cat-shark f99e1e156d docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本
- 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根
- workspace-layout 补「共有技能单一来源」的落位与理由
- .rgignore 排除 archived 历史快照
2026-11-18 14:59:45 +08:00

4.0 KiB
Raw Blame History

按需阅读:Notes 行文与去泄露自检

提炼自 DeepSeek Harness 仓库内 dsh-prose-standard 与 dsh-trim-cot-leakage 两个 skill 的可搬运部分。写/改 Note 时对照此清单;只改代码不动 Note 时跳过。

原则

  • 只写代码说不清的:行为、失败、时序、所有权、后果与取舍。别复述代码或推导过程。
  • 不变量能编进类型、可见性或 API 报错的,别只写在笔记里。
  • 说人话,点名谁做了什么、在什么条件下、会怎样;少用“契约/边界/形态”等抽象词,除非指的就是该技术主体。
  • 一个事实只在一处讲透,其余链过去;别把同一规则抄得到处都是。
  • 写完自问:这段话不看实现能独立成立吗?不看当时聊天,现在的读者能验证吗?

写前自检(来自 prose-standard)

  • 每段保留完整命题:主体/动作、条件/时序、must/may/never、否定保证与例外、所有权/副作用/失败与后果——缺一不可。
  • implemented 用现在时,描述已落地事实;去掉计划口吻与 checklist。
  • 保留可检索的机制名与关键 must/may/never、时序与否定强调;装饰性加粗和感叹少用。
  • 一个改动内批量套用刚学到的规则到相似段落,别只改一处。

按位置查

  • Decision/Consequences:区分、抛错/拒绝、副作用、所有权、时序、取消、持久化是否说清。
  • 自由节(拓扑/契约/schema):讲清职责、依赖与非显而易见的选择及指向。
  • Alternatives/Consequences:同时写代价与收益,点名放弃的能力与重引入条件。
  • Testing/Verification:只解释“为何这样验证”(fixture/断言/真实入口的必要性),不写走读。

去泄露自检(来自 trim-cot-leakage)

对每段可疑文字问:只有当时的会话/PR/草稿可见吗?HEAD 的读者能独立验证吗? 不能则重述为仓库视角,删去会话痕迹。能解析也≠安全——可验证只代表过了去泄露这一关,README/文档等当前状态面上,可解析的变更叙事仍是变更叙事,按第 3 类路由。

常见泄露(命中即改):

  1. 死引用:(decision 7)/(audit C2)/§N/plan §1.4 — 改为对已提交 Note/文档的具名路径引用,无主则删引用、重述事实。
  2. 栈/PR 视角:后续 PR/本 PR 新增/上一 commit — 改为已落地的机制或扩展点;未做事项用 TODO 或 issue 引用,或收进 ## Deferred 小节。
  3. 变更叙事:used to/不再/旧 X/this cut/now — 改为现在时;回归用现在时反事实“若无 X 则 Y”。
  4. 评审编排:评审时否掉/reviewer 确认/v5 — 只留决定与理由,删谁说的、何时说的。
  5. 自证正确:这样转是安全的,因为… — 改为使之安全的 invariant,或直接删(代码已自明)。
  6. 过程复述:先 X 再 Y/测试走读 — 删,只留非显然契约。
  7. 含糊与占位:应该够了/probably fine — 升为 TODO/FIXME 或明确边界。
  8. 语言串台:中英混杂的工作语言片段 — 翻译或删除。

不算泄露(保留): issue 引用 #1470/TODO(name):(裸 TODO 注意正文扫描,见上条豁免)、Agent Note 与 postmortem 内的已合并 PR 引用、suppression 理由、现在时反事实、带实测值的边界、运行时 old/new 状态、已提交文档的 § 编号。

删过头警示(overcorrection traps,来自 trim-cot-leakage)

删之前先把段落里的命题列全,再对照四个"删过头"的坑:

  • 把必须/禁止的义务删成"可以这样"的背书——约束变可选。
  • 把"计划中/考虑过"的假设删成已落地事实——proposed 当 implemented。
  • 删掉一句真事实,只因为它读起来像过程叙述。
  • 丢掉承重溯源:实测:512 嵌套 ≈ 0.15s 里的 实测、来源标注与编号删掉,结论就没根了。