Vibe Project Maintenance（DSH 风格项目记忆体系）
概述
为 AI 编程（vibe coding）项目建立和维护一套"跟随仓库"的文字体系，让后续任何新开的 Agent 都能拿到：必须遵循的规则、系统运转的事实、以及当初的决策因果——从而防止项目滑向没人敢动的一次性工程。
本 skill 的方法论来自对 DeepSeek Harness（DSH）项目源码维护方式的分析，核心是三条：
- 三层文字各司其职：
AGENTS.md管规则，docs/管事实，.agents/notes/管因果；职责不混、位置不改。 - 事实与因果分离：docs 描写"现在的系统怎样运转"，notes 记录"当初为什么写成这样、否定过哪些方案"。两者回答的问题不同，不能写在同一处。
- 测试管当下，笔记管未来：测试保证当前代码运行无 bug；笔记管住后续 agent 不把老账忘了、不把已被否决的方案重新提一遍。
核心原则：
- 首次执行才创建体系；再次执行维护同一套 canonical 结构，不创建第二套。
- 笔记只为"非平凡改动"而写，不是流水账；改小样式、修单文件 bug 不写。
- "被放弃的方案"是一篇笔记最重要的部分；缺了它，下个会话的 agent 会把旧方案当新方案重新提一遍。
- 架构升级只做新增和迁移，不改写旧结论，保持演进脉络可追溯。
- 单篇文档目标不超过 300 行，规则条目每条一两行加跳转链接。
何时使用
满足任一条件即使用：
- 用户要求建立或维护项目决策笔记、Agent Notes、
.agents/notes/体系 - 用户要求建立或分层组织
AGENTS.md规则文件 - 用户抱怨：AI 重复踩坑、重复提出已被否决的方案、项目越写越乱不敢改、每次新会话都要重新解释背景
- 刚完成一次非平凡改动（技术选型、架构调整、绕坑修复），需要沉淀决策因果
- 用户要求像 DeepSeek 团队一样维护项目
不使用：
- 只修改已有笔记中的少量文字或错别字
- 平凡改动（改样式、修单文件 bug）后的例行记录
- 项目尚无任何真实代码、无可记录的决策
三层文字体系
| 位置 | 职责 | 回答的问题 | 面向 |
|---|---|---|---|
根目录 AGENTS.md + 各关键目录 AGENTS.md |
开工必读规则，每条一两行，附详情跳转链接 | "必须遵循什么" | 所有 agent |
docs/ |
架构全景、子系统语义、操作手册、事故复盘 | "现在的系统到底怎样运转"（事实） | 开发者与使用者 |
.agents/notes/ |
决策记录，按模块目录分类 | "当初为什么写成这样、否定过哪些方案"（因果） | 将来的维护者和新开的 agent |
各层内部规则
AGENTS.md（规则层）
- 根目录一份只写全局必读原则，每条一两行 + 详情跳转链接
- 每个关键目录（子系统、模块）各放一份，模块相关规范写在子目录的
AGENTS.md中 - 严禁把所有规矩一股脑堆进根文件——膨胀后 agent 反而无法遵循
docs/（事实层）
- 结构分层：架构全景在
architecture.md，子系统规范在subsystems/，项目操作在cookbook/，事故复盘在postmortem/，绝不混写 - 去废话守则：严禁"以前/现在/不再"等历史变迁词（历史归 notes），禁止手抄 API 列表
- 限制单篇长度，超限直接视为需要拆分，避免文档腐化
.agents/notes/（因果层）
- 只记录代码装不下的"为什么"与踩坑细节，不描述"是什么"（那是 docs 的事）
- 按目录分类，严禁维护全局 INDEX.md 总索引，避免多分支并行开发时产生提交冲突
- 一篇笔记必须包含"被放弃的方案"部分
与 agent-onboarding-docs skill 的关系
两者互补，不重复建设：
agent-onboarding-docs生成的CLAUDE.md/DEVELOPMENT_GUIDE.md等三件套属于事实层（docs/ 的等价物）- 项目已有 onboarding 三件套时，本 skill 不重建事实层，只补齐规则层（分层 AGENTS.md）和因果层（
.agents/notes/） - 两套体系并存时，在
CLAUDE.md文档地图中登记.agents/notes/，互相链接
渐进式加载参考文件
只读取当前步骤需要的参考文件：
| 场景 | 必读文件 |
|---|---|
| 不确定参考资料位置 | references/index.md |
| 三层体系尚未建立（首次初始化） | references/initial-setup.md |
| 准备写一篇笔记 | references/note-writing-guide.md |
| 日常改动后判断写哪里、架构升级 | references/update-routing.md |
| 写完准备验收 | references/quality-checklist.md |
不要一次性加载全部参考资料。
工作流程
Step 0：判定执行状态
检查项目根目录是否存在：
AGENTS.md（根目录规则文件）.agents/notes/目录（决策笔记体系）CLAUDE.md/DEVELOPMENT_GUIDE.md等 onboarding 三件套
| 状态 | 判定 | 行为 |
|---|---|---|
| 首次初始化 | 三层均不存在 | 按 references/initial-setup.md 建立 |
| 日常维护 | 体系已存在 | 按 references/update-routing.md 路由本次改动 |
| 部分建立 | 只有事实层（onboarding 三件套） | 补齐规则层与因果层，复用事实层 |
禁止生成 -new、-v2、日期副本或另一目录中的重复体系。
Step 1：首次初始化
- 扫描项目结构、构建配置、入口与核心模块，识别"关键目录"
- 审计已有文档：onboarding 三件套、README、
.lingma/rules/、代码注释中的决策线索 - 建立规则层：根
AGENTS.md+ 关键目录AGENTS.md，规则从真实代码和已有规范提取，不臆造 - 复用或建立事实层：已有三件套则只登记引用；否则按 architecture / subsystems / cookbook / postmortem 分层创建
- 建立因果层：创建
.agents/notes/目录骨架，按模块分目录 - 存量决策迁移：从 git 历史、会话记忆、代码注释中回溯已发生的重大决策与踩坑，只为有据可查的决策补写笔记；无法确认因果的不写
- 详细步骤见
references/initial-setup.md
不要为迁移存量而虚构决策过程；宁可少写，不可编造。
Step 2：日常维护路由
每次改动后按以下优先级判断（详表见 references/update-routing.md）：
- 平凡改动（改样式、修单文件 bug）：只改代码 + 跑测试，不写任何文字
- 事实变化（接口契约、运行机制、模块职责变了）：更新 docs/ 对应文档，删除旧事实，不用历史变迁词
- 规则确立（发现 agent 反复犯同类错误、确立新的必须遵循项）：更新对应层级
AGENTS.md，每条一两行 + 跳转 - 非平凡改动（技术选型、架构调整、绕坑修复、否决过备选方案）：写一篇 notes
- 架构升级：只新增和迁移，不改写旧结论；旧笔记保留，新版本决策写新笔记并在旧笔记头部加"已被 X 取代"的跳转链接
Step 3：写笔记
- 读取
references/note-writing-guide.md获取模板和判定标准 - 核心结构：背景 → 决策（结论）→ 被放弃的方案（最重要）→ 影响与边界
- 只写因果，不写事实；事实写 docs
Step 4：质量检查
完成后必须读取并执行 references/quality-checklist.md。至少确认：
- 三层职责没有互相混写
- 每篇笔记都有"被放弃的方案"（或明确说明当时确实没有备选）
- docs 无历史变迁词、无 API 手抄
- AGENTS.md 每条规则不超过两行
- 没有创建全局 INDEX.md
- 存量迁移的决策均有真实证据
红线
- 把决策因果写进 docs/，或把系统事实写进 notes/，造成职责混淆
- 写没有"被放弃的方案"部分的决策笔记
- 为平凡改动写流水账笔记
- 在根
AGENTS.md堆积全部规则导致膨胀 - 维护全局 INDEX.md 总索引
- 架构升级时直接改写旧笔记结论，抹掉演进脉络
- 编造存量决策的背景或讨论过程
- 已有体系时生成第二套重复结构
- 让笔记、规则或事实文档无控制地增长到近千行
示例
首次初始化成熟项目
发现只有 onboarding 三件套（事实层）
→ 识别关键目录
→ 建立根 AGENTS.md + 子目录 AGENTS.md（规则层）
→ 创建 .agents/notes/ 目录骨架（因果层）
→ 从 git 历史和会话记忆迁移有据可查的存量决策
→ 在 CLAUDE.md 登记 notes 体系
→ 质量检查
非平凡改动后沉淀
完成"会话协议从 V2 升级到 V3"
→ 判定为非平凡改动 + 架构升级
→ 旧 V2 决策笔记不删除，头部加"已被 V3 取代"链接
→ 新写 V3 笔记：背景 / 决策 / 被放弃的方案 / 影响与边界
→ docs/ 中受影响的机制描述同步为 V3 事实
→ 质量检查
平凡改动
修复某页面按钮颜色
→ 只改代码 + 跑测试
→ 不写笔记、不动 AGENTS.md、不动 docs
参考入口
从 references/index.md 开始查看全部参考文件及加载条件。
