1. 项目概述一个为AI编码助手设计的UI设计规范与智能体系统最近在探索如何让Claude Code和Cursor这类AI编码助手更高效地产出高质量的UI代码时我发现了一个非常有意思的开源项目agents-ui-craft。这本质上不是一个可以直接运行的软件而是一套规范驱动的UI设计智能体系统。简单来说它就像为你的AI编程伙伴Claude或Cursor配备了一整套UI设计团队的“思维框架”和“工作手册”。传统的UI开发无论是手动编写还是借助AI生成常常面临风格不一致、设计模式混乱、可维护性差等问题。AI虽然能写代码但它缺乏一个持续、统一的“设计原则”来指导每一次的代码生成决策。这个项目就是为了解决这个问题而生。它通过定义一套完整的“宪法”、角色分工、评审流程和共享的设计知识库将AI从一个单纯的代码生成器转变为一个懂得遵循设计规范、具备批判性思维的“UI工匠”。这套系统特别适合前端工程师、全栈开发者以及产品团队中负责快速构建UI原型的成员。无论你是想确保一个大型项目中所有AI生成的UI组件都保持统一还是希望在小项目中快速获得符合现代设计语言如清晰的信息层级、可访问性、响应式布局的代码这套系统都能提供一个结构化的引导。接下来我将带你深入拆解它的核心设计、如何上手使用并分享我在实际配置和应用过程中的一些心得与踩过的坑。2. 核心架构与设计哲学解析2.1 规范驱动与宪法约束为什么需要“宪法”agents-ui-craft最核心的理念是“规范驱动”。这与我们常见的“结果驱动”或“提示词驱动”有本质区别。它不是简单地给AI一个任务描述如“画一个登录框”然后期待一个过得去的结果。而是预先定义好一整套游戏规则让AI在规则内进行创作。项目根目录下的CONSTITUTION.md文件就是这套规则的“根本大法”包含了从C1到C11共十一条宪法条款。这些条款不是具体的技术实现而是高层次的设计原则和价值观。例如它可能规定“C1用户意图至上”、“C2信息层级必须清晰”、“C3交互必须具有可预测性”、“C4代码需具备可访问性基础”等等。为什么这比一个复杂的提示词更有效一个复杂的提示词可能会被AI在后续对话中逐渐遗忘或稀释。而“宪法”作为一个被持续引用的权威文件为所有后续的AI决策提供了不可动摇的评判基准。在系统中这体现为“宪法对齐门控”机制——任何设计产出在最终被接受前都需要经过一道或多道以宪法条款为标准的审查“门”。这确保了AI的行为不会偏离最初设定的设计轨道。2.2 八角色协同系统从创建到批判的完整工作流该系统模拟了一个专业的UI设计团队设置了八个不同的AI智能体角色分为两大类六位创造者和两位评审者。六位创造者角色构成了UI从无到有的核心生产线意图分析师负责解析用户模糊的需求将其转化为明确、可执行的设计意图说明书。结构架构师根据意图说明书规划UI的整体布局、组件结构和导航流产出结构规范。视觉设计师在结构基础上定义颜色、字体、间距、阴影等视觉属性产出视觉语言规范。组件工程师将视觉和结构规范转化为具体的、可复用的前端组件代码如React/Vue组件。交互细节师专注于微交互、状态反馈如加载、成功、错误、动画曲线等细节的实现。内容策略师确保界面上的文案清晰、一致、符合品牌调性并处理好国际化i18n的占位逻辑。两位评审者角色则负责质量把控规范守门员这是一个“只读”的批判角色。它的唯一职责是拿着CONSTITUTION.md和UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md操作规范对照检查创造者们的产出。它不进行修改只提出是否符合规范的异议。这模拟了代码审查中“审核者”的角色保证了客观性。工艺成熟度审计师这个角色站在更高维度评估整个UI设计的成熟度、一致性和未来可维护性。它会参考CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md工艺与判断基础中的共享知识识别潜在的设计反模式或技术债。这种角色划分的妙处在于它将一个复杂的UI设计任务进行了职责分离。当你需要对某个具体环节比如调整颜色对比度以满足可访问性进行优化时你可以直接与“视觉设计师”或“规范守门员”对话而不必让AI在“全栈设计师”的角色中混淆上下文。2.3 共享知识层工艺与判断的基础CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md这个文件是整个系统的“共享大脑”或“设计模式库”。它包含了所有角色在做出判断时都需要用到的公共知识设计透镜一系列审视UI的固定角度例如“从首次用户视角看”、“从可访问性工具视角看”、“从性能瓶颈视角看”。核心问题集针对任何UI决策都可以提出的标准问题例如“这个操作的主要按钮足够突出吗”、“错误状态是否提供了恢复路径”。反模式清单明确列出需要避免的常见糟糕设计比如“神秘肉导航”、“模态框滥用”、“不一致的反馈机制”。这个共享层的存在确保了八位角色虽然分工不同但使用的是同一套设计语言和评判标准。当“结构架构师”设计一个布局时和“规范守门员”审查这个布局时他们对于什么是“好的信息层级”有着共同的理解基础。这极大地减少了内部分歧和沟通成本。3. 文件结构与核心配置详解要真正用好这套系统必须理解其文件组织方式。它不是一个黑盒所有规则都是透明、可修改的Markdown文件。3.1 核心治理文件系统的源代码项目根目录下的几个.md文件是系统的配置核心我习惯称它们为“治理文件”CONSTITUTION.md如前所述这是宪法。它是最高准则通常在你熟悉系统后可以根据自己团队的设计规范进行定制。例如如果你的品牌色是蓝色系你可以在相关条款中强调主色的应用规则。UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md这是操作规范说明书。它详细定义了每个角色的具体输入、输出、职责边界、可调用的工具如能否访问网络、能否读写文件以及他们之间如何协作。你可以把它想象成每个角色的“岗位说明书”。§5章节尤其重要它包含了每个角色的具体“契约”。CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md共享知识库。这部分内容最具有普适性也最值得你花时间阅读和吸收。即使不接入AI其中的设计透镜和反模式清单对你个人进行UI评审也极有帮助。AGENTS.md这是一个任务到智能体的映射表。它告诉你当遇到“制定设计系统Token”、“审查组件API”等具体任务时应该优先调用哪个角色。这能帮你快速选择正确的工具。3.2 智能体实现Claude Code 与 Cursor 的配置系统为两款主流的AI编码工具提供了开箱即用的配置但原理不同。对于 Claude Code智能体以“子智能体”的形式存在。具体文件位于.claude/agents/目录下每个角色一个.md文件。每个文件都遵循Claude Code的子智能体格式包含YAML前置元数据定义了角色名称、描述、核心指令和详细的角色说明。当你将整个项目克隆到工作区Claude Code会自动加载这些智能体。你可以通过/agents命令查看所有已加载的智能体并通过类似“请使用结构架构师角色来帮我分析这个页面的布局”这样的指令来明确调用。注意Claude Code的子智能体配置是“只读”启动的。这意味着像“规范守门员”这样的评审角色其配置中已经预设了disallowedTools: [Write, Edit]确保它只能阅读和评论不会意外修改你的文件完美符合其审计职能。对于 CursorCursor的规则机制不同它使用.cursor/rules/目录下的规则文件。本项目提供了ui-craft-system.mdc文件。你需要将这个文件复制到你的项目根目录下的.cursor/rules/文件夹中。这个规则文件被设置为alwaysApply意味着只要你在当前项目中与Cursor对话这套UI设计规范就会在后台持续影响Cursor的代码生成和建议无需每次手动提及。一个关键区别Cursor的规则是全局、隐式生效的而Claude Code的智能体需要你显式调用。这意味着在Cursor中你可能会更自然地获得符合规范的代码建议而在Claude Code中你对工作流程的控制力更强可以进行更精细的角色调度。3.3 artifacts目录与集成模式artifacts/目录是一个约定占位符。它代表了使用此系统的项目产出的中间或最终产物应该存放的位置。例如“结构架构师”产出的structure-spec.md或者“组件工程师”生成的组件代码片段。在实际项目中你可以将这个目录链接到你的docs/或specs/目录下。项目文档建议了两种集成到现有应用仓库的模式子模块模式将agents-ui-craft作为Git子模块添加到你的项目里例如放在vendor/目录下。然后通过符号链接symlink将子模块内的.claude/agents/链接到你主项目的根目录。这样做的好处是你可以随时通过更新子模块来获取智能体系统的最新版本。一次性复制模式直接将你需要的治理文件宪法、操作规范等和.claude/agents/目录复制到你的主项目中并将其纳入你的版本管理。这种方式更简单直接但后续更新需要手动同步。实操心得对于团队项目我强烈推荐子模块模式。它明确了这套设计规范是一个独立的、可版本化的“依赖项”。当团队更新设计规范时只需要更新子模块引用所有成员都能同步。对于个人或快速原型项目复制模式更轻量。4. 完整上手实操与工作流演示4.1 环境准备与项目初始化假设我们使用Claude Code进行演示目标是为一个新的“任务管理应用”创建登录页面的UI代码。步骤1获取智能体系统# 在你的工作目录下克隆智能体系统仓库 git clone https://github.com/saralobo/agents-ui-craft.git # 进入目录查看核心文件 cd agents-ui-craft ls -la此时你应该能看到前文提到的所有核心.md文件和.claude、.cursor目录。步骤2集成到你的项目我们采用“一次性复制模式”来创建一个演示项目。# 回到上级目录创建你的应用项目文件夹 cd .. mkdir my-task-app cd my-task-app # 将智能体系统的核心文件复制过来 cp -r ../agents-ui-craft/.claude . cp ../agents-ui-craft/CONSTITUTION.md . cp ../agents-ui-craft/CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md . cp ../agents-ui-craft/UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md . # 可选创建artifacts目录用于存放产出 mkdir -p artifacts步骤3验证智能体加载在VS Code中打开my-task-app文件夹并确保已安装并登录Claude Code插件。在Chat界面输入/agents并发送。你应该能在回复中看到一个列表其中包含“意图分析师”、“结构架构师”等八个智能体这表明系统已成功加载。4.2 分步工作流从需求到代码现在我们模拟一个完整的UI设计流程。阶段一需求澄清意图分析师在Claude Code聊天框中明确指定角色intent-analyst 我们需要为“极简任务管理应用”设计一个登录页面。核心用户是追求效率的个体工作者。功能包括邮箱登录、密码登录、忘记密码链接、第三方登录Google、GitHub选项以及注册新账户的入口。请生成一份意图说明书。“意图分析师”会开始工作它会询问一些澄清问题并最终产出一份artifacts/intent-spec.md文件。这份文件会明确业务目标、用户画像、核心任务和成功标准。阶段二结构设计结构架构师基于意图说明书我们召唤结构架构师structure-architect 请基于 artifacts/intent-spec.md 中的需求设计登录页面的布局结构规范。考虑移动端优先的响应式设计。结构架构师会产出artifacts/structure-spec.md里面可能包含整体采用居中卡片布局卡片内部分为标题区、表单区邮箱/密码输入框、记住我复选框、登录按钮、辅助链接区忘记密码、分隔线、第三方登录按钮组、注册引导区。同时会注明在不同屏幕尺寸下的布局变化。阶段三视觉设计视觉设计师visual-designer 请参考我们的结构规范 (artifacts/structure-spec.md)定义一套清新、专业的视觉语言。主色调建议使用蓝色系体现可靠与效率。请产出视觉规范包括颜色、字体、间距、圆角等。视觉设计师会产出artifacts/visual-spec.md定义诸如主色#2563eb错误色#dc2626字体家族system-ui, -apple-system标题字号、正文字号使用4px为基数的间距系统4px, 8px, 16px, 24px...卡片圆角8px输入框圆角6px。阶段四组件实现组件工程师现在我们可以将规范转化为代码。假设我们使用React和Tailwind CSS。Component-engineer 请根据结构规范 (artifacts/structure-spec.md) 和视觉规范 (artifacts/visual-spec.md)使用React和Tailwind CSS实现登录页面的主要组件。请先创建最核心的LoginForm组件。组件工程师会开始编写LoginForm.jsx应用定义的颜色、间距并构建出完整的表单JSX结构。它可能会询问一些细节比如第三方登录按钮的图标如何处理。阶段五交互与细节交互细节师interaction-detailer 请审查并增强刚才生成的LoginForm组件的交互细节。重点包括表单验证的实时反馈、登录按钮的加载状态、密码显示/隐藏切换功能。交互细节师会修改组件添加表单验证逻辑、为提交按钮添加loading状态并实现一个眼睛图标用于切换密码明文显示。阶段六内容与文案内容策略师content-strategist 请审查当前组件和页面中的文案。确保按钮标签、提示信息、错误信息、占位符文本清晰、一致且友好。例如将“Submit”改为更具体的“Sign In”。内容策略师会优化所有文本确保品牌声音一致并将静态文本提取为常量或i18n键为国际化做准备。4.3 质量审查流程在任一阶段或所有组件完成后我们可以启动评审流程。调用规范守门员进行合规审查reference-gatekeeper 请依据 CONSTITUTION.md 和操作规范全面审查 artifacts/ 目录下所有的产出物以及当前项目中的LoginForm组件代码。请列出任何不符合宪法条款的问题。守门员会逐条检查例如“C4可访问性检查密码输入框未关联aria-describedby属性以提示密码要求建议补充。”“C2信息层级检查错误信息仅用红色文字对于色盲用户可能不够清晰建议同时添加图标或下划线。”调用工艺成熟度审计师进行高阶评估craft-maturity-auditor 请从整体工艺成熟度角度评估我们为登录页面创建的这套UI设计。是否存在反模式与未来可能扩展的仪表盘页面在设计语言上如何保持一致性审计师可能会指出“当前设计使用了硬编码的颜色值建议将颜色定义为CSS自定义属性或Tailwind配置以方便未来维护和主题切换。”“登录卡片与未来仪表盘的卡片样式阴影、圆角需要建立统一的设计Token。”5. 常见问题、排查技巧与进阶实践5.1 智能体未加载或角色不识别问题在Claude Code中输入/agents后看不到八个智能体或提及角色无反应。排查确认目录位置确保.claude/agents/文件夹位于你当前VS Code工作区根目录下。Claude Code只加载当前打开文件夹下的配置。检查文件完整性确保从原仓库复制的.claude/agents/目录内包含所有8个.md文件且文件内容未被损坏。重启Claude Code有时插件需要重新加载工作区配置。尝试完全重启VS Code。查看Claude Code设置在VS Code设置中搜索“Claude”确保“Subagent Directories”等路径设置正确通常默认即可。5.2 智能体行为不符合预期问题某个角色如视觉设计师给出的建议非常泛泛没有参考宪法或共享知识库。排查与解决强化上下文引用在指令中明确要求它参考特定文件。例如“visual-designer请**严格依据CONSTITUTION.md中的C3一致性和C7美学完整性条款并参考CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md中的‘视觉平衡透镜’来评审这个配色方案。”检查操作规范打开UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md找到对应角色§5章节查看其“核心指令”部分。你可能需要将该角色的核心指令复制到对话中以重置其上下文。分步引导AI在处理复杂、多步骤任务时可能丢失上下文。将大任务拆解分多次对话进行每次明确当前步骤和依据的规范。5.3 在Cursor中应用效果不明显问题已将.mdc规则文件放入正确位置但Cursor生成的代码似乎没有受到明显影响。排查规则文件位置确保ui-craft-system.mdc文件位于你的项目根目录/.cursor/rules/下。rules文件夹可能需要手动创建。规则语法用文本编辑器打开.mdc文件检查其内容是否为有效的Cursor规则格式。确保没有语法错误。主动提及虽然规则设置为alwaysApply但在复杂任务开始时主动在对话中提及“请遵循我们项目的UI设计宪法规则”可以更好地唤醒Cursor对规则的注意力。规则冲突检查项目中是否有其他.mdc规则文件可能存在规则冲突。可以尝试暂时移除非UI相关的规则文件进行测试。5.4 性能与成本考量上下文长度频繁引用多个长篇规范文件宪法、操作规范、共享知识库会快速消耗AI模型的上下文窗口。这可能导致对话后期模型“忘记”了早期的规范。优化策略按需引用不要一次性要求AI参考所有文件。在特定阶段只引用最相关的1-2个文件。例如在视觉设计阶段主要引用宪法和视觉相关的共享知识部分。总结与摘要可以为每个规范文件创建一个简短的“摘要版”或“速查卡”只包含最核心的条款和问题在对话中优先使用摘要仅在需要深度审查时引用全文。分段对话将整个UI设计流程分成多个独立的对话会话。每个会话专注于一个角色和阶段并重新注入必要的规范上下文。这样虽然增加了手动操作但保证了每个阶段上下文的清晰和高效。5.5 自定义与扩展打造你自己的设计宪法这套系统的真正威力在于其可定制性。MIT许可证允许你自由修改和分发。定制宪法打开CONSTITUTION.md将里面的C1-C11条款修改成你公司或团队的设计原则。例如加入你们独有的设计系统名称、品牌价值观描述。扩充共享知识库在CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md中添加你们团队在实践中总结出的特有“反模式”或“最佳实践”。例如“反模式在我们的数据看板中避免使用超过5种以上的颜色编码序列。”创建新角色如果你发现现有六位创造者无法覆盖你的需求比如需要一个专门的“数据可视化设计师”你可以模仿.claude/agents/下的文件格式创建一个新的智能体文件并在AGENTS.md和操作规范中定义它的职责和契约。集成现有设计系统将你的Figma设计Token、组件库文档链接或代码片段以引用的形式融入到共享知识库或各个角色的指令中让AI生成的代码能直接匹配你现有的设计资产。一个进阶实践你可以建立一个“智能体工厂”流水线。使用脚本或简单的CI/CD流程在代码提交前自动用“规范守门员”智能体对变更的UI组件文件进行审查并将审查意见以评论形式提交到Pull Request中。这能将设计规范检查真正融入到开发流程中。经过一段时间的实践我发现agents-ui-craft系统最大的价值不在于替代设计师而在于提升开发者与AI协作的规范性和产出质量的下限。它迫使你在写第一行代码前先思考设计原则并通过多角色的评审机制不断纠偏。刚开始设置和调用角色会觉得有些繁琐但一旦流程跑顺它就像一位永不疲倦、严格遵循章程的设计伙伴能帮你把那些容易忽略的细节如可访问性、一致性牢牢守住。对于追求代码质量和设计规范性的团队来说投入时间学习和定制这套系统长远看会是一笔非常划算的投资。