本文针对大型历史项目（项目规模大、技术栈混乱、结构不清晰）的整改工作，梳理可落地、易理解的实操经验，明确整改目标、步骤及核心要求，为后续同类项目整改提供参考，同时约束后续功能迭代规范执行；本经验同样适用于新项目开发，可通过持续维护实现长期规范管理，助力AI高效生成符合要求的代码。

一、整改核心目标

1. 解决历史项目“技术栈不清晰、项目结构混乱”的痛点，提升项目可维护性；

2. 生成标准化文档，供AI后续生成代码时直接参考，避免重复扫描全局代码，提升开发效率；

3. 建立统一的开发规范（项目规则），约束后续功能迭代按规则执行，避免项目混乱加剧；同时适配AI阅读理解习惯，确保AI生成代码符合公司要求。

二、整改前提说明

• 项目范围：针对大型历史项目（如路径 xxx/compliance-parent/ 类项目），此类项目普遍存在代码量大、模块划分不清晰、技术栈零散等问题；同时本经验可直接复用至新项目开发，实现从初期就规范管理。

• 核心原则：无需全局扫描所有代码（避免冗余耗时），必要时仅读取关键模块代码，重点聚焦“结构梳理+规范建立”；规范建立需兼顾AI阅读理解习惯，便于AI快速适配。

• 文档存放路径：所有整改生成的文档，统一存放在项目指定目录下，便于后续查阅和使用，路径为：xxx/compliance-parent/项目结构/（新项目可参照此路径规范存放）。

三、整改实施步骤（分3步，清晰可落地，适配老项目+新项目）

第一步：梳理项目结构，生成《项目结构简要文档》

核心目的：明确项目整体架构，让AI和开发人员快速定位模块位置，避免重复扫描全局结构；新项目可在初始化阶段梳理结构并生成文档，后续随迭代持续维护。

• 文档名称：《项目结构文档.md》

• 文档存放路径：xxx/compliance-parent/项目结构/项目结构文档.md（新项目可按此路径规范存放，随模块新增、调整及时更新）

• 文档核心内容（简洁、分层清晰，适配AI快速读取）：

• 主要模块：拆分项目核心业务模块、公共模块、依赖模块，明确各模块核心作用；新项目可在初期规划模块，老项目按现有结构梳理，不强制修改原有结构。

• 包路径：记录各模块对应的具体包路径（如 com.xxx.compliance.xxx），便于快速定位代码；格式统一，方便AI识别。

• 职责说明：简要描述每个模块、每个包的核心职责，无需冗余细节，聚焦“定位+用途”，语言简洁规范，贴合AI阅读习惯。

第二步：总结开发规范，生成《开发技术规范文档》（核心为项目规则）

核心目的：建立统一的开发标准（项目规则），约束后续功能迭代，避免因规范不统一导致项目更加混乱；核心适配AI阅读和理解，确保AI按照符合公司规则的要求生成代码，同时区分老项目与新项目的规则适配逻辑。

• 文档名称：《开发技术规范.md》（又称项目规则文档）

• 文档存放路径：xxx/compliance-parent/项目结构/开发技术规范.md（新项目可按此路径存放，随公司规则更新、项目需求变化持续维护）

• 文档核心内容（贴合项目实际，可落地，适配AI阅读，区分老项目/新项目）：

• 技术栈说明：明确项目当前使用的核心技术栈（如后端框架、数据库、中间件、依赖包版本等），避免后续迭代引入不兼容技术；老项目按现有技术栈梳理，新项目按公司标准技术栈规划。

• 编码规范：统一代码命名规则（类、方法、变量、常量）、代码注释规范、代码格式要求；规则清晰、格式统一，便于AI识别和复用。

• 模块开发规范：明确各模块的开发标准（如接口开发规范、异常处理规范、日志输出规范）；贴合AI生成逻辑，减少AI生成代码后的修改成本。

• 迭代规范：后续功能迭代的流程、代码提交规范、测试规范，确保迭代过程有序；

• 项目规则适配说明（核心补充）：

  • 2.1 老项目适配：若老项目历史遗留问题多，不方便修改现有开发规则，梳理现有代码逻辑，让AI识别一套可复用的规则，后续生成代码时贴合老项目现有规范，不强制修改原有代码逻辑。

  • 2.2 公司已有沉淀：若公司本身已沉淀成熟的开发规则，直接整理这套规则，明确细节要求，让AI严格按照公司现有规则执行，确保代码生成的一致性和规范性。

第三步：文档落地与后续执行（老项目+新项目通用）

核心目的：让整改成果落地，确保后续开发和迭代严格遵循规范，发挥文档价值；同时实现文档的持续维护，适配项目全生命周期，助力AI长期高效复用。

• 文档使用：将《项目结构文档.md》和《开发技术规范.md》（项目规则）同步给所有开发人员，同时供AI后续生成代码时直接参考，无需重复扫描全局代码；老项目AI按适配后的规则生成代码，新项目AI按公司标准规则生成。

• 执行约束：后续所有功能迭代、代码修改，必须严格遵循《开发技术规范.md》；老项目可在原有规则基础上逐步优化，新项目从初期就严格执行规范。

• 文档维护：项目迭代过程中，若模块结构、技术栈、公司规则发生变更，及时更新对应文档，确保文档与项目实际、公司要求保持一致；新项目可随功能迭代持续完善文档，老项目可结合优化进度逐步更新，实现文档的长期复用。

四、整改注意事项（补充适配老项目+新项目）

• 避免全局扫描代码：历史项目代码量大，全局扫描耗时且无必要，重点梳理核心模块和关键代码即可；新项目初期代码量少，可一次性梳理完整，后续随迭代补充。

• 文档简洁实用：两份核心文档以“易读、易懂、可参考、适配AI”为原则，避免冗余内容，聚焦核心信息；规则描述清晰、无歧义，方便AI快速理解和执行。

• 规范落地优先：整改的核心不是生成文档，而是通过文档约束后续开发，确保项目长期可维护；同时兼顾老项目的兼容性和新项目的规范性，让AI生成的代码更贴合实际需求。

• 持续维护优先：无论是老项目还是新项目，文档（项目结构、项目规则）都需持续维护，随项目迭代、公司规则更新及时调整，确保AI每次生成代码都能参考到最新、最贴合的信息。