跳转至

天猫新品营销技术团队AI编码实战指南（上）

Ch09.029 天猫新品营销技术团队AI编码实战指南（上）

📊 Level ⭐⭐ | 14.9KB | entities/天猫新品营销技术团队ai编码实战指南上.md

天猫新品营销技术团队AI编码实战指南（上）

→ 原文存档

摘要

天猫新品营销技术团队（卓屿）基于阿里淘内私有项目的实战，系统性梳理 AI 辅助编码从问题诊断到落地方案的完整方法论。核心论点是：AI 生码效果不取决于模型选型，而取决于"前置准备 → 开发前 → 开发中 → 完成后"的全流程工程化。指南将 AI 编码痛点归纳为"写不对、写不好、写不了、改不动"四类，提出"最大化复用、自然语言第一、二八定律"三大核心思想，并将需求分为"需求驱动型"和"工程主导型"两类对应不同实操路径。

核心要点

AI 生码的四大痛点

痛点 表现 根因
写不对 没有按用户意图实现，存在缺陷或无法运行 用户输入模糊、意图不清晰
写不好 代码质量/风格/方案不符合要求 缺少规范约束、自检机制
写不了 项目隐含逻辑过多，AI 无法理解（如私有 SDK） 项目知识不可达
改不动 在错误中循环，甚至改坏其他部分 上下文过长、AI 理解力弱

五大根因与解法

  1. 项目/需求隐含信息过多（AI 不知道）

  2. 解法：使用 NPM/Artifact 这类带声明的包；提供 MCP 工具/项目知识库/需求文档

  3. 用户输入不精准（没给 AI 说）

  4. 解法：prompt 模版、输入扩写工具、Spec Coding、AGENT.md 持续约定、意图识别、CodeWiki 仿写

  5. 关键洞察：文档应该"小而精+持续补充"，而非"大而全"

  6. 任务复杂度高

  7. 降低任务复杂度：识别重复工作流封装复用、复杂任务拆分、固定实现思路减少选型负担

  8. 降低工程复杂度：解耦的工程结构、CodeWiki 提高检索效率

  9. 缺少自检环节

  10. 代码质量自检：本地引入 lint + CR 平台 AI 助手

  11. 功能自检：前端 MCP 页面测试、后端单测、大型任务拆黑盒

  12. 模型/Agent 能力限制与随机性

  13. 上下文窗口：留存过程文档、精准上下文、用户 Rule 监控注意力（如要求每次以"谢谢"结尾以检测上下文是否溢出）
  14. 修改型问题：降低任务体量与代码理解难度
  15. 死循环：识别常见错误场景，By Case 分析积累经验

三大核心思想

  1. 最大化复用
  2. 模块优先：每个功能视为可信任的黑盒
  3. 胶水编程：用最小量胶水代码组合已有模块

  4. 工作流复用：标准化流程沉淀到 Skill

  5. 文档先行

  6. "PRD 即单测，文档即代码"
  7. 优先修改文档而非代码

  8. 基于 Spec-kit 模型，理想是文档与代码 100% 互转，但实测应采用"够用就行"策略

  9. 二八定律

  10. 0% → 80%（蜜月期）：从零开始生成新功能极快
  11. 80% → 100%（深水区）：边缘 Case、与旧逻辑耦合时，AI 表现断崖式下跌
  12. 提效重点：1) 提高前 80% 的质量；2) 提高后 20% 的效率

两类实战案例对比

维度 需求驱动型（DO WHAT） 工程主导型（HOW TO DO）
强调 "要什么功能" "怎么实现"
人工介入 少，关注结果 多，关注代码质量
代码规范度 低 高
验收标准 低 高
隐含知识量 低 高
AI 扮演角色 功能开发者 编码辅助员
案例 小二后台/研发自用工具 线上 C 端页面/商家端页面

落地准确率层级数据

实施方式 出码准确率 人工介入成本
AI 自由发挥 70% 高
有语料的三方包 80% 低
私有包 + 调用规范 95% 低

深度分析

1. "降低复杂度"是 AI 编码的元方法论

指南反复强调降低任务复杂度，本质是承认AI 在 80%→100% 区间的能力衰减是结构性的，不能靠提示词工程修复。两个具体抓手： - 组件拆分：把一个验收卡口严格、迭代频率高的大任务，拆到多个简单、可测试的黑盒； - 流程拆分：用清单文档记录完成情况，恢复对话时可快速重建上下文。

这与 nanobot 的 subagent 设计哲学完全一致：长任务委托给子任务，主流程保持清晰。也呼应 harness engineering 中"working set 管理"原则。

2. "视图分离"是 C 端 AI 编码的核心架构决策

C 端 AI 编码不好用的主要原因是视觉与逻辑耦合度太高，而 AI 天生缺乏视觉感知力。指南给出的解法是强制视图与逻辑分离： - AI 先完成纯逻辑组件（含属性与事件接口） - 视觉组件通过 D2C 工具或视觉稿单独生成 - 用 AI 完成视觉组件与逻辑组件的事件/属性绑定

这种架构带来两个直接收益： 1. CR 压力骤减：视图分离后的购物车组件，CR 时只需重点查看主逻辑 index.tsx 的变更 2. 逻辑复用最大化：剥离视觉的业务逻辑可在不同场景复用，视觉素材可快速迁移到不同项目

这是一个被低估的工程决策：为了让 AI 写好代码，需要主动重构工程结构使其"AI 友好"。

3. "前置文档"是隐含知识可达性的核心机制

工程主导型需求中，AI 完全无从下手的根因是业务语义、内部平台开发模式、团队实现规范这三类隐含知识没有可达入口。指南给出的实践是： - 渐进式披露原则：入口文档信息全而精，详细内容创建子文档 - 文档 AI 生成 + 人工修改并存 - 知识库统一存放位置，便于读取

值得注意的是：前期冷启动写前置文档非常费劲（投入产出比看似低），但复用到第二个相似需求时，"预制文档"的价值会显著体现。这与 腾讯混元 CL-Bench Life 测试揭示的"AI 错因主要是上下文误用而非长文推理不足"完全吻合——AI 不会主动检索时，把信息直接堆到入口文档反而效率最高。

4. "git 版本管理+多分支多方案对比"是 AI 编码的安全网

指南强调"符合需求的代码可能在前几个小时甚至前一天的某个版本"，这是 AI 编码独特的工作模式： - 多方案对比用分支：尝试三种实现路径用三个分支 - 版本管理用 commit：微调阶段及时存档，防止覆盖式写入丢失关键状态

这背离了传统软件工程的"分支 = 功能"语义，演化为"分支 = 实验"。配合 AI 工具的回退功能（但不能完全信任），形成实际可行的安全网。

5. "意图识别 + Spec Coding"的张力

指南提出两个看似矛盾的方向： - 意图识别：基于项目上下文自动推测模糊部分（节省用户输入） - Spec Coding：以详细文档作为 AI 输入（增加用户输入）

实际选择标准是项目复杂度与验收标准的乘积： - 简单需求驱动型：意图识别足够 - 复杂工程主导型：Spec Coding 必需

这种"看场景选方法"的二分法，比通用方案更务实，避免了"一种方案打天下"的过度工程化。

6. "代码质量决定迭代成功率"的复利效应

指南给出一个关键数据点：初始的代码质量对后续迭代成功率有较大影响。如果源代码已经在堆砌代码，后续迭代时 AI 会延续这个风格，导致迭代成功率急速下降，并丧失人工介入修改代码的空间。

这意味着 AI 编码存在质量复利效应： - 早期严格控制代码质量 → 后续 AI 能高质量延续 → 迭代效率持续高 - 早期允许低质量堆砌 → 后续 AI 越改越乱 → 最终人工重写

对应的工程要求：第一次让 AI 生成代码时就必须有清晰的工程结构和代码规范，否则后续无法挽回。

实践启示

  1. 建立全流程节点优化清单：照搬"前置准备 → 开发前 → 开发中（新建型/迭代型分流）→ 完成后"四阶段，每阶段建立检查项，而不是把 AI 编码当作"一次性 prompt"。

  2. 强制视图分离架构：对所有 C 端项目，在工程初始化阶段就规定"视图组件不含业务逻辑"。这是 AI 编码效率提升的最大单一杠杆。

  3. AGENT.md 作为活文档：在仓库根目录维护持续更新的 AGENT.md，记录约定、踩坑、修复模式。Cursor/Claude Code 等工具会自动读取，提高一致性。

  4. PRD 即单测的工程化实践：复杂需求用 spec 工具把 PRD 转换成近似单元测试的功能文档，必要时落地为真单测。这同时解决了"需求模糊"和"验收无标准"两个问题。

  5. By Case 沉淀错误模式：对持续失败的场景，建立 By Case 库，沉淀对应解法。这是对抗模型随机性的核心机制——把"经验"从个人转移到团队资产。

  6. Skill 化工作流沉淀：识别"可标准化/重复性强/涉及文件多"的流程，沉淀到标准 AI Skill（含描述、指令、脚本、模版）。例：后端 solution 创建、前端配置项新增 + 读取代码生成、D2C → 逻辑视图绑定流程。

  7. AI CR 必须前置：在发布前引入 AI CR 助手（带自定义规则），不要等到 PR 阶段才发现问题，否则与人工 CR 形成"AI 写、人工救"的低效循环。

  8. 接口统一性约束：对私有 SDK 等隐含知识重的部分，提供 mcp 工具或自动生成调用文档（Artifact7 等），把 95% 准确率的方案规模化。

与现有知识体系的关联