- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
4.0 KiB
4.0 KiB
按需阅读: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 类路由。
常见泄露(命中即改):
- 死引用:
(decision 7)/(audit C2)/§N/plan §1.4— 改为对已提交 Note/文档的具名路径引用,无主则删引用、重述事实。 - 栈/PR 视角:
后续 PR/本 PR 新增/上一 commit— 改为已落地的机制或扩展点;未做事项用TODO或 issue 引用,或收进## Deferred小节。 - 变更叙事:
used to/不再/旧 X/this cut/now— 改为现在时;回归用现在时反事实“若无 X 则 Y”。 - 评审编排:
评审时否掉/reviewer 确认/v5— 只留决定与理由,删谁说的、何时说的。 - 自证正确:
这样转是安全的,因为…— 改为使之安全的 invariant,或直接删(代码已自明)。 - 过程复述:
先 X 再 Y/测试走读— 删,只留非显然契约。 - 含糊与占位:
应该够了/probably fine— 升为TODO/FIXME或明确边界。 - 语言串台:中英混杂的工作语言片段 — 翻译或删除。
不算泄露(保留): issue 引用 #1470/TODO(name):(裸 TODO 注意正文扫描,见上条豁免)、Agent Note 与 postmortem 内的已合并 PR 引用、suppression 理由、现在时反事实、带实测值的边界、运行时 old/new 状态、已提交文档的 § 编号。
删过头警示(overcorrection traps,来自 trim-cot-leakage)
删之前先把段落里的命题列全,再对照四个"删过头"的坑:
- 把必须/禁止的义务删成"可以这样"的背书——约束变可选。
- 把"计划中/考虑过"的假设删成已落地事实——proposed 当 implemented。
- 删掉一句真事实,只因为它读起来像过程叙述。
- 丢掉承重溯源:
实测:512 嵌套 ≈ 0.15s里的实测、来源标注与编号删掉,结论就没根了。