TL;DR
代码能精确记录 “发生了什么”，却无法保留 “为什么这么做”。缺乏结构化上下文的项目会陷入"慢性失忆"，导致协作成本攀升、AI 输出不可靠。
Docs-First（以文档为中心） 范式通过将目标、约束、决策与状态沉淀为单一事实源，并建立「背景 → 分析 → 决策 → 实施 → 回写」的自更新闭环，让项目拥有可追溯、可演进的"记忆"。这不仅是工程习惯的升级，更是 AI 从"被动辅助"进化为可靠 Agent 的必要基础设施。最终，研发范式将从依赖个体记忆，彻底转向依赖系统状态。

在很长一段时间里，软件工程几乎默认了一个前提，代码是项目最核心的资产。我们通过代码来理解系统、评估复杂度、讨论架构，甚至潜意识里认为——只要读懂代码，就等于读懂了项目。但越来越多的实践表明，即使模型能力已经足够强，如果项目本身缺乏清晰、稳定、可追溯的上下文，AI 的表现依然不可靠。随着项目复杂度上升，这种不可靠甚至会被放大。问题不在于 AI 不够聪明，而在于它缺少一个可以持续依赖的 “项目记忆”。这正是"Docs-First（以文档为中心）"范式要解决的核心问题。

我创建了 project-docs-manager 技能，以标准化流程维护结构化项目文档库，帮助 AI 自主理解项目全貌、历史决策与当前状态。该技能遵循「单一事实源」「机器可读优先」「闭环自更新」三大原则，支持本地目录、Obsidian、云端文档等多种媒介，并内置初始化、迭代记录、状态查询等完整工作流。
🔗 源码与使用说明：https://github.com/isLouisHsu/skills/tree/main/skills/project-docs-manager

背景

代码的边界：它记录行为，但不解释决策

在传统开发模式中，代码承担了过多本不属于它的职责。我们习惯通过代码理解系统的来龙去脉，但代码本质上只能回答 “发生了什么”。它可以精确描述执行路径，却无法解释 “为什么要这样做”。当你看到一段复杂甚至诡异的逻辑时，往往会陷入这种状态：这是经过深思熟虑的设计，还是某次紧急修复留下的临时方案？它是否依赖某些已经消失的前提？是否存在更简单的方案，只是曾经被否决？当前实现，是"最优解"，还是"当时可行解"？这些信息，几乎从不在代码中，而是可能存在于已经关闭的 issue、零散的聊天记录、某个成员的个人记忆。而这些载体都有一个不可持续的共同特点。随着时间推移，这些上下文会逐渐丢失，项目开始进入一种微妙的状态——它仍然可以运行，但越来越难以被理解。

项目失忆：系统仍在运转，但无人真正理解

当关键决策背景没有被系统化保存时，项目会逐渐"失忆"。这种失忆不会立刻导致错误，而是以更隐蔽的方式出现，每一次修改都变得更加谨慎，因为没有人真正确定会触发什么连锁反应；系统的演进开始依赖经验和直觉，而不是明确的认知结构；新成员的上手周期不断拉长，老成员则逐渐成为"唯一知道为什么的人"。最终，团队开始出现改动变慢、风险增加、讨论变得低效（反复还原背景）的现象，进入一种高成本协作状态。这并不是工程能力的问题，而是上下文没有被结构化保存的问题。

AI 放大了这个问题，而不是解决它

很多人期待 AI 能自动弥补这些缺陷，但现实恰恰相反。人类可以在信息不完整的情况下，通过经验做出"差不多正确"的判断。但 AI 不具备这种能力。它对上下文的依赖是刚性的、显式的，你提供什么，它就基于什么推理。

当上下文是零散的、临时拼接的，AI 的理解就不可避免地产生偏差。而且由于上下文窗口的限制，它几乎不可能一次性掌握整个项目，只能在局部信息中做决策。这就导致一个常见现象，每一次新的对话，几乎都像一次"重新开始"。你不得不反复解释背景，而 AI 的输出质量也随着上下文质量波动。问题逐渐清晰——我们缺少的不是更长的 prompt，也不是更强的模型，而是一个稳定、结构化、可持续更新的上下文系统，也就是一个真正意义上的"项目记忆"。

SKILL: project-docs-manager

Docs-First 并不是简单地强调"多写文档"，而是重新定义文档的地位：文档从"辅助说明"，变成"项目状态的核心载体"。在这个范式下，项目中的关键信息必须被显式管理，包括项目目标、约束条件、关键决策、当前状态与历史演进路径。这些信息不再分散存在，而是统一沉淀在一个 单一事实源（Single Source of Truth） 中。正如你在 project-docs-manager 这个实践中看到的，其核心原则就是：所有知识必须进入文档库，而不是停留在对话中；文档必须具备结构，而不是随意叙述；每次迭代必须更新文档，形成闭环。这意味着一个根本变化，判断不再依赖"谁记得更多"，而依赖"系统记录了什么"。

核心设计遵循三大铁律：

单一事实源（Single Source of Truth）：所有项目知识沉淀在项目文档库中，不散落在聊天记录里。文档库是 AI 和人类共同的唯一参考。
机器可读优先（Machine-Readable First）：文档使用固定的 section、字段和格式，而非随意叙事。这让 AI 能快速解析、定位和更新，无需猜测文档结构。
闭环自更新（Self-Updating Loop）：每次迭代结束后，AI 必须更新文档，确保下一次 session 看到的是最新状态。绝不留"口头约定"。

这种设计将"写文档"从一种被动的、滞后的事务性工作，转变为驱动项目演进的核心机制。当你要求 AI 执行某项任务时，它首先读取的是 当前项目状态 而非你的 prompt；当它完成工作后，必须将决策背景和实施结果写回文档库，为下一次迭代积累上下文。

仅仅把信息写下来是不够的。如果文档只是自然语言的堆叠，它依然难以被高效使用。Docs-First 更进一步要求文档具备稳定结构，使其同时对人类和机器友好。这也是为什么在实践中，文档库通常会演化为一种"轻量知识系统"。而在 project-docs-manager 的具体实现中，这种结构被标准化为一套固定的文件架构：

"仓库索引 + 媒介详情"两层架构

{docs_path}/                    # 仓库内（入口索引）
└── _INDEX.md                   # 目录索引（轻量，AI 优先扫描），链接指向 {media_path}

{media_path}/                   # 文档媒介（实际文档）
├── OVERVIEW.md                 # 全局概览 + 当前进展
├── CHANGELOG.md                # 变更历史索引（时间倒排，一句话摘要）
├── KNOWLEDGE.md                # 知识库索引（一句话摘要）
├── changes/                    # 变更详情
│   └── YYYY-MM-DD_xxx.md
└── knowledge/                  # 知识详情
    └── topic_xxx.md

每个文件的职责边界清晰：

文件	职责	AI 扫描策略
`_INDEX.md`	文档库全局目录，列出每个文件路径和一句话说明	最高 — 每次 session 首先读取
`OVERVIEW.md`	项目背景、目标、当前状态、核心指标、团队分工	高 — 理解项目全貌
`CHANGELOG.md`	变更历史索引，每条记录：日期、标题、一句话结果、详情链接	高 — 了解迭代历史
`KNOWLEDGE.md`	知识条目索引，每条：主题、一句话说明、详情链接	中 — 按需查阅
`changes/*.md`	单次变更详情：背景、方案、实施、结果、TODO	低 — 仅需深入时打开
`knowledge/*.md`	单个知识主题详情：定义、上下文、相关链接	低 — 仅需深入时打开

这种分层设计带来的关键变化是：AI 先扫索引做决策，只在必要时打开详情。信息可以被快速定位，而不是全文搜索；上下文具有层级，而不是平铺；决策之间存在明确引用关系（如 → 详见 [文件名](相对路径)）。文档不再只是"描述"，而变成一种可查询、可导航、可演化的上下文系统。

project-docs-manager 还支持多种文档媒介——你可以将详档存放在本地目录、Obsidian Vault 或钉钉/Notion 等云端平台，而仓库内只维护 _INDEX.md 作为入口索引，保持代码仓库的轻量。

Docs-First 最重要的变化，不在"写"，而在"更新"。在这个范式中，每一次迭代不仅是代码的变化，还必须伴随一次完整的上下文更新：为什么要做这件事、做过哪些分析、最终如何决策、实际执行了什么、结果如何。这些信息不会停留在即时沟通中，而是被整理并纳入文档体系。

project-docs-manager 将这种更新流程标准化为 严格的工作协议 ，每次文档变更必须完成四步：

更新 _INDEX.md（如有新文件）
更新 CHANGELOG.md（追加变更记录）
更新 OVERVIEW.md 中的"当前进展"（如状态变化）
检查并更新相关文档中的交叉引用链接

根据用户意图，AI 自动进入对应流程：

首次创建文档库 → 执行初始化流程：检测 → 创建骨架 → 注册到 CLAUDE.md
记录新的迭代/变更 → 执行更新流程：收集输入 → 分析 → 实施 → 记录 → 更新索引
查看项目状态 → 直接读取 _INDEX.md → OVERVIEW.md
查找历史决策 → 读取 CHANGELOG.md → 打开对应 changes/*.md
查阅知识 → 读取 KNOWLEDGE.md → 打开对应 knowledge/*.md

为了让 AI 真正做到"自动感知项目状态"，project-docs-manager 设计了一条隐式加载链路：

CLAUDE.md（AI 每次 session 自动加载）
  → 包含文档库路径和操作规范
    → 指示 AI 首先读取 {docs_path}/_INDEX.md
      → _INDEX.md 引导 AI 按需读取 {media_path}/ 下的文档

随着时间推移，项目不会因为迭代变多而变得混乱，反而会变得更容易理解，因为决策的上下文在不断积累，而不是不断丢失。这本质上形成了「背景 → 分析 → 决策 → 实施 → 结果 → 回写文档」的闭环，而这个闭环，正是 AI 能稳定参与的基础。

当一个项目具备稳定的上下文系统后，AI 的角色会发生质变。它不再需要反复理解项目背景，或是依赖一次性的大段 prompt，或是在不完整信息中做猜测。相反，它可以像读取数据库一样获取当前状态，并沿着历史决策链进行推理，从而在既有上下文上继续推进工作。这使得 AI 从"辅助工具"转向一种更接近 Agent 的角色，基于当前状态做判断 → 执行具体操作 → 将结果写回系统 → 规划下一步行动，整个过程形成一个自我强化的循环。而这一切的前提，不是模型能力，而是上下文是否被系统化管理。

结语

从长远来看，代码一定会不断变化、重写甚至被替代。但那些关于"为什么这样做"的信息，如果没有被记录，就会永久消失。一旦这些信息消失，项目就会逐渐失去可解释性，团队效率下降，AI 也难以真正发挥作用。Docs-First 的真正价值，在于它完成了从"依赖人类记忆的过程"，转变为"依赖系统状态的过程"的底层转变。它让隐性的认知变成显性的结构，让项目第一次真正拥有"记忆"。

而当项目不再依赖个体记忆，而建立在可持续的上下文之上时，我们才有可能让 AI 不只是参与开发，而是开始主导开发。这不是一个一蹴而就的变化，但路径已经清晰——从文档开始，构建一个可以被机器理解的工程世界。