# 按需阅读:何时写、何时改与决策流转 > 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//`,文件名日期不动(首次提出日) 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. 可选:源码入口反向注释 宿主若已有此惯例,可在核心入口留一行: ```typescript // Note: 会话持久化采用文件句柄管理,避免并发写冲突 — 见 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md export class SessionFileHandlePool { // ... } ``` 不是门禁。`check-note-anchors` 只做软报告,不进 CI。