AI Coding

当 AI Coding 工具收到自然语言任务时，会遵循类似人类开发人员解决问题的流程：

• 收集上下文信息。
• 制定计划。
• 修改文件、运行命令并验证结果。

传统对话大模型通常只能告诉你“应该怎么做”，但 AI Coding 工具会和项目真实文件交互，包括读取、修改代码和文档、运行命令、查看报错、迭代修复。这背后，是模型理解意图并转换为工具调用的能力。

工具能力

在代码研发中，并不需要太多上层复杂工具。真正重要的是底层文件操作和命令执行能力，以及模型如何智能组合这些工具完成多步骤任务。

常见工具包括：

• 读取、搜索和编辑文件。
• 运行 Shell 命令。
• 调用子 Agent。
• 读取网页或截图。
• 管理待办事项。
• 执行测试和构建。

上下文管理

每个项目都有大量文件，如何管理上下文非常重要。项目级说明文件，例如 AGENTS.md 或 CLAUDE.md，可以帮助 AI 快速理解项目结构、命令、编码规范和工作流程。

一些实践技巧：

• 操作具体文件时，直接引用文件路径。
• 涉及报错时，提供完整报错信息。
• 涉及前端时，提供截图或页面地址。
• 如果 AI 跑题或做多余事情，及时打断。
• 对重复问题，把正确做法写入项目说明。
• 长时间对话上下文混乱时，重新开启任务或压缩上下文。

前端设计上下文

让 AI 写前端时，只说"做得好看一点"没有约束力。AI 会从训练语料里拼出一个看起来合理的界面，但每次颜色、字号、间距、按钮状态、文案风格都可能漂移。真正有效的做法是把设计规范写成 AI 可以执行的上下文文件，让它在生成代码前先理解系统边界。

一份好的设计上下文，不只是列出几个色值和字体，而是把视觉选择转成语义规则。AI 最擅长执行明确映射：什么状态对应什么 token，什么组件用什么层级，什么文案算合格，什么动效应该被禁止。规则越贴近执行动作，输出越稳定。

颜色系统要按状态组织。不要只写"主色是蓝色、辅助色是灰色"，还要说明背景、边框、实心色块、文字和图标分别使用哪些 token。更进一步，可以把同一颜色系列拆成固定梯度：浅层用于默认背景，更深一层用于 hover，再深一层用于 active；中间层用于边框；高层用于实心按钮、标签和强调元素；最高层用于主要文字和图标。这样 AI 在写按钮、卡片、输入框时，不需要临时猜 hover 应该加深多少。

亮色和暗色主题应该共用同一套语义 token。比如 gray-1000 表示最高优先级文字，在亮色主题里映射到深色，在暗色主题里映射到浅色。开发和 AI 关注的是"这是主文字"，不是具体色值。只要 token 名字稳定，主题切换就不会变成两套互相分裂的设计。

间距系统要限制选择。给 AI 十几个甚至几十个间距值，会让页面节奏变得松散。更适合的方式是定义少量基础值，并说明它们的语义：组内元素用小间距，相关控件之间用中间距，模块之间用大间距，页面区块之间用更大间距。用户未必能说出具体像素，但会感受到哪些内容属于一组、哪里开始进入新的区域。

字体系统也应该从"字号选择"转成"角色选择"。先定义标题、标签、正文、辅助说明、按钮等角色，再为每个角色指定字号、字重、行高。AI 写界面时先判断文本承担什么功能，再套用对应 token。这样比让 AI 自己决定 14px 还是 15px 稳定得多。

组件状态要写完整。一个按钮至少有默认、hover、active、disabled、focus 几种状态；输入框至少有默认、聚焦、错误、禁用、只读几种状态；弹窗、菜单、toast、tab、tooltip 也都有自己的状态和层级。设计上下文不需要把每个组件都写成完整实现，但要说明状态之间如何变化、边框和背景如何跟随、焦点是否必须可见。

文案规则是前端设计上下文里最容易缺失的一层。按钮文案应该尽量包含动作和对象，例如"删除成员"比"删除"更清楚；错误提示应该说明发生了什么、为什么发生、用户下一步能做什么；操作完成提示只需要说明状态变化，不需要重复"成功"这类低信息词。文案规范能减少用户猜测，也能减少 AI 生成空泛提示。

动效要克制。很多界面状态变化应该立即发生，尤其是 hover、active、选中、展开小控件这类轻量反馈。只有当界面层级发生明显变化时，动效才有必要，例如弹窗出现、抽屉进入、内容区域切换。设计上下文应当明确哪些交互不加动画，哪些交互可以使用短动画，避免 AI 默认把所有元素都做成缓慢的淡入淡出。

无障碍规则必须前置。文字和背景要有足够对比度；状态变化不能只靠颜色表达，还要有图标、文本或形状辅助；可交互元素必须保留清晰焦点状态；按钮、链接、输入框要有可理解的标签。无障碍是设计系统的基础约束，不能等上线前再补。对 AI 来说，提前写进上下文比事后逐项修更可靠。

可以把这类规范放进项目里的 DESIGN.md、design.md 或前端专项规则文件中。它最好包含这些部分：

• 颜色 token：语义、状态、亮暗主题映射。
• 间距 token：组内、组间、模块、页面区块的使用规则。
• 字体 token：标题、正文、标签、按钮、辅助说明的角色样式。
• 组件状态：默认、hover、active、disabled、focus、error 的处理方式。
• 文案规则：按钮、错误、空状态、成功提示、确认弹窗的表达方式。
• 动效边界：哪些地方不用动画，哪些地方用短动画。
• 无障碍要求：对比度、焦点、键盘导航、非颜色状态表达。

AI Coding 的质量很大程度取决于上下文质量。代码规范告诉 AI 怎么写代码，设计规范告诉 AI 怎么做产品界面。没有这层约束，AI 生成的是一次性页面；有了这层约束，AI 才能在多次迭代中维持同一套产品气质。