历史项目入库

aiops-historical-project-intake 从已有代码、文档、配置中逆向提炼项目知识，生成结构化的 canonical 文档。

适用场景

• 接手一个维护了几年但文档缺失的老项目
• 开源项目二次开发前，需要了解项目结构和决策背景
• 项目有文档但分散在 README、Wiki、设计文档里，没有人整理过
• 想让 AI agent 理解项目，但不知道从哪开始

输入来源

按可靠程度排列：

1. 源码、测试、迁移脚本、配置文件、构建脚本 — 最可靠。代码不会撒谎。
2. 已有的 README、设计文档、接口文档 — 有用但需要交叉验证。
3. CodeGraph 和 Understand Anything 的图谱结果 — 辅助定位调用关系和模块边界。
4. 人的补充说明 — 有价值但需要标注来源。

一条底线：源码和旧文档冲突时，以源码为准。冲突本身记入 ADR 或 open-questions。

执行步骤

1. 确认 .aiops/ 已初始化——没有的话先调 aiops-governance-bootstrap

2. 确定项目的源码根目录和目标知识路径

3. 用 Understand Anything 建立项目理解，必要时用 CodeGraph 辅助

4. 盘点证据来源：入口文件、manifest、API 路由、配置、测试、已有文档

5. 按优先级生成文档：

   第一轮（最低闭环）：

   • README.md — 只做导航，不做叙事
   • architecture/ — 系统边界、模块职责、依赖方向
   • workflows/ — 核心业务流程，连接到源码路径

   第二轮（完善）：

   • specs/ — 接口、配置、协议、数据合约
   • prd/ — 产品目标、约束、用户能力
   • adr/ — 已确认的架构决策（包括从代码中反推的）

   第三轮（人类阅读）：

   • guides/docs/ — 概述、接入指南、变更流程

6. 不确定的内容放入 open-questions.md，标注证据等级

7. 完成后执行 aiops-knowledge-review 做质量检查

关键原则

先建骨架，再填内容

第一轮不要追求文档齐全。先让 agent 能回答这几个问题就够了：

• 这个项目有哪些模块和子产品？
• 核心业务流程怎么走的？
• 改一个模块时哪些文件会受影响？

达到这个标准后，后续可以在日常使用中逐步完善。

区分"已确认"和"看起来合理"

从代码反推架构特别容易把"应该是这样设计"写成事实。一条规则：能从源码、配置、测试中验证的才算已确认，其他的写进 open-questions.md。

例如，看到模块 A 只 import 了模块 B 的三个函数，你可以写"A 依赖 B 的 X、Y、Z 接口"。但如果代码里没有说明选择 B 的理由，就不要编造理由。

不做一次性工程

历史入库产出的文档要接入后续维护流程——之后每次代码变更，Hook 都会记录，维护技能会根据 pending 更新相关文档。

所以第一轮的文档不需要完美。结构搭好、核心事实准确就够了。剩下的在日常使用中持续改进。

完成标准

合格的入库结果，应该让新加入的 AI agent 能回答：

• 这个 workspace 里有哪些项目和子产品？各自负责什么？
• 核心业务流程经过哪些模块和文件？
• 改某类功能时应该召回哪些文档和源码？
• 哪些接口、配置、数据结构不能随意改动？
• 哪些结论证据不足，需要人类确认？