Posted by: Phodal Huang April 29, 2025, 1:45 p.m.

AI 友好架构是一种将成熟的软件架构原则与生成式 AI 的能力相结合并进行调整的软件构建方法。其核心目标是创建一个既便于人类协作，又能被 AI 高效理解、分析、生成和持续演进的代码资产与系统环境，从而显著提升开发效率。

生成式 AI 在你的代码库上工作不好存在诸多原因，其中一个就是：你的代码库不够 AI 友好。而除了 AI 不友好之外，它存在的另外一个问题就是： 对于人类来说也不友好。 工作于代码库的团队没有保持一致的规范与最佳实践，导致了代码库的可读性差、可维护性差、可扩展性差等问题。

软件工程：团队实践优于最佳实践

软件工程并没有所谓的真正最佳实践，只有适合于团队的实践。在使用 AI 之前，我们有必要对团队现有的软件工程实践进行一个简单的梳理。

代码命名规范的产生：构建统一的语言

举我们最简单的金融场景作为示例，你有一个产品名称：稳享灵动慧利，那么你的代码应该怎么写：

• 直接翻译：SteadilyEnjoyAgileWisdomAndBenefits
• 挑选重点：AgileBenefitController
• 拼音全称：WenXiangLingDongHuiLi
• 拼音首字母：WXLDHL
• ……

通常来说，方案 1 和方案 2 肯定不是你的首选，因为你的 Tech Lead/架构师会告诉你：其他人看不懂 —— 并不止是考虑到外包或者新手程序员，还要考虑其他 人查找代码时也会一脸懵逼。方案 3 和方案 4 是最常见的选择，所以只要团队达成一致即可。

代码检视在检视什么：维护团队最佳实践

当拼音达到了某种默契之后，会达到另外一种泛滥：用户会被翻译为 YongHu，或者作为福建人经常遇到的梗：YongFu。那么，如何去避免这个问题呢？一种 简单的方法是：代码检视。在这种场景下，你使用 Sonarlint 之类的工具，并不能很好地帮助你解决这个问题，所以我们会依靠于代码检视在一定程度上解决 这个问题。

我们预期代码检视的目的是：

• 规范一致性：命名规范、代码风格、注释规范等
• 保持最佳实践：通用逻辑模式采用、代码重用等
• 业务逻辑正确：代码修改是否符合业务逻辑
• 潜在的 bug：逻辑错误、性能问题等

通常来说，你很难通过代码检视来发现潜在的 bug：

• 多数人很难深入了解业务逻辑，难以考虑到所有的边界条件
• 代码检视的时间有限，无法覆盖所有的代码

所以，多数情况下，代码检视的目的并不是为了发现 bug，而是为了让团队达成一致的规范与团队最佳实践。

遏制面条式代码：分层筑结构，内聚定边界

我们常常在微观细节上追求代码质量，却可能忽视了宏观架构的持续“腐化”，导致可维护性下降，最终陷入“面条式代码”的困境。这往往是因为我们未能 从结构层面思考：新代码应置于何处？ 相关逻辑应如何组织？ 错误的放置和无序的增长，不仅使代码超出人类的认知极限，也让 AI 难以有效理解和介入。

应对之道在于构建清晰的结构，这主要依赖于两个相辅相成的策略：

1. 架构分层 (Layering)：在宏观上，通过分层（如表现层、业务逻辑层、数据访问层）来划分系统的主要职责区域 。这强制性地隔离了不同类型的关注点（例如，界面逻辑不应与数据存储逻辑混合），为代码库提供了高层级的秩序和导航图。
2. 逻辑内聚 (Cohesion/Aggregation)：在微观上，即在各层内部，强调内聚性。这意味着功能上紧密相关的代码单元（类、函数、模块）应该聚合在一起 。例如，所有处理“用户认证”的逻辑应集中管理，而不是散落在各处。这确保了模块功能的单一性和明确性。

分层定义了“社区”（不同职责的大区域），内聚则定义了“家庭”（功能相关的小单元）。

当现有的设计不够时，重构变成了我们改进的手段，以将不同职责的代码，按照逻辑关系，清晰地划分到不同的“层”或者“模块”中去。

尝试并理解 AI 代码生成的限制要素

通常来说，在我们使用 AI 进行编程时，会分为多种方式：

• 网页聊天式生成：即 ChatGPT 之类的网页聊天式生成，其特点是需要手动输入上下文
• IDE 插件式生成：即在 IDE 中直接生成代码，可以选择上下文，或者自动选择上下文

两种模式的核心差异在于是否带有用户的上下文信息。

理解基于上下文的 AI 代码生成：龙生龙，凤生凤

在使用 AI 插件的代码补全时，你会明显发现：生成的代码质量优于 ChatGPT 之类的网页聊天式生成。以 AutoDev 示例项目 假设我们希望生成一个新的 API 接口：delete blog 接口，那么我们会在 getBlog 的结束处添加一个注释： Untitled 工程中的 BlogController 为例。

@RestController
@RequestMapping("/blog")
public class BlogController {
    BlogService blogService;

    public BlogController(BlogService blogService) {
        this.blogService = blogService;
    }

    @ApiOperation(value = "Get Blog by id")
    @GetMapping("/{id}")
    public BlogPost getBlog(@PathVariable Long id) {
        return blogService.getBlogById(id);
    }
    // delete blog by id

随后，触发 AI 模型的补全或者模型生成，生成的代码如下：

    @ApiOperation(value = "Delete Blog by id")
    @DeleteMapping("/{id}")
    public void deleteBlog(@PathVariable Long id) {
        blogService.deleteBlogById(id);
    }

其中的 @ApiOperation 便是根据我们前面的代码规范而生成的附加代码，在 deleteBlog 这个方法名同样会受到我们前面代码命名规范的影响。 也因此，当你基于别人的代码修改时，会发现 AI 的质量可能不如你预期的那么好。好的代码会让 AI 生成更好的代码，而屎山则更容易让 AI 生成屎山。当两种类型（规范好和差）的代码非常好的混合在一起时，你就只能靠运气了。

如果你预期 AI 生成一大段代码（多个方法）时，当缺乏足够的上下文时，补全式模型的效果会大打折扣，诸如于生成不存在的方法。而现在的补全式模型往往为了效果更好 ，所以会过度拟合，进而导致难以生成大段代码。

理解好的问题表达的重要性：欲速则不达

在生成式 AI 时代，问题表达的质量直接影响生成代码的质量。我们在使用 AI 进行编程时，通常会面临两种情况：

• 模糊的需求描述：如 “实现一个用户管理功能”，AI 可能生成不完整或不符合预期的代码。
• 问题过于急迫或简单：希望通过简短的指令迅速得到代码，这种做法往往会导致生成的代码存在许多潜在问题。

在 AI 帮你实现用户管理功能时，他需要先能通过当前的代码库理解什么是用户，什么是管理，才能有限地根据你的需求生成代码。否则，AI 会根据自己的理解 随机生成代码，导致质量不高。

因此，首先我们需要定义：在生成式 AI 时代，什么是好的问题？（这个可以交给 AI 来研究，诸如 Google DeepResearch）。

核心要素初步识别

通过初步搜索，我发现了一些构成有效 AI 提示的关键要素，例如清晰的任务指令、充分的背景信息、具体的细节描述、明确的角色设定、 期望的输出格式以及所需的语气和风格。此外，提供范例和设定约束条件也是很重要的技巧。

简单来说就是好的提示词技巧。有效的提示词需要清晰和具体，诸如于：

• 明确任务指令: 清晰地说明希望 AI 完成的具体任务（如“编写一个 Python 函数”、“重构这段 Java 代码”、“生成 SQL 查询”）。避免使用模糊或歧义的语言。
• 提供充分背景信息 (Context): AI 需要上下文来理解任务所处的环境。这包括：
  • 项目背景: 告知 AI 项目的目标、使用的技术栈（语言、框架、库版本）、架构模式等。
  • 现有代码: 提供相关的现有代码片段、接口定义、类结构或函数签名，让 AI 了解当前的实现方式和约束。
  • 领域知识: 如果任务涉及特定业务领域，提供相关的领域术语、规则或概念（如 DDD 中的通用语言）。
• 具体细节描述: 详细说明需求，包括输入、输出、预期行为、需要处理的边界条件或错误情况。例如，不仅仅是“计算阶乘”，而是“编写一个 Python 函数 factorial，接受一个整数 n 作为输入，返回 n 的阶乘。确保处理 n 小于 0 的情况，返回 None”。

结合这些提示词工程技术，特别是充分利用现有代码库的上下文和领域知识，可以显著提高 AI 生成代码的准确性、相关性和质量，使其更好地融入项目。

理解受限的小参数理解能力：巧妇难为无米之炊

PS：如这里的子标题，我们借助于 ChatGPT 生成了歇后语。

在现今的 AI 辅助编程工具里，通常会带有大量的不同模型，诸如于：补全、FastApply、聊天、推理等。不同模型参数不一，有的模型参数高达 175B，甚至更高，而有的模型则只有 6B。通常来说，参数越大，模型的理解能力越强。诸如于网传的早期的 Copilot 应用中：补全采用的是 ~ 12B 的模型 Codex，而补全采用的是 ~175B 的模型 GPT-3.5。当你的参数量变小以后，比如采用的是 3B 的补全，模型很难理解复杂的需求，又或者是对于中文的理解能力变得非常有限。在这种时候，可能会出现类似于，你 使用简单的中文描述，模型却无法理解的情况。

当你想实施复杂的需求时，你就需要借助于参数大的模型来构建。因此，模型越大，生成质量越好，但是速度越慢；针对不同场景，需要不同生成策略

构建 AI 友好编程：从实践到模式

通过一篇文章来介绍 AI 友好型架构是一种困难的事，我将尽可能使用模式来抽象，以便于你在不同的场景下进行使用。 这些模式的目标是创建一个既便于人类协作，又能被 AI 高效理解、分析、生成和持续演进的代码资产与系统环境。

模式：领域知识丰富上下文与问题定义

问题：用户的需求描述往往模糊不清，AI 难以理解其意图，导致生成的代码质量不高。

实践方式：领域语言与提示词工程优化用户输入

解决方案：通过应用领域驱动设计（DDD）的原则，将复杂的业务领域知识显式化、结构化，为 AI 提供更丰富、更精确的上下文信息， 从而提升其对需求的理解和生成代码的质量。

实现示例：在 AutoDev 中，我们通过 AI 生成领域术语表，用户在输入内容后，可以选择优化提示词来丰富上下文信息。

1. 构建术语表。通过静态代码分析拿到所有的类名、函数名信息，交给模式来分析理解和生成，生成 domain.csv，包含中英文和描述信息。
2. （可选）用户介入编辑术语表。
3. 优化提示词。用户在 AutoDev 的输入框内，点击优化提示词后，即可以将上下文信息带入需求中。

举例：用户的需求是：“实现一个用户管理功能”，那么可以结合领域知识，利用 DDD 的通用语言（Ubiquitous Language），将其重新定义为：实现一个“用户账户管理”的功能，包含“用户注册 (Customer Registration)”、“用户激活 (Account Activation)”、“用户资料更新 (Profile Update)”等。即通过领域术语来丰富需求描述，提供更清晰的上下文信息。

详细定义示例：“（角色：资深 Java 工程师）使用 Spring Boot 框架，实现一个‘客户账户管理’限界上下文的核心功能，包括： （1）处理 POST 请求 /customers/register 用于客户注册 (Customer Registration)，接收包含'name', 'email', 'password' 的 JSON，验证 email 格式和密码强度，成功后保存至数据库并发布‘CustomerRegistered’领域事件。（2）处理 POST 请求 /accounts/activate/{token} 用于账户激活 (Account Activation)……” 这种方式提供了更清晰的业务术语、技术约束和具体行为描述。

实践方式：将需求工程应用于 AI 交互

解决方案：在 IDE 连接在线的需求相关的工具（如 Jira、Confluence、Notion 等），将用户的输入/需求转换为检索条件（如关键词），调用在线的工具 进行检索，获取相关的需求信息，再将用户的输入转换为带完整需求上下文信息的提示词，交给 AI 进行处理。

实现示例：在 Cursor、Copilot、AutoDev 等工具中，可以通过自定义 Agent、MCP 等工具，让用户可以接入自己的需求工具、智能体，以让用户 按照自己的需求进行检索。

1. 用户构建自己的 Jira MCP 服务器
2. 将 MCP 服务器配置到项目中使用
3. 将检索到的 Jira Issue 的摘要、验收标准（Acceptance Criteria）、附件设计文档等内容，按照“领域术语表 + 需求模版”格式汇总，交由模型来处理。

举例：用户输入：“添加支付提醒功能”，可以由工具来提示：在 Jira 中找到 2 条相关 Issue：PAY-102、INVOICE-58，是否将它们的描述和验收标准作为上下文？[是/否]？ 由用户来进行确认是不否进行关联，并进一步优化提示词。

模式：基于项目知识与规范的智能生成

问题：AI 编程助手通常缺乏对特定项目的深入理解，包括其编码规范、技术栈选型、架构设计、领域术语、历史决策以及团队约定等。当开发者与 AI 交互时， 若不手动提供这些上下文，AI 生成的代码或建议往往是通用的，可能不符合项目标准、引入不兼容的技术、或与现有架构冲突。反复手动提供完整上下文效率低下且易遗漏关键信息。

解决方案：构建一个系统性的框架，使 AI 助手能够自动、持续地获取并利用项目特定的知识和规则，从而将其响应“锚定”在项目的实际环境中。

实践方式：借助 Project Rule 预先定义项目上下文

问题：在每次与 AI 交互时手动提供完整的项目特定上下文（编码规范、技术栈、架构模式、API 约定等）效率低下且容易遗漏，导致 AI 生成的代码不符合项目要求或团队标准。

解决方案：利用现代 AI 编码助手提供的“项目规则”或“自定义指令”功能，预先定义项目上下文信息，使 AI 能够自动加载并遵循这些规则。这需要结合有效的知识捕获和管理策略， 并通过检索增强生成（RAG）技术将知识提供给 AI。

实现示例：利用现代 AI 编码助手提供的“项目规则”、“自定义指令”或类似配置功能。

举例：在项目特定位置（如 .cursorrules, .github/copilot-instructions.md, IDE 设置）创建配置文件。其可能包含以下内容：

• 规则内容: 使用自然语言（常为 Markdown）描述：
  • 编码规范与风格指南: 如命名约定、代码格式化标准。
  • 技术栈与库约束: 指定使用的框架、库版本，禁用或推荐特定库/API。
  • 架构模式与设计原则: 如微服务、事件驱动，DDD 限界上下文划分，SOLID 原则的特定应用。
  • API 使用约定: 内部/外部 API 的调用方式、认证要求、数据格式。
  • 错误处理策略: 标准的异常处理流程、日志记录级别与格式。
  • 领域术语: （可链接到第一个模式中的术语表）项目的核心业务术语及其含义。
• 作用域管理: 支持全局、项目级、特定文件类型/路径的规则设置，甚至动态激活规则（如 Cursor）。

通过有效利用这些 AI 代码助手内置的规则配置功能，团队可以显著提升 AI 代码助手的实用性和可靠性，使其更好地融入特定项目的开发流程。

实践方式：持续的项目知识捕获与注入

解决方案：让 AI Agent 能够利用项目中不断积累和演变的动态知识，以及用户偏好，理解更深层次的背景、决策逻辑和隐性经验。

实现机制：利用 AI Agent 的 "Memories" 功能，将关于工作区和用户偏好的关键信息持久化存储在本地（例如，可能存储在项目下的 .augment 文件夹内的 augment.memories 文件中）。系统会自动学习并更新这些记忆，同时用户也可以通过直接编辑记忆文件、点击交互界面中的 按钮或向 Agent 发出明确指令来手动管理记忆内容。这些存储的记忆随后作为检索增强生成（RAG）的关键知识源：系统在处理请求时会检索相关的记忆， 并将其与当前上下文（如代码库信息）一同注入给大语言模型，从而生成更符合用户需求和项目背景的响应。

举例：诸如 Augment 的 Memories 会记录用户在对话中的关键细节，以 augment.memories 保存在项目中，以供后续对话时使用。 以下是之前记录的一些具体用户偏好示例，这些都可能被存储在 augment-memories.md 中：

• The user wants to use jetBrains jewel repository as a reference for fixing project errors.
• Use JetBrains JewelUI components exclusively instead of Material components.
• The user wants to use a send button icon from JetBrains jewel instead of a restart icon.

潜在的挑战：记忆污染/损坏：自动学习可能出错，手动编辑也可能引入错误；透明度不足：难以完全理解记忆内容及其影响；管理开销： 需要用户主动监控和清理，增加负担；安全风险：本地文件可能成为提示注入的目标。

小结：手动的知识获取

需要强调的是，“项目知识驱动的上下文注入”模式的成功实施，高度依赖于团队持续进行有效的知识管理。这包括对显式知识 资源（如项目文档、知识库、代码注释、设计规范）的系统性维护，以及对隐式知识 （蕴含在团队经验、历史决策、沟通讨论、开发实践中）的挖掘与沉淀。只有当这些项目知识被有效捕获并变得可访问时，“项目规则”和“Agent Memories”等上下文注入机制才能发挥最大效用，（通常通过 RAG 技术）为 AI 提供准确、丰富的上下文信息。

模式：自文档化代码增强语义化表达

问题： 传统的软件文档（如外部规格说明书、设计文档、注释文件）往往与代码实现不同步，维护成本高，信息滞后 。代码作为开发者沟通的核心媒介，如果本身不够清晰，会导致其他开发者（或 AI 工具）难以理解其功能、意图和交互方式，增加了认知负荷和维护难度 。

实践方式：语义化命名与结构化设计

解决方案： 让代码本身成为其最主要、最准确的“文档” 。通过系统性地应用一系列编码实践（如清晰命名、良好结构、明确类型、策略性注释等），使代码的结构、命名和表达方式尽可能清晰、直观，从而让阅读者能够直接通过阅读代码来理解，减少对外部解释的依赖 。

实现示例：

• 命名规范：使用描述性强的变量、函数和类名，如 calculateInvoiceTotal() 而非 calc()。
• 结构化设计：遵循设计模式（如 MVC、MVVM）和编码规范，确保代码模块化、可重用。

实践方式：适应于 AI 理解的编程范式

问题：传统编程往往隐含许多假设：函数输入参数的有效范围、返回值关系等没有明确定义。调用者或开发者难以预知这些假设，一旦违背前提就可能引发错误。AI 辅助生成的代码也无法知道这些潜在契约，可能产生行为不可预测的实现。

解决方案：在代码中显式定义前置条件（Precondition）、后置条件（Postcondition）和不变量（Invariant）。例如，在函数签名或注释中声明参数要求， 在关键位置加入断言（assert）或使用契约库。这样函数的期望行为清晰可见，任何调用都必须满足前置条件，保证后置结果符合预期。明确的契约既约束了代码正确性，也为 AI 提供了语义线索。

实现示例：

• 利用类型系统 (Type Systems)：在静态强类型语言（Java, C#, TypeScript）中，明确的类型注解提供了关于数据结构、函数签名和预期数据流的强形式化信息，AI 可利用这些信息生成类型安全且符合接口的代码。
• 采用契约式设计 (Design by Contract, DbC)：通过嵌入形式化的前置条件 (requires)、后置条件 (ensures) 和不变量 ( invariant)，精确描述组件的责任和期望行为。
• 拥抱函数式编程 (Functional Programming, FP) 原则：
  • 纯函数： 无副作用，输入相同则输出相同，简化 AI 的推理过程。
  • 不可变性： 避免状态修改，使代码状态更易预测和跟踪。
  • 高阶函数与组合： 模块化和声明式风格可能更易于 AI 理解结构和意图。

语义丰富性与实用性的权衡：像高级类型系统和 DbC 这样的技术为 AI 提供了显著更丰富的语义信息，但与基本的命名约定或注释相比，它们的采用成本和复杂性更高。AI

的理解能力随着更明确的语义信息的增加而提高。

模式：验证优先开发（Validation-First Development）

验证优先开发（Validation-First Development，简称 VFD）是一种针对 AI 生成代码固有不确定性与幻觉现象而设计的软件开发模式。它以“生成-审查-测试-优化”为核心循环，强调 先快速生成，再严格验证与优化，通过多轮迭代保障最终软件产出的正确性、可靠性与可维护性。

在代码生成语境下，幻觉指的是 AI 生成了看似合理但实际上是错误的、不存在的、无意义的或者与事实不符的代码、API 调用、库引用、配置项或逻辑片段。例如，AI 可能自信地使用一个虚构的库函数，或者实现一个听起来合理但算法逻辑完全错误的排序方法。 这种现象源于大型语言模型基于模式匹配和概率预测的本质，而非真正的理解或推理。

背景问题：传统开发方法论（如 TDD、BDD）强调精确的预先定义和确定性实现，难以适应 AI 代码生成固有的概率性及其可能产生的“幻觉”（即看似合理但实际上错误的代码）。
直接将未经充分验证的 AI 生成代码集成到系统中，存在质量、安全性和合规性风险，容易快速积累技术债务。

实践方式：生成-审查-测试-优化循环

解决方案：采用以“验证”为核心的快速迭代循环，充分利用 AI 的生成效率，同时确保产出符合质量标准。
核心原则是承认 AI 输出的概率性，将开发焦点从“规范驱动实现”转向“生成后验证”，并通过严格、多维度的检验管理潜在风险。

实现示例：

• 生成 (Generate)。使用 AI 代码生成工具（如 GitHub Copilot、Cursor、Windsurf 等）根据提示快速产出代码、测试用例、文档等内容。
• 审查 (Review) 。结合人工审查（代码走查、逻辑检查、幻觉识别）与自动化工具（静态分析、风格检查、复杂度分析、安全扫描）评估生成产物。
  可辅助使用工具，如 Windsurf 的 Lint 自动修复功能或 CodeRabbit 的智能审查模块。
• 测试 (Test) 。采用全面、自动化的验证策略，超越传统单元测试，涵盖功能正确性（如属性基测试）、性能效率、安全漏洞扫描（SAST/DAST）、鲁棒性（模糊测试）及语义正确性（业务规则验证、架构约束检查）。
• 优化 (Optimize)。根据审查与测试结果，通过人工修改或优化提示词（Prompt Engineering）进行改进，形成持续闭环迭代，直至达到质量标准。

检查策略

由于幻觉检测是一个活跃且未完全解决的研究领域，目前最佳实践通常是结合多种手段进行：

• 事实核查与交叉引用。将 AI 生成的代码（尤其是 API 调用、库使用、配置项等）与官方文档、可靠代码库或 API 规范进行比对验证。理论上，也可以借助专门训练的 AI 辅助进行交叉验证。
• 一致性检查。核查生成内容是否与项目现有代码约定、架构模式、设计风格保持一致。例如，若 AI 生成了与项目其他部分截然不同的数据处理逻辑，应引起警觉。
• 静态分析与类型检查。利用强类型语言特性和先进静态分析工具，捕捉明显幻觉，如调用未定义变量、错误函数、错误类型等问题。
• 依赖关系验证。检查生成内容中引用的外部库、模块或 API 是否实际存在，并确认版本兼容性。
• 置信度评分（谨慎使用）。部分 AI 工具提供置信度分数。低置信度可能提示存在幻觉风险，但高置信度也不能完全排除错误，因此需辅助使用。
• 人工审查的重要性。当前阶段，经验丰富的开发者通过人工走查仍是识别复杂幻觉和微妙逻辑错误最有效的方式。
• 针对性测试。针对怀疑存在幻觉的部分，设计特定测试用例验证其功能正确性、边界条件与隐含假设。

模式：面向 AI 理解的代码重构

代码重构是改进现有代码结构和质量而不改变其外在行为的过程。

问题：代码太长时，AI 可能会无法理解，或者超出上下文，或者是生成的代码质量不高，可以通过重构来解决这个问题。许多重构技术天然地有助于提升代码对 AI 的友好度，因为它们的目标通常是降低复杂性、提高可读性和增强模块化。

• 上下文超载：当单个函数或文件过长时，AI 模型容易因 token 限制或困惑于多重责任而无法有效理解全局逻辑
• 可读性差：缺乏清晰的方法划分与命名，令 AI 难以提取关键业务意图，生成的补全或重写质量不高

实践方式：应用经典重构技术优化代码结构与可读性

定义：代码重构是改进现有代码结构和质量而不改变其外在行为的过程，通过消除代码异味、提高模块化和可读性，降低复杂度，从而更易于 AI 工具进行分析和生成高质量代码

解决方案：系统化采用诸如提炼函数（Extract Method）、提炼类（Extract Class）、重命名（Rename Variable/Method）、等经典重构手法，消除代码异味， 降低每个模块的认知复杂度，从而使 AI 模型更易聚焦于单一职责和业务逻辑

实现示例：

• 识别“上帝类”或“神对象”：通过静态分析工具定位文件或类中责任过多的区域。
• 提炼函数：将长方法中逻辑块拆分为独立、具名的小方法，如将“数据校验”、“业务处理”、“日志记录”分别提炼出来。
• 提炼类：将相近职责或状态数据抽离到新的类中，减少主类耦合度。
• 重命名：统一变量、方法、类的命名规范，使其业务意图对 AI 更直观。
• 移除死代码与临时代码：剔除无用方法和注释，降低上下文噪声。

实现方式：借助 AI 辅助分析进行结构性重构

AI 直接重构的问题：

• 模块依赖不透明：多层调用链与高耦合使得开发者和 AI 难以把握整体结构，重构风险高。
• 重构决策凭印象：缺乏数据支撑，易遗漏高价值改动点或误伤核心功能。

解决方案：引入自动化的调用关系分析（Usage Analysis）与依赖追踪（Dependency Tracking）技术，结合 AI 辅助解释或总结， 形成数据驱动的重构策略。通过理解某个类、模块、方法的使用情况，量化其改动影响范围、频次、耦合度，科学规划重构顺序与粒度。

解决方案：

1. 利用静态分析或 LSP（Language Server Protocol）工具，生成目标类/方法的调用点列表、调用频次及调用层级图；
2. 用 AI 对这些结果进行自然语言摘要，帮助快速理解各调用方的上下文；
3. 基于调用热度和耦合度，制定分阶段重构策略，先从高频、深层调用处入手，后续再优化低频、可替换模块。

实现示例：诸如 AutoDev 提供的 /usage 命令，可以帮助你分析代码的调用情况。

1. 分析代码调用情况：使用 AutoDev 提供的 /usage 命令（例如 /usage:com.example.service.OrderService）来分析指定代码（如 OrderService）的调用情况。目的是通过了解代码的具体使用场景（例如：“OrderService.processOrder 在 CheckoutController 中被调用 8 次用于提交订单；在 BatchProcessor 中被异步调度 3 次用于批量结算。”）为后续重构提供依据。
2. 确定重构策略：基于第一步的分析结果，由 AI 评估并决定最适合的重构策略。
3. 执行重构与修正：AI 调用其 AI IDE 能力来执行具体的重构操作，并负责修正过程中可能出现的错误或遗漏。

与 AI 纯修改相比，借助于 Intellij IDEA 的重构功能才能更好地进行重构。

注意事项

进行这些重构时，应采用小步快跑、持续集成和自动化测试（如遵循 Red-Green-Refactor 模式）来确保不破坏现有功能。通过有针对性的重构，可以系统性地改善代码库结构，使其更易于 AI 理解、导航和生成高质量代码。

定义 AI 友好架构

AI 友好架构是一种将成熟的软件架构原则与生成式 AI 的能力相结合并进行调整的软件构建方法。其核心目标是创建一个既便于人类协作，又能被 AI 高效理解、分析、生成和持续演进的代码资产与系统环境，从而显著提升开发效率。

将上述的模式总结为表格：

模式名称	主要目标	关键技术/示例	AI 交互阶段	主要益处	关键挑战/依赖
1. 领域知识丰富上下文与问题定义	提升 AI 对用户意图和需求的理解	DDD 通用语言, 提示词工程, 术语表生成, 需求工具集成 (Jira)	输入处理	减少歧义, 提高生成代码的业务准确性	需要建立和维护领域知识体系, 需求管理流程集成
2. 基于项目知识与规范的智能生成	使 AI 生成的代码符合特定项目规范和上下文	项目规则 (Project Rules), Agent Memories, RAG, 自定义指令	生成	生成的代码更贴合项目实际, 减少返工	需要持续捕获、维护和更新项目知识, RAG 效果依赖知识质量
3. 自文档化代码增强语义表达	让代码本身传递更多意图和约束信息	语义化命名, 结构化设计, 类型系统, 契约式设计 (DbC), 函数式编程 (FP)	代码本身/分析	减少对外部文档依赖, AI 更易理解代码逻辑和约束	高级范式 (DbC, FP) 学习曲线陡峭, 实施成本较高
4. 验证优先开发 (VFD)	管理 AI 生成代码的不确定性, 确保最终质量	生成-审查-测试-优化循环, 幻觉检测策略, 全面自动化测试 (属性基测试, 模糊测试等)	输出验证/优化	安全地利用 AI 生成能力, 控制质量风险, 持续改进	需要建立强大的验证体系, 人工审查仍不可或缺
5. 面向 AI 理解的代码重构	降低现有代码复杂度, 提升 AI 处理效率和理解能力	提炼函数/类, 重命名, 移除死代码, AI 辅助调用分析 (/usage)	代码处理/分析	AI 更易分析/修改代码, 提高 AI 辅助工具效果	需要投入重构成本, 依赖自动化测试保障安全

上述模式的几个关键点是：

1. 人类友好是基础：AI 友好的代码库首先必须是人类友好的，遵循一致的团队规范（如命名约定）、清晰的代码结构（分层与内聚），具备良好的可读性、可维护性和可扩展性。
2. 显式化的上下文与意图：通过领域驱动设计（DDD）的通用语言、丰富的领域术语表、优化的提示词工程以及与需求工具的集成，为 AI 提供清晰、准确的任务背景和业务意图（对应模式 1）。同时，利用项目规则（Project Rules）、Agent 记忆（Memories）和 RAG 技术，注入项目特定的规范、技术栈和历史决策（对应模式 2）。
3. 代码本身的语义表达：强调代码的自文档化能力，通过语义化命名、结构化设计、明确的类型系统、契约式设计（DbC）或函数式编程原则，让代码本身就能清晰地传达其功能、约束和意图，减少 AI 理解的障碍（对应模式 3）。
4. 适应 AI 生成特性的流程：采用“验证优先开发”（Validation-First Development, VFD）模式，建立“生成-审查-测试-优化”的迭代循环，承认并管理 AI 生成代码的不确定性和潜在“幻觉”，通过严格的多维度验证（包括幻觉检测）确保最终产出的质量和可靠性（对应模式 4）。
5. 持续优化的结构：通过面向 AI 理解的代码重构，应用提炼函数/类、重命名等经典技术，并借助 AI 辅助分析（如调用关系分析），持续改进代码结构，降低复杂度，使其更易于 AI 处理和理解（对应模式 5）。

而基于以上模式，AI 友好的架构可以被视为一个多层次的系统，涵盖了从基础知识到交互情境化、生成与验证、以及持续改进反馈的各个方面。

1. 第一层：基础知识与结构层 (Foundational Knowledge & Structure)：强调清晰的领域知识定义、结构良好且语义丰富的代码库，为 AI 理解和操作奠定基础。
2. 第二层：交互情境化层 (Contextualized Interaction)：关注在人机交互的关键节点，通过精确的需求信息和项目特定知识（利用 RAG、Agent Memory 等技术注入）为 AI 提供必要的上下文。
3. 第三层：引导生成与验证层 (Guided Generation & Validation)：AI 在此层根据第一层的基础知识和第二层的实时上下文进行代码生成，并通过严格的验证优先开发（VFD）流程确保产出质量。
4. 第四层：持续改进反馈层 (Continuous Improvement Feedback Loop)：利用第三层的验证结果反馈优化提示词、更新知识库、触发代码重构或语义增强，并通过持续的知识管理确保持续改进。

当然，AI 友好的架构并不是一成不变的，它需要随着技术的发展、团队的需求和项目的演变而不断调整和优化。通过这种方式，团队可以在快速发展的 AI 技术环境中，保持高效的开发流程和高质量的代码产出。

总结

AI 编程并不是银弹，而是一个需要团队共同努力的过程。通过结合领域知识、项目规范、代码结构和验证流程，团队可以有效地利用 AI 编程助手的能力，提升开发效率和代码质量。