企业官网建设流程全解析

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从无到有的核心生产线：

1. 意图分析师：负责解析用户模糊的需求，将其转化为明确、可执行的设计意图说明书。
2. 结构架构师：根据意图说明书，规划UI的整体布局、组件结构和导航流，产出结构规范。
3. 视觉设计师：在结构基础上，定义颜色、字体、间距、阴影等视觉属性，产出视觉语言规范。
4. 组件工程师：将视觉和结构规范转化为具体的、可复用的前端组件代码（如React/Vue组件）。
5. 交互细节师：专注于微交互、状态反馈（如加载、成功、错误）、动画曲线等细节的实现。
6. 内容策略师：确保界面上的文案清晰、一致、符合品牌调性，并处理好国际化（i18n）的占位逻辑。

两位评审者角色则负责质量把控：

1. 规范守门员：这是一个“只读”的批判角色。它的唯一职责是拿着CONSTITUTION.md和UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md（操作规范），对照检查创造者们的产出。它不进行修改，只提出是否符合规范的异议。这模拟了代码审查中“审核者”的角色，保证了客观性。
2. 工艺成熟度审计师：这个角色站在更高维度，评估整个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]，确保它只能阅读和评论，不会意外修改你的文件，完美符合其审计职能。

对于 Cursor：Cursor的规则机制不同，它使用.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/目录下。

项目文档建议了两种集成到现有应用仓库的模式：

1. 子模块模式：将agents-ui-craft作为Git子模块添加到你的项目里（例如放在vendor/目录下）。然后，通过符号链接（symlink）将子模块内的.claude/agents/链接到你主项目的根目录。这样做的好处是，你可以随时通过更新子模块来获取智能体系统的最新版本。
2. 一次性复制模式：直接将你需要的治理文件（宪法、操作规范等）和.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后看不到八个智能体，或@提及角色无反应。
• 排查：
  1. 确认目录位置：确保.claude/agents/文件夹位于你当前VS Code工作区根目录下。Claude Code只加载当前打开文件夹下的配置。
  2. 检查文件完整性：确保从原仓库复制的.claude/agents/目录内包含所有8个.md文件，且文件内容未被损坏。
  3. 重启Claude Code：有时插件需要重新加载工作区配置。尝试完全重启VS Code。
  4. 查看Claude Code设置：在VS Code设置中搜索“Claude”，确保“Subagent Directories”等路径设置正确（通常默认即可）。

5.2 智能体行为不符合预期

• 问题：某个角色（如视觉设计师）给出的建议非常泛泛，没有参考宪法或共享知识库。
• 排查与解决：
  1. 强化上下文引用：在指令中明确要求它参考特定文件。例如：“@visual-designer请**严格依据CONSTITUTION.md中的C3（一致性）和C7（美学完整性）条款，并参考CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md中的‘视觉平衡透镜’，来评审这个配色方案。”
  2. 检查操作规范：打开UI-CRAFT-AGENT-SYSTEM-OPERATIONAL-SPEC.md，找到对应角色（§5章节），查看其“核心指令”部分。你可能需要将该角色的核心指令复制到对话中，以重置其上下文。
  3. 分步引导：AI在处理复杂、多步骤任务时可能丢失上下文。将大任务拆解，分多次对话进行，每次明确当前步骤和依据的规范。

5.3 在Cursor中应用效果不明显

• 问题：已将.mdc规则文件放入正确位置，但Cursor生成的代码似乎没有受到明显影响。
• 排查：
  1. 规则文件位置：确保ui-craft-system.mdc文件位于你的项目根目录/.cursor/rules/下。rules文件夹可能需要手动创建。
  2. 规则语法：用文本编辑器打开.mdc文件，检查其内容是否为有效的Cursor规则格式。确保没有语法错误。
  3. 主动提及：虽然规则设置为alwaysApply，但在复杂任务开始时，主动在对话中提及“请遵循我们项目的UI设计宪法规则”，可以更好地唤醒Cursor对规则的注意力。
  4. 规则冲突：检查项目中是否有其他.mdc规则文件，可能存在规则冲突。可以尝试暂时移除非UI相关的规则文件进行测试。

5.4 性能与成本考量

• 上下文长度：频繁引用多个长篇规范文件（宪法、操作规范、共享知识库）会快速消耗AI模型的上下文窗口。这可能导致对话后期，模型“忘记”了早期的规范。
• 优化策略：
  • 按需引用：不要一次性要求AI参考所有文件。在特定阶段，只引用最相关的1-2个文件。例如，在视觉设计阶段，主要引用宪法和视觉相关的共享知识部分。
  • 总结与摘要：可以为每个规范文件创建一个简短的“摘要版”或“速查卡”，只包含最核心的条款和问题，在对话中优先使用摘要，仅在需要深度审查时引用全文。
  • 分段对话：将整个UI设计流程分成多个独立的对话会话。每个会话专注于一个角色和阶段，并重新注入必要的规范上下文。这样虽然增加了手动操作，但保证了每个阶段上下文的清晰和高效。

5.5 自定义与扩展：打造你自己的设计宪法

这套系统的真正威力在于其可定制性。MIT许可证允许你自由修改和分发。

1. 定制宪法：打开CONSTITUTION.md，将里面的C1-C11条款修改成你公司或团队的设计原则。例如，加入你们独有的设计系统名称、品牌价值观描述。
2. 扩充共享知识库：在CRAFT-DESIGN-JUDGMENT-FOUNDATIONS.md中，添加你们团队在实践中总结出的特有“反模式”或“最佳实践”。例如，“反模式：在我们的数据看板中，避免使用超过5种以上的颜色编码序列。”
3. 创建新角色：如果你发现现有六位创造者无法覆盖你的需求（比如需要一个专门的“数据可视化设计师”），你可以模仿.claude/agents/下的文件格式，创建一个新的智能体文件，并在AGENTS.md和操作规范中定义它的职责和契约。
4. 集成现有设计系统：将你的Figma设计Token、组件库文档链接或代码片段，以引用的形式融入到共享知识库或各个角色的指令中，让AI生成的代码能直接匹配你现有的设计资产。

一个进阶实践：你可以建立一个“智能体工厂”流水线。使用脚本或简单的CI/CD流程，在代码提交前，自动用“规范守门员”智能体对变更的UI组件文件进行审查，并将审查意见以评论形式提交到Pull Request中。这能将设计规范检查真正融入到开发流程中。

经过一段时间的实践，我发现agents-ui-craft系统最大的价值不在于替代设计师，而在于提升开发者与AI协作的规范性和产出质量的下限。它迫使你在写第一行代码前先思考设计原则，并通过多角色的评审机制不断纠偏。刚开始设置和调用角色会觉得有些繁琐，但一旦流程跑顺，它就像一位永不疲倦、严格遵循章程的设计伙伴，能帮你把那些容易忽略的细节（如可访问性、一致性）牢牢守住。对于追求代码质量和设计规范性的团队来说，投入时间学习和定制这套系统，长远看会是一笔非常划算的投资。