- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
4.8 KiB
4.8 KiB
按需阅读:何时写、何时改与决策流转
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 所守护的模块发生演进,但核心决策并未被推翻时:
- 直接修改,不记流水账:
- ❌ 错误:在文末追加
### 2026-09-02 更新:类名重命名为 X - ✅ 正确:直接在正文中将旧类名替换为新类名,保证任何时候打开这篇 Note,它反映的都是 HEAD 分支的绝对事实。
- ❌ 错误:在文末追加
- 时态永保现在时:
- 始终使用现在时(
系统使用 SQLite 作为持久化引擎),严禁使用变更叙事(系统不再使用 JSONL,现在使用 SQLite)。门禁只拒提案标题,现在时靠这条纪律,不靠词法扫描。
- 始终使用现在时(
3. proposed → implemented 改写清单
同一次改动里做完:
- 移到
implemented/<class>/,文件名日期不动(首次提出日) Status: proposed→Status: implemented## Proposal→## Decision,改成现在时(已落地的事实)## Acceptance criteria/## Risks折进## Consequences(或现在时## Testing/## Verification)- 删计划段(
## Plan/ 迁移步骤 / 开放问题)
门禁靠骨架变化卡住:implemented 里残留 ## Proposal 会失败。
4. 取代:部分重叠 vs 完全吸收
部分重叠:新方案只覆盖旧方案一部分 → 两篇都留,双方加相对链接;只更新仍成立的事实。禁止归档、禁止推迟。
完全吸收(旧方案被彻底淘汰):
- 审计旧 Note 资产:独有的安全边界、否定性保证、失败场景、重新引入条件、验证缺口。
- 搬迁与吸收:写入新 Note 的
## Decision/## Alternatives considered/## Consequences。 - 旧 Note 二选一:
- 删除:新篇已写入旧篇全部独特内容,且入站链接已改完 → 物理删除,不进
archived/。 - 归档:旧篇还有独立杠杆(否定性保证、所有权边界、重新引入条件)→
archive-agent-note.ts。只插Archived:一行;互链写在新笔记。
- 删除:新篇已写入旧篇全部独特内容,且入站链接已改完 → 物理删除,不进
- 修复入站链接:把仍指向旧路径的相对链接改到新 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。