历史项目生成文档
历史项目生成文档的目标，是把已有代码、配置、测试、历史文档和图谱分析结果，沉淀成一套可被 coding agent 持续召回和维护的项目级知识库。
这类场景通常发生在遗留项目、长期维护但文档松散的项目、接手项目、开源项目二次开发之前。判断结果好不好，不看文章是否完整好读，而看新的 agent 是否能基于文档理解项目边界、定位代码、判断影响面，并安全继续开发。
治理对象
治理对象是 workspace 下的项目级知识。一个项目可以包含多个产品，每个产品下可以包含多个微服务。例如数字证书认证系统里可能同时存在 CA、RA、KMC、OCSP 等产品，并分别对应独立代码服务。文档需要先建立项目边界，再识别产品、微服务和外部上下游关系。
推荐落点：
.aiops/projects/<project>/
project.yaml
iteration-bindings.yaml
README.md
open-questions.md
iterations/
products/
guides/
其中 README.md 只做导航索引，面向人阅读的连续叙事放在 guides/，面向 agent 召回的事实文档放在 iterations/ 和 products/ 下。产品级目录承载产品版本、能力边界和产品内微服务划分；微服务级目录承载服务接口、模型、流程和验证入口。
生成顺序
历史项目不要一开始就追求文档齐全。第一轮应先解决 agent 进入项目所需的最低知识闭环。
- 识别 workspace、项目、产品和微服务边界。
- 扫描源码入口、manifest、配置、测试、已有文档。
- 使用
understand-anything建立项目理解，必要时使用codegraph辅助定位调用关系。 - 生成项目索引和开放问题。
- 按项目、产品、微服务三级落点沉淀 PRD、architecture、specs、adr、workflows 事实。
- 为人补一份
guides/阅读入口。
第一轮最重要的是 architecture 和 workflows。architecture 让 agent 知道模块和依赖方向，workflows 让 agent 知道关键业务链路如何流经代码。没有这两类文档，后续维护很容易变成局部猜测。
五类文档怎么写
prd/ 写项目为什么存在、服务谁、解决什么问题、不解决什么问题。历史项目的 PRD 从代码能力、用户入口、配置项、测试用例和已有说明中反推，再把不确定内容写进 open-questions.md。
architecture/ 写系统边界、产品关系、微服务职责、依赖方向、运行时组件、数据流和部署形态。对于包含 CA、RA、KMC、OCSP 这类产品的项目，architecture 必须说明它们之间的责任边界和交互路径。
specs/ 写具体接口、命令、配置、数据结构、协议、任务和行为约束。specs 是 agent 修改代码时最常被召回的事实层。
adr/ 写已经确认的架构选择、取舍和边界。历史项目里没有原始 ADR 时，可以从代码现状补写“已发生决策”，但必须标明证据和不确定性。
workflows/ 写端到端流程，例如证书签发、密钥托管、吊销查询、定时同步、异常处理。每条流程都要尽量连接到源码路径、配置路径或测试路径。
证据规则
历史项目最容易出现的问题，是 agent 把“看起来合理”的系统解释写成事实。文档应区分已确认事实、推断和待确认问题。不能证明的内容不要塞进正文，应进入 open-questions.md。
优先证据来源：
- 源码、测试、迁移、配置、构建脚本。
- 已有 README、设计文档、接口文档。
understand-anything和codegraph的图谱结果。- 人类补充说明。
如果源码和旧文档冲突，以源码为准，并把冲突写进开放问题或 ADR。
完成标准
合格的历史项目文档，应让 agent 能回答这些问题：
- workspace 里有哪些项目、产品和微服务？
- 每个产品和微服务的职责边界是什么？
- 核心业务流程经过哪些模块和文件？
- 修改某类能力时应该召回哪些文档和源码？
- 哪些接口、配置、数据结构不能随意改变？
- 哪些结论证据不足，需要人类确认？
达到这个标准后，历史项目文档才从“给人看的总结”变成“项目级知识治理资产”。