Agent Notes（代理笔记）
定义
DeepSeek Harness 仓库中一种特殊的设计文档类型：由 agent 自己撰写的、类 RFC 的决策/提案记录，记录影响代码库的决策的”为什么”和”放弃了什么”——这些是代码和普通文档无法承载的部分。
核心要点
定位（原文）
“An Agent Note records a decision or proposal that affects this codebase — the why and what we gave up, the parts code and docs can’t carry.”
一条 Agent Note 记录的是「影响这个代码库的某个决策或提议」——重点是为什么这么做、以及我们放弃了什么。这些恰恰是代码和文档承载不了的部分。
强制制度
“Every non-trivial change MUST add or update at least one Agent Note in the same PR.”
即：任何非平凡改动，必须在同一个 PR 里新增或更新至少一条 Agent Note。纯机械性/本地化改动可豁免。
路径编码的两个轴
每条 Agent Note 的路径是 {lifecycle}/{class}/yyyy-mm-dd-topic-title.md：
- Lifecycle（生命周期）：
proposed/（提案）、implemented/（已实施）、rejected/（被否） - Class（类别）：
feature/bug-fix/simplification/architecture/process/testing
文件格式骨架
implemented 笔记必含：
## Problem
## Decision
…自由技术章节…
## Alternatives considered
## Consequences
其中 Alternatives considered（被考虑的替代方案）是强制的——每条被否的替代方案都要说明为什么落选：
“A decision recorded without what it beat invites re-litigation.”
归档与冻结
已实施的笔记在”决策完成且理由不再指导未来工作”时归档到 archived/，一旦归档即永久冻结（不得编辑、翻译、移动、删除），也不作为当前行为的权威。
意义
Agent Notes 把”设计决策的隐性知识”外化为可机械校验的文件。它意味着 DeepSeek Harness 用自己的 agent 开发自己，并让 agent 在开发过程中持续写下设计理由——这本身是对 Harness工程 “为什么这么设计”问题的一种工程化回答。