Files
lpt-meta/.agents/skills/write-notes-like-deepseek/references/when-to-write.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.8 KiB
Raw Blame History

按需阅读:何时写、何时改与决策流转

SKILL §4 的深度展开。每个重要改动或评审时对照一次。

核心心智:更新既有归属,严禁重复新建(Update the owning note)

DeepSeek 的公开演进历史(deepseek-ai/deepseek-harness 的 git 记录)里能看到同样的形态:Note 的新增很少,现有 Note 的就地事实修正占了绝大多数。 不要把 Note 当做一次性发表的博客或流水账。它是与代码共存亡的「现行法律」。

一篇 Note 永远不被改写成另一个决定:事实(路径、符号、默认值)就地改;决定或理由翻转 → 新开一篇并互链。禁止把 ## Decision 改写成反面,禁止只靠 git 当旧理由的唯一副本。


1. 场景判定矩阵

场景 操作动作 典型范式
代码重构、改名、移包、改默认参数 原地更新现有 Note 事实 Decision 核心理由不变;直接改路径、类名、默认值(不追加变更流水账)。理由变了就走新建,不走原地
写新 Note 之前 当场审计活跃笔记 按模块名/关键词搜 proposed + implemented + rejected;每篇命中当场分类(无关 / 部分重叠 / 完全吸收 / 过时提案),和这篇新 Note 一起落盘。禁止推迟到大扫除
提出全新的架构尝试或技术选型 新建 proposed/ 动手编码前写清动机、真实考虑过的备选与验收指标
完成开发并准备合入主干 转为 implemented/ 见 §3 改写清单;与代码同批落盘(git 场景即同一 commit/PR)
方案被新决策部分取代 两篇都留、互链 只更新仍成立的事实。禁止归档
方案在评审中被否决 移入 rejected/ 或删除 仅当其理由能避免未来重蹈覆辙时保留并写清原因;否则彻底删除
新架构完全取代了旧架构 先吸收,能删则删,否则归档 见 §4。指针写在新笔记里,不写进归档篇
版本封版打标、依赖小补丁、排版 免除(Not Applicable) 直接提交代码,无需任何 Note

2. 原地同步法则(In-place Fact Sync)

当现有 Note 所守护的模块发生演进,但核心决策并未被推翻时:

  1. 直接修改,不记流水账:
    • ❌ 错误:在文末追加 ### 2026-09-02 更新:类名重命名为 X
    • ✅ 正确:直接在正文中将旧类名替换为新类名,保证任何时候打开这篇 Note,它反映的都是 HEAD 分支的绝对事实。
  2. 时态永保现在时:
    • 始终使用现在时(系统使用 SQLite 作为持久化引擎),严禁使用变更叙事(系统不再使用 JSONL,现在使用 SQLite)。门禁只拒提案标题,现在时靠这条纪律,不靠词法扫描。

3. proposed → implemented 改写清单

同一次改动里做完:

  1. 移到 implemented/<class>/,文件名日期不动(首次提出日)
  2. Status: proposed → Status: implemented
  3. ## Proposal → ## Decision,改成现在时(已落地的事实)
  4. ## Acceptance criteria / ## Risks 折进 ## Consequences(或现在时 ## Testing / ## Verification)
  5. 删计划段(## Plan / 迁移步骤 / 开放问题)

门禁靠骨架变化卡住:implemented 里残留 ## Proposal 会失败。


4. 取代:部分重叠 vs 完全吸收

部分重叠:新方案只覆盖旧方案一部分 → 两篇都留,双方加相对链接;只更新仍成立的事实。禁止归档、禁止推迟。

完全吸收(旧方案被彻底淘汰):

  1. 审计旧 Note 资产:独有的安全边界、否定性保证、失败场景、重新引入条件、验证缺口。
  2. 搬迁与吸收:写入新 Note 的 ## Decision / ## Alternatives considered / ## Consequences。
  3. 旧 Note 二选一:
    • 删除:新篇已写入旧篇全部独特内容,且入站链接已改完 → 物理删除,不进 archived/。
    • 归档:旧篇还有独立杠杆(否定性保证、所有权边界、重新引入条件)→ archive-agent-note.ts。只插 Archived: 一行;互链写在新笔记。
  4. 修复入站链接:把仍指向旧路径的相对链接改到新 Note(引历史快照时才指向 archived/)。

--superseded-by 只校验新笔记存在,并在新笔记末尾补一条指向归档路径的相对链接。


5. 可选:源码入口反向注释

宿主若已有此惯例,可在核心入口留一行:

// Note: 会话持久化采用文件句柄管理,避免并发写冲突 — 见 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
export class SessionFileHandlePool {
  // ...
}

不是门禁。check-note-anchors 只做软报告,不进 CI。