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

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