7–9 月笔记整理：架构、Agent 与技术写作

这组七、八、九月的笔记一共十七张照片。几次讲座、论文阅读和工程复盘夹在一起，相邻的页未必讲同一个主题。所以整理时按问题拆成短文，逐页转录也留着，方便以后回查。短文的范围跟着问题走，不按页数平均切：相邻的页可能分进不同的短文，同一页记的两类内容也会各归一处。

翻来覆去，这些页讨论的还是三件事：目标写到什么程度算清楚，实施过程留下哪些证据，已有内容怎么整理才能下一次接着用。下面的顺序是阅读安排，不代表三个月里的发生顺序。

为什么按问题拆，不按页数或月份

这种拆法不是我发明的，几套成熟的做法都指向同一边。写文档的 Diátaxis 先认需求再定形式：用户有四种不同的需求，对应四种文档，文档本身要围着需求的结构来组织。按页数切，等于让纸张的边界替读者决定内容。

拆到多细，Andy Matuschak 的 Evergreen notes should be atomic 讲得很实在：一条笔记只讲一件事，但尽量把这件事讲完整。太宽会错过新冒出来的关联，太碎又会把链接网络一起切碎。他也承认这里没有标准答案，“just a bunch of tradeoffs”。这组短文有长有短，就是这么来的。

卡片盒那边更干脆，zettelkasten.de 的总览第一条就是“Don’t use categories.”：不预设分类，靠链接让结构自己长出来。它还区分了收集和学到：“Collecting information does not increase your knowledge.” 逐页转录属于收集，留着是为了回查；真正的产出是拆出来的那些短文。从读书笔记到成文的流程，同站另一篇说的也是先在纸上记，再聚成簇，一个簇里从最一般的写起，相关的放一起，不同的问题尽量分开。

从需求和架构开始

• 架构图画到哪一层，Spec 写到哪一步：C4 分层和接口边界，回答设计文档该放什么细节。
• 遗留系统改造：先确定要保留的业务，再迁移接口：转向已有系统，先调查真实流程、评估业务价值，再通过切片和接口迁移推进。

这两篇可以连着读。说明一个新系统，先要定下写到哪一层；面对已有系统正好反过来，手头的说明往往不够，缺的部分要从真实流程里补出来。

Agent 的执行、评测与改进

• 给长任务留下可接手的状态：来自工作流与任务复盘，重点是阶段输入、交付物和结束条件。
• Agent 评测：把结果和执行轨迹分开看：task、trial、grader 等术语，以及两种成功率表达的差异。
• 读 SIA：同时改工作流程和模型权重：单独的一篇论文笔记。

SIA 和评测是连着的：改进循环依赖反馈，先得知道反馈究竟在评价什么。评测那篇把结果和执行轨迹分开记，回答的正是这个问题。一条反馈说的是这次跑没跑成，还是过程里哪一步偏了，两种情况对应的改法不一样。

让运行结果能被检查

• AI 写 Playwright 测试：把操作录制变成行为验证：定位、断言、动态数据和 CI 里的失败信息。
• 可观测性笔记：从埋点到能处理的告警：把原页混在一起的数据流和包含关系拆开，画成独立的 Mermaid 图。

这些内容保留的是工程方法，没把笔记里的某个数字写成实测结果。测试数量、内存开销和工具成本尤其如此，它们各自跟不同的条件有关：测试数量看覆盖范围，内存开销看运行环境，工具成本看调用次数。没有环境条件，这些数不足以拿来比较。

输入材料与写作

• 提示词写清任务，上下文保存当前事实：任务说明、示例、结构化输出和历史管理。
• 技术笔记怎么写得容易接着读、接着做：段落、图注、代码示例和下一步行动。
• Attention 阅读便笺：为什么要挡住未来位置：篇幅很短，单独保存 Transformer 的半页阅读记录，免得和工作习惯里的“注意力”混成一类。

这次整理的范围

这些笔记记于七月到九月，原页没有逐一标日期，所以没再按月份划分；九月只覆盖整理前的内容。

这次先把已有的问题和阅读线索留下来。以后再读时，可以接着补具体案例，核对结论适用的条件。

这个索引页现在不完整，我觉得也不用急。zettelkasten.de 的作者描述过自己的结构笔记：一开始只是一条普通笔记，跟着想法长大，中途“pretty messy”，之后再一点点重构。Maggie Appleton 总结数字花园的几条原则里也有“Many entry points but no prescribed pathways”和“imperfect by design”：按关联组织而不是按日期，永远不算写完。

卢曼的卡片盒是这类笔记库的极端样本：比勒费尔德大学的档案项目记录的是约九万张卡片，写于 1951 到 1996 年之间。十七张照片离那还远，道理却相通：这类笔记是一直往里补的，不指望一次整理完。