一、这是什么

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

它不只是一个文档管理工具。它要实现的是在项目中建立一套结构化文档体系，充当 AI 的"项目记忆"和"驱动引擎"，从而让 AI 能够自主地理解项目现状、提出优化方向、执行变更、回收效果、沉淀知识，然后基于新的认知发起下一轮迭代——全程不依赖人类重新交代背景。

🔗 源码与使用说明：https://github.com/isLouisHsu/skills/tree/main/skills/project-docs-manager

它的文档架构是"仓库索引 + 媒介详情"两层：

1
2
3
4
5
6
7
8
9
10
11
{docs_path}/
└── _INDEX.md                  ← AI 每次会话的启动入口

{media_path}/
├── OVERVIEW.md                ← 项目全貌：背景、目标、指标、当前状态
├── CHANGELOG.md               ← 迭代历史：每次变更的一句话结果
├── KNOWLEDGE.md               ← 知识索引：踩过的坑、发现的规律
├── changes/                   ← 迭代详情：方案、实施、效果、遗留
│   └── 2026-04-07_xxx.md
└── knowledge/                 ← 知识详情：技术要点、业务约束
    └── topic_xxx.md

这套结构不是给人类写的项目文档，而是 AI 的操作系统——它从中读取目标、感知现状、检索历史、规避已知陷阱，并在每次迭代后将新认知写回，供下一次会话的 AI 继承。

二、为什么需要这个 Skill

先看看 AI 开发卡在哪了。 跟 AI 协作写代码，表面上挺顺的——你说一句它写一段。但真做起项目来，处处都是断层：

  1. 想让它主动推进？它不知道要干嘛。 项目目标、当前进度、优先级队列，这些信息只在你的脑子里，AI 只能干等着你的下一条指令。
  2. 换了个会话，一切归零。 上次聊到一半的架构决策、刚发现的坑、临时调整的方案，AI 全忘了。你得重新讲一遍，或者让它从代码里猜——但代码只告诉它"现在长什么样"，不会说"为什么长成这样"“之前试过什么”。
  3. 做完就结束，没有然后。 AI 的典型节奏是：接任务 → 写代码 → 交差。它不会回来看跑没跑通、效果达没达标，更不会基于结果规划下一轮。但真实迭代是循环的：分析 → 方案 → 实施 → 观测 → 沉淀 → 再分析……
  4. 同样的坑，反复踩。 两周前被证伪的方案，AI 可能重新提出来；上次实施时才暴露的约束，它再次忽视。没有记忆，就没有学习。
  5. 人跟不上机器的节奏。 当 AI 真的自主跑起来，你怎么知道它做了什么、为什么这么决定、效果好不好？翻聊天记录太碎，看代码 diff 太累，你需要一种快速对齐的方式。

所以，交付件应该是文档，而不是代码。 代码是 AI 几秒钟就能写出来的东西，也能几秒钟重写。代码廉价且可再生。 真正值钱的是项目上下文——为什么要做？做到哪了？试过什么、效果如何？哪些路走不通？下一步该往哪？如果这些只在你脑子里，或散落在聊天记录里，AI 就永远是个"单步执行工具"。每次会话都要重新交代背景、重复约束、纠正方向，它的能力被锁死在被动模式里。Project Docs Manager 做的事很简单：把项目上下文从人脑搬到结构化文档里，让 AI 能自己读、自己理解、自己推进。

如此，工作模式会发生根本性的转变：

  1. AI 开始主动提案。 有了 OVERVIEW.md 里的目标和指标，AI 能判断：“距离目标还有 15%，上一轮优化效果一般，但 KNOWLEDGE.md 里记了 B 方向的线索——建议这次试试 B。”
  2. 会话断了，认知还在。 新会话的 AI 花几秒读一遍 _INDEX.md → OVERVIEW.md → CHANGELOG.md，就能从上次停下的地方继续，不用你重新讲故事。
  3. 迭代真正闭环。 每次结束必须写 changes/ 记录效果、更新 OVERVIEW.md 的指标、沉淀新发现到 KNOWLEDGE.md。这些直接成为下一次的输入，做完不是终点，而是下一轮的起点。
  4. 错误变成资产。 CHANGELOG.md 记着每次尝试（包括搞砸的），changes/*.md 留着被否决的方案及原因，KNOWLEDGE.md 存着实战摸出来的规律。AI 会查历史：“缓存方案上次因为一致性问题挂了，这次换个角度。”
  5. 人和 AI 同频。 结构化的变更记录让你几分钟就能审完 AI 的完整决策链，OVERVIEW.md 随时告诉你项目在哪。不用追聊天记录，也能随时介入把控方向。

三、它是如何生效的

1. 启动感知：AI 自动恢复项目认知

Skill 初始化时会在项目的 CLAUDE.md 中注册文档库路径。此后每次 AI 会话启动，自动触发认知恢复链路：

1
2
3
4
5
CLAUDE.md（AI 自动加载）
  → 发现文档库配置 → 读取 _INDEX.md
    → 加载 OVERVIEW.md（目标、现状、指标）
    → 加载 CHANGELOG.md（迭代历史）
    → 按需加载 KNOWLEDGE.md 和详情文件

零成本启动，不需要人类交代背景。AI 开口说的第一句话就可以是：“基于当前项目状态，我建议下一步……”

2. 初始化：从项目中提取已有上下文

对已有项目，初始化不是创建一堆空模板，而是主动扫描：

  • 项目结构和技术栈（Glob 扫描文件树）
  • 现有文档（README、CONTRIBUTING 等）
  • Git 历史（提交记录、标签、分支）
  • 依赖和配置

扫描结果被预填充到文档模板中，经用户确认后落盘。项目不是从零开始"被文档化"的，而是已有的隐性知识被显性化、结构化。

3. 迭代驱动：UPDATE 流程实现自主闭环

UPDATE 是这套体系的核心引擎，它定义了 AI 驱动项目前进的完整路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
① 读取文档 → 理解项目现状和历史
        ↓
② 差距分析 → 当前指标 vs 目标，识别优化空间
        ↓
③ 方案设计 → 1-3 个方案 + 推荐理由 + 风险评估
        ↓
④ 人类审批 → 确认方案（人类保留决策权）
        ↓
⑤ 实施执行 → 按方案落地，模块级评审
        ↓
⑥ 效果回收 → 收集前后对比数据
        ↓
⑦ 文档更新 → 写入变更详情、更新索引和概览、沉淀知识
        ↓
⑧ 准备下一轮 → 更新后的文档成为下次迭代的输入
        ↓
      回到 ①

关键点在于第⑦步和第⑧步之间的衔接——文档的更新不是"归档"，而是"加载弹药"。每一次迭代写入的效果数据、新发现的知识、调整后的优先级，都直接成为下一次 AI 分析和决策的依据。

迭代不是人类发起的，是文档驱动的。人类只需要在第④步把关。

4. 索引纪律：控制 AI 的认知成本

让 AI 高效消费文档的关键是分层：

层级 文件 内容 每条长度
入口层 _INDEX.md 文档目录 < 150 字符
索引层 CHANGELOG.md、KNOWLEDGE.md 摘要 + 链接 < 150 字符
详情层 changes/*.md、knowledge/*.md 完整记录 不限

大多数决策只需读取入口层和索引层（3 个文件），不需要打开任何详情文件。只有需要深入分析特定历史决策时才进入详情层。这让 AI 在上下文窗口有限的约束下，仍能高效获取项目全貌。

5. 媒介灵活性：适配已有工作流

文档的存放位置不局限于代码仓库，支持本地目录、Obsidian vault 和云文档（钉钉文档、Notion 等）。仓库内只保留一个轻量的 _INDEX.md 作为跳板。团队可以按已有习惯选择文档载体，不需要为了用这套体系而改变工作流。

四、一句话总结

Project Docs Manager 把项目上下文从人类的脑子里搬到结构化文档中，让 AI 能够自主读取现状、提出方案、执行变更、回收效果、沉淀认知，然后用新的认知发起下一轮迭代。