别再让 AI 瞎写代码了！几个月从 “改一崩三” 到效率翻倍，我靠这套 5S+6A 规范避坑 90%

用 AI 写代码的人，多半都有过这种窒息时刻：

前两周还在庆幸 “终于不用自己敲代码了”，结果项目推进到一半，彻底卡住 —— 前后端接口字段对不上，AI 补的功能把原有逻辑冲得稀烂，甚至改个简单的库存判断，都牵出三个新 bug。

一开始我以为是 AI 不靠谱，直到踩遍坑才发现：不是 AI 不行，是我们没给 AI “规矩”。

这几个月我把 “5S 文档规范 + 6A 流程” 落地到 3 个项目里，从 “天天擦屁股” 到 “效率翻倍”，现在把这套能直接复用的方法拆给你，看完就能用，尤其适合中小型开发项目。

一、先搞懂：AI 编程和传统编程，差的不是 “写代码”，是 “文档”

这是我踩过最痛的坑：

之前让 AI “写个生鲜下单接口”，没给任何文档，结果它自己加了 3 个没用的参数，还把 “库存不足提示” 写成了 “库存过多”，我查了 2 小时才找到问题。

后来用 5S+6A 才明白：AI 不是 “自由写手”，是 “按规则办事的助手”。传统编程是 “先写代码再补文档”，AI 编程必须反过来 —— 先把文档说清楚，再让 AI 按流程走，才不会瞎写。

比如再做 “下单功能”，我先按 5S 规范建了 3 个文档：

• 《说明文档.md》：写清 “用户在手机上下单，支持微信支付，10 分钟未支付自动取消”；

• 《设计文档.md》：用图表画好 “下单→扣库存→生成订单” 的流程；

• 《接口文档.md》：明确请求参数要 “user_id（必填）、goods_id（必填）”，错误码 “ERROR_001 = 库存不足”。

拿着这 3 个文档让 AI 写代码，不仅一次过，后续改逻辑时，我只需要更新文档里的 “取消时间”（比如从 10 分钟改成 15 分钟），AI 就会精准修改，再也不用反复说 “你改错了”。

二、5S 文档规范：5 个 “说明书”，让 AI 不瞎写

很多人觉得 “写文档浪费时间”，但用 AI 编程时，文档就是 “给 AI 的指令”。这 5 个文档是项目的骨架，缺一不可，每个文档的 “写法 + 用法” 都给你整理好了：

1. 《说明文档.md》：项目的 “随身记事本”，从启动写到交付

这是最核心的文档，每次改代码前先更它，主要写 6 件事，别漏：

• 项目概述：叫什么（比如 “生鲜电商下单系统”）、要做什么（用户下单 + 支付 + 取消）、用什么技术（Python+Django）、啥时候交；

• 需求对齐：用 “5W1H” 写清（Who：用户；What：下单减库存；When：24 小时可用；Where：小程序；Why：方便用户；How：点商品→选数量→支付）；

• 进度记录：改完代码就填（比如 “5.20 完成下单接口，待办：加支付回调”）；

• 踩坑记录：比如 “之前没统一时间格式，导致订单时间对不上，后来全项目用 UTC”；

• 后续计划：要加的功能（比如 “优惠券”）、可能的风险（比如 “高峰期卡顿”）。

AI 帮忙点：让 AI 先写初稿，你补细节，它会自动识别 “模糊需求”（比如你只写 “要支持支付”，AI 会问 “支持微信还是支付宝？”）。

2. 《接口文档.md》：前后端 & AI 的 “沟通密码”，别再反复问

之前前后端天天吵 “这个参数叫 user_id 还是 userId”，有了这个文档，再也没这事：

• 通用说明：基础 URL（比如/api/v1/）、用 Token 认证、返回 JSON 格式；

• 接口列表：比如 “下单接口” 是 POST 请求，URL 是/order/create，只有登录用户能调用；

• 接口详情：请求参数里 “user_id 是数字，必填”，响应成功返回 “order_id”，库存不足返回 “ERROR_001”。

AI 帮忙点：让 AI 根据《设计文档.md》生成接口文档初稿，你只需要核对参数名和错误码。

3. 《设计文档.md》：架构不跑偏的 “图纸”，别等后期重构哭

别上来就写代码，先画好 “图纸”：

• 架构图：用 Mermaid 画（比如 “用户→小程序→接口层→服务层→数据库”），AI 能直接生成；

• 模块设计：比如 “下单模块” 有个OrderService类，里面有createOrder（创建订单）、cancelOrder（取消订单）方法；

• 数据库设计：order表有order_id、user_id、create_time字段，给user_id加索引。

AI 帮忙点：AI 会校验你的架构是否和现有系统冲突（比如 “会不会和用户登录系统抢资源”），还能自动补全表结构。

4. 《TASK_XX.md》：把大功能拆成 “AI 能搞定的小任务”

大功能 AI 容易写乱，必须拆成 “≤20 行代码、≤2 小时” 的小任务：

• 比如 “下单功能” 拆成 3 个小任务：

  1. 写参数校验函数（检查 user_id 和 goods_id 有没有传）；

  2. 写库存扣减逻辑（调用库存接口，扣完返回成功）；

  3. 写订单生成逻辑（把数据存进数据库）；

• 每个任务要写 “验收标准”：比如 “参数没传时，返回 ERROR_003”。

AI 帮忙点：AI 会提示 “这个任务太大了，得拆”，还能画甘特图，标清楚 “先做校验，再扣库存，最后生成订单” 的依赖关系。

5. 《验收文档.md》：别等上线才发现问题，测试时就记好

测试不是 “点一点就行”，要按文档记录：

• 测试用例：比如 “场景：用户没传 goods_id；输入：user_id=123，goods_id 没传；预期输出：ERROR_003”；

• 测试结果：10 条用例过了 8 条，2 条失败（比如 “优惠券过期没提示”）；

• 验收结论：“没通过，要改优惠券提示逻辑”。

AI 帮忙点：AI 能自动生成测试代码，还会统计 “测试覆盖率有没有到 80%”，没到会提示你补用例。

三、6A 流程：从需求到交付，一步不跑偏，AI 全程帮你盯

光有文档还不够，得按 6 个阶段推进，每个阶段有明确目标，AI 还会帮你 “查漏补缺”，不会跑偏：

1. Align（需求对齐）：把 “模糊需求” 变 “没争议的共识”

别一开始就写代码！先把需求聊透：

• 用 “5W1H” 问清楚：比如产品说 “要做个下单功能”，你要问 “用户能取消吗？取消后库存退不退？”；

• 把答案写进《说明文档.md》的 “需求对齐” 章节；

• AI 会帮你挑 “模糊的地方”：比如你没写 “取消后要不要退库存”，AI 会主动问。

2. Architect（架构设计）：避免 “后期重构到哭”

需求清楚了，再设计架构：

• 定技术栈（比如 “用 Django 因为团队熟，用 Redis 存购物车”）；

• 画架构图、写《设计文档.md》；

• AI 会校验 “你的架构能不能扛住 100 人同时下单”，还能补 “异常处理流程”（比如 “下单失败要回滚库存”）。

3. Atomize（任务原子化）：拆成 “AI 能搞定的小任务”

按 “模块→功能点→代码单元” 拆任务，比如 “下单模块→参数校验→写校验函数”；

• 每个任务≤20 行代码，≤2 小时；

• 生成《TASK_XX.md》，标清楚依赖关系；

• AI 会提示 “这个任务依赖还没写”“验收标准太模糊”。

4. Approve（任务审批）：别做 “无用功”，先确认任务没问题

任务拆完别直接做，先审批：

• 检查 3 件事：任务覆盖所有需求吗？验收标准能测试吗？依赖合理吗？

• 比如 “没加‘优惠券校验’任务”，就补上；

• AI 会挑 “验收标准模糊的”，比如你写 “好用就行”，AI 会让你改成 “响应时间≤1 秒”。

5. Automate（自动化执行）：AI 写代码 + 测试，你只需要核对

这步才是 AI 写代码，但要按规矩来：

• 让 AI 按《TASK_XX.md》写代码，必须遵循 PEP8 规范（比如函数名用小写 + 下划线）；

• AI 会自动生成测试代码，跑一遍用例；

• 改完代码后，更新《说明文档.md》的进度和《验收文档.md》的测试记录。

6. Assess（质量评估）：交付前最后 “体检”，别漏坑

上线前必须做的 “质量检查”：

• 查 3 件事：代码实现了所有需求吗？有没有冗余代码？文档和代码对得上吗？

• 写《说明文档.md》的 “项目总结”：比如 “总共花了 8 小时，比预期快 2 小时，踩坑点是‘时间格式没统一’”；

• 把所有文档放进docs/目录，方便后续查；

• AI 会生成 “需求匹配度报告”，比如 “90% 需求已实现，10% 待优化（优惠券过期提示）”。

四、3 个 “绝对不能踩” 的红线，和 1 个 “通关密码”

按 5S+6A 做，还要记住这 3 个红线，踩了必翻车；以及 1 个 “阶段通关密码”，没过就别往下走：

1. 3 个红线：别碰！碰了必返工

• 红线 1：别等延期了才处理。AI 每天会生成 “进度风险报告”，预测要延期就立刻补措施（比如 “先做核心的下单，优惠券后续加”）；

• 红线 2：别加 “临时功能”。要加新功能，必须先更《说明文档.md》，写进任务清单，拒绝 “先加上，后续补文档”—— 临时功能会让代码越来越乱；

• 红线 3：别容忍错误。编译错误必须改，还要标清楚 “为什么错”（比如 “少了个逗号”）；测试覆盖率必须≥80%，不够就补用例。

2. 1 个通关密码：阶段转换前，必须过 AI 的 “校验清单”

每个阶段结束，AI 会自动触发校验，没过就整改，别硬往下走：

• 文档符合 5S 格式吗？（比如《TASK_XX.md》有没有验收标准？）

• 前序工作做完了吗？（比如 Architect 阶段结束，《设计文档.md》写完了吗？）

• 任务拆分够小吗？（每个任务≤20 行代码吗？）

• 测试覆盖率≥80% 吗？

• 代码和文档一致吗？

最后：

其实用 5S+6A，核心不是 “多写文档”，而是 “让 AI 按规则做事”—— 前期花 1 小时建文档，后期能省 10 小时擦屁股。

5S+6A规范下载地址：https://download.youkuaiyun.com/download/sirwill/92182119

我刚开始落地时，也觉得 “麻烦”，但用了一次就发现：AI 从 “瞎写的工具” 变成了 “靠谱的助手”，再也不用天天改 bug。

你在用 AI 编程时，踩过最痛的坑是什么？是 “AI 瞎写代码” 还是 “改一崩三”？评论区聊聊～