AI 编程别被带偏了：决定代码结构的，永远是你的“经验与习惯”
很多人用 AI 写代码越写越崩溃，本质是因为被 AI 牵着鼻子走，接受了一套自己完全不熟悉的复杂架构。AI 时代最高效的工程化流程，不是听 AI 吹嘘所谓的“最佳实践”，而是参考成熟架构与 AI 对齐思路，用你最顺手、最习惯的代码风格去约束 AI。本文分享一套“人主导、契约驱动”的极简 AI 工程化落地指南。
一、 AI 开发的核心认知：你才是“主架构师”
- 用 AI 辅助开发，最容易踩的坑就是： 给 AI 发了个需求，AI 吐出了一套极其晦涩、分层繁琐的代码（比如复杂的 DDD 或不必要的抽象）。代码虽然能跑，但你看着极度别扭。后续调试 Bug 或加新功能时，你发现自己根本改不动。
必须明确一个前提：AI 只是执行层，代码是你天天要看的，你才是最后接盘和维护的人。 让 AI 写代码的唯一标准，不是它有多“先进”，而是它符不符合你熟悉、顺手且认可的模式。
二、 人为主导的 5 步极简落地主线
- 我们遵循 “带着需求确定架构，带着架构设计模块，带着模块确定 UI” 的递进逻辑，把控制权死死抓在自己手里：
[1. 需求澄清] ──> 自己理清逻辑与边界，沟通中完善
│
[2. 架构与 Demo 验证] ──> 参考成熟架构 + 数据表设计 ➔ 跑最小 Demo ➔ 审查顺不顺眼 ➔ 确定范本
│
[3. 业务模块确定] ──> 拆解模块清单 ➔ 核心模块“一文一契约” ➔ 细化技术设计
│
[4. UI 状态机] ──> 参考同类优秀 UI，先定 5 大状态再画界面（说一些你想要的风格，让他出三种ui图，通过图去做）
│
[5. agent.md] ──> 沉淀项目架构与模块清单，让 AI 照猫画虎1：需求澄清（自己先想通，在沟通中完善）
- 别直接提技术，先提“场景与边界”。
明确业务逻辑：先用你自己的逻辑把需求想明白，在与 AI 或团队沟通中不断完善。
特别要明确“本期暂不做什么”（例如：暂不做多租户、暂不做复杂重试机制），防止 AI 擅自扩写逻辑。
用真实数据做契约：给 AI 看真实的输入/输出 JSON 样例（Acceptance Examples），
用明确的数据代替笼统的自然语言。2：架构对齐与最小 Demo 验证（确定代码与数据库规范）
- 架构不能凭空捏造，也不能任由 AI 乱套模式。必须经过“对齐”与“Demo 验尸”：
参考成熟架构与数据库设计：找 1~2 个业界同类优秀项目的架构案例和表结构设计作为参考。
结合你的习惯与 AI 讨论分层逻辑（如：第三方 LLM Provider 放哪一层？数据表如何设计？）。
让 AI 跑一个最简单的 Demo：思路聊定后，不要急着建完整项目，
只让 AI 针对一个最简单的接口写一个极简 Demo。
审查代码风味与个人习惯：重点看包划分、异常处理和数据封装是不是你熟悉的范式。
只要有一行代码让你觉得拧巴，立马让 AI 改到你顺手为止。
固化为项目唯一范本：审查通过后，这个 Demo 和数据规范就升格为整个项目的代码范本。3：业务模块的确定与细化方法（核心：带着架构设计模块）
- 确定好架构和代码范本后，如何把大需求拆解为一个个可落地的业务模块？核心原则：重要的模块单写一份文档，进行需求的逐层细化。
如何拆解业务模块？
按业务领域收敛：比如一个电商应用，拆分为 User（用户与鉴权）、Product（商品管理）、
Order（订单与支付）、Chat（AI 客服）。
按数据流向隔离：每个模块拥有独立的数据契约，防止 AI 在写代码时跨模块直连数据库偷懒。模块文档怎么写？（一模块一文档）
- 在 docs/modules/ 目录下，为每一个核心模块建立独立的 .md 技术文档。文档中必须包含：
模块职责与技术架构：明确写清该模块负责什么，属于架构中的哪一环，
绝对禁止做什么（如：Order 模块禁止直接修改 User 表）。
接口与数据契约：定死 API 的 Request / Response 结构、数据库 Schema 变更以及统一错误码。
行为策略：定义好幂等键、超时重试与降级策略。
核心逻辑：AI 每次只阅读当前模块的文档 + Step 2 审定的 Demo 范本去写代码，
上下文极度干净，绝对不会“越界发挥”。4.UI 界面与组件确定（带着模块找公共组件，按审美定 UI）
可说一些你想要的风格，让他出几种ui图，更好的通过图去决定
- 参考同类优秀项目时，不要只看页面长什么样，更要把它转化为可落地的组件与状态逻辑：
审美确认与公共组件抽离
按个人喜好定视觉：挑选你最喜欢、最顺眼的开源组件库（如 Element Plus、Shadcn UI、Ant Design）
或同类优秀项目的界面样式。
优先复用公共组件：不让 AI 每次重新造轮子。明确告诉 AI：“表格用公共组件 BaseTable，
弹窗用 BaseModal，异步上传用 FileUploader”，保持组件的高度复用与样式统一。- 结合模块能力，绑定 5 大页面状态机
参考同类优秀 UI 项目时，别只看界面长什么样，先让 AI 结合模块能力维护好页面状态机：
Loading（加载中）
Success（正常展示）
Empty（空数据）
Error（报错与重试）
Partial Success（部分成功/异步处理中）
把状态控制死，UI 只是状态的“渲染器”，前端代码就不会飘。什么是状态机
简单来说，状态机就是给 UI 装了一个**“互斥开关”**。它规定一个页面在任意时刻，只能处于一种明确的‘状态’， 并且必须根据状态去显示对应的界面。
如果不定义状态机，AI 写的前端代码通常只有“加载成功”的完美情况，一旦遇到网络慢、没数据或报错，页面就会尴尬白屏或崩溃。 有了状态机，UI 只是状态的“渲染器”，逻辑就不会飘。
UI也可以使用Creative Production、Product Design二个插件
5.沉淀 agent.md（项目架构与模块清单）
- agent.md 是整个项目的“路由大脑”和规矩手册，主要包含两大部分：
项目架构与代码约束：附上你在 2 审定通过的 Demo 结构与目录规范，告诉 AI：“所有代码完全照此模板骨架生成！”
模块清单与文档索引：列出项目所有模块，并指明路径，告诉 AI “要做订单模块，请先阅读 docs/modules/order.md”。版权所有
版权归属：念宇