ai coding guide tmall deep dive¶

Ch09.012 ai coding guide tmall deep dive¶

📊 Level ⭐⭐ | 22.0KB | entities/ai-coding-guide-tmall-deep-dive.md

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

本指南是基于天猫新品团队实践经验的全面AI辅助编码实战手册，从问题本质到解决方案，从理论框架到实战案例，系统性介绍如何让AI更好地完成大部分编码需求。

AI生码的四大痛点¶

当前AI代码生成存在四个核心问题，按严重程度排列：

五大问题根因与解法¶

1. 项目/需求隐含信息过多¶

由于淘系内部项目代码包含专属业务逻辑和来自四面八方的SDK工具库代码，面对无处获取的项目知识，即使是最强模型也无济于事。

解法：

• 使用有明确声明的NPM包，或接入Artifact等辅助文档生成工具
• 提供可访问的外部知识库，包括但不限于MCP工具/项目知识库/需求文档

2. 用户输入不精准，必要信息不足¶

代码开发是从模糊的需求转向无歧义的代码，模糊部分在实现中必然会被补充，实现不合预期的一大原因就是模糊部分没有明确说明。

解法：

• 用户主动增加输入内容/辅助工具提升输入质量
• 对常见情况提供prompt模板，使用时根据实际需求作部分修改
• 借用工具进行用户输入扩写，以及对必要的模糊部分进行标记与阐明
• 引入Spec Coding方案，以详细的文档作为AI输入
• 对高频场景做出约定，通过约定来覆盖模糊（如维护一份持续更新的AGENT.md）
• 意图识别，基于项目上下文自动推测模糊部分
• 接入MCP工具，扩大AI感知力，使AI能更好地理解用户意图
• 通过代码索引/项目文档/CodeWiki等辅助手段，使AI可以基于项目代码快速仿写与推测

最佳实践：最适合的方案应该是先给出一个可以基本描述清楚需求的小文档，再根据AI实际产出的偏离情况来进行问题补充。

3. 任务复杂度高¶

AI生码的成功率会随着任务复杂度的提升而在某个节点开始骤降，此时需要通过合适的手段降低任务难度。

降低任务复杂度：

• 识别重复的工作流与代码，进行针对性优化与封装复用，从而减少生码的代码量与不确定性
• 复杂任务拆分，将单个不易测试的大型任务，拆成多个可验收的小型黑盒
• 固定实现思路/细节，统一思维模型，通过约定来减少思维/选型负担

降低工程复杂度：

• 借助优秀的工程结构设计，实现代码/模块/文件的天然解耦
• 具有优秀工程结构的仓库天然就有较高的AI生成成功率
• 通过代码索引/项目文档/CodeWiki等辅助手段，提高AI检索效率

4. 缺少自检环节¶

现在的常规生码流程，只会进行基础的代码规范与语法检测，并没有完整的Review & Test流程。

代码质量自检：

• 在本地引入自检流程，及时完成代码质量确认
• 使用Code平台的AI CR助手进行发布前预检，可以自定义CR规则

功能自检：

• 前端可以通过接入MCP的方式让AI可以感知前端页面，从而进行部分功能测试
• 后端可以通过单测直接查看功能正确性
• 对于无法测试的大型任务，可以拆分到多个易于验收的黑盒（如前端进行视图分离，对逻辑hooks部分进行单元测试）

5. 模型/Agent的差异与能力限制¶

模型的不同/编码工具的不同都会影响生成结果，即使是同一个模型，也会因为模型的随机性而产生不同的结果。

上下文窗口有限：

• 留存过程文档，实现上下文复用，跳过收集环节
• 代码上下文：仓库信息、接口信息
• 项目上下文：PRD、功能文档
• 提供更精准的上下文，尽量不让AI靠文件猜测
• 通过用户Rule监控注意力状态（比如：让AI每次对话结束都要用谢谢结尾，如果没有则说明上下文窗口已经爆了）

随机性/模型差异导致生成内容质量不稳定：

• 提供更严格的约束文档/Spec Coding方案
• 补充自检环节

修改型问题错误率高：

• 修改型问题相当于上下文更多、正确率要求更高的生码任务
• AI理解力弱，所以修改型任务准确率更低，这就是大家最常提到的"改不动"的问题
• 主要解法是降低任务复杂度：减少AI理解代码的难度或者降低生码任务体量

天生对某些问题能力弱，容易卡在死循环里：

• 识别常见错误场景，By Case分析积累经验，沉淀对应的解法

核心方法论¶

最大化复用¶

无论人工编码还是AI编码，最有效率的提效方案就是提高代码的复用度。在AI编码的背景下，通过复用还可以提高生码任务的确定性，极大降低任务复杂度，提高对代码的掌控度，保证生成结果的质量。

模块优先：将每一部分开发都视为一个明确输入输出的标准可复用模块（可信任的黑盒），且所有相关声明可以通过明确路径访问获取。

胶水编程优先：优先使用已有模块，不要自己造轮子，通过最小量的"胶水代码"将它们组合成完整系统。

工作流复用：对于一些可标准化/重复性强/复杂度高的工作流程，可以及时沉淀到标准的AI工作流（包括但不限于文档、MCP、Skill）。

文档先行¶

文档是AI Coding的第一要素，PRD即单测，文档即代码，优先修改文档而不是代码。这部分文档并不要求大而全，重点是对大方向的描述，与部分易混淆部分的详细说明。

二八定律¶

认清AI的28定律：20%时间可以完成80%的任务，但是剩下的20%要80%的时间。

提高AI生成效率的重点：1是提高前80%的质量，2是提高后20%的效率。

全流程节点优化¶

一次AI Coding的执行流程大概可以概括为：理解用户意图 > 查找上下文 > 设计执行方案 > 代码生成 > 简单校验。掌控AI生码，就是在每个环节都进行明确声明与介入。

前置准备¶

• 准备项目/团队知识库，提供公共组件API、业务知识，包括但不限于mcp/知识库/文档
• 确定基础的代码实现规范，约束代码风格，通常命名README.md/AGENTS.md放在根目录
• 以尽可能明确、解耦的形式，设计仓库的目录结构与实现方案

开发前¶

明确需求内容（代码无关）：

• 对于不明确的情况，可以使用一些辅助工具或者基础模版进行标准化prd的产出
• 需求明确部分，不建议涉及具体实现，目前的AI编码能力已经足够强大，重点说明功能需求即可
• 如果需要进一步明确各部分功能点，可以通过spec工具转换成近似单元测试的功能文档

任务设计与拆分：

• 组件拆分：将复杂、验收卡口严格但无法直接测试、涉及模块多、迭代频率高的大规模任务，拆分到多个简单、迭代频率低、可测试的黑盒
• 流程拆分：将复杂任务进行分步拆解，并通过清单文档记录完成情况

开发中（新建型需求）¶

• 创建并持续迭代过程文档，如页面README、组件说明，从而保障每次对话时AI可以快速获取信息
• 及时管理上下文窗口，确保AI没有失去专注度
• 尽可能使用严格解耦的架构设计，防止留下技术债
• 引入自检机制，保障功能与质量
• 让AI自行添加调试点位，通过调试信息修改问题
• 对黑盒组件/功能创建单元测试
• 通过MCP工具进行页面测试
• 使用AI单独进行代码质量Review环节

常见陷阱： 在一次会话中进行大量任务，这会导致上下文太长太宽泛，模型注意力丢失。对于独立的任务，应该及时新建对话。

开发中（迭代型需求）¶

常见问题场景及后果：

迭代型任务成功率更低的原因： AI天生重模仿而弱理解，新建型任务侧重于模型对代码的仿写能力，而迭代型任务要求AI理解代码且精准修改。

优化策略：

• 注意及时约束，防止AI目标漂移
• 尽量传入精准的上下文，减少AI搜索范围
• 对于复杂迭代，最好及时通过git进行版本管理
• 进一步迭代成功率，主要依赖于仓库架构的解耦程度，改不动时就要依靠极致性的解耦
• 人工必须介入时，可以采用人工提供方案、AI执行改动的半自动方案节省时间

完成后¶

基于需求完成情况及时进行问题点分析与资产沉淀，理想情况甚至可以考虑让AI基于已有经验进行自我迭代。

• 基于生码过程中的常见问题，及时迭代基础规范文档
• 识别关键流程，沉淀到Skill（资产化的AI SOP，包含描述、指令、脚本、模版等内容）
• 识别关键模式，沉淀到标准化组件/模版

两类实战案例¶

AI编码过程中，有个比较重要的关注点是在保证迭代成功率的同时，还要留出一定的可为可介入空间，以及保持对代码的掌控度。根据验收要求以及实际情况，可以将实际需求分为以下两类。

需求驱动型（DO WHAT）¶

关注点：

• 想办法完全阐明需求点，防止AI臆造或偏离
• 要有一定的辅助手段来保证代码质量，从而提高迭代成功率
• 留出一定的人工介入空间，不要产出一堆难以介入的代码

实现风格对比：

工程主导型（HOW TO DO）¶

关注点：

• 代码需要严格符合工程质量
• 编写者要保留对代码大部分的掌控度，且产出内容人工可介入度高
• 对于这类复杂度高/隐含知识多的项目，怎么让AI可以知道做

前置知识准备： 对于这类业务仓库，隐含知识及其多，这些隐含知识有些来自业务语义，有些来自内部平台的开发模式，也有一些来自各自团队的实现规范。如果没有前置输入，AI完全无从下手，此时需要提前识别业务语义下的隐含知识与一些实现规范/方案，并将其沉淀到文档，让AI有迹可循。

视图分离原则： C端AI编码不好用的一个主要原因就是C端逻辑与视觉耦合度太高，而AI又天生缺乏对视觉内容的感知力。最佳解法是尽可能将视觉代码与逻辑代码分离，先让AI完成逻辑代码部分，再单独通过其他方案完成视觉组件的编写。

视图分离的好处：

• 极大地减少了前端的CR压力
• 视图修改不再影响逻辑
• 业务层和视图层均可以快速迁移复用

出码准确率参考¶

深度分析¶

本质洞察：AI编码的核心矛盾¶

天猫团队的实践经验揭示了AI编码的本质矛盾：AI擅长模仿与快速生成，但弱于理解与精准修改。

这一矛盾决定了AI编码的适用边界：

五大痛点的深层关联¶

四大痛点（写不对、写不好、写不了、改不动）并非独立存在，而是由五大根因共同决定：

1. 项目隐含信息过多 — AI无法获取的私有知识是根本障碍
2. 用户输入不精准 — 模糊需求必然导致模糊实现
3. 任务复杂度高 — 复杂度骤降点决定了AI能力的边界
4. 缺少自检环节 — 无完整Review/Test流程意味着质量无保障
5. 模型/Agent能力限制 — 上下文窗口、随机性、理解力都是不可逾越的约束

这五个因素相互叠加，形成"改不动"的死循环：迭代次数越多，上下文越复杂，AI越容易偏离预期。

二八定律的工程启示¶

28定律不仅是现象描述，更是指引优化方向的灯塔：

• 前80%任务（蜜月期）：让AI自由发挥，专注于功能完整性而非代码质量
• 后20%任务（深水区）：人工深度介入，聚焦边缘Case与旧逻辑耦合

关键策略：

• 尽可能扩大前80%的比例（通过复用、模块化、文档先行）
• 提高后20%的处理效率（通过拆分、版本管理、半自动方案）

复用为王的工程价值¶

最大化复用不仅是效率提升手段，更是确定性保障。当天团队提出的"模块优先"、"胶水编程优先"、"工作流复用"三个层次，构成了一套完整的复用体系：

• 模块复用：可信任的黑盒，减少理解成本
• 代码复用：最小化胶水代码，降低生成不确定性
• 流程复用：标准化AI SOP，固化最佳实践

私有包+调用规范能实现95%准确率，正是因为它将复用发挥到极致。

视图分离的战略意义¶

对于C端业务，视图分离不仅是代码组织技巧，更是一种AI时代的架构哲学：

• 业务逻辑：AI擅长，可以快速生成
• 视觉实现：AI天生弱项，需要借助D2C等专用工具

这种分离让AI在擅长的领域发挥最大价值，同时将弱项交给专用工具处理。

实践启示¶

立即可落地的优化手段¶

1. 建立最小可用文档规范

• 不追求大而全的文档，而是"够用就好"
• 优先输出能描述清楚需求的小文档
• 根据AI实际偏离情况进行增量补充
• 实践表明，经过2-3次迭代即可形成精准好用的输入文档

2. 上下文窗口管理

• 每次对话结束时让AI用"谢谢"结尾
• 如果没有出现"谢谢"，说明上下文窗口已满
• 及时创建过程文档（页面README、组件说明）恢复上下文
• 大型任务及时新建对话并传入过程文档

3. 任务拆分与验收

• 复杂任务拆分为多个可测试的黑盒
• 每个黑盒有明确的输入输出和验收标准
• 借助单测直接验证功能正确性
• 通过MCP工具实现前端功能感知与测试

4. 版本控制与迭代策略

• 使用git进行版本管理，为每个重要节点创建commit
• 多方案对比时使用分支管理
• 复杂迭代时记录可回退的版本点
• AI生成是覆盖式的，必须及时存档

5. 私有知识库建设

• 提前沉淀业务语义和实现规范
• 建立公共组件API文档
• 维护持续更新的AGENT.md
• 通过渐进式披露原则管理文档复杂度

不同场景的策略选择¶

需求驱动型（DO WHAT）

• 重点：完全阐明需求点 + 辅助手段保证质量
• 策略：提供足够信息的文档 + 约束产出格式
• 底线：留出人工介入空间，不要产出难以理解的代码

工程主导型（HOW TO DO）

• 重点：前置知识准备 + 人工保留掌控度
• 策略：视图分离 + 技术方案预审
• 关键：渐进式披露文档，入口文档信息全而精

准确率提升路径¶

提升建议： 1. 优先建立私有包和调用规范（投入一次，长期受益） 2. 为高频场景配置严格约束文档/Spec Coding 3. 接入MCP工具扩大AI感知范围 4. 对复杂场景配置By Case经验积累机制

相关实体¶

• Karpathy Claude Md Rules
• Ai Memory Architecture Deep Dive
• Tmall Ai Coding Practice Team Knowledge Base
• Tmall Ai Coding Practice Team Knowledge Base Npm
• Pi Openclaw Coding Harness
• MOC

→ 原文存档