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

52 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 按需阅读:Notes 行文与去泄露自检
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/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` 里的 `实测`、来源标注与编号删掉,结论就没根了。