写在前面：关于怎么写 notes，感兴趣的佬友可以看一下我之前写的这个 skill： 【开源】像 DeepSeek 团队一样维护项目
免责声明：本文以下所有内容纯属个人分析，写的也是比较的粗浅，不代表任何真实事实，另外由于言语水平有限加纯看图说话手敲，可能会显得比较流水账****佬们也可以选择直接看图
最近在站内经常刷到佬友们发的一些关于AI 编程的提问，问的内容几乎都在同一个痛点上：vide coding项目可维护性。
[
image-202609150942500411760×394 65.7 KB
[
image-202609150940233761374×330 41.7 KB
[
大家聊的角度不同，但背后其实说的都是同一件事情，代码越写越快，项目却慢慢滑成了一次性工程，到了后面维护的时候根本不敢随便改。
这种感觉相信经常vibecoding 的佬友应该很熟悉，一方面，每次新开的 agent 是没有以前需求背景的上下文信息的，需要从当前的代码以及你口述的内容中进行猜测；另一方面，很多时候agent 追求的是局部最优，甚至为了这个局部最优绕过了项目的基本规范；另外agent 也对你之前踩过哪些坑一无所知，以上的几点原因就导致了随着vibe 的时间越久，项目就越来越“屎山”，没人敢随便去动它。
[
那么，DeepSeek 团队是怎么维护项目的？
从 DeepSeek Harness 项目的开源代码中，我们可以窥见一二。下面我将结合自己的认识以及 DSH 源码的结构，做一个粗浅的分析。
一、三大核心部分
在 DSH 项目中，项目改动相关的文字职责拆得很开，主要分成三大块：
[
- 根目录 AGENTS.md，agent开工必读的规则（一般一条只有一两行，主要写的是开发过程中必须遵循的原则，并附上详情跳转链接）。
- docs/，当前系统的整体项目图谱与开发者规范（主要包括架构全景、子系统运行语义等内容，主要描述的是当下系统是怎么运转的）。
- .agents/notes/，仓库里的决策记录（专门放代码装不下的为什么与踩坑细节）。
在我们平时开发的过程中，很多团队会选择把所有的规矩一股脑的追加根目录的agents.md 里，结果导致其快速膨胀，也导致了agent 很难很好的遵循定好的规则。下面是dsh 的agents.md 的内容：
[
dsh 的agents.md 不止有一个，而是在每个关键的目录中都会放一个，把对应模块的相关信息以及规范都写在子目录的agents.md 中
[
二、docs/ 是怎么管的
在我们平时开发的项目中，估计对于 docs/目录佬友们早就见怪不怪了，因为大模型最喜欢在改代码的时候给你写各种各样的文档了，所以怎么写一篇docs 也不是本文的重点。
但是必须说明的是，dsh 里面的文档的组织结构还是非常值得学习的，而且这套组织也可以很容易的学习到我们的项目中。具体的结构如下
[
14-docs-architecture1920×987 358 KB
](https://cdn3.ldstatic.com/original/4X/a/3/0/a3094f3194fe6324021d009f3eceba4be202afdd.jpeg “14-docs-architecture”)
- 结构分层：架构全景在 architecture.md，子系统规范在 subsystems/，项目操作相关在 cookbook/，事故复盘在 postmortem/，绝不混写
- 去废话守则：主要包括严禁写「以前/现在/不再」等历史变迁词、禁止手抄 API 列表等，避免文档的快速腐化
- 限制文档长度：CI 代码会限制每篇文档字数上限，超过规定的长度直接报错打回，避免了文档的过度膨胀。
看完了上面两个部分，接下来进入本文真正要深挖的核心。很多项目代码越改越乱，根源就在于缺少了第三块文字。
三、事实与决策取舍的分离
看到这里，佬友们可能会想，既然 docs/ 已经把全景架构和子系统契约写得这么详细，为什么不顺手把每个模块的技术选型以及开发的心路历程也都写在里面，非要多折腾一个 .agents/notes/ 目录？
因为他们有个根本性的区别，docs 描写的是“事实”，而notes 记录的是“因果”。
[
09-homes2800×1400 385 KB
](https://cdn3.ldstatic.com/original/4X/f/e/0/fe098bc3b3268eedb51feeeae379fc8a5534e1e7.png “09-homes”)
docs/ 是面向开发者与使用者的，所以其中文档回答的是「现在的系统到底怎样运转」的问题。他记录的必须是关于当前代码的确定事实，而不可能长篇大论的把历史决策，开发过程踩过的坑，舍弃了哪些东西这些细节记下来。不然光是找一个功能点的描述我们都得找半天 
而 .agents/notes/ 面向将来的维护者和新开的agent，回答的是「当初为什么写成这样、否定过哪些方案才妥协成现在这样」。两者职责完全不同，所以不能都记录在同一个地方。
为了方便大家有个快速的了解，我之前做过一个看板，都是DSH 项目中真实的笔记，感兴趣的佬友们可以看看。 工程决策看板：https://czm15053.github.io/write-notes-like-deepseek-demo/
[
board-baseline1600×1125 231 KB
](https://cdn3.ldstatic.com/original/4X/b/8/b/b8b1cdb467a5fdcf0446ccbc4e823b66e2489c43.jpeg “board-baseline”)
在看板里我们能清晰看到dsh 项目中上千条的架构决策跟随代码演进的完整脉络。
[
board-timeline1600×1125 316 KB
](https://cdn3.ldstatic.com/original/4X/7/a/4/7a40644928311aa3924882c89a516ba2b4084a7f.png “board-timeline”)
四、一篇笔记长什么样
那么，在dsh 项目中一篇真实的笔记到底长什么样呢？是否都是一些长篇大论呢？下面我们来看一下
[
04-anatomy2800×2080 471 KB
](https://cdn3.ldstatic.com/original/4X/6/6/0/66007e41d3a3f5232452079248682ecba424ce93.png “04-anatomy”)
其中个人认为最重要的是第三个部分：被放弃的方案。必须写清楚当时还想过什么、为什么放弃。如果缺了这个部分，下个会话的 Agent 可能还是会把它当新方案重新提一遍。
举一个源码中的笔记作为例子，从图中我们可以看出背景是这样的：由于之前 DSH 源码中的现成库用得很少，导致agent自行推断出严禁加依赖的错误认知，选择很多东西都从零去手写一份，大大增加了维护难度。为了避免这种情况的发生，DSH团队专门补了篇笔记把这个规矩写下来。
[
image-20260915101618429839×744 133 KB
](https://cdn3.ldstatic.com/original/4X/2/5/4/2542b05d885e5a80aa58fb9988e8142771707725.png “image-20260915101618429”)
[
11-dependencies-case1920×1042 374 KB
](https://cdn3.ldstatic.com/original/4X/9/c/9/9c9ddd8870198ec917d4501f69de12093cdd8363.jpeg “11-dependencies-case”)
五、那么什么时候需要写一篇notes 呢？
看到前面对于notes 的格式卡得这么严，佬友们的第一反应可能是，改个小样式、修个单文件 bug 也要单独写一篇notes 吗？
那肯定是不用的。笔记不是流水账，不能什么情况都写。一般来说在dsh 只有进行“非平凡改动”的时候才会留下notes。至于什么是非平凡改动，可以参考下图。
[
03-scenarios2800×1656 367 KB
](https://cdn3.ldstatic.com/original/4X/3/d/f/3dfc50e0f4bbe033754c7627c42c4f719fa620b5.png “03-scenarios”)
总体的开发流程大概是这个样子
另外，笔记按目录分类，在 dsh 项目中严禁维护全局 INDEX.md 总索引，避免多分支并行开发时产生提交冲突。
[
07-no-index2800×1600 384 KB
](https://cdn3.ldstatic.com/original/4X/1/8/a/18ab9fdd7ca178140b5a2cff7bc759ea9fcfcc8a.png “07-no-index”)
六、升级不去修改旧的结论，只做新增和迁移
平时日常迭代的规矩已经有了，那时间久了架构大升级怎么办？
以最近 DSH 的会话协议从 V2 升到 V3为例：
[
13-version-evolution2800×1400 490 KB
](https://cdn3.ldstatic.com/original/4X/8/1/b/81bd5455a235480024b7dcbcb6016d8d713dd558.png “13-version-evolution”)
七、双重防线，测试管当下，笔记管未来
把这些环节串起来看，他们防 AI 乱改代码，其实就是两条腿走路。一条腿卡住当下代码，另一条腿管住历史记忆。测试负保证当前的代码的运行没有 bug，笔记负责管住未来的agent别把老账忘了。
[
12-testing-guardrails2800×1400 442 KB
](https://cdn3.ldstatic.com/original/4X/1/e/c/1ec452fd03579c1afc965e13bb3b28f764085cb1.png “12-testing-guardrails”)
个人取舍与思考
这套工程做法拿到别的项目，我觉得最值得抄的是他们的这套 Agent Notes，可以在一定程度上提升我们项目的可维护性。当然如果你的项目中还没有沉淀关于项目架构的 docs，也可以好好参考 DSH 的docs 目录下的文档架构。最后，再提一下我写的这个 skill 项目，可以让你像 dsh 一样书写自己项目的 notes。
开源推广声明 今天写了篇新的文章，感兴趣的佬友可以看看
从 DSH 源码看 DeepSeek Harness 团队是如何维护项目的 建议佬们可以优先看一下下面的demo，可以更清楚的了解 Deepseek harness 的文档到底是怎样的，链接： 工程决策看板 相信做开发的佬友们都有经历过这样血压飙升的时刻：花了很长时间和AI 讨论写了一段设计非常复杂的代码逻辑，虽然…