游乐游手机版
首页/AI教程/文章详情

企业AI落地规范从零到一全流程实战指南

时间：2026-06-06 17:19
一、为什么需要「AI 落地规范」 在真实的业务项目里引入 AI 辅助编写代码，听起来很酷，但实际操作中坑可不少。拿 Cursor、Claude Code、Trae 这类工具来说，最常见的几个头疼问题包括： 生成的代码风格与现有工程完全不搭：目录结构、命名方式、组件写法各自为政，难以融合。 需求理解总

一、为什么需要「AI 落地规范」

在真实的业务项目里引入 AI 辅助编写代码，听起来很酷，但实际操作中坑可不少。拿 Cursor、Claude Code、Trae 这类工具来说，最常见的几个头疼问题包括：

万字长文之——AI落地规范

  • 生成的代码风格与现有工程完全不搭：目录结构、命名方式、组件写法各自为政，难以融合。
  • 需求理解总跑偏：缺乏结构化的需求和接口说明，AI 只能靠“猜”业务逻辑，幻觉问题愈发严重，影响代码质量。
  • 可维护性堪忧：没有统一规则，后续开发者甚至 AI 自己想在现有约定下续写时，都会困难重重。

要解决这些问题，需要从两个方向同步推进，缺一不可：

  1. 输入规范：将需求、接口、配置等内容编写成 AI 能读懂、能执行的结构化文档。
  2. 输出规范：用项目规则来约束 AI 生成的目录结构、命名方式、组件写法以及接口调用格式，简单说就是给 AI 立规矩。

下面以某个 Vue 项目中的模块「xxxx缴费记录查询」和对应的规则文件为例，看看我们团队是如何搞定这件事的。

二、输入规范：把需求写成 AI 读得懂的语言

AI 能否在工程中稳定输出，前提是需求和接口必须清晰、结构化地写出来。依靠口头交代或零散的聊天记录，基本就是在给自己挖坑，代码只会越写越乱。

2.1 功能文档结构

一份规范的功能文档目录大致如下：

xxxx缴费记录查询/
├── xxxx缴费记录查询-需求.md  # 功能概述、流程、页面与规则
├── xxxx缴费记录查询接口-需求.md  # 接口入参、出参、取值与规则
├── 系统参数配置.md  # 提示信息、开关等可配置项
└── 原型文件/  # HTML/CSS/JS 原型
  • 需求文档（前端用）：包含功能概述、流程图（推荐用 Mermaid）、页面分区（导航栏、查询区、列表区等）、控件表（名称、类型、是否必录、规则、数据元）、页面规则（如页面初始化、数据查询规则）。
  • 接口需求文档（后端用）：接口概述、入参/出参表（附带数据元标识、字段名、类型、是否可空）、接口规则（入参校验、表来源、取值规则）。
  • 系统参数配置（共用）：按模块或页面列出可配置项，例如主页面提示信息，前端直接从配置里读取，而不是硬编码写死。

这样结构化之后，AI 的能力就能充分发挥：按照「页面 + 控件 + 规则」生成页面和交互逻辑；按照「入参/出参 + 规则」生成 API 调用和数据传输对象；按照「配置项」生成从 store 或 config 里读取提示或开关的代码。

2.2 AI 时代的需求文档怎么写

这里有一个关键点：统一使用对 AI 更友好的 Markdown 文档来写需求。这对写需求的同学来说是一个新挑战，但绝对值得投入。

一、功能概述

用一两句话说清楚功能面向谁、做什么、范围是什么。对 AI 的作用是：确定模块边界、页面标题、路由命名。

二、详细流程

先用 Mermaid 把流程图画出来，再配上简短的流程说明。例如：

sequenceDiagram
     actor 用户
     participant 本功能 as 本功能
     participant 外部系统 as 外部系统
     rect rgba(135, 206, 250, 0.4)
         Note over 用户,外部系统: 1. 【页面初始化】
        用户->>本功能: 1) 访问xxxx缴费记录查询页面
        本功能->>外部系统: 引用4.1规则初始化
        外部系统-->>本功能: 返回初始化配置及数据
        本功能-->>用户: 展示xxxx缴费记录
    end

写法要点：流程中的步骤要与后文「四、页面规则说明」里的规则编号对应上，比如“引用 4.1”，这样实现时才能按规则写出正确的初始化逻辑。对 AI 来说，这能帮助它生成正确的调用顺序，清楚先取配置再取列表。

三、页面需求分析

按页面 → 区域 → 控件的层次进行分层，用表格把每个区域的控件写清楚。

  • 导航栏：操作按钮和标题。用表格列出控件名称、是否可操作、控件类型、交互事件及规则；标题单独一行说明。

  • 页面提示区域：文案不写死，而是引用配置。这样 AI 会生成“从配置读取，如果没配置则不展示”的逻辑，而不是硬编码一段文字。

  • 查询条件选择区域：用一张表统一描述控件，建议列名包括：

    列名 说明与示例
    控件名称 xxx
    控件类型 年度选择框、下拉框
    可操作/必录/是否可见 Y/N，便于做校验与展示
    初始状态/数据 默认当前系统年度、暗文「请选择」
    操作规则及取数口径 格式 YYYY、最大不超过当前年度、下拉选项：xxxx；引用“xx数据查询规则”
    数据元字段名 与接口对齐

    示例（节选）：

    控件名称 控件类型 可操作 必录 是否可见 初始状态/数据 操作规则及取数口径
    年度 年度选择框 Y Y Y 默认显示当前系统年度 格式 YYYY；最大不能超过当前系统年度。引用“xx数据查询规则、xx组件”
    xx 下拉框 Y N Y 暗文：请选择 下拉选项：xxx。引用“xx数据查询规则”

  • 列表区域：同样用表格列出“展示项 + 取数口径 + 数据元”。比如缴费金额要写清楚单位、格式（¥、保留两位小数）。这样 AI 能直接生成列表列的定义和格式化逻辑。

四、页面规则说明

用编号规则把“页面初始化”“查询规则”等说清楚，并且与前文的引用保持一致。

  • 4.1 页面初始化：逐条写清楚“根据哪份配置做哪件事”“根据哪条规则初始化数据”。比如：根据《系统参数配置.md》对“页面提示区域”进行初始展示；根据“xx数据查询规则”初始化展示页面数据。
  • 4.2 缴费数据查询规则：先写查询条件的转换规则，再写调用哪个接口。AI 可以根据这些规则生成查询参数的组装和接口调用逻辑。

2.3 我们为什么规定这样写需求文档？

维度 写法 好处
结构化 功能概述 → 流程 → 页面分析 → 规则说明；接口概述 → 入参/出参 → 接口规则 层次清晰，AI 和人都能按章节定位；先“做什么”再“怎么做”，减少遗漏。
表格化 控件表、入参表、出参表、代码映射表 机器可读性强，AI 可直接用于生成表单字段、请求参数、列表列、常量映射；前后端对齐同一张表，字段名和类型保持一致。
引用与编号 “引用 4.1 规则”“引用xxx组件”“引用xx数据查询规则”“根据系统参数配置.md” 需求内可追溯，实现时按编号找到对应规则及组件；提示区、查询逻辑等不写死，便于多地区配置。
数据元与取数口径 数据元标识符、字段名、取数口径、格式备注 与标准数据元一致，利于对接；取数口径让前端知道哪些字段是后端计算、如何展示。
流程 + 规则 Mermaid 流程图 + 规则编号 先有时序再有条文，AI 能生成正确的调用顺序和初始化逻辑；规则可单独实现、单独测试。
配置与代码分离 提示内容取自系统参数配置、若未配置则不显示 文案和开关可配置，AI 生成“读配置再展示”的代码，避免硬编码，便于多环境。

整体来看，需求文档按照“概述 → 流程 → 页面/接口表格 → 规则说明”来写，并用表格和编号把控件、字段、映射、规则、组件编号固定下来，既能让人一眼看懂，也能让 AI 按表生成代码、按规则生成逻辑，减少歧义和返工，也为后续从 1 到 N 的迭代打下良好基础。

2.4 需求文档中建议包含的要素

要素 说明 对 AI 的用途
功能概述 一两句话说清功能做什么、谁用 确定模块边界、路由/菜单命名
流程图 用 Mermaid 等画清主流程 生成顺序逻辑、调用关系
页面分区 导航栏、提示区、查询区、列表区等 对应 template 区块与组件
控件表 控件名称、类型、必录、可见性、初始值、操作规则、数据元 生成表单项、校验、字段绑定
数据元 中文名、标识符、字段名、类型、长度 与接口字段、DTO 对齐
页面规则 如「4.1 页面初始化」「4.2 xx数据查询规则」 生成 mounted/created 逻辑与查询条件转换

接口需求文档里则建议包含：

  • 接口概述、入参/出参表（含数据元与检索策略）；
  • 入参校验、涉及的表、关键取值规则。

这样 AI 生成的 API 封装、请求参数和数据模型才能和后端的约定对上。

2.5 系统参数配置的用法（可选）

「系统参数配置.md」中按模块列出“主页面提示信息参数配置”等，并说明使用场景、配置项、默认值。前端应当从配置里读取提示语等内容，而不是在页面里写死。这样 AI 生成的代码会去读取配置状态，便于多地区或多环境的差异化定制。

三、输出规范：用项目规则约束 AI 的代码

有了清晰的输入还不够，还需要统一输出：目录结构、命名方式、组件结构、API 和状态管理方式都要和现有项目保持一致。在我们的项目里，xxx-xxx-h5-rules 就承担了这个角色。

3.1 规则体系概览（xxx-xxx-h5-rules）

规则文件 作用 对 AI 的约束
project-structure.mdc 项目结构、入口、路由位置 新模块放在哪、如何拆分目录
vue-coding-standards.mdc Vue 组件顺序、JS 规范、路由/Vuex/API 约定 组件结构、命名、mapState/mapMutations 用法
component-development.mdc 通用/业务组件、标准父/子页面结构 页面用 xxTransition + keep-alive、子页面 name 与 class 命名
api-integration.mdc HTTP 封装、接口组织、错误与加密 api 模块写法、http 使用方式
business-modules.mdc 业务模块列表、新增模块步骤 路由/store/api 注册顺序与命名
build-deployment.mdc 构建、环境、部署 不随意修改构建与公共路径

这些规则需要被 Cursor 这类工具识别，通常放在 .cursor/rules 目录下，或者在说明里引用，这样 AI 在生成代码时默认就会遵循它们。

3.2 部分 mdc 文档说明

规则文件不只是代码，而是“说明 + 列表 + 目录树 + 代码块”的组合。下面按文件摘录部分原文作为参考。

README.mdc（总览）

---
alwaysApply: true
description: xxx-xxx-h5 项目规则总览
---
# xxx-xxx-h5 项目规则总览

## 规则文件说明
本目录包含 xxx-xxx-h5 项目的所有 Cursor 规则文件，用于指导 AI 助手更好地理解和开发该项目。

### 规则文件列表
1. **project-structure.mdc** - 项目结构指南
   - 项目概述和核心目录结构
   - 模块化架构特点说明
   - 主要入口文件和配置文件位置
2. **vue-coding-standards.mdc** - Vue 2.x 编码规范
   - Vue 组件开发规范
   - JavaScript 编码标准
   - 路由和状态管理规范
  • 用 frontmatter 声明 alwaysApply: true、description，方便 Cursor 按需加载或常驻。
  • 用编号列表加子项说清楚每个规则文件负责什么，AI 能快速判断该查哪个文件。

project-structure.mdc（结构说明）

# xxx-xxx-h5 项目结构指南

## 项目概述
xxx-xxx-h5 是一个基于 Vue 2.x 的 H5 应用，采用模块化架构设计。

## 核心目录结构

### 主要入口文件
- main.js - 应用主入口，配置 Vue 实例和全局插件
- App.vue - 根组件
- vue.config.js - Vue CLI 配置文件

### 路由系统
- router/index.js - 主路由配置，包含所有模块路由
- router/ - 各功能模块的路由配置

## 模块化架构特点
项目采用功能模块化设计，每个业务功能都有对应的：
- 路由配置 (router/)
- 状态管理 (store/)
- API 接口 (api/)
- 页面组件 (views/)
这种设计便于维护和扩展新功能。
  • 先概述再拆目录，AI 能建立起“模块 = router + store + api + views”的心智模型。
  • 即使没有具体代码，也能约束“新模块该建哪些目录、放在哪”。

vue-coding-standards.mdc

---
globs: *.vue,*.js
description: Vue 2.x 编码规范和最佳实践
---
### 组件命名
- 组件名使用 PascalCase
- 文件名与组件名保持一致

### 路由命名
- 路由名称使用 camelCase
- 路径使用 kebab-case
- 模块路由统一导入到主路由
- 使用常量导出路由名称，便于维护
  • globs 限定只在 *.vue,*.js 下生效，避免在无关文件中误用。
  • 条文式的约定（命名、路径、常量），不需要代码也能约束生成结果。

同一个文件里还可以配上“获取系统配置”的说明、注意事项和代码示例。先写“在组件中获取系统配置必须使用以下方式”，再贴代码；接着用注意事项列出几条关键点（比如用户信息走 getters、系统配置走 state、箭头函数、避免在 methods 里访问 store）。示例代码：

// vue-coding-standards.mdc 中规定的方式
export default {
    computed: {
        sbfConfigs: (vm) => {
            return vm.$store.state.configs.xxx
        }
    }
}
  • 先写“必须使用以下方式”再贴代码，AI 会优先采用这个写法。
  • 注意事项能减少“能跑但不符合项目习惯”的生成内容，比如把配置写在 methods 里。

component-development.mdc

### 组件设计原则
- 单一职责：每个组件只负责一个功能
- 可复用性：组件应该可以在不同场景下复用
- 可配置性：通过 props 提供灵活的配置选项
- 可扩展性：支持插槽和事件扩展

### 标准页面组件结构
- 页面组件放在 `views/` 目录
- 按功能模块组织子目录
- 组件名使用 `moduleName.pageName` 格式
- 父级组件使用 `xxTransition` 和 `keep-alive`
  • 设计原则是纯文字说明，但能引导 AI 不写“大而全”的单文件页面。
  • 标准页面组件结构这四条直接对应“放哪、怎么命名、用什么包裹”，和后文的代码块保持一致。

api-integration.mdc

### 模块化 API 结构
api/
├── index.js    # API 主入口
├── account.js  # 账户相关接口
├── apply.js    # 申请相关接口
├── basecode.js # 基础代码接口
├── pay.js      # 支付相关接口
└── ...         # 其他业务模块接口

### 核心 HTTP 配置
- core/http.js - 基础 HTTP 配置
- core/httpEncrypt.js - 加密 HTTP 配置
- core/BusinessError.js - 业务错误处理
  • 目录树让 AI 知道新模块的 api 文件应该放在哪、如何与 index 挂载。
  • 核心 HTTP 配置列出文件和职责，生成请求代码时会关联到 @/core/http、BusinessError。

3.3 这样写 mdc 规则的好处

写法 好处
frontmatter（alwaysApply / globs / description） 工具可按路径或全局决定何时注入规则，减少无关上下文；description 便于人和 AI 快速理解文件用途。
分文件（结构 / Vue / 组件 / API / 业务 / 构建） 单个文件短小、职责清晰，AI 检索时容易命中“路由”“组件”“API”等关键词；后续增删规则不影响其他领域。
说明 + 列表 + 代码一起写 既有“必须”“应”等约束性文字，又有可复制的模板代码，AI 既知道“为什么这样”又知道“长什么样”，生成时更少偏离。
注意事项 / 命名规范等条文 不依赖代码也能约束命名、数据来源（如 config 只从 computed 取）、错误处理方式，避免“风格正确但细节不符合项目习惯”。
目录树与入口说明 明确新模块该建哪些目录、在 index 里如何挂载，AI 生成的目录和 import 关系更一致。
标准模式 + 复杂模式并存 简单业务用标准模式（reset/set、queryList），复杂业务用 actions/getters，AI 能按需求选模板，而不是自己发明一套。

总的来说，把规则写成“可执行的说明 + 可粘贴的代码”，并配合 frontmatter 和分文件组织，能让 AI 在正确时机、正确范围内套用约定，减少反复修改和风格漂移，也方便新人或后续 AI 继承同一套规范。

四、总结

  1. 新功能先写清需求与接口
    至少具备：功能需求（含流程与页面分析）、接口需求（入参/出参/规则）、与前端相关的系统参数配置。

  2. 把项目规则显式化
    像 xxx-xxx-h5-rules 一样，把结构、Vue、组件、API、业务模块、构建拆成独立规则文件，并让 AI 在上下文中能读到这些规则。

  3. 模块命名与注册统一
    业务模块用拼音首字母；新增模块严格按 router → store → api → views 的顺序注册，并在主入口中挂载。

  4. 配置与数据元不写死
    提示语、开关等走系统参数配置；字段名、数据元与接口文档一致，便于前后端联调与 AI 二次修改。

  5. 用现有模块当模板
    让 AI 参考历史模块的 router/store/api/views 实现方式，再结合需求与接口文档生成新模块，可减少风格偏差。

五、结语

AI 要在现有工程里稳定落地，不能只靠“说人话”提需求，而需要：

  • 输入侧：把需求、接口、配置写成结构化、可检索的文档，后期甚至可以引入向量库来编排；
  • 输出侧：用项目规则（如 xxx-xxx-h5-rules）来约束目录、命名、组件、API 和状态管理。

AI 落地规范是一个系统化的工程，这篇文章只介绍了需求侧和代码生成侧的一部分内容，还有很多地方没有展开，权当提供一些参考思路。

来源：https://juejin.cn/post/7605105527257759744
ai
上一篇OPD模式最适合哪些岗位 下一篇AI帮我写一万行代码后我却看不懂自己的项目了
本站内容用于信息整理与展示，如有侵权或内容问题请及时联系处理。

相关推荐

补充同频道和同主题内容，方便继续浏览更多相关内容。

同类最新

继续查看同栏目最近更新的文章。

更多
Synthesia零基础教程：客户端安装与工作区权限设置
AI教程 · 2026-06-07

Synthesia零基础教程：客户端安装与工作区权限设置

本文介绍了AI视频生成工具Synthesia的入门流程。内容涵盖从官网下载客户端、完成账户注册与登录，到软件安装与启动的完整步骤。详细说明了如何初始化工作区，包括创建首个AI视频项目、选择模板与AI主播。最后，指导用户理解并设置团队协作中的不同权限角色，以便安全高效地共同管理项目。

 FramePack新手入门指南：安装启动报错修复导出全流程
AI教程 · 2026-06-07

FramePack新手入门指南：安装启动报错修复导出全流程

本文详细介绍了FramePack工具从下载安装到项目导出的完整流程。内容涵盖软件安装步骤、首次启动设置、常见报错解决方案以及项目打包导出方法。指南旨在帮助用户快速掌握工具核心操作，解决使用过程中可能遇到的技术问题，确保顺利完成AI视频帧处理任务。

 FLUX.1保姆级教程：环境安装、显存优化与首次出图测试
AI教程 · 2026-06-07

FLUX.1保姆级教程：环境安装、显存优化与首次出图测试

本文详细介绍了FLUX 1的安装与初步使用流程。内容涵盖从Python环境配置、代码仓库克隆、依赖包安装，到关键的显存优化设置，最后指导用户完成首次文生图测试。教程旨在帮助用户顺利搭建运行环境，解决常见安装问题，并实现基础图像生成功能。

 AnythingLLM新手实战：本地大模型部署后知识库接入设置
AI教程 · 2026-06-07

AnythingLLM新手实战：本地大模型部署后知识库接入设置

本文介绍了在本地部署大模型后，如何为AnythingLLM设置知识库。内容涵盖知识库的基本概念、创建与配置步骤、文档上传与处理技巧，以及如何通过问答测试其效果。旨在帮助用户有效整合本地文档资源，构建个性化的AI知识助手，提升信息检索与利用效率。

 Aider安装失败排查：扩展冲突与登录异常全解析
AI教程 · 2026-06-07

Aider安装失败排查：扩展冲突与登录异常全解析

本文针对Aider安装过程中常见的扩展冲突与登录异常问题，提供了系统的排查思路与解决方案。内容涵盖如何识别并处理与其他AI工具的兼容性问题，解决因网络或账户设置导致的登录失败，以及通过环境检查、依赖更新等步骤彻底排除安装障碍，帮助用户顺利完成安装与配置。