AI 规范：模板工程方法论

第 1 章引言：AI 编程的「确定性」之困

大模型正在改变前端的生产方式。开发者把需求交给 AI，AI 返回可运行的代码------这是过去两年的常态。

但当代码规模从「一个函数」增长到「一个页面、一个完整工程」时，一个根本矛盾浮现出来：

AI 编程的根本矛盾是「确定性」。

LLM 本质上是概率生成器。面对同一段需求，它每次输出的结构、命名、分层都可能不同。这不是 bug，而是它的底层工作方式。

而工程恰恰最需要确定性------可预测的结构、可 review 的差异、可长期维护的一致性。这两者的冲突，构成了 AI 编程规模化之后必然撞上的墙。

我们曾试图用「规则」解决这个问题：把工程规范写成文档，要求 AI 遵守。但规则是抽象的文本，AI 需要先「理解」再「生成」------理解会产生偏差，偏差就导致漂移。

规范约束了「什么不能做」，却没有给出「应该长什么样」。AI 遵守了每一条规则，产出的代码却依然千差万别。

于是需要一个介于「抽象规则」与「最终代码」之间的东西：把规则投影成具体可复制的样板，让 AI 从「从零推理」变成「复制 + 按字段改造」。

这就是本文的主角------AI 模板。而在展开它之前，我们必须先回答一个更大的问题：模板在 AI 工程化的整体版图中，到底处在什么位置？

第 2 章概念模型：AI 工程化的三个层次

任何一套成熟的 AI 工程化体系，都不是单个工具的堆砌，而是三个层次的分工协作。它们回答不同的问题：

层次	载体	回答的问题	对应的 AI 行为	工程类比
约束层	规范（rules）	必须遵守什么？Why + 边界	遵守 / 校验	法律法规
生成层	模板（templates）	怎么产出合规新代码？How + 可复制	复制 + 改造	脚手架
复用层	组件（components）	有哪些成品直接拿来用？	引用已有资产	零件库

下图展示了 AI 工程化体系的三层模型架构，以及各层之间的协作关系：

图 2-1 AI 工程化三层模型架构图

三层缺一不可：

只有规范、没有模板：AI 知道「不能违反什么」，却不知道「应该长什么样」，确定性没有解决。
只有组件、没有模板：组件库解决了「复用已有资产」，但新代码（新页面、新 API 模块）仍要从零生成，没有样板可依。
有规范、有模板、有组件：约束划定边界，模板兜住「生成」这一步的确定性，组件兜住「复用」这一步的效率------三者闭环，才是完整的 AI 工程化。

结论：一套完善的 AI 工程化体系，恰恰需要这三个层次。模板不是孤立的工具，而是「生成层」的引擎，是连接抽象约束与最终代码的关键枢纽。

第 3 章模板定位：生成层的引擎

理解了三层模型，模板的定位就清晰了：模板是生成层的引擎，是「约束」通往「 代码 」的桥梁。

3.1 模板 vs 规范：Why 与 How 的分工

规范（rules）和模板（templates）不是两套平行的规则，而是同一套规则的两种投影：

维度	规范（rules）	模板（templates）
回答	为什么、边界在哪	怎么落地、长什么样
形态	抽象文本、规则条目	可运行的代码样板
约束方式	描述「不可违反」	内嵌 `[MUST]` / `[禁止]` 注释
消费对象	AI 理解后遵守	AI 直接复制改造

两者双向同步、以规范为源 ：模板是规范的「执行投影」，规范是模板的「规则源」。模板不得创造新规则------所有模板里的约束，都必须能在对应规范里找到出处。冲突时以规范为准。

3.2 模板 vs 组件：样板与成品的区别

模板与组件最容易被混淆------它们看起来都是「代码」。但二者的本质完全不同：

维度	模板（templates）	组件（components）
本质	骨架 / 样板	成品 / 资产
消费方式	复制 + 改造成新代码	直接引用复用
生命周期	生成时的起点，改造后即「消失」	长期存在，被多处引用
对象	结构（页面 / API 模块 / store）	零件（按钮 / 弹窗 / 表格）

一句话区分：模板是「用来写新 代码 的」------复制它、改它，它就变成你的业务代码；组件是「拿来用的」------引用它，它始终在那里。

3.3 范式转变：从「凭规则生成」到「复制 + 改造」

这不仅是工具的差异，更是一种生产范式的转变：

范式	AI 的生成方式	不确定性
凭规则生成	读抽象规则 → 理解 → 从零推理 → 生成	高（理解偏差 + 结构漂移）
复制 + 改造	读模板 → 复制骨架 → 按字段改造	低（骨架固定，只改业务差异）

后者的本质是：把 AI 的创造性，从「结构设计」 降维 到「字段填充」------结构是预置好、经过验证的，AI 只负责注入业务差异。这是确定性提升的根本来源。

需要说明的是，这种转变并非没有代价。模板是一份需要人维护、会随规范演进持续更新的资产。它换取的是确定的产出：结构不再漂移、典型错误在生成层被规避。

对高频形态 （如 CRUD 列表页、API 三件套），这份投入是值得的；对低频、探索性场景，保留「凭规则生成」反而更灵活。因此「复制 + 改造」不是对所有代码一刀切，而是按形态权衡------这也解释了为什么模板体系的第六段式 README 要专门回答「何时不用此模板」。

第 4 章模板的作用：确定性核心 + 四维价值

模板在 AI 编程中的作用，可以浓缩为一个核心 + 四个维度。

4.1 核心：解决「确定性」

模板把抽象规则投影成具体可复制的 代码样板，把「从零推理」变成「复制 + 按字段改造」，从而把不确定性压缩到最小的「改造」一步。

规则文本 → AI 理解 → 生成：偏差可能发生在理解层，也可能发生在生成层，漂移不可控。
模板代码 → 复制 → 改字段：骨架是预置的、经过验证的，偏差只可能发生在「改」这一步，且这一步是局部的、可 review 的。

4.2 四维价值

维度	论证
① 确定性	生成起点从「规则文本」变为「样板代码」，结构漂移被骨架锁死，偏差压缩到字段层
② 一致性	全团队 AI 生成代码共享同一骨架，结构可预测、差异可 review、交接成本低
③ 效率 / 上下文经济	AI 不必每次重新推理目录结构、import 顺序、样板声明，节省 tokens，聚焦业务差异
④ 质量兜底	模板内嵌 `[MUST]` / `[禁止]` 注释与「常见错误」清单，把错误模式在生成层就规避，而非等 review 兜底

这四维形成一个完整的论证闭环：确定性解决「能不能对」，一致性解决「好不好维护」，效率解决「快不快」，质量解决「少不少返工」。

用一个列表页的生成场景回看这四维：没有模板时，AI 每次都要重新设计查询逻辑放哪、列配置放哪、空态错误态怎么处理，结构漂移明显；有模板后，骨架预置了「hooks 管数据 + index.tsx 编排 + 组件注入」的标准分层，AI 只需填充字段与业务差异。

确定性来自骨架锁死结构，一致性来自全团队共享同一骨架，效率来自不再重复推理样板，质量来自「常见错误」清单在生成层就规避了漏空态、漏错误处理这类典型问题。

第 5 章模板体系概览：6 个模板 + 内部结构

5.1 六类模板

.claude/templates/front/ 提供 6 类前端标准样板，覆盖「从后端接口到页面」的完整链路：

模板	路径	何时用
API 模块	`api-module/`	新建 `api/{module}/` 三件套（index / request / types）
公共组件	`component/`	新建 shared / business 组件
Zustand Store	`store/`	新建 store（simple / persist / immer 三子模板）
Hook	`hook/`	新建封装 `useRequest` 的查询 hook
列表页	`list-page/`	新建 CRUD 列表页（三段式 + 弹窗）
表单页	`form-page/`	新建独立路由的表单页 / 向导 / 配置页

5.2 模板的内部结构

每个模板由「主文件 + 六段式 README」构成。

主文件（最小可跑样板）：

结构完整、能跑，业务字段用占位符（如 xxxAPI、XxxDTO）
关键约束用 // [MUST]、// [禁止] 标注
每个需替换处用 // TODO: 替换为实际 XX 标注
文件头注释标明：模板名 / 适用场景 / 规则源 / 复制后必改

六段式 README（使用说明书）：

何时用此模板
何时不用此模板
复制后必改
模板特有的常见错误
完整禁止项（指向规范切片）
规则源（指向规范切片）

5.3 模板长什么样：一段示例

下面是一个简化的 API 模块模板骨架，展示模板内部如何通过标注引导 AI 完成「复制 + 改造」：

dart 复制代码

// 模板：api-module（最小可跑样板）
// 适用：新建 api/{module}/ 三件套
// 规则源：02-api-layer.md / 03-type-definition.md
// 复制后必改：将 Xxx 替换为实际模块名

// index.ts ------ 方法定义
export const xxxAPI = {
  // TODO: 替换为实际接口路径
  getList: (params: QueryDTO): Promise<PageResponse<ItemDTO>> => {
    // [MUST] 走模块独享 axios 实例，禁止组件直接 import axios
    return xxxRequestApi.get('/xxx/list', { params });
  },

  create: (payload: CreatePayload): Promise<ItemDTO> => {
    return xxxRequestApi.post('/xxx', payload); // [禁止] 变更请求不可自动执行
  },
};

可以看到三个关键信号：// TODO 标出必改点、// [MUST] 标出不可违反的约束、// [禁止] 高亮常见错误。AI 复制这个骨架后，只需要替换业务差异，而结构与约束由模板兜底。

5.4 模板与切片的双向同步

切片是规则源（Why + 边界），模板是执行投影（How + 可复制）
改切片 → 检查并同步模板；改模板 → 检查是否违反对应切片
模板不得创造新规则，所有约束须在切片里有出处
冲突以切片为准（除非切片过时，先改切片）

这套「模板 <-> 切片映射表」保证：规范每前进一步，模板都跟着落地；模板永不脱离规则源而漂移。

第 6 章如何使用：AI 三层自动调用机制

模板最核心的价值，不在于「被人类阅读」，而在于被工程机制自动「喂」给 AI。这是本项目最独特、也最能代表「AI 工程化」的部分。

整个调用机制自上而下分为三层，通过工程化手段确保模板被 AI 自动、无感地使用：

图 6-1 AI 三层自动调用机制流程图

上图展示了模板从「人类编写的文档」到「AI 实际使用」的完整链路：L1 指令层从规则上强制 AI 必读，L2 注入层从技术上确保内容自动进入上下文，L3 模板层则在代码内部提供具体的改造引导------三层叠加，让模板从「可选参考」变成「生成必经之路」。

6.1 L1 指令层：CLAUDE.md 强制预读

项目的 CLAUDE.md 将「新建代码前必读对应模板 README」标记为 [MUST] 级要求。AI 在新建 api / 组件 / store / hook / 列表页 / 表单页前，必须先扫描对应模板------即使 AI 自信能凭规则生成。

6.2 L2 注入层：pre-tool.mjs 自动注入

检测到 AI 新建文件（Write） 时，自动按路径读取对应模板的 README 内容，注入到 AI 的上下文。这意味着：

开发者无需手动把模板塞给 AI------机制替你做了
模板不是「可选参考」，而是生成流程中的固定一步
注入是自动、无感、零成本的

同时，该 hook 还提供保护性警告：当 AI 试图修改模板本身时，会提示「模板由用户维护，AI 不得主动修改」------保证模板作为团队共享资产不被 AI 随意改动。

6.3 L3 模板层：内部引导改造

模板内部通过三层标注引导 AI 完成「复制 + 改造」：

// TODO: 替换为实际 XX --- 明确的必改点
// [MUST] --- 不可违反的约束
// [禁止] --- 常见错误的高亮提醒

6.4 人类开发者视角

对人类开发者，模板同样可作为标准结构的参考示例 ：翻看模板理解项目的标准骨架，复制后按业务改造。但模板的首要消费者是 AI，人类开发者是副产品------这是它与传统「代码模板」最本质的区别。

第 7 章收益对比：有模板 vs 无模板

收益不是抽象的承诺，而是可感知的差异。下表与前文「四维价值」形成闭环------同一个维度，前面回答「为什么模板重要」，这里回答「到底差多少」。

维度	无模板（凭规则生成）	有模板（复制 + 改造）
确定性	模型理解规则有偏差，结构漂移，每次生成长不一样	骨架固定，偏差压缩到「改字段」一步，结构可预测
一致性	各次生成结构各异，review 与交接成本高	全团队共享同一骨架，差异可读、可 review
效率	每次从头推理样板代码，消耗 tokens 与时间	直接复制骨架，聚焦业务差异，生成更快
质量	错误模式靠事后 review 兜底，返工率高	错误模式在生成层规避，返工率低

关于量化 ：收益的最有力证据是「体系自洽 + 真实工程实践」。若项目积累到可量化的指标（如 AI 首次生成可用率、单页生成耗时、返工次数），可补充进本表；但在缺乏真实数据时，刻意保持定性 + 相对性表述，而非编造数字------一套站得住脚的方法论，比脆弱的伪量化更有说服力。

第 8 章与替代方案的对比：模板不是唯一答案

8.1 模板 vs 纯 AI 自动生成

没有模板的「纯 AI 自动生成」，就是前文的「凭规则生成」------确定性差、漂移不可控。模板本质上是给这个流程加了一个「结构锚点」。

8.2 模板 vs 组件库

组件是成品复用 （引用一个按钮、一个弹窗），模板是结构样板（新建一个页面、一个模块）。二者互补而非互斥------模板内部往往还会引用组件库。

结论：模板不是替代上述任何一种方案，而是补上它们都没覆盖的一环------让「生成新代码」这一步具有确定性。

8.5 汇总对比

方案	消费者	确定性	灵活性	与模板的关系
纯 AI 自动生成	AI	低	高	模板是它的「结构锚点」
组件库	AI / 人	---	---	与模板互补，非替代
模板	AI	高	中	---

第 9 章落地路径

理解模板的价值是一回事，落地是另一回事。这里给出四步路径。

9.1 第一步：盘点高频代码形态

找出团队反复生成的页面 / 模块类型（如 CRUD 列表页、API 三件套、查询 hook）。只有高频形态才值得做模板，低频形态不必过早抽象。

9.2 第二步：从规范提炼模板

模板不得创造新规则。先从已有规范切片提炼骨架，再补占位符与 [MUST] / [禁止] 标注，最后写六段式 README。规范是源，模板是投影。

9.3 第三步：接入三层机制

把「新建前必读模板」写进 CLAUDE.md，再用 pre-tool hook 实现自动注入。这一步让模板从「文档」变成「机制」，是价值放大的关键。

9.4 第四步：小范围试点 + 迭代

先让少数人试用，收集「复制后必改」的痛点，反哺模板与规范。模板是活资产，会随规范演进持续更新，而不是一劳永逸。

第 10 章常见误区与 FAQ

10.1 误区澄清

误区	澄清
模板会僵化创新	模板只约束结构，不约束业务实现，AI 的灵活性保留在「改造」一步
有组件库就不需要模板	组件解决「复用成品」，模板解决「生成新结构」，二者解决不同问题
模板越多越好	模板数量应匹配高频形态，过多会带来维护负担与选择成本
模板 = 代码片段库	模板内嵌规范约束与规则源，是一个「带约束的可复制样板」，不只是代码

10.2 常见 FAQ

模板会不会过时？

不会，前提是保持与规范切片双向同步。规范演进时同步更新模板，模板就不会漂移。

模板与规范冲突时怎么办？

以规范为准。若规范已过时，先修正规范再更新模板------模板不得成为规则的例外。

一个模板适合所有团队吗？

不适合。模板是「规则的执行投影」，不同团队的规范不同，模板也应定制。

模板和组件如何配合？

二者互补。模板负责「生成新结构」，组件负责「复用成品」；模板内部通常会引用组件库，让 AI 生成的新页面既结构合规、又复用已有资产。

模板会不会降低代码质量？

不会，反而提升。模板内嵌 [MUST] / [禁止] 与「常见错误」清单，把典型错误在生成层规避；结构由经过验证的骨架兜底，质量只会更稳定。

谁负责维护模板？

模板是团队共享资产，由团队成员维护，AI 不得主动修改。规范演进时，由人同步更新模板，保持与规范切片一致。

第 11 章演进路线与展望

11.1 短期：补全模板体系

第二批模板（compound 组件 / 详情页 / 路由配置 / 错误边界）按需补齐。当前「不做模板、凭切片生成」的场景，在真实需求出现后评估是否沉淀为模板。

11.2 中期：从「生成」到「校验」

接入 tsc --noEmit / eslint / vite build，让生成结果在机制层被校验，而非依赖 review 兜底。同时沉淀真实指标，让「有模板 vs 无模板」的对比从定性走向数据支撑。

11.3 长期：从「单项目模板」到「跨团队 AI 工程化方法论」

本文的三层模型（约束 / 生成 / 复用）不局限于本项目。它是一套可迁移的 AI 工程化框架：

任何团队构建 AI 编程体系时，都可以用这三层自检：约束是否清晰？生成是否有样板？复用是否沉淀？
模板机制可以推广到后端、测试、文档等领域------凡是「需要确定性产出」的地方，都可以引入「复制 + 改造」的样板范式

从「一个项目的模板」到「一种工程化方法论」，是这份文档最想传达的终局。

附录 A 术语表

术语	含义
约束层 / 规范（rules）	定义「必须遵守什么」的规则切片，Why + 边界
生成层 / 模板（templates）	可复制的代码样板，AI「复制 + 改造」的起点
复用层 / 组件（components）	可被直接引用的成品资产库
L1 指令层	CLAUDE.md 强制 AI 新建前必读模板
L2 注入层	pre-tool.mjs 自动把模板 README 注入 AI 上下文
L3 模板层	模板内部的 TODO / `[MUST]` / `[禁止]` 引导
复制 + 改造	模板消费方式：复制骨架 → 注入业务差异