AI 辅助前端开发：两个月踩坑实录

70 多次提交，删除近 50,000 行「给 AI 看的文档」，废弃 4 套方案------这是一个 AI 驱动前端项目从过度设计到务实收敛的真实记录。

写在前面

这篇文章不是成功经验分享，而是失败方案的尸检报告。

2026 年初，我启动了一个 AI 辅助前端开发项目（React + TypeScript + Ant Design 生态），目标是构建一套让 AI 能高效参与的前端工程体系。两个月后回头看 git 历史，发现最有价值的不是最终留下的代码，而是那些被删掉的东西。

项目关键数据：

指标	数据
项目周期	约 2 个月
总提交数	70+
核心提示词文件修改次数	30 多次（平均不到 2 天改一次）
核心提示词行数变化	~150 → ~300 → ~250（先膨胀后收敛）
被删除的「给 AI 看的文档」	近 50,000 行
被废弃的完整方案	全量知识库、V1/V2/V3 生命周期设计、迁移分析框架、JSON 代码生成器

时间线总览

sql 复制代码

Month 1  项目初始化 + 基础搭建
         AI 配置中心第一次重构
            ↓
Month 2  迁移分析手册整套删除（近 8,000 行）
         全量知识库删除（约 4 万行）
         V1/V2/V3 生命周期设计全部废弃（约 1,700 行）
         从「模式」重构为「生命周期阶段」
         JSON 代码生成器引入（2,000 多行）→ 重构（近 1,000 行）→ 放弃，转向填空模板（约 1,100 行）

两个月，净删除近 50,000 行「给 AI 看的文档」，这些都是交过的学费。

一、全量知识库是毒药，不是补药

核心论点：AI 自动索引代码库生成的全量知识文档，不但没有提升效率，反而淹没了关键信息。

我做了什么

项目初期，我用 AI 工具自动分析整个代码库，生成了一套百科全书式的知识文档。80 多个 Markdown 文件，覆盖了你能想到的所有维度：

系统架构设计、数据流架构、状态管理架构
API 集成、HTTP 请求封装、数据模型定义
组件系统、组件架构、通用组件、业务组件
路由配置、路由守卫、导航菜单
安全开发、性能优化、故障排除
......

每个文件 300-600 行，总计约 4 万行。看起来很完整，对吧？

发生了什么

这些文档几乎没有任何正面作用。AI 在生成代码时，需要的不是「系统架构的全景描述」，而是「用封装组件不要用原生 Table」这种 10 个字的规则。

全量知识库的三个致命问题：

关键信息被稀释：当上下文里塞满了 300 行的「数据流架构」描述，真正重要的「禁止直接 import axios」反而被淹没
自动生成 = 正确废话：AI 分析代码库生成的文档，本质上是对代码的复述，不包含任何「应该怎么做」的判断
上下文预算被浪费：小参数模型连摘要本身都放不下

删除的那一天

一次性删除，80 多个文件：

复制代码

80+ files changed, 约 -40,000 行

替代方案是一张 21 行的错题集------从 AI 实际犯过的错中提炼出来的规则表：

编号	适用场景	核心规则（一句话）
P001	列表页含弹层	禁止手动管理 Modal 的 open 状态，用工具函数封装
P002	含可编辑表格	声明式表单组件不支持行内编辑，用专门的可编辑表格组件
P003	所有页面	回调中未使用的参数加 `_` 前缀
P004	含字段联动	禁止声明式依赖收集写法，用 watch + 条件判断
P005	含确认弹窗	用 `Modal.confirm` 命令式调用
P006	表格列配置	避免 `as const`，用显式类型注解

21 行 > 40,000 行。不是因为 21 行包含了更多信息，而是因为它只包含了 AI 真正会犯错的信息。

反直觉认知

给 AI 的知识不是越全越好，而是越精准越好。知识库的价值不在于覆盖度，而在于命中率。

二、弱模型对渐进式架构的水土不服

核心论点：为强模型设计的「智能」特性------渐进式自主权、动态风险判断、上下文生命周期管理------在弱模型面前几乎全部失效。

背景

项目需要同时支持两类 AI：

强模型（Claude、GPT-4 等商业 API）：推理能力强，上下文窗口大
弱模型（私有部署的小参数模型，7B-13B 级别）：推理能力有限，上下文窗口小

最初的架构是为强模型设计的，包含了多项「看起来很聪明」的渐进式特性。以下是三个典型的翻车案例。

2.1 渐进式自主权

原始设计：

AI 在执行任务时，系统会根据其历史表现动态调整自主权：

arduino 复制代码

连续 2 个 Task 的代码检查通过且无用户纠正
    → 后续 Task 自动提升至全自主模式
用户纠正了写法或指出错误
    → 立即回退至标准模式
切换到新模块/新阶段
    → 重置为标准模式

这个设计很优雅------AI 表现好就给更多自由，表现差就收紧控制。

弱模型实际表现：

问题出在「连续 2 个 Task 通过」这个条件判断上。弱模型需要：

记住上一个 Task 的检查结果
记住上上个 Task 的检查结果
判断当前是否满足提升条件
执行模式切换

这本身就是一个需要强推理的多步决策任务。弱模型的表现是：要么永远不提升 （因为无法追踪历史），要么在第一次通过后就自行「提升」了（因为误判条件）。

踩坑教训：

用户显式声明三档模式就行了。不要让 AI 自己判断自己该获得多大自主权------这本身就是个元认知任务。

复制代码

「使用保守模式」→ 所有写操作前必须确认
 默认            → 修改/删除需确认，创建无需确认
「使用全自主模式」→ 仅删除和全局配置修改需确认

2.2 上下文生命周期管理

原始设计：

为了在长任务中管理上下文，设计了 9 段式摘要机制------当上下文接近容量上限时，自动生成包含完整状态恢复信息的结构化摘要。

弱模型实际表现：

小上下文模型（比如 8K token）连摘要本身都占满了 token 预算。一个精心设计的 9 段摘要可能就要 2,000 tokens，占了 25% 的上下文，留给实际工作的空间反而更少了。

踩坑教训：

不要让 AI 自己做上下文管理。改用文件持久化 （每个 Task 完成后写入 progress 文件）+ 命令恢复（新会话通过脚本获取上下文），把上下文管理从 AI 侧移到工具侧。

2.3 多入口决策

原始设计：

项目同时维护两套入口文档：

完整版提示词（约 250 行）------给强模型
精简版提示词------给弱模型

AI 根据自身能力选择读哪个。

弱模型实际表现：

让弱模型判断自己「弱不弱」，这本身就是个强推理任务。实际表现：弱模型读了完整版，然后因为上下文不够用而表现更差。

踩坑教训：

弱模型环境只暴露精简版作为唯一入口。不给选择，就不会选错。

三个案例的共同教训

不要让 AI 做元认知（思考自己的思考过程）。

特性	推理驱动（失败）	规则驱动（可行）
自主权	AI 根据历史表现自动调整	用户显式声明模式
上下文	AI 自动生成结构化摘要	文件持久化 + 命令恢复
入口选择	AI 根据能力选择文档版本	环境只暴露一个入口

三、JSON 驱动代码生成反而降低了 AI 效率

核心论点：用 JSON Schema → TS 生成器 → 输出代码的方式，中间引入了太多 AI 需要理解的抽象层，不如直接给填空式模板。

我的思路

为了让 AI 能快速生成 CRUD 页面，我设计了一套 JSON 配置驱动的代码生成器。思路是：

bash 复制代码

用户描述需求 → AI 填写 JSON 配置 → TS 生成器读取配置 → 输出 .tsx/.ts 代码文件

这需要一套完整的类型系统来描述配置结构（近 300 行），AI 要理解字段定义、查询参数定义、枚举定义、额外 API 定义等多种嵌套结构：

typescript 复制代码

// 类型定义片段（总计近 300 行，AI 必须全部理解才能正确填写）
interface FieldDef {
  name: string;
  type: 'string' | 'number' | 'boolean';
  label: string;
  required?: boolean;
}

interface QueryParamDef {
  name: string;
  type: string;
  label: string;
  formType: string;      // 对应表单控件类型
  enumName?: string;      // 关联枚举名（select 时用）
}

interface ExtraApiDef {
  name: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  path: string;
  params?: { name: string; type: string }[];
  body?: { name: string; type: string }[];
}
// ... 还有更多嵌套结构

越修越复杂

AI 经常填错 JSON 配置，于是我不断增加校验和推导逻辑来「帮助」AI：

标准化预处理器（约 460 行）------ 把 AI 填的不规范配置自动修正
声明式推导规则（约 90 行）------ 从字段名自动推导表单类型
类型守卫（约 50 行）------ 场景分类
别名映射（约 80 行）------ 字段名到控件类型的映射
枚举收集器（约 100 行）------ 自动收集散落的枚举定义

总代码量膨胀到 3,000 多行。我在用越来越复杂的工程手段来弥补一个根本性的设计缺陷。

为什么失败

javascript 复制代码

JSON 方案的认知链路：
AI 需要理解近 300 行类型定义
  → 正确组装嵌套 JSON 配置（字段 + 查询参数 + 枚举 + API）
    → JSON 交给 TS 生成器解析
      → 生成器按模板拼接输出代码
        → 任何一步出错，整条链路断裂

填空模板的认知链路：
AI 直接看到最终代码的样子
  → 把 {Entity} 替换成 User，把 {columns} 替换成真实列定义
    → 完成

核心问题是中间抽象层 。JSON Schema 是给人类程序员用的工具------人类擅长理解抽象层次并在层次之间转换。但 AI（尤其是弱模型）擅长的是模式匹配和文本替换，不是抽象推理。

最终 3,000 多行 TS 的 JSON 生成器，被约 1,100 行 Markdown 的填空模板替代了。对比：

维度	JSON 生成器	填空模板
AI 需理解的代码量	3,000+ 行 TS	~1,100 行 Markdown
抽象层数	3 层（类型定义 → JSON 配置 → 生成代码）	1 层（模板 → 代码）
出错时排查	对比 JSON 和输出，排查生成逻辑	直接在模板上看
弱模型适配	几乎不可用	开箱即用

反直觉认知

代码生成的最佳方式不是「配置化」，而是「可视化」。让 AI 直接看到最终产物的样子，比让它理解一套生成规则要高效得多。这跟传统软件工程的直觉完全相反------我们通常认为抽象和配置化是更高级的做法。但对 AI 来说，抽象是认知负担，不是效率工具。

四、过度设计的生命周期------三版废弃的教训

核心论点：用复杂的状态机来管理 AI 的开发流程，是在用工程师的思维框架约束一个语言模型。

三版设计的兴衰

V1（约 300 行）：完整的工作流生命周期设计，定义了多阶段、多状态的开发流程状态机。AI 需要根据当前代码状态和上一阶段的输出来决定进入哪个阶段。

V2（约 800 行）：V1 被发现太理想化，于是加入了更多应对现实的机制------状态恢复、上下文快照、多任务并行、异常回退等。可以叫「复杂多机制方案」。

V3（约 550 行）：V2 太复杂导致 AI 根本无法遵循，于是做了激进精简。但精简过头，砍掉了一些必要的阶段区分，变成了一个过于简陋的线性流程。可以叫「过度精简方案」。

三个版本都没有活过一天。 同一天全部废弃，一次性删除：

复制代码

3 files changed, 约 -1,700 行

根本问题

V1 假设 AI 能做复杂的状态推理，V2 试图用更多规则来弥补推理不足，V3 把规则砍得太狠失去了区分度------三个方向都不对。

真正的问题在于：旧方案让 AI 根据代码状态来推理应该进入哪个阶段。 比如 AI 需要判断：

当前有没有 API 文件？
页面完成度到了什么程度？
是否需要先写规格书？

这些判断本身就是模糊的、主观的。

最终出路

废弃整套状态机，改为关键词路由表------AI 不再分析代码状态，而是直接根据用户消息中的关键词路由到对应阶段：

复制代码

旧方案（AI 推理进入哪个阶段）：
  分析当前代码状态 → 判断是否有 API → 判断页面完成度 → 决定进入哪个模式

新方案（关键词匹配）：
  用户说「画页面」   → 进入 Demo 阶段
  用户提供接口文档   → 进入接口处理阶段
  用户说「改造」     → 进入适配阶段
  用户说「联调」     → 进入对接阶段
  用户说「改一下」   → 进入修复阶段

反直觉认知

开发流程的决策权应该留给人类，AI 只需要高效执行。关键词路由表比状态机决策树有效一百倍。把「决策」变成「匹配」，把「推理」变成「查表」。

五、迁移分析框架的覆灭------让 AI 做「分析再决策」是个陷阱

核心论点：为 AI 设计「采集→分类→分析→决策」的多步分析框架，AI 在第一步就会偏航。

这套框架有多庞大

为了将旧项目的 Vue 页面迁移到新的 React 技术栈，我设计了一整套 AI 驱动的迁移分析体系。这套体系后来被整体删除：

复制代码

20+ files changed, 近 -8,000 行

它包含：

迁移总指南（约 160 行）------ 6 步执行流程
4 种页面分析手册：列表页（约 300 行）、表单页（约 270 行）、详情页（约 220 行）、复杂组合页（约 230 行）
场景识别规则（约 110 行）------ 4 种场景的判定条件和互斥关系
5 步执行模板：画像→分类→上下文→分析→任务拆解
4 种输出模板：模块上下文、概览、项目画像、任务列表

设计意图 vs 实际效果

设计意图：

arduino 复制代码

旧 Vue 文件 → step-0 画像 → step-1 分类(识别4种场景)
  → step-2 上下文(读取关联文件) → step-3 分析(按手册提取字段/组件/API)
    → step-4 任务拆解(生成迁移计划) → 执行迁移

实际效果：

场景识别本身就是模糊的：一个 Vue 文件可能同时有列表、搜索表单和详情弹窗------它是列表页还是复杂组合页？AI 的判断在不同会话之间不一致，同一个文件有时被分为「列表页」有时被分为「复杂组合页」
分析手册占满上下文：每种页面分析手册 200-300 行，加上通用规则和输出模板，AI 还没开始实际工作，上下文已经用了一大半
分析结果的质量不可控：AI 在「提取」阶段的输出高度依赖推理能力。弱模型的提取结果经常遗漏关键信息------比如漏掉了一个重要的表单联动逻辑，导致后续生成的代码缺少这个功能
多步流程的错误累积：每一步都有误差，5 步累积下来，最终输出偏离预期很远

替代做法

最终没有用任何分析框架。直接：

让 AI 读旧的 Vue 文件
给它目标项目的代码模板
让它直接生成新代码

跳过了「分析」这个中间步骤。AI 不需要先把旧代码的结构分析成一份中间文档，再根据中间文档生成新代码------它可以直接从旧代码中提取意图，按新模板写出来。

反直觉认知

「先分析再执行」是人类的工作方式，不是 AI 的最优路径。对 AI 来说，分析和执行可以是同一步。多给 AI 一个中间步骤，就多给了它一个出错的机会。

六、同样的内容，换个包装方式就行了------Skill 封装的启示

核心论点：弱模型对渐进式提示词水土不服，但把同样的知识封装进 Skill（固定步骤指令）后，效果反而比强模型自由发挥还稳定。这不是内容问题，而是知识包装方式的问题。

现象

前面说了，弱模型在面对渐进式架构时几乎全面翻车。但一个反直觉的现象是：把完全相同的规则、模板、组件文档、错题集封装进一个固定步骤的 Skill 之后，弱模型的表现反而变得很稳定------甚至比强模型在自由模式下的表现更可预测。

这里说的「完全相同的内容」是字面意思：组件替换规则、API 命名规范、错题集、代码模板------一个字没改，只是换了一种组织方式。

渐进式提示词 vs Skill 的结构差异

渐进式提示词的执行路径（AI 需要 5 次决策）：

复制代码

AI 读取主提示词（约 250 行）
  → 【决策1】判断当前处于哪个阶段
  → 【决策2】导航到对应的阶段文件（需要在文件树中找路径）
  → 【决策3】判断需要读取哪些组件文档
  → 【决策4】判断用哪个代码模板
  → 【决策5】在编码过程中回忆散落在各处的约束规则
  → 生成代码
  → 自检时需要回忆之前读过的规则

Skill 的执行路径（AI 需要 0 次决策）：

bash 复制代码

Skill 被触发（关键词匹配，不需要 AI 判断）
  → 步骤1：收集需求信息（固定动作）
  → 步骤2：读取指定的组件文档（路径直接给出，不需要寻找）
  → 步骤3：读取代码模板（路径直接给出）
  → 步骤4：按模板生成 types.ts
  → 步骤5：按模板生成 api/index.ts
  → 步骤6：按模板生成页面
  → 步骤7：按模板生成弹层组件
  → 步骤8：对照内置规则表自检
  → 步骤9：运行验证命令
  → 步骤10：输出文件清单

关键区别不在内容，在结构：

维度	渐进式提示词	Skill
知识组织	分散在数十个文件中，AI 按需导航	打包为自包含 bundle，一次性加载
步骤编排	隐式的------AI 需要推理「下一步该做什么」	显式的------固定步骤表，第 N 步做什么写得清清楚楚
文档读取	条件式------「如果你在做 X 场景，读 Y 文件」	命令式------「步骤 2：读取 A.md + B.md」
决策点	5+ 个（阶段判断、文件选择、模板选择...）	0 个（所有决策已内化为步骤表的固定路径）
约束执行	依赖 AI 在编码时「回忆」之前读过的规则	约束内联在模板和自检步骤中，不依赖回忆

为什么会这样

这个现象揭示了一个关于 AI 认知模式的关键洞察：

渐进式架构的隐含假设是 AI 能做「元工作」。

所谓「元工作」，就是「为了工作而做的工作」------判断自己处于什么阶段、决定读哪些文件、选择用哪个模板。这些「元工作」对人类来说几乎无感（人类的工作记忆可以轻松处理这种上下文切换），但对弱模型来说，每一个决策点都是一次可能出错的推理。

5 个决策点，每个 80% 的正确率，最终正确率只有 32%。

而 Skill 的做法是：把所有「元工作」在设计时就完成了。步骤表就是预编译好的执行计划。AI 不需要判断「我该做什么」，只需要执行「步骤 N 告诉我做什么」。

用一个类比：渐进式提示词像是给 AI 一张城市地图，让它自己导航到目的地；Skill 像是给 AI 一个逐弯导航指令------「前方 200 米左转，然后直行 500 米」。同样的路线，同样的终点，但后者不需要 AI 有任何空间推理能力。

自包含 bundle 的妙处

除了步骤编排的差异，还有一个关键设计：自包含 bundle。

渐进式提示词中，知识是散落的：

bash 复制代码

约束规则 → 在主提示词里
组件 API → 在 .ai/docs/components/ 下
代码模板 → 在 .ai/templates/ 下
错题集 → 在 .ai/rules/ 下

AI 需要在不同文件之间跳转、交叉引用，每次跳转都是一次上下文切换。

Skill 的 bundle 模板把相关知识打包在一起：

markdown 复制代码

一个 crud-template.md（约 280 行）包含：
  - 这个页面类型需要用到的代码骨架
  - 关键组件的 Props 摘要（不需要跳转去读完整文档）
  - 该场景常犯的错误提醒
  - 填空占位符和替换说明

对弱模型来说，「一次读完所有需要的信息」远比「按需在文件树中寻找信息」要可靠。 因为后者需要 AI 维护一个「我还缺什么信息」的心智模型------而这又是一项「元工作」。

反直觉认知

弱模型不是能力不够，而是决策预算 不够。同样的知识，如果不需要 AI 做任何「关于如何使用这些知识」的决策，弱模型一样能执行得很好。Skill 的本质不是简化知识，而是预编译决策。
这对架构设计的启发是：如果你发现 AI 在某个环节表现不稳定，先不要急着简化内容------试试看是不是可以把「AI 需要做的决策」变成「预先确定的步骤」。

七、还有哪些坑值得单独聊

以下几个主题后续会单独写，这里先点到。

7.1 错题集 vs 最佳实践------「不要做什么」比「要做什么」有效

从 AI 反复犯的错误中提炼规则，形成「负面参照」而非「正面指导」。

项目里 AI 犯的错有明显的聚集性------某些错误会在不同会话中反复出现。比如每次生成弹层代码都会用 useState 手动管理 open 状态，每次遇到可编辑表格都会尝试用不支持编辑的组件。

把这些错误沉淀成 6 条规则后，对应的错误基本消失了。但如果换成正面表述------「请使用工具函数封装弹层」------AI 经常「知道但不执行」。

核心认知：错题集 > 最佳实践文档。AI 对「禁止做 X」的遵从度远高于「推荐做 Y」。

7.2 TypeScript 高级语法对弱模型的暗杀

弱模型在生成 TypeScript 代码时，对某些社区常见的语法模式表现极差。

典型案例：as const 字面量类型。这是 TypeScript 社区的标准模式，但弱模型经常在不需要的地方加 as const，或者加错位置，导致类型报错。

最终的做法是双管齐下：

提示词层面 ：沉淀为规则，避免使用 as const，用显式类型注解替代
组件库层面 ：将类型定义从精确联合类型放宽为 string，从根源消除弱模型的类型错误

核心认知：与其教 AI 写出正确的高级语法，不如改变约束让简单语法也能通过。规则适配 AI，比 AI 适配规则容易得多。

7.3 提示词文件的 36 次修改------迭代成本比你想的高

核心提示词文件在 2 个月内被修改了 30 多次。行数从约 150 膨胀到约 300，又收敛到约 250。

这 30 多次修改大致分为：

新增规则（~15 次）：发现新的 AI 错误模式
精简/删除（~10 次）：发现规则冗余或 AI 无法理解
结构重组（~8 次）：重新组织信息层次
措辞调整（~3 次）：让弱模型更容易解析

核心认知：提示词工程不是一次性工作，而是一个持续的测试-反馈-修正循环。它跟产品迭代一样需要版本管理、A/B 测试和数据驱动的决策。

7.4 知识蒸馏------不同能力的 AI 需要不同粒度的知识

项目最终建立了一套分层知识体系：

详细版（数十个文档）：给强模型
蒸馏版（少量 bundle）：给弱模型，只包含必要规则

每条知识按优先级分类：

P0（必须蒸馏）：组件替换规则、导入规则、错题集
P1（部分蒸馏）：验证体系、编码规范
不蒸馏：生命周期高级特性、纠错沉淀流程（强模型专属）

核心认知：「一份文档适配所有模型」是偷懒。为不同能力层次的 AI 准备不同精度的知识包，虽然维护成本高，但效果差距巨大。

写在最后

两个月下来，最大的认知转变是：

AI 辅助开发的瓶颈不在 AI 的能力，而在人类给 AI 设计的框架。

我们习惯性地用工程师的思维给 AI 设计系统------分层抽象、状态机、配置驱动、分析框架。但 AI 不是一个需要被「架构」的系统，它是一个需要被引导的协作者。

最终活下来的方案都有一个共同特点：把复杂度从 AI 侧移到工具侧/人类侧。

不让 AI 判断自主权 → 人类声明模式
不让 AI 管理上下文 → 文件持久化 + 命令恢复
不让 AI 填 JSON 配置 → 直接给填空模板
不让 AI 分析再决策 → 直接从输入到输出
不让 AI 选择入口 → 环境只暴露一个
不让 AI 自行编排步骤 → 用 Skill 预编译决策

尤其是最后一条，可能是最反直觉的发现：弱模型的瓶颈不是知识量，而是决策量。同样的知识，消除决策点后就能用。这意味着我们在设计 AI 辅助系统时，「减少 AI 需要做的决策」可能比「降低任务难度」更有效。

50,000 行删除的文档，就是这个认知的学费。

如果你也在做 AI 辅助开发，希望这些踩坑记录能帮你少走弯路。后续会挑几个点单独展开，欢迎讨论。

作者是一名前端开发者，正在探索 AI 辅助工程化开发的边界。文中所有数据均来自真实项目的 git 历史。