企业官网建设流程全解析

前言：

本节聚焦 AI 编程在存量项目维护与扩展中的应用。首先介绍什么是存量项目以及它为什么需要被特别对待，然后阐述存量项目维护的四大实践——补充项目说明书、补充测试、补充代码规范、参考现有代码，最后说明如何将这四大实践整合成系统化的工作流。

1. 存量项目的特点与挑战

1.1 什么是存量项目

存量项目是指已经上线运行、维护时间较长、代码量较大的已有系统。这类项目通常具有以下特点：

1. 代码结构复杂：经过多任开发者之手，架构可能已经偏离最初设计。
2. 文档缺失或不完整：关键设计决策散落在代码注释或老员工的记忆中。
3. 技术栈可能过时：使用了旧版本的框架或库，与当前主流技术栈有差距。
4. 新人上手困难：理解代码需要较长的学习周期。

存量项目是真实世界中最常见的项目形态。根据行业统计数据，企业中约70%~80%的开发工作是在维护和扩展已有系统，而非从零构建新项目。因此，学会用 AI 高效维护存量项目，是 AI 编程能力中最重要的组成部分。

1.2 存量项目为什么需要被特别对待

在增量开发中（新功能从零开始），AI 通常表现良好，你可以给它完整的上下文，让它生成风格一致的代码。但在存量项目中，情况要复杂得多，会存在很多问题，具体如下：

• 问题 1：AI 不了解项目的历史约束。存量项目中存在大量“隐性知识”，也就是那些在代码中体现但从未被文档化的设计决策。例如，为什么这个接口用了 POST 而不是 GET？为什么这个字段叫user_id而不是uid？为什么要在这里加缓存？这些决策背后往往有其合理性，但如果 AI 不知道这些约束，那么它生成的代码可能会“技术上正确”而“业务上错误”。
• 问题 2：AI 会引入风格不一致的代码。在没有约束的情况下，AI 会根据训练数据中的“统计平均”来决定代码风格。每次生成的代码风格都有可能略有差异，长期积累会破坏代码库的一致性，增加维护难度。
• 问题 3：直接修改可能导致回归问题。存量项目往往缺乏完整的测试覆盖。贸然让 AI 修改某个模块，有可能破坏已有的隐式依赖，导致意想不到的回归问题。

这些问题不是 AI 能力不足导致的，而是因为 AI 没有获得足够的项目上下文。解决这些问题的方法，就是下面将要介绍的四大实践。

2. 存量项目维护的四大实践

经过大量工程实践验证，用 AI 维护存量项目的最佳策略可以归纳为四大实践，如图 1 所示。为什么是这四大实践？因为这四大实践分别解决了存量项目维护中的不同问题：

1. 补充项目说明书解决的是“AI 不了解项目背景”的问题。
2. 保持环境健康解决的是“修改缺乏安全保障”的问题。
3. 补充代码规范解决的是“代码风格不一致”的问题。
4. 参考现有代码解决的是“AI 输出质量不稳定”的问题。

图 1：用 AI 维护存量项目的四大实践

四大实践互为补充，缺一不可。下面逐一介绍每种实践的具体方法和注意事项。

2.1 实践 1：补充项目说明书

如果你的项目还没有项目说明书，第一步就是为项目创建一份。项目说明书的价值在于：它是一份“项目入门手册”，让 AI 能够像了解项目的新成员一样工作。那么，存量项目的项目说明书应该包含什么？与新项目不同，存量项目的项目说明书需要特别关注以下几点：架构决策记录、关键模块的职责说明、技术债说明、代码审查要点。

（1）架构决策记录

存量项目中存在大量“当年为什么这么做”的设计决策。这些决策往往是踩坑后的经验总结，但从未被正式记录。在项目说明书中补充这些决策，能帮助 AI 避免“重复踩坑”。具体示例如下：

## 重要架构决策 为什么订单模块不使用软删除？ 订单数据有财务合规要求，必须保留完整历史，不能物理删除。 → AI 必须理解：任何涉及订单删除的功能，都必须是软删除或状态标记。 为什么用户模块有 user_id 和 uuid 两个标识符？ user_id: 内部使用，int 类型，自增，供数据库 join 使用。 uuid: 对外暴露，string 类型，用于 API 响应和前端交互，防止 ID 枚举攻击。 → AI 必须理解：不能随意替换这两个字段。

（2）关键模块的职责说明

存量项目中，某些模块的职责边界可能不清淅。在项目说明书中补充关键模块的职责说明，可帮助 AI 理解“这个模块负责什么，不负责什么”。具体示例如下：

## 关键模块职责 UserService (src/services/user_service.py) 负责：用户注册、登录、权限校验、资料修改。 不负责：订单处理（属于 OrderService）、消息推送（属于 NotificationService）。 → AI 必须理解：不能在 UserService 中直接操作订单数据。

（3）技术债说明

存量项目中必然存在技术债。在项目说明书中诚实说明这些技术债，能帮助 AI 在必要时避开它们。具体示例如下：

## 已知技术债 [ ] 旧版支付模块 (src/payment_v1/) 使用同步调用，已计划迁移到 payment_v2。 新功能禁止在 payment_v1 上继续开发。 [ ] 缓存层目前使用 Redis 字符串，建议迁移到 Hash 结构（已在 backlog 中）。 → AI 生成缓存代码时，可以参考现有模式，但不需要改进架构。

（4）代码审查要点

存量项目的代码审查往往有一些特别需要注意的点。在项目说明书中补充这些审查要点，可帮助 AI 生成更容易通过审查的代码。具体示例如下：

## 代码审查关注点 订单模块 必须保留审计日志（谁、什么时候、做了什么修改）。 金额计算必须使用 Decimal，禁止使用 float。 用户模块 敏感字段（密码、手机号）不得出现在日志中。 用户注销必须走软删除流程。

2.2 实践 2：保持环境健康

存量项目的一个普遍问题是测试覆盖不足。在用 AI 修改存量项目之前，首要任务是确保项目处于“干净可用”的状态，这是防止 AI 破坏已有逻辑的第一道防线。

为什么环境健康如此重要？主要有以下几方面的原因：

1. 建立质量基线：测试让开发者知道“修改前的行为是什么”，从而开发者可判断“修改后的行为是否正确”。
2. 防止回归：完整的测试套件能快速发现 AI 修改引入的问题。
3. 降低心理负担：有测试保护，开发者更敢于接受 AI 的修改。

具体而言，在让 AI 开始工作之前，需要确保以下几点：

1. 程序可编译：代码没有语法错误，能够正常运行。
2. 已有测试通过：运行现有测试套件，确保全部通过，这是验证存量逻辑未被破坏的基准线。
3. 环境干净：没有遗留的临时文件、未提交的改动或正在运行的进程。

在 AI 修改代码后，立即重新运行测试套件，确认已有测试依然全部通过。如果测试失败，则说明 AI 的修改引入了回归问题，需要及时修复。

2.3 实践 3：补充代码规范

存量项目可能已经有一套代码规范，但这些规范往往只存在于代码审查文档或老员工的记忆中，并没有被正式记录下来。将代码规范补充到规则中，能让 AI 自动遵守这些规范，减少风格碎片化。

那么，如何识别存量项目的代码规范呢？代码规范往往体现在现有代码中。阅读代码时，注意以下几方面：

1. 命名约定：变量、函数、类的命名风格。
2. 错误处理方式：是否使用自定义异常、是否记录日志。
3. 文档风格：是否有 docstring、使用什么格式。
4. 依赖管理：是否禁止使用某些库。

需要将规范固化为规则，识别出规范后，将其写入规则文件。具体示例如下：

--- alwaysApply: true --- 项目编码规范 命名规范 (已通过代码审查确认) 函数名: snake_case (如 get_user_by_id)。 类名: PascalCase (如 UserService)。 常量: UPPER_SNAKE_CASE (如 MAX_RETRY_COUNT)。 错误处理规范 业务错误使用自定义异常 (继承 AppException)。 禁止使用 "raise HTTPException" (在 API 层统一处理)。 捕获异常后必须记录日志。 文档规范 所有公共函数必须有中文 docstring。 docstring 格式: 功能描述 + 参数说明 + 返回值说明。

2.4 实践 4：参考现有代码

在存量项目中，让 AI 参考现有代码而不是“从零创作”，是提升输出质量最有效的方法。这个理念最初被形象地称为“胶水编程”，AI 的主要工作是把现有代码“粘”到新的业务场景上。

什么是“胶水编程”呢？“胶水编程”是一个很早就有的概念，指的是用少量代码将已有的模块、库或服务连接起来形成一个完整系统。在 AI 时代，这个概念重新火了起来，因为 AI 特别擅长“照着做”，只要给它一个高质量的参照物，它就能生成风格一致的代码。为什么“照着做”有效呢？这是因为，大语言模型的工作方式是在给定上下文的条件下预测下一个最可能出现的词汇，当你提供高质量的参照代码时，模型的预测空间被大幅收窄，它会倾向于生成与参照代码结构和风格高度一致的输出。

在提示词中提供参考代码的具体示例如下：

## 任务
参照以下“用户管理”模块的实现，为“商品管理”创建类似的功能。

## 约束

• 严格遵照参照代码的结构、命名风格和错误处理模式。
• 不要引入参照代码中没有的设计模式。

## 参照代码
[粘贴 user_service.py 的完整代码。]

## 差异说明
(1) Product 没有密码字段，去掉所有密码相关逻辑。
(2) Product 需要额外的库存扣减方法。
(3) Product 的删除是软删除。

参考现有代码时要注意以下 3 个事项：

1. 确保参照物质量过关：如果参照代码本身有问题，AI 会复制这些问题。
2. 明确指出差异点：不要让 AI 自己猜测哪些地方需要调整。
3. 重点审查差异部分：AI 在“复制”部分通常没问题，问题往往出在“定制”部分。

3. 存量项目维护的工作流

现在将四大实践整合成一个系统化的工作流，如图 2 所示。

图 2：存量项目维护工作流

一个实用的经验法则是，在存量项目中，使用 AI 修改代码前，应自问：这份项目说明书和规则是否已经包含足够的上下文？如果没有，先补充它们，再让 AI 执行。这个顺序很重要，先建立上下文，再进行修改，能显著降低引入问题的风险。

希望这篇整理后的内容符合你的博客发布需求！如果有其他章节需要整理，随时发给我。