MasterGo+Claude Code：设计稿自动生成Android布局代码的实践

做 Android 的兄弟们大概率都有过这种经历：设计稿切好了，标注也标了，你对着图纸眯着眼睛数间距，8、16、24、40……然后在 XML 或者 Compose 里一笔一笔把界面描出来。一份首页从量尺寸到手写代码，半天时间就没了，工期紧的时候连摸鱼都摸不安稳。最近我把 MasterGo 和 Claude Code 组合起来，让设计稿直接产出 Android 布局代码，先后跑通了首页、登录页、列表详情页三条完整链路，这套流程基本定型了。

这篇文章就是把完整实践路径摊开来讲：为什么我不让 AI 直接对着截图写代码，开工前要准备哪些东西，设计稿怎么喂给 Claude Code，提示词按什么规则写，以及一套从设计稿到可运行 App 的实测流程。适合正在处理"设计稿到代码"这个环节的 Android 开发，也适合想给团队搭一条 AI 辅助生产线的工程效率负责人。内容偏实操，基本是能直接抄作业的程度。

1. 为什么不建议让 AI 对着截图直接写布局

1.1 截图里没有结构，AI 只能"猜"

第一次用 AI 写布局的人，多数是这么操作的：把 UI 截图丢给 AI，说"按这个给我生成一个 Android 页面"。出来的东西第一眼确实像，打开代码就崩了——颜色全是 #F5F5F5 这种硬编码，间距全是一串 14dp、18dp、23dp 的魔数，文字直接用中文字符串写死在 XML 里，布局嵌套六层起步。原因不复杂：截图是光栅图，里面只有像素，没有层级、没有间距定义、没有颜色 token、没有组件复用关系。AI 只能从视觉上去猜哪些是文本、哪些是间距、哪个容器套哪个容器，猜出来的结果自然和工程规范没关系。

这不是 AI 能力不够，是信息维度不够。设计工具里那些我们平时看不见的东西，恰恰是布局代码最需要的：图层树（谁在谁里面）、自动布局的 gap 和 padding（间距是结构化的，不是量出来的）、颜色变量和文本样式（直接对应 colors.xml 和 typography）、组件实例（对应可复用布局或 Compose 组件）。这些结构信息，比一张截图的十倍信息量还多。所以正确的姿势不是"给 AI 一张图，让它无中生有"，而是"把设计工具里的结构化信息交给 AI，让它老老实实翻译"。

1.2 谁干活的边界要划清楚

我把这条管道拆成两段：MasterGo 负责出"图纸+清单"，Claude Code 负责当"施工队"。图纸的意义在于，每一个间距、颜色、字体都写得明明白白；清单的意义在于，AI 不需要自己翻图层、找样式，拿到 JSON 就能照着施工。Claude Code 的职责也不是"从零生成一个大约差不多的界面"，而是"按照仓库里已有的约定，把清单翻译成符合工程规范的代码，并且自己跑构建、跑 lint、反复改到通过"。

这听起来像是多此一举，实际差别很大。施工队进场之前，你先给了图纸和清单，它自然知道在哪里挖地基、在哪里砌墙。你什么都不给，只拿一张效果图说"照着盖一栋"，那它只能按自己的经验自由发挥。后面你验收的时候，改起来比让它一开始就按图纸干还累。而且设计工具里的图层命名是现成的语义信息，AI 可以直接把这些名字变成控件 id 和变量名，这等于设计侧顺手把代码的可读性也做了。

1.3 为什么选 Claude Code 而不是普通聊天窗口

这个选择不是拍脑袋。普通聊天窗口的致命问题在于：它看不见你的项目。你告诉它"用我们项目的 colors.xml 里的 primary_color"，它没法打开你的仓库确认这个字段到底叫什么。Claude Code 是跑在项目目录里的，它真的会去读你的 build.gradle、res/values 下的资源文件、现有的 Compose 主题，然后按真实存在的名字生成代码。生成完还会顺手帮你跑一下构建，lint 报了什么错，它再改一轮。

这就把"生成代码"变成了"在真实工程里改代码"。一次成败取决于代码能不能编译、资源能不能解析，而不是"看起来像不像"。实测下来，用这招生成的布局，第一次构建通过率比聊天窗口高出一大截，主要是因为它不会编出项目里根本不存在的资源名。后面我慢慢把这里面的流程拆开，发现真正决定生成质量的，是开工前那三件准备工作。

2. 开工前的三件套：图层整理、仓库约定、命令接入

2.1 图层整理：给 AI 一份能读懂的图纸

第一步是语义化命名。在 MasterGo 里，把图层名从"矩形 217"改成"screen_login / header_logo / input_username / btn_primary"。命名不需要很讲究，只要层级清楚、语义明确即可。AI 生成代码时会把这些名字直接映射成 view 的 id 和变量名，命名整理得越干净，生成出来的代码越像人写的。我之前让 AI 生成过一个页面，变量名全带"Rectangle_213"这种残渣，后来回头图层重命名一遍再跑，代码完全换了个样子。

第二步是能自动布局就不用绝对定位。MasterGo 的自动布局会把内边距、子元素间距（gap）结构化地记录下来，导出的 JSON 里有精确的 padding 和 gap 数值。没有自动布局的图层，AI 只能靠坐标差值去推到 8 和 9 这种近似值，再修一遍的功夫比一开始就排好更贵。所以我的原则是：进入管道之前，凡是层层叠叠的盒子，全部改成自动布局；这个改动成本非常低，收益却直接体现在生成质量上。

第三步是颜色和文本样式统一用变量。MasterGo 支持把颜色、字号整理成样式/变量，导出时节点引用的是变量名而不是具体色值。这样 AI 能直接建立"designToken.cardBg = #FFFFFF""designToken.textPrimary = #1A1A1A"这种映射关系，到了 Android 这边就变成 colors.xml 的引用。这一步做完，后面写提示词、做映射都会省很多事。

2.2 仓库约定：把规则写进文档，而不是写进每次提示词

布局规范这种约束，如果每次生成都要在提示词里敲一遍，很容易敲漏，AI 也不会稳定遵守。我建议在仓库里放一份 docs/android-layout-guide.md，把这些固定条款写死：

• 明确技术栈：XML ViewSystem 还是 Compose，老项目还涉及 androidx 的版本约束；
• 资源引用：颜色必须走 @color，文案必须走 @string，尺寸使用 dp 并且优先抽 dimens；
• 命名规则：id 用小写下划线，Compose 组件函数用帕斯卡命名法，文件按页面或模块分包；
• 性能红线：LinearLayout 嵌套不超过三层，能用一个 ConstraintLayout 解决就不要套三层 LinearLayout；
• 可访问性：图片必须带 contentDescription，纯装饰性图标才允许空标签；
• 适配规则：根布局用 match_parent，可滚动页面判断内容是否超一屏再决定加不加 ScrollView。

文档还可以附带一个"golden file"，也就是一两个你们团队心中"标准写法"的布局文件。实测证明，给 AI 一个真实范例，比写一百行文字约束都管用。它对着范例模仿出来的结构，跟你手写代码的风格几乎一致。我们团队后来把之前手写的两个页面放进去当范例，生成结果的代码风格明显向范例靠拢了。

2.3 Claude Code 接入：CLAUDE.md 与自定义命令

Claude Code 启动时会读项目下的 CLAUDE.md 当作长期记忆。我在里面只写一行核心指引："Android 布局生成遵循 docs/android-layout-guide.md，先读取该文件再动手。"这样每次运行都自动继承规则，不用反复粘贴。

再进一步，可以把常用操作收敛成一个斜杠命令。在项目根目录建一个 .claude/commands/gen_layout.md，内容是提示词模板：告诉 Claude Code 读哪个 JSON 文件、目标框架是什么、输出到哪个目录、生成完必须跑一次构建和 lint。用的时候只要输入 /gen_layout app/design/home.json，它就会按模板执行。这套做完之后的日常就变得很简单：设计稿更新 → 重新导出 JSON → 跑命令 → 审查 diff。团队里其他同事也能用，不需要每个人都去研究提示词怎么写。

3. 设计稿进 AI 的三种通道：复制标注、JSON 快照、截图双通道

3.1 通道 A：开发者模式里复制标注

MasterGo 开发者模式能直接看单个图层的尺寸、间距、颜色信息，你可以把关键标注原样复制进提示词。优点是省事、零接入成本，适合那种"只有一个按钮/一个卡片要对齐"的临时需求。缺点是信息是二维的，整个页面的树状层级需要人工梳理，页面一多就累死人。我的判断是，它适合做"单点补全"，不太适合整屏生成。如果你的工作流里大部分时间只是微调某个控件，通道 A 已经够用，不需要上重型方案。

3.2 通道 B：节点树 JSON 快照

这是整套流程的中枢。用社区插件或者自己写脚本，把 MasterGo 里一个 Frame（比如一整个登录页）导出成结构化 JSON。所谓导出脚本，逻辑上其实就是递归遍历图层树，遇到节点就读取它的类型、名字、宽高、布局模式、内边距、间距、文本内容、颜色引用，然后把这些字段拼成一个 JSON。脚本本身不复杂，几十行就能跑起来，但要注意把所有引用名称完整保留，后面 AI 翻译资源时全靠它们。好的快照长得像这样：

{ "type": "FRAME", "name": "screen_login", "width": 375, "height": 812, "layoutMode": "VERTICAL", "paddingLeft": 20, "paddingRight": 20, "paddingTop": 32, "gap": 24, "children": [ { "type": "TEXT", "name": "title_welcome", "text": "欢迎回来", "fontSize": 28, "colorRef": "colorTextPrimary" }, { "type": "TEXT", "name": "subtitle_desc", "text": "登录后可同步你的数据", "fontSize": 14, "colorRef": "colorTextSecondary" }, { "type": "FRAME", "name": "input_area", "layoutMode": "VERTICAL", "gap": 12 } ] }

Claude Code 读进这个 JSON 之后，会自动识别 frame、text、gap、padding，并翻译成布局代码。重点在于：JSON 里的结构关系就等同于 Android 的布局层级，不会发生"AI 猜层级"的事情。这一条保证了生成结果的结构正确性，剩下需要处理的只是属性怎么映射到 Android 的写法。把 JSON 快照放进项目仓库还有额外的好处：以后 AI 想改页面，直接读快照就能还原设计意图，不用重新回设计工具里找。

3.3 通道 C：JSON + 截图双通道

我在实际流程里推荐的是这个组合：把 JSON 快照和界面截图同时给 Claude Code。JSON 提供精确数值，截图提供视觉意图，它能对照截图确认"这里到底是个横向排列的搜索框加按钮，还是两行左对齐的文本"。同时它还能发现 JSON 里可能没体现的细节，比如阴影、状态栏颜色、模糊背景，这些在设计工具里经常以特殊属性存在，不一定进了快照字段。

Claude Code 可以读取图片文件，做法是：把设计稿导出成一张清晰的整屏 PNG（宽度按 375 逻辑像素导出就行），和 JSON 放在同一个目录，提示词里直接指定两个文件路径。三种通道的对比，简单列个表：

实测下来，通道 C 生成的页面，人工返工次数从平均三轮降到一轮以内。大部分情况下，生成的代码直接进 IDE 看一眼，改改细节就能用。

4. Android 提示词的两套约束：XML 与 Compose 的写法差异

4.1 面向 XML ViewSystem 的映射规则

如果项目还在用 XML 布局，关键是给 AI 一张"设计稿属性到 Android 属性"的对照表。我一般直接在提示词里写清楚：

• 根 Frame 如果 layoutMode 是 VERTICAL 且宽度撑满，对应 LinearLayout vertical 或 ConstraintLayout；
• layoutMode + gap 对应子元素的 marginLeft/marginTop，或者直接用 ConstraintLayout 的 chain 处理；
• paddingLeft/paddingRight 对应根布局的 android:paddingStart/paddingEnd；
• 文本节点的 fontSize、lineHeight 对应 TextView 的 textSize 和 lineSpacingExtra；
• colorRef 必须映射到 @color 资源，禁止出现 #FFFFFF 硬编码；
• 图片占位对应 ImageView，必须写 contentDescription（装饰性图标写 null）。

同时给它一条硬约束："嵌套层级不允许超过三层，能用 constraint 完成的排列不要用多个 LinearLayout。"这一条能把第一版的布局深度直接控制在合理范围内。很多生成结果之所以被人嫌弃，问题就出在嵌套深度上，提前写死这一条能省掉一半 review 时间。

4.2 面向 Compose 的映射规则

Compose 的映射逻辑又不一样，自动布局的 VERTICAL + gap 在 Compose 里几乎可以直接翻译成 Column + Arrangement.spacedBy；FRAME 带 padding 对应 Modifier.padding；水平排列对应 Row。但 Compose 有两个容易翻车的点：

• 字体和颜色必须走主题：让 AI 用 MaterialTheme 里的 colorScheme 和 typography，别在 Composable 里写死 Color(0xFF1A1A1A)；
• 间距虽然可以直接写 dp，但要让 AI 优先用统一的 spacing 常量（如果你们项目有），没有的话就抽一个内聚对象管理，避免同一屏里出现 15dp、14dp、16dp 三种接近值。

如果项目里已经有一套现成的组件库（比如 Button、TextField 封装），提示词里要把组件名列出来，明确要求"输入框必须用 InputField 组件"。这样生成出来的代码直接就是业务组件树，而不是一堆裸控件。这一点对 Compose 项目尤其重要，因为 Compose 的复用单元就是函数，AI 不知道你的组件库就很容易重新发明轮子。

4.3 一份可以直接复用的提示词模板

我现在的 /gen_layout 命令核心模板长这样：

你是 Android 资深工程师。读取 app/design/screen_login.json 和 app/design/screen_login.png。 要求： 1. 先阅读 docs/android-layout-guide.md，严格遵守其中的工程规范； 2. 使用 Compose（或 ViewSystem）生成 app/src/main/java/.../ui/login/LoginScreen.kt； 3. 所有颜色引用主题色，文本引用 stringResource，间距引用统一常量； 4. 嵌套不超过三层，优先使用 Column / Row / Spacer； 5. 生成完成后运行 ./gradlew :app:compileDebugKotlin，修复所有编译错误和 lint 警告。 不要只给出代码，先把你对 JSON 结构的关键判断用三句话说明，再输出完整文件。

加最后一句是有私心的：让 AI 先讲判断，等于强制它把设计稿结构说一遍。碰到 JSON 里缺信息的情况（比如阴影没导出），它会主动提出来而不是默默跳过。这个"先复述再动手"的习惯，帮我挡掉了好几次生成结果与设计稿结构不匹配的问题。

5. 实测链路：登录页从设计稿到可运行代码

5.1 一次真实跑通的五个步骤

我用一个虚构的登录页举例，设计稿大概是：顶部 Logo 和欢迎文案，中间两个输入框（用户名、密码），底部一个主按钮，外加一个"忘记密码"的文字链接。第一步，在 MasterGo 里把这一屏整理好命名和自动布局，导出 screen_login.json 和 screen_login.png；第二步，确认主项目根目录已有 CLAUDE.md 和布局规范文档，把两个文件丢进 app/design/；第三步，终端跑 /gen_layout；第四步，AI 生成 LoginScreen.kt 后自己触发编译；第五步，打开 Android Studio 的 Preview 看视觉效果，review 一遍资源引用。

整个过程从整理设计稿到代码落盘，大约四十分钟，其中人工花时间的部分主要是第一步的整理和最后一步的 review。AI 处理中间三个环节大概十分钟不到。第一次跑通的时候我还觉得是自己运气好，连续跑了几个不同页面之后才确认，这个稳定性主要来自前期的准备动作，而不是偶然。

5.2 第一版代码和我会让它改的地方

第一版生成的 Compose 代码结构基本可用，但一定会有几个我要求必改的问题。比如输入框宽度写死了固定 dp，我必须让它改成 Modifier.fillMaxWidth()；按钮颜色直接用了 Color(0xFFFF6A00)，我要让它引用主题里的 primary 色；输入框文案直接写死在代码里，我必须抽成 stringResource。"必须让它改的地方"恰恰是工程规范和快速出活的分界点，规范文档写清楚了，AI 改起来很快，一般一轮就能全改完。

改完的代码大概长这样：

@Composable fun LoginScreen(onLogin: () -> Unit) { Column( modifier = Modifier .fillMaxSize() .padding(horizontal = 20.dp, vertical = 32.dp), verticalArrangement = Arrangement.spacedBy(24.dp) ) { Text( text = stringResource(R.string.welcome_back), style = MaterialTheme.typography.headlineMedium ) InputField( value = username, onValueChange = { username = it }, label = stringResource(R.string.username) ) Button( onClick = onLogin, modifier = Modifier.fillMaxWidth() ) { Text(stringResource(R.string.login)) } } }

如果项目走 XML 路线，生成的对照版本也差不多：外层一个垂直 LinearLayout，根宽 match_parent，padding 对应设计稿的内边距，内部控件全部引用 @string 和 @color，两个输入框之间靠设计稿的 gap 换算成 marginTop。最终提交前我会再检查一遍，确保没有硬编码残留在 diff 里。

5.3 构建与 Review 的检查清单

review 的时候我基本只看四件事：第一，资源引用是否都走了解析器（不是硬编码）；第二，可滚动内容有没有漏掉滚动容器；第三，横向排列的控件在窄屏下会不会挤爆（该用 weight 的地方有没有用）；第四，语义化命名是否合理，id 或变量名是不是还带着默认名。这四件事都有问题的话，直接回到提示词里补规则，比在 IDE 里手工改更划算，因为下一个页面也会踩同样的坑。

6. 踩坑记录与排查清单：固定宽度、密度换算、嵌套地狱

6.1 设计稿整屏固定宽度导致的适配翻车

第一次跑通后我拿真实业务页面测试，发现生成的页面在一个老机型上右边被裁掉一块。排查到最后，根因是设计稿的 Frame 写死了 375 宽，AI 忠实翻译成了固定 width(375.dp)。问题不在 AI，在于我给的图纸就是一张"一列火车图"。修复方式是在规范里加一条："根节点禁止固定宽度，一律 fillMaxWidth/match_parent；横向排列的列表项用 weight。"从此没再犯。这个坑最容易被忽略，因为你 review 的时候默认用的模拟器刚好也是 375 宽，看不出任何问题。

6.2 密度换算：先确认设计稿画布是几倍图

这个坑比较隐蔽。设计稿如果是按 1x 逻辑尺寸画的（比如宽度 375px），转换比例是 1:1，直接照抄 dp 没问题。但有些团队的切图习惯是 2x 甚至 3x 画布，导出的 JSON 里 width 是 750 或 1125。如果 AI 不知道当前设计稿是什么倍数，它会把 750px 当成 750dp，整个页面就会大一圈。我的做法是在导出 JSON 的脚本里直接写入 dpr 字段，并让提示词声明"所有尺寸除以 dpr 得到 dp"。事前写清楚，比事后发现再来一遍快得多。后来我把这条也写进了规范文档，防止同事接手脚本时踩同样的坑。

6.3 嵌套地狱与"差不多就行"的颜色漂移

JSON 快照忠实保留了设计工具的图层树，而设计工具的图层树天然比 Android 更"碎"——光一个按钮可能就拆了五六个图层。AI 如果照着树形结构生成，结果就是三层 LinearLayout 套一个按钮，性能不致命但看着难受。处理办法是在提示词里写死"层级不超过三层"，并让 AI 主动合并语义上的单层分组。有些按钮快照里有背景层、文字层、阴影层，生成代码时只需要一个 Button 组件，需要靠提示词里的"语义合并"指令去抵消树形结构带来的冗余。

配色漂移则是另一种典型：设计稿里两个灰度色在肉眼看来差不多，但一个是 token，一个是本地样式，AI 会忠实生成两个资源。我一般让它生成完列一张"映射清单"，把每个界面元素对应的色值和资源名列成表格，review 时一眼就能看出哪个颜色该合并。这一步已经成为固定流程，因为颜色资源一旦泛滥，后面整个项目的主题统一性都会受影响，不是一个页面的事。

6.4 常见问题的排查速查表

最后分享一个实际操作里的习惯：一次只给 AI 一屏设计稿，不要图省事把整个几十屏的页面全塞进去。屏数一多，第一屏的细节质量就会明显下降，而且单屏生成、单屏 review、单屏提交的节奏，也方便同事做 code review。这个流程用到现在，最明显的变化是纯布局页面的人工工作量少了七成左右，剩下的时间都花在真正需要人判断的事情上——交互状态、边界条件、组件复用这些 AI 还没法替我决定的部分。