AI 编程
如何使用 AI 为遗留软件编写文档
一套基于代码和运营证据使用 AI 为遗留软件编写文档的流程，覆盖架构、数据流、隐性业务规则、依赖、运行手册，以及不靠猜测的事实验证。
遗留软件的真实行为分散在代码、数据库、任务、配置、部署脚本、客服知识和运维人员经验中，因此很难靠一份架构概述讲清楚。团队需要知道系统做什么、关键规则在哪里、数据如何流动、失败如何处理，以及怎样安全验证变更。
AI 编程工具能够跨文件整理大型代码库，但也可能给出听起来合理却不正确的解释。可靠方法是证据优先：重要结论必须指向代码、Schema、配置、遥测或经过确认的领域专家。
明确文档要支持的目标
先确定读者和用途。新工程师需要导航图；运维人员需要部署、监控、恢复和升级流程；迁移团队需要系统边界、数据所有权、兼容约束和隐性规则；审计人员可能需要访问控制和数据血缘。
第一轮只选择一个关键流程及其依赖。一次要求覆盖整个遗留系统，通常只会得到浅层且很快过时的页面。
保护密钥和生产数据
只使用获准访问仓库的 AI 环境。排除密钥、私钥、生产导出、个人信息、客户 Payload 和机密日志。配置名称可能有用，但真实值通常不需要。发现阶段保持只读，并明确禁止连接生产、安装依赖、执行破坏命令或仅根据名称推断行为。
建立有证据的系统清单
检查仓库规范、Manifest、路由、入口、Schema、Migration、服务、任务、集成客户端、测试、部署文件和运维脚本。先识别组成部分，再解释它们如何协作。
使用这个英文 Prompt：
Act as a software archaeologist. Inspect the supplied repository evidence and create a system inventory covering entry points, services, data stores, queues, scheduled jobs, external integrations, authentication boundaries, configuration, deployment artifacts, and tests. For every statement, cite the file, symbol, schema, or command that supports it. Mark anything not proven by the repository as unknown. Do not change code.
让实际运维过系统的工程师审核清单，确认重命名服务、废弃模块、生成文件和只在特定环境启用的路径。
梳理架构和责任边界
先画出用户、遗留系统、外部系统和主要数据存储的上下文，再列应用、API、Worker、队列、定时任务和数据库。图应足够简单，才能持续维护。
对每个组件记录职责、负责人、运行环境、部署单元、上游输入、下游依赖、数据分类、健康信号和仓库位置。没有负责人时应明确标为缺口，而不是默认指向最近修改代码的人。
追踪关键业务流程
选择对客户、收入、合规或运营影响最大的流程，例如开户、下单、开票、权益变更、退款、数据导入或月末处理。从触发点一直追到最终状态。
Trace this business workflow through the legacy system: [workflow]. Start at the user or system trigger and follow UI, API, validation, service logic, database reads and writes, background jobs, integrations, retries, and final user-visible state. List the exact files or symbols at every step, identify hidden business rules, and flag branches that require runtime verification.
使用测试、受控本地运行、Staging 遥测或运维走查进行验证。静态代码无法完整显示 Feature Flag、运行时配置、数据库触发器、外部回调和人工调度。
提取隐性业务规则
遗留规则常藏在条件判断、状态转换、校验消息、SQL 过滤、Cron、表格交接或客服流程中。为每条规则记录稳定编号、自然语言说明、证据位置、影响流程、负责人、例外、测试覆盖和最后核实日期。
不要为了文档好看而简化混乱规则。先记录系统当前实际行为，再单独记录业务方认为它应该如何工作，这对安全迁移非常重要。
记录数据模型与血缘
梳理关键实体、标识符、关系、生命周期状态、保留要求和权威系统。对关键字段记录创建、转换、校验、存储、暴露和删除位置，并包括会影响行为的触发器、视图、缓存、搜索索引和导出。
使用代表性 Schema，不使用真实客户记录。确认时间戳、币种、时区、Null 和历史行是否具有特殊含义，这些细节经常造成迁移缺陷。
记录集成和失败行为
对每个外部集成记录认证方式但不记录密钥值，并说明请求响应、超时、重试、幂等、限流、Webhook 校验、对账和失败责任。标明哪些失败会立即展示给用户，哪些会变成延迟运营任务。
让 AI 寻找“外部调用成功但本地写入失败”以及相反情况，再用代码和测试验证。没有证据证明幂等时，不能假设重试安全。
编写部署与运维手册
记录环境建立、配置注入、发布、Migration 顺序、健康检查、告警路由、回滚或前向修复。每一步包含前置条件、命令、预期输出、停止条件和按角色定义的升级联系人。
在非生产环境执行手册。没有真正运行过的 Runbook 只是草稿，应记录验证日期和责任团队。
建立新人上手路径
把文档组织为系统上下文、术语表、本地设置、只读走查、关键流程、常见故障和一个小型安全变更。链接到权威页面，不要在多个位置复制同一段内容。
维护文档地图，说明每类信息由哪一页负责，避免 README、Wiki、Runbook 和迁移计划互相矛盾。
用证据审查每项结论
最后让 AI 做矛盾和时效性审查：
Review this legacy system documentation against the supplied code and operational evidence. Find unsupported claims, stale names, missing failure paths, undocumented dependencies, secrets or personal data that should be removed, and instructions that cannot be reproduced. Return findings by severity with the evidence and the smallest documentation correction. Do not edit code.
人工抽查重要结论、链接、符号、命令和图。对过时后可能造成事故的页面设置负责人和复查日期。
实际示例
团队计划替换计费服务，旧文档只写“夜间任务创建发票”。代码追踪发现还有队列触发的即时用量调整、后台路由创建的人工贷项，以及将状态复制到账本表的数据库触发器。
记录这四条路径后，迁移团队不会只搬走明显的 Cron 而丢失调整和账本历史。AI 加快了发现，测试与运维审核则确认了哪些路径仍在运行。
质量检查清单
- 重要结论指向代码、Schema、配置、遥测或已确认专家。
- 当前行为与未来目标明确分开。
- 关键流程覆盖成功、失败、重试和恢复。
- 数据血缘标明权威系统和转换点。
- 集成文档包含幂等与对账。
- Runbook 有预期输出、停止条件和验证日期。
- 文档不包含密钥或个人数据。
- 页面有负责人和可执行的时效策略。
常见错误
- 没有仓库证据就要求 AI 总结架构
- 把文件名和函数名当成运行行为证明
- 只记录成功路径
- 将生产记录或密钥复制进 Prompt
- 忽略触发器、队列、Flag 和人工运营
- 为了易读而改写真实的混乱规则
- 生成大量无人负责的 Wiki 页面
- 把迁移建议混进当前事实基线
常见问题
**AI 能自动记录整个代码库吗？** 它可以创建初始清单，但没有范围、证据要求和人工核实的大规模自动文档并不可靠。
**文档应该和代码放在一起吗？** 稳定技术契约和 Runbook 适合版本控制，业务背景可以放在其他系统。关键是每个主题只有一个权威位置和明确负责人。
**多久复查一次？** 相关代码、基础设施、集成或运营变化时立即复查，并定期验证关键 Runbook 与所有权。
**同一文档可以支持迁移吗？** 可以。先冻结有证据的当前状态，再单独制作目标架构、差距分析和迁移计划。