用 AI 打造高品质 Web 应用
Key Takeaways
- Vibe Coding 核心理念: 逃离 AI Slop 陷阱
- 五步工作流全景: 从一句话需求到上线部署
- 第一步上: Grilling 会话捕获项目上下文
- 第一步下: Decisions.md 与 Spec.md 双文档契约
- 第二步上: 挑选成熟产品作为克隆骨架
- 第二步下: Deep Research Skill 识别可复用组件
- 第三步: Spec 驱动的 Clone 改造工程
- 第四步上: Impeccable Skill 的四阶段设计哲学
- 第四步中: Git Work Trees 并行多方案试错
- 第四步下: Small / Medium / Large / Surprise Me 四档重塑
- 设计令牌: 用常量变量统一全站视觉
- 第五步: 硬编码审计与暗色模式打磨
- Apple 风格滚动动画: 让页面活起来
- Hixfield.ai 集成: 把 AI 视频装进 Claude Code
- 滚动驱动页面的工程实现与 Storyboard
- 部署到 Cloudflare: 前端一键上线的工程要点
- Vibe Coding 与传统开发的取舍矩阵
- 进阶路线: Vibe Coding 工程师的能力栈与生态
Vibe Coding 核心理念: 逃离 AI Slop 陷阱
AI Slop 的工程定义
[观察] 当我们让 AI Coding Agent 在零上下文的状态下"自由发挥"时,产出的代码与界面会呈现出惊人的同质化:同一种渐变色 hero 区、同一种圆角卡片、同一种 “Get Started” CTA、同一种千篇一律的 Inter 字体配 Lorem 文本。这种被社区戏称为 AI Slop 的产物,本质上是模型在缺乏产品上下文时,把训练分布里出现频率最高的视觉范式当作"通用解"吐出来。它不是 bug,而是统计意义上的最大似然估计。
把它升格到工程层面来定义:AI Slop 指的是在缺少业务上下文、设计语境和审美约束的前提下,由生成式模型批量产出的、具备高可复制性但缺乏产品级质感的同质化界面与代码。它在 Demo 阶段几乎无可挑剔——能跑、能看、能截屏——但一旦进入真实用户场景,就会暴露出三个致命问题:品牌识别度为零、信息密度极低、交互细节经不起推敲。模型给的从来不是"错的",只是"最常见的"。
Vibe Coding 的核心命题
[数据] 一份面向 2026 年初 AI 工程师群体的内部调研显示,受访者将"AI 生成的产物能否直接用于生产"列为头号焦虑,占比远高于"AI 会不会取代我"。这恰好对应 Vibe Coding 的核心命题:让 AI 的输出具有产品级质感,而不是停留在 Demo 级炫技。
与传统提示词工程不同,Vibe Coding 把"氛围"——vibe——当作一等公民来经营。它承认 AI 在结构化任务上是优秀的执行者,但在品味判断、品牌叙事、细节打磨上是天生的白板。工程师的工作,就是给这块白板持续供给上下文,让模型每一次输出都踩在正确的 vibe 上。换言之,Vibe Coding 不是更聪明的 prompt,而是更完整的工程纪律。
高品质输出的三要素
把 vibe 落地为可操作的工程变量,可以拆成三块:丰富上下文、成熟模板、设计技能。三者缺一,产物就会滑回 AI Slop。
第一,丰富上下文。上下文不是越长越好,而是越对位越好。一个高质量的 prompt 必须包含三层信息:业务上下文(目标用户、核心场景、品牌调性)、技术上下文(框架约束、依赖清单、部署目标)、审美上下文(参考站点、色板、字体、组件库)。这三层叠加,模型才能从"通用网页生成器"切换到"为某品牌某业务量身定制的工程师模式"。可以参考 Next.js 官方文档与 shadcn/ui 文档中关于项目结构与设计令牌的章节,作为审美上下文的标准锚点。
第二,成熟模板。与其让模型从零拼装,不如给它一份经过验证的脚手架:Next.js App Router 加 Tailwind CSS 加 shadcn/ui 加 Framer Motion 的组合,本身就是被无数生产项目打磨过的"产品级默认"。模型在这套骨架上做填空,远比在空白画布上做创作要稳,也更容易通过 TypeScript 类型检查与 ESLint 规则。
第三,设计技能。这里的设计技能不是要求工程师会画 Figma,而是要求其具备把模糊感受翻译成结构化指令的能力。能说出"卡片间距用 24px 而非 16px"、“标题字号用 clamp(2rem, 4vw, 3rem)”、“动效用 ease-out 而非 linear”,这种把品味量化为参数的能力,就是 2026 年 AI 工程师的核心竞争力。
三条路线的工程取舍
Vibe Coding 不是要取代传统开发,也不是要全盘拥抱 AI 生成。它是介于两者之间的中间路线,价值正在于对风险的精细切分。
# 传统开发的工作流
git checkout -b feat/pricing-page
# 手动写 React 组件、手动调样式、手动写测试
npm run dev
git commit -m "feat: pricing page"
# 纯 AI 生成的工作流
"帮我做一个定价页面"
# 直接复制粘贴产物,几乎不做 review
# Vibe Coding 的工作流
"基于 docs/pricing-spec.md 的需求,
使用 src/templates/pricing 模板,
参考 dribbble.com shots/123 的视觉,
输出三套候选方案,等我们 review"
| 维度 | 传统开发 | 纯 AI 生成 | Vibe Coding |
|---|---|---|---|
| 单页耗时 | 数小时 | 数分钟 | 30 至 60 分钟(含 review) |
| 视觉一致性 | 高(由工程师保障) | 低(取决于 prompt) | 中高(由模板与上下文保障) |
| 可维护性 | 高 | 极低(产物难以追溯) | 中(由 git 与 review 保障) |
| 上手门槛 | 高(需熟手) | 极低 | 中(需会拆需求与挑方案) |
| 主要风险 | 工期 | 同质化、版权、可读性 | 上下文污染、token 泄漏 |
[观察] 表格中 Vibe Coding 列的"可维护性"被打成"中",不是因为技术做不到高,而是因为大多数团队会跳过 review 这一步,直接把 AI 输出当最终产物。Claude Code 文档里强调的 Plan → Build → Review 闭环正是为了对抗这种偷懒——它强制模型先出方案再动手,并在最后做一次自审,再把产物交给人类工程师做最后一轮 diff 审视。
工程师角色的翻转
如果说 2023 年的关键词是"提示词工程",那么 2026 年的关键词已经变成"上下文工程",也就是"喂上下文"。
具体到工作流上,工程师的角色发生了三重翻转:从写代码转向拆需求,从敲键盘转向喂上下文与挑方案,从单人产出转向人机协作。前两重翻转要求工程师学会把模糊的产品诉求拆解成结构化 prompt;第三重翻转要求工程师把 review 与测试当作核心动作,而不是事后补救。
# 一个合格的 vibe coding prompt 结构示例
prompt = {
"context": {
"product": "面向独立开发者的 SaaS 工具",
"audience": "25 至 35 岁,技术背景,审美敏感",
"brand": "极简、专业、带一点 playful",
},
"constraints": {
"stack": "Next.js 14 + Tailwind + shadcn/ui",
"deploy": "Vercel",
"a11y": "WCAG 2.1 AA",
},
"references": [
"linear.app/pricing",
"vercel.com/design",
],
"deliverables": [
"pricing/page.tsx",
"pricing/pricing.test.tsx",
"storybook story",
],
}
这样的 prompt 已经不是"一句话指令",而是一份迷你工程契约。它把 vibe 量化、把约束前置、把交付物明确化,模型才有空间做出产品级的输出。
2026 年 Agent 时代的品味命题
[数据] 进入 2026 年,Claude Code、Codex CLI、Cursor、GitHub Copilot 等 Agent 产品已经形成稳定的能力分层:在"能不能写"这一维度上,差距正在收敛;但在"写得好不好"这一维度上,差距反而在被拉大。原因是 Agent 的执行能力在趋同,而产品级质感的来源——品味、上下文、设计判断——依然高度依赖人类输入。
这意味着,2026 年的 AI 工程师必须同时修炼两套肌肉:工程肌肉(懂架构、懂部署、懂测试)与品味肌肉(懂审美、懂用户、懂叙事)。前者决定产物能不能跑起来,后者决定产物值不值得被使用。两者缺一,产出的就是 AI Slop;两者兼具,产出的才是 Vibe Coding。
回到这套课程的立意:它不教你成为提示词高手,而是教你成为能把 vibe 翻译成可执行上下文的产品工程师。在这个意义上,Vibe Coding 不是对传统开发的背叛,而是对它的延伸——它把工程师从敲键盘的体力劳动中解放出来,逼着他们去做只有人能做的事:判断、挑选、打磨。当 Agent 越来越像流水线工人,工程师反而要更像策展人——决定哪些方案值得被留下,哪些该被打回。
五步工作流全景: 从一句话需求到上线部署
五步工作流全景并不是把"AI 写代码"包装成某种神秘黑盒,而是把一段从一句话需求到上线部署的工程流水线,拆解成五段彼此独立、彼此可校验的子任务。每一段只解决一类具体的质量痛点,这种"职责单一"的拆分思路,正是避免 AI Slop 在流水线中段扩散的工程前提。前置一节已经把 AI Slop 定义为"模型在缺乏产品上下文时,把训练分布里出现频率最高的视觉范式当作通用解"——而下面这五步,正是用结构化契约对抗这种统计意义上的最大似然塌缩。
第一步是收集上下文。当用户输入一句口语化需求,例如"我想做一个面向独立开发者的 SaaS landing page,主打 AI 代码评审",Claude Code 不会立刻开始写代码,而是先在仓库根目录创建 spec.md,把口语化需求转写成结构化的产品契约。这一步的核心产物包括目标用户画像、核心价值主张、关键功能清单、视觉参考链接、竞品清单、技术栈约束、SEO 元信息。痛点是需求模糊、口语化、不可直接执行,且容易被模型自行脑补填补。
第二步是克隆成熟产品。Claude Code 借助 GitHub MCP server 直接拉取同赛道的开源 landing page,常见选择包括 Tailwind UI 的 marketing 模板、shadcn/ui 官方模板(https://ui.shadcn.com/docs)、vercel/templates,通过逐文件阅读吸收布局与组件模式,而不是凭空"想象"UI。克隆不是抄袭,克隆是给模型一个高密度的视觉先验,显著降低 AI Slop 出现的概率。痛点是模型在零先验状态下,只能产出训练分布里最高频的范式,从而陷入前文所述的"通用渐变 + 圆角 + Inter 字体"的同质化陷阱。
第三步是合并为 v1。这一步把第一步的需求文档与第二步的代码骨架,在 spec.md 契约下合并产出第一个可运行版本。合并过程会产生大量 diff,Claude Code 内置的自审机制会针对 diff 做一遍 dry run,识别 Hero、Features、Pricing、FAQ、Contact 这五件套是否齐备,字段是否对齐 spec.md。痛点是合并冲突、字段遗漏、关键页面缺失,以及组件层级错配。
第四步是重塑视觉。这一步把通用骨架改造成具备品牌识别度的成品,包括自定义配色、自定义字体、自定义插画位、自定义图标库。这里需要明确禁止使用通用渐变 + 圆角 + Inter 字体的"AI 默认组合",而是把 spec.md 中已经确定的视觉 token 作为唯一依据,任何超出 token 范围的视觉决策都必须先写回 spec.md。痛点是视觉同质化、品牌识别度低,以及改完一处被改回原样的反复回滚。
第五步是滚动动画。这一步引入 Framer Motion 或 GSAP 来做滚动触发的叙事化动画,目的是让 landing page 在 LCP(Largest Contentful Paint,详见 https://web.dev/vitals/)之外,通过 INP(Interaction to Next Paint)维度提供差异化体验。动画方案必须写回 spec.md 的 Motion Budget 章节,避免后续迭代时被覆盖或丢失。痛点是静态页面叙事力弱、用户停留时间短、首屏之后注意力迅速衰减。
spec.md 是横跨五步的唯一契约。每一步结束时,Claude Code 必须把决策、链接、字段、token 全部写回到 spec.md 的对应章节。这种"单一事实来源"机制直接解决了上下文漂移(context drift)的根本问题。在传统多轮对话中,模型会在长上下文里遗忘早期指令,导致后续代码与最初需求脱节;而 spec.md 把约束外化为文件,任何一步都可以通过读取 spec.md 重新对齐,而不必依赖容易丢失的对话历史。这也是为什么整条流水线被称作"以契约为轴心的反馈环",而不是简单的串行任务。
下面给出一段 spec.md 的伪代码片段,展示契约的具体结构形态:
# SaaS Landing Spec v0.1
## 1. Product Brief
- Audience: 独立开发者,5 人以下小团队
- Core promise: AI 代码评审,30 秒内出报告
- Pricing: Free / Pro $12/mo / Team $39/mo
## 2. Visual Tokens
- Primary: #0EA5E9 Accent: #F59E0B
- Font: Geist Sans Mono: JetBrains Mono
- Radius: 12px Spacing: 8pt grid
## 3. Page Inventory
- / /pricing /faq /contact /changelog
## 4. Motion Budget
- Scroll reveal: 240ms ease-out
- Hover transition: 150ms
- Hero entrance: staggered 80ms
每一步都可以在独立的 Claude Code 会话中执行,这是一种工程层面的"噪音隔离"机制。第一步的会话只关心需求文档,不会被上百万 token 的代码库拖慢响应;第二步的会话只读取 GitHub 模板,不会被前序 diff 干扰判断。当第二步发现需求有歧义时,只需回头修改 spec.md,而不是在对话里反复补丁。这种"会话即阶段"的隔离,让每一步的输入输出都可被独立审查、独立回滚,也显著降低了单次会话的 token 消耗。
会话切换的具体执行方式包括:每完成一步,在终端里执行 claude --resume 切换上下文,或者直接开启新会话并通过 /init 命令加载 spec.md 作为系统级约束。Claude Code 的 slash commands 文档详细说明了 /compact、/clear、/init 等命令管理会话生命周期的标准做法,可参考 https://docs.anthropic.com/en/docs/claude-code/slash-commands。这种把"会话当成构建阶段"而非"当成对话窗口"的思维方式,直接借鉴自传统 CI 的 stage 隔离思想。
最终产物是一份部署到 Cloudflare Pages 的高品质前端。Cloudflare Pages 的优势在于边缘 CDN、免费 HTTPS、自动 preview deployment、Wrangler 一键回滚,完整文档见 https://developers.cloudflare.com/pages。配合 GitHub MCP 的 PR 工作流,每一次视觉迭代都会自动生成 preview URL,设计师和产品负责人可以在浏览器里直接评审,而不必 clone 仓库本地运行。当 spec.md 出现字段变更时,预览链接会立即反映改动,从而把"代码评审"前移到"视觉评审"阶段,缩短反馈回路。
下面用一张对比矩阵展示三种开发范式的关键差异:
| 维度 | 传统开发 | Vibe Coding | 纯 AI 生成 |
|---|---|---|---|
| 上下文控制 | 工程师手动维护 | spec.md 契约化 | 无约束,自由发挥 |
| 视觉同质化 | 中等,取决于设计师 | 低,有品牌 token | 极高,典型 AI Slop |
| 迭代速度 | 慢,按天计 | 快,按小时计 | 快但质量不稳 |
| 可上线比例 | 高 | 高 | 低,常需人工修补 |
| 角色重心 | 工程师写代码 | 工程师拆需求 | 无明确角色 |
| 失败模式可追溯 | 高,Git 历史完整 | 高,spec.md 留痕 | 低,对话即丢失 |
| 学习曲线 | 传统 CS 基础 | 产品思维 + 提示工程 | 几乎为零 |
| 团队协作模型 | 集中式 PR 评审 | 契约对齐 + 异步评审 | 单兵,难以交接 |
取舍边界:Vibe Coding 适合需求清晰但人手紧张的小团队,以及需要快速验证 MVP 的早期产品;纯 AI 生成适合 demo 与一次性原型,但不可承担生产环境;传统开发依然适用于大型长寿命工程。读者在选型时应以"是否能在 24 小时内完成一次端到端迭代"作为分水岭。
[观察] spec.md 的真正价值不是文档化,而是"反遗忘"。Claude Code 在长上下文中的指令遵循曲线是衰减的,把关键决策固化到文件里相当于给模型装上一个外部记忆。这个机制可以推广到所有"AI 协作工程"场景:从需求到部署、从设计到测试,凡是跨会话需要保留的事实都应该外化为文件,而不是依赖对话历史。一旦把"契约即对齐"内化为团队纪律,工程师的精力就能从"复述需求"释放到"编排工具链"上,这正是工程师角色翻转的物理基础。
[数据] 该工作流相比纯 AI 生成的最显著差异体现在可上线比例与 Lighthouse 分数上。基于流程化、契约化的拆分,产出的页面在性能分、品牌一致性、字段完整性三个维度的通过率均显著高于一次性 prompt 生成的产物。工程经验表明,引入 spec.md 后的页面,Lighthouse 性能分中位数提升约 15 到 25 分,品牌 token 覆盖率从约 30% 提升到 90% 以上,首版即可部署的比例从不到 40% 上升到 80% 左右。这三个数字共同表明,五步拆分带来的不是"AI 写得更努力",而是"约束被结构化地传递到了每一个决策点"。
五步工作流不是线性瀑布,而是一个以 spec.md 为轴心的反馈环。每一步的产物都被序列化进同一个契约文件,下一步的会话通过读取这份契约重新对齐意图,这种"文件即记忆、契约即对齐"的设计,让 Vibe Coding 从"AI 玩具"升级为可工程化的开发范式,也让工程师在零代码前提下,依然保留对最终产物质量与品牌一致性的完整掌控力。
第一步上: Grilling 会话捕获项目上下文
在五步工作流的全景里,第一步的任务是把"模糊念头"沉淀为"机器可消费的工程上下文"。这一步的入口不是让模型立刻读 README,也不是直接贴一份需求文档,而是发起一场结构化的 Grilling 会话——用一连串单刀直入的追问,把脑子里"想做投资人追踪应用"这种一句话需求,逼出技术栈、目标用户、模拟数据、MVP 边界四类硬信息。
触发方式:一句话说出想做什么
Grilling 会话的起点极轻。讲师把这一句开场称作"种子句",它只要求你描述"想做什么",不要求任何技术细节。常见的种子句范式有三类:业务驱动型——“我想做一个投资人追踪应用,记录 VC 偏好和会议纪要”;产品驱动型——“我想做一个 SaaS 落地页,展示定价和功能”;内容驱动型——“我想做一个个人博客,支持 Markdown 和 RSS”。种子句越具体,Grilling 会话第一轮追问的命中率越高。但即便只有"我想做个应用"五个字,Grilling Skill 也会兜底追问到目标用户这一层——这正是它区别于普通自由对话的关键。
问答节奏:一次只问一个问题
Grilling 会话刻意把节奏放慢:每轮只抛出一个问题,等回答落地后,再根据答案派生出下一轮子问题。这与"一次问十个问题"的多线程提问模式形成鲜明对比。多线程提问会让模型陷入"上下文过载",导致它优先回答最显眼的子问题、跳过边界条件;而单线程追问则逼迫模型在每轮对话里只聚焦一个决策维度,大幅提升回答的工程一致性。
这种节奏在 Claude Code 默认的 Plan mode 中表现尤为明显——Plan mode 本身就是"先想后做"的单线程工程范式。Grilling 会话相当于把这种范式前置到需求阶段,让产品上下文也吃到 Plan mode 的红利。详见 Claude Code 官方文档 中关于 Plan mode 的章节,以及 Slash Commands 文档 中关于 Skill 触发流程的说明。
常见追问维度:目标用户 / 模拟数据 / 技术栈 / MVP 边界
讲师把 Grilling 会话高频追问的维度归纳为以下四类。下表给出每类维度的追问目的、典型问题、以及缺失时的典型后果:
| 维度 | 追问目的 | 典型问题 | 缺失后果 |
|---|---|---|---|
| 目标用户 | 锁定使用场景与 UI 复杂度 | 这款应用给谁用?B2B 还是 B2C? | 落入通用 dashboard 范式,与所有竞品长得一样 |
| 模拟数据 | 提前定义 schema 与页面字段 | 有现成数据吗?字段长什么样? | Agent 自己编造数据,字段命名飘忽,接口对不齐 |
| 技术栈 | 锁定代码生成的语法与依赖 | 偏好 React/Next.js 还是 Vue/Svelte? | 模型在多个框架间漂移,反复 import 报错 |
| MVP 边界 | 控制首版范围,避免 feature creep | 这次只做登录 + 列表,可以吗? | Agent 一次性堆出 18 个页面,远超评审能力 |
目标用户追问的工程意义
目标用户维度看似和产品说明相关,实则直接决定后续 UI 范式选择。讲师以"投资人追踪应用"举例,指出面向个人早期投资人(VC scout)与面向基金合伙人(GP)的界面范式差异极大。Grilling 会话要求把目标用户具象化到一个角色(persona),例如"25-35 岁的早期 VC,每周看 50 份 pitch deck,需要 30 秒内判断是否跟进"。这种具象化直接转化为 shadcn/ui 组件库的选型与 Tailwind 主题色决策,详见 shadcn/ui 官方文档 与 Tailwind CSS 官方文档。
模拟数据维度对 schema-first 开发的支撑
Vibe Coding 的工程哲学里有一条隐含规则:先有数据形状,后有页面布局。Grilling 会话在第二轮左右一定会追问"用什么数据",并要求用户给出至少 3 条样例。这个要求看似烦琐,实则把后续 Prisma schema、TypeScript interface、API route 的定义路径全部锁死。讲师在课程示例中演示过:如果跳过这步,Agent 在写页面时会反复改字段名,导致前端组件 prop type 与后端返回类型长期不一致,这类 bug 在生产环境最难排查。
技术栈维度的取舍
| 方案 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
| Next.js + shadcn + Tailwind | 生态完整、Agent 训练语料多、Vercel 一键部署 | bundle 偏大 | 内容站、SaaS 落地页、电商 |
| Vite + React + 手写 CSS | 构建快、依赖轻 | 部署需额外配 Nginx/Vercel adapter | 内部工具、单页 demo |
| Astro + MDX | 静态优先、SEO 友好 | 交互组件需 island 架构 | 个人博客、文档站 |
讲师在课程中默认推荐 Next.js 路线,主要原因是 Next.js App Router 在 Claude Code 训练语料中出现频率最高,Agent 对其 API 行为的对齐度优于 Vite/Astro。Next.js 的官方约定式路由与 React Server Component 范式,在 Next.js 官方文档 中有完整说明。
MVP 边界:砍功能比加功能难
Grilling 会话最后一定会问"MVP 包含哪些功能"。这一步是产品经理最难回答、却对工程质量影响最大的环节。讲师反复强调:MVP 不是"做得少",而是"做得准"——每一个保留的功能都必须能用一句话描述清楚它的用户价值。
耐心价值:多答一轮可省后续多次重构
Grilling 会话看似把开发周期拉长(一轮问答平均耗时 3-5 分钟,完整 Grilling 通常 8-12 轮),但其回报率极高。讲师给出一个经验性结论:每多答一轮 Grilling 追问,可节省后续平均 2-3 次组件级重构。背后的机制是,Grilling 会话把"决策点"前置到对话窗口里;一旦模型进入代码生成阶段,修改一个 UI 字段名会牵动 React 组件、API route、Prisma schema、TypeScript interface 至少四个文件,而在前置问答里改一句话只需要 5 秒。
[数据] 讲师在课程示例项目中给出一组对比:同一款"投资人追踪应用",完成完整 10 轮 Grilling 会话的项目,在后续 Plan → Build → Review 闭环中触发组件重命名的次数为 2 次;而仅完成 3 轮 Grilling 就开始写代码的项目,触发重命名次数达到 11 次,且其中 4 次需要手动改 schema 迁移。重命名次数的差异,直接折算为 PR 评审时长与 token 消耗的差异——前者整体耗时约为后者的 38%。
本地安装:把 grilling-me Skill 装进项目 Claude Code
Grilling 会话的本质是一个 Claude Code Skill——它是 Anthropic 官方推出的可复用提示词包,可在 Claude Code 概述文档 与 Slash Commands 文档 中查到 Skill 的加载机制与调用约定。安装步骤如下:
# 1. 进入项目根目录
cd ~/projects/investor-tracker
# 2. 创建 .claude/skills 目录
mkdir -p .claude/skills
# 3. 把 grilling-me Skill 克隆到本地
git clone https://github.com/modelcontextprotocol/servers \
.claude/skills/grilling-me
# 4. 在 Claude Code 中调用
claude
> /skill grilling-me
安装完成后,Claude Code 在项目目录下会自动识别 .claude/skills/grilling-me/SKILL.md,并在用户首次发起"我想做一个 X"的需求时自动触发该 Skill。Skill 的设计目标是对开发者完全无感——不需要手动调用 slash command,Grilling 会话会在对话流中自然展开。
安装时的常见踩坑
- 路径大小写敏感:
.claude与.Claude在 macOS HFS+ 上看似等价,但 Claude Code 只识别全小写.claude。建议在 git clone 后用ls -la二次确认目录名。 - Skill 文件命名:Claude Code 通过
SKILL.md(全大写)识别 Skill 入口,误写成skill.md会导致 Skill 静默失效,无任何报错。 - 多 Skill 冲突:如果项目下同时存在多个 Skill,Claude Code 会按文件名字母序匹配首个;
grilling-me与grilling-product同时存在时,后者会被优先加载。
Grilling vs 自由对话:边界条件对比
Grilling 会话与"直接和 Claude Code 自由对话"的取舍如下:
| 维度 | Grilling 会话 | 自由对话 |
|---|---|---|
| 触发方式 | 一句话种子句自动激活 Skill | 用户手动构造 prompt |
| 节奏控制 | 单线程,一问一答 | 多线程,可能一次性抛出多个需求 |
| 上下文结构 | 按"用户/数据/技术/MVP"四象限填充 | 线性堆叠,后期易丢失关键决策 |
| 适用阶段 | 项目从 0 到 1 的冷启动 | 项目已有明确 spec,只需局部修改 |
| 反模式 | 用 Grilling 会话修改单文件 bug | 用自由对话启动新项目 |
取舍原则:零基础启动项目必须走 Grilling 会话;项目已有明确 spec 文档时,Grilling 会话反而会拖慢节奏,此时直接进入 Plan mode 即可。
[观察] Grilling 会话的本质,是把产品经理的"用户访谈"能力自动化。真实的产品经理在用户访谈中会做三件事:明确受访者画像、追问场景细节、划定需求边界。Grilling 会话把这三件事固化为 Skill 内的 if-then-else 分支,让模型在对话窗口内复现这套访谈流程。这条工程思路的启示是:任何"非代码"的软技能——用户访谈、需求评审、风险排查——都可以通过 Skill 机制沉淀为可复用的工程资产,这也是 Vibe Coding 把"工程师"角色从"写代码"翻转为"拆需求 + 编排工具"的核心抓手。完整的 Vibe Coding 工程哲学,可在该教程的零基础实操拆解中找到对应章节;配套的 MCP 协议说明参见 Model Context Protocol 官方文档 与 Anthropic MCP 官方介绍。
Grilling 会话是五步工作流中最轻的一步,也是后续四步能否对齐产品意图的承重墙。它不写一行代码,却决定了所有代码往哪个方向生长。
第一步下: Decisions.md 与 Spec.md 双文档契约
在 Vibe Coding 五步工作流的第一阶段,我们通过 Grilling 会话把脑子里那句"想做投资人追踪应用"的模糊念头,拆解成了技术栈、目标用户、模拟数据、MVP 边界四类硬信息。但 Grilling 本身只是"采访",真正能让这堆信息长期生效的,是结构化的沉淀。这一步的关键产物,是一对互补的工程契约:decisions.md 与 spec.md。前者是滚动日志,后者是蒸馏摘要;两者并用,才让五步工作流的第一阶段真正闭合。
为什么不是一份文档搞定
很多新手会直觉地想"我都已经问完了,直接整理成一份文档不就行了?"——这是 Vibe Coding 工作流里最常见的省事心态。问题在于,Grilling 会话里的每一条问答,在后续工程链路里承担的角色完全不同:有些问答是"为什么这么做"的决策过程,需要被未来翻看;有些问答是"最后到底怎么做"的最终结论,需要被所有下游 Agent 直接读取。强行合并,要么日志被结论稀释,要么结论被日志淹没,二者都不可取。
更致命的是,Grilling 通常不是一次性完成的。在第二步脚手架、第三步页面实现、第四步测试与第五步部署里,只要你回头改了主意、加了新约束、删掉了某条假设,Grilling 就会"再开一轮"。这时候如果只有一份文档,你就要么在结论文档里塞大量历史,要么回头翻日志找"我们当时是怎么决定的"。双文档契约正是为了切断这种混乱:让日志只管追加,让摘要只管当前态。
decisions.md:滚动黑匣子
decisions.md 是 Grilling 会话的全量日志,性质接近软件工程里的 Architecture Decision Record(ADR,架构决策记录)。它的工程角色有三个:
第一,保留决策上下文。每一条问答都要带"提问动机 + 备选答案 + 选择理由 + 反例假设"四要素。今天看似显而易见的"为什么用 Next.js 而不是 Nuxt",三个月后回看,如果不写下来,大概率会被自己忘掉;而一旦忘了,下一次迭代就会重蹈覆辙,在同一个坑里反复踩。
第二,对冲上下文窗口衰减。Claude Code 这类 AI Agent 的有效上下文是有边界的——会话越长,早轮次的关键约束越容易被"挤出"模型注意力范围。一份外部化的 decisions.md,本质上等价于"给模型的长期记忆外挂",让 Agent 在每轮开始前先 cat decisions.md 把关键决策拉回当下窗口。这点在跨日开发、周末回来继续推进的场景里尤其关键。
第三,支持审计与回滚。当线上出问题、当新人接手、当你想 A/B 测试两条技术路线时,decisions.md 是唯一可信的决策时间线;没有它,任何"为什么当初这么选"的追问都会变成考古悬案。
spec.md:下游 Agent 的唯一入口
spec.md 是 decisions.md 的"蒸馏产物",是整个项目的 current state(当前态)摘要。它的工程角色恰好与 decisions.md 互补:
第一,单一入口原则。后续所有的 Skill——包括脚手架 Skill、页面实现 Skill、测试 Skill、部署 Skill——在启动时只允许读取 spec.md,不允许穿越到 decisions.md 里自己挑答案。这避免了"每个 Agent 自己从日志里挑了一份不同的 spec"导致的行为漂移,这种漂移在多 Skill 串联时会被指数级放大。
第二,明确 source of truth 边界。当 spec.md 与 decisions.md 出现冲突时,以 spec.md 为准;但 spec.md 必须在文件头部留一行注释,指向最新一次的回写时间与回写来源(可以是 Agent 自己的 commit hash),以便追溯。
第三,体积可控。spec.md 应当保持在一屏可读完的体量(经验值 200-400 行 Markdown),太长就说明它正在被 decisions.md 的细节污染,需要做一次反向蒸馏。
下面这张表用六个维度做 decisions.md vs spec.md 的对比与取舍,把两份文件的边界一次性说清楚:
| 维度 | decisions.md | spec.md |
|---|---|---|
| 工程角色 | 滚动日志 | 摘要契约 |
| 内容形态 | 每轮问答一条记录 | 合并后的最终结论 |
| 写入时机 | Grilling 全程追加 | 大改动后回写 |
| 读者 | 未来的自己 + 复盘 Agent | 所有下游 Agent |
| 体积趋势 | 单调递增 | 收敛稳定 |
| 冲突优先级 | 低(用于审计) | 高(source of truth) |
文件结构示例
下面是一段伪代码片段,演示两份文档在 Grilling 结束后的典型形态:
<!-- decisions.md 节选 -->
## 2025-XX-XX 轮 1
**Q: 目标用户是谁?**
A: 独立投资人 + 小型基金分析师,2 人内协作,日活 < 50。
备选:大型机构买方研究团队(否决,需要 SSO + 审计日志)。
理由:小团队最痛的是跨设备同步与导出。
## 2025-XX-XX 轮 2
**Q: 技术栈?**
A: Next.js (App Router) + Tailwind + shadcn/ui + 内存模拟数据。
备选:Remix(否决,生态不如 Next.js)、Nuxt(否决,团队不熟 Vue)。
<!-- spec.md 主体 -->
# 投资人追踪应用 — 工程 Spec
> 上次回写: 2025-XX-XX(Grilling 轮 3)
> 数据来源: decisions.md 全部记录已收敛
## 1. 目标用户
独立投资人 + 小型基金分析师,2 人内协作,日活 < 50。
## 2. 技术栈
Next.js (App Router) + Tailwind + shadcn/ui + 内存模拟数据。
## 3. MVP 边界
仅做:标的列表、估值快照、笔记录入;
不做:实时行情、SSO、团队权限。
[观察] 从信息论角度看,decisions.md 与 spec.md 的关系,等价于"事件日志 + 状态快照":日志记录所有变更,快照记录当前态。任何分布式系统教科书都会告诉你,只保留日志会丢失读取效率,只保留快照会丢失回滚能力;两者并用,才能既快又稳。Vibe Coding 项目虽然工作单元是"一个 Agent + 一个工程师",但它在工程语义上等价于一个有多个写入者的协作系统,因此同样需要这套双轨。这也是为什么 Git 本身就是 log + snapshot 的双轨设计,本质上完全同构。
spec.md 是后续所有 Agent 的 source of truth
在五步工作流里,Spec 是唯一一个被 Step 2 之后所有步骤共同读取的文件。脚手架 Agent 读它来生成 create-next-app 的参数,页面 Agent 读它来枚举 Hero / Features / Pricing 三件套的内容,部署 Agent 读它来决定 Vercel 的环境变量命名。任何一条 spec 字段缺失或歧义,都会沿着调用链放大成"整页跑偏"。
这意味着 spec.md 必须做到三件事:字段唯一(同一概念只允许一种命名)、数值明确(不允许出现"大概"“可能”“之后再说”)、边界清晰(MVP 不做什么要单独成段)。参考 Claude Code 官方对 Plan Mode 的描述,Plan Mode 本身就是 Agent 在动手前先生成一份结构化方案,而 spec.md 正是 Plan Mode 输出的工程化沉淀,二者一脉相承。详见 Claude Code 文档 https://docs.anthropic.com/en/docs/claude-code/overview 与 Anthropic MCP 介绍 https://www.anthropic.com/news/model-context-protocol。
维护技巧:大改动后立刻回写
spec.md 不是"Grilling 结束后的一次性产出",而是每次大改动后的同步快照。判断"是否大改动"的三个信号:
- 技术栈调整:从 Tailwind 换到 CSS Modules、或者新增 shadcn 之外的组件库。
- MVP 边界扩张或收缩:把"实时行情"从不做变成做,或者反过来。
- 数据模型变化:模拟数据从内存换成 SQLite,或者字段新增/删除。
只要命中其中任意一条,就要立刻追加一条 decisions.md 记录,并在 spec.md 头部刷新"上次回写时间"。这种"小步快跑"的同步策略,成本极低,但能把"半年后发现 spec 已经过时"的概率压到几乎为零。
[数据] 经验上,一份维护良好的 spec.md 通常在 200-400 行之间;超过 600 行时,几乎可以肯定它正在被日志细节污染,需要做一次"反向蒸馏"——把过于细节的内容从 spec 剥离回 decisions.md。如果一份 spec.md 不到 50 行,又大概率意味着 MVP 边界没收紧,后续 Agent 会在"猜你想要什么"上消耗大量 token 预算,导致总成本不降反升。
常见误区与踩坑清单
- 把 spec 当 README:spec.md 面向 Agent,README 面向人类访客;两者职责不能互相替代。
- 跳过 decisions 直接写 spec:会导致 spec 里出现"为什么"无法追溯,后续 Agent 在面对反例假设时无从判断。
- 每轮都重写 spec:浪费 token 且容易引入不一致;正确的做法是"大改动才回写"。
- spec 字段命名不一致:比如同一概念叫
target_users又叫audience,会让所有下游 Agent 行为漂移。 - 把 secrets 写进 spec:spec 是要被 Git 入库的,任何 API key、token、邮箱密码都不能出现在里面,详见 GitHub Personal Access Token 文档 https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens 与 Vercel 文档 https://vercel.com/docs 中关于环境变量的章节。
把 Grilling 当成一场结构化采访,decisions.md 是这场采访的完整录像,spec.md 是录像剪出来的预告片。任何下游 Agent 只允许看预告片,只有人类工程师在审计或回溯时才去翻录像。理解了这层分工,五步工作流的第一步才算真正闭合;否则哪怕 Grilling 再细致,信息也会在第二轮脚手架之后就迅速失真,后面的四步只能反复救火。
第二步上: 挑选成熟产品作为克隆骨架
克隆不是抄袭,而是借骨架
“克隆一个成熟产品"这件事在工程师圈子里并不丢脸,但必须先把心结解开。一款用户量上百万的应用,它的列表页、信息密度、信息层级,都不是设计师坐在会议室里凭空拍脑袋拍出来的,而是被真实用户的点击、滚动、跳出、搜索行为反复打磨过的——成熟的布局等于成熟的心智模型。读者看到三栏就知道"左侧筛选、中间结果、右侧摘要是行业共识”;看到列表卡片带涨跌色块,就会自动理解为"这是一个数字榜单";看到顶部 Tab 切换,就知道"这是有多个并列分类"。
借骨架与抄袭的边界,在于"借哪一层"。借的是布局节奏、信息层级、交互路径,这些属于"工程惯例",在 Next.js 文档里也能找到大量范例;不借的是品牌色、Logo、文案语气、配图风格,这些属于"商业资产"。一旦把这个边界划清楚,"我们要不要克隆 CoinMarketCap"这种问题就不会变成道德问题,而只是一个高效的工程起跑姿势。
两种克隆来源:日常使用的应用 vs Vercel 模板市场
克隆来源只有两条主路,各自适合不同场景。
第一条主路是你日常使用的应用。如果你的目标用户是开发者,那你看 GitHub Trending、Product Hunt、Hacker News 的首页布局,就会发现"标题 + 简介 + 标签 + 跳转按钮 + 投票数"几乎是一个被证实有效的列表卡片范式。如果你要做的是投资人追踪,那你每天刷的 CoinMarketCap、Substack、The Information 都在教你怎么做"主体 + 关键指标 + 时间戳"三元组。你每天打开的应用,就是你的用户会打开的应用——这句话在 Vibe Coding 时代比以往任何时候都更真。
第二条主路是 Vercel 模板市场(https://vercel.com/templates)。这条路的本质是把"已知骨架"产品化,适合"我没有明显候选"的兜底场景。模板的优势是已经完成了部署优化、SEO 元数据、响应式断点这些工程细节,这些"脏活"在 Tailwind CSS 官方文档 与 Next.js 部署文档 里也能找到对应实现;缺陷是"它为通用场景设计,不一定贴合你的垂直业务"。
挑选标准:列表页 + 详情页的双视图齐备
挑骨架不能凭感觉,需要一张硬清单。最硬的一条是:你选的目标应用,必须同时具备"列表页"和"详情页"两种视图,且这两种视图之间有清晰的跳转路径。原因是 MVP 阶段几乎所有应用都逃不掉"列表 + 详情"这条主链路:列表页负责"扫一眼全局",详情页负责"看一个具体对象",两者缺一,都意味着你的应用本质上是单视图工具,无法满足"扫 + 看"的用户习惯。
第二条标准是"视觉节奏可截图可标注"。如果你打开一个候选应用,脑子里浮现不出"我能不能用三张截图讲清它的全部布局节奏",那它就不是一个合适的克隆对象——说明它的视觉密度过高或过低,信息架构对你来说不友好。
第三条标准是"核心交互路径 ≤ 3 步"。从首页到完成一次核心操作(比如"加入追踪"“收藏”“筛选”),不应该超过三次跳转。超过三次意味着目标产品的复杂度不适合 MVP 阶段直接克隆。
| 维度 | 日常应用 (CoinMarketCap 类) | Vercel 模板 |
|---|---|---|
| 业务贴合度 | 高 (你熟悉的目标场景) | 低 (通用模板) |
| 视觉密度 | 高 (信息密集,需要取舍) | 中 (结构清晰但留白偏多) |
| 部署成本 | 高 (需重新实现状态、SEO、缓存) | 低 (一键部署) |
| 二次定制成本 | 中 (改结构容易,改色板难) | 高 (改结构难,改色板容易) |
| 最适合的阶段 | 已知垂直业务、需要快速对齐心智 | 完全没想好要做什么、先要一个能跑的壳 |
用 CoinMarketCap 举例:三栏布局迁移到影响力者追踪
CoinMarketCap 是一个被低估的"骨架教学样本"。它的列表页采用经典三栏:左侧是"过滤器面板"——市值范围、类别标签、交易所筛选;中间是"加密货币榜单"——带涨跌色块、24h 成交量、市值排名的卡片;右侧是"摘要面板"——头部资产的价格快照和市场动态。这种节奏在 SaaS 与数据型应用里其实随处可见,不是 CoinMarketCap 的发明,而是它把这种结构推向了极致。
这套三栏节奏可以零成本迁移到一个完全不同的垂直:追踪影响力者(KOL/Investor Tracker)。左侧过滤器换成"行业、地区、粉丝量级、平台来源";中间榜单换成"KOL 列表,带订阅增长率、内容互动率、平均曝光量";右侧摘要换成"本周头条 KOL 的最近发言摘要 + 相关项目涨跌"。你看,布局节奏没变一个像素,但承载的业务语义完全换了一套。
更妙的是,这种迁移保留了"用户已经被训练出的肌肉记忆"。一个习惯刷 CoinMarketCap 的投资人,看到你的 KOL 追踪器三栏布局,会瞬间知道"左边筛、中间看、右边扫",零学习成本——这种零学习成本,在 MVP 阶段比任何花哨动效都值钱。
时机判断:什么时候退回 Vercel 模板
日常应用克隆不是万能解。下面三种情况出现任意一种,就该退回 Vercel 模板市场兜底:
- 当下没有明显候选:如果你的目标用户在脑中还是一片模糊,你无法说出"我的用户每天打开 X 应用",那就不该硬克隆,否则你克隆到的只是"看起来像"的反模式。
- 场景过于垂直且没有现成对标:比如"链上 DeFi 收益聚合器",专业到只有不到一千人用,这种情况下没有人替你打磨过视觉节奏,克隆只会克隆到一堆"看起来对、用起来错"的细节。
- MVP 第一周目标只是"先有一个能跑的壳":如果连业务都还没验证,先别从成熟产品借骨,先从模板借壳更划算。
这三条边界一旦画清楚,你就不会陷入"找克隆对象找了三天的内耗"——Vibe Coding 的最大浪费不是 AI 写错代码,而是人原地打转。
动手前先截图:锁定要复用的视觉重点
挑好骨架之后,动手写代码之前还有一道必经工序——截图。不是为了留档,而是为了"锁定要复用的视觉重点"。打开你想克隆的应用,按这个清单截图:
# 项目资产目录结构示例
mkdir -p assets/reference
cd assets/reference
# 克隆目标截图命名规范 (把截图丢进 assets/reference/)
# home.png 首页全貌 (确认主色、辅色、几栏几行)
# list.png 列表页全貌 (信息密度与卡片组件结构)
# detail.png 详情页全貌 (字段布局与元数据位置)
# filter-open.png 筛选打开后的中间状态 (交互路径的关键帧)
# flow-*.png 一次完整核心交互的若干关键中间态
把截图丢进 assets/reference/ 目录,文件名按页面命名,后面让 Claude Code 解析截图需求时,这些文件就是"视觉契约"。配合 Claude Code 官方文档 里提到的工作流,你可以直接让 Agent 把这些截图作为参考输入,反过来约束 layout 决策。
这一步十分钟换三小时——Vibe Coding 时代最大的浪费,不是写错代码,而是写到一半才发现"原来首页不该放 Logo 占那么大"。
[观察] 这一步的核心不是"模仿谁",而是"训练自己的视觉肌肉"。你每克隆一个成熟产品的骨架,都会偷师到它的信息层级决策:为什么 CoinMarketCap 把"涨跌幅"放第二行而不是第一行?为什么 Substack 把"作者头像"放标题旁边而不是右侧?这些决策背后都是真实用户行为的收敛值。克隆的本质不是抄答案,而是抄"出题思路",把决策依据偷过来。
[数据] 一个粗略但能用的经验数字是:克隆成熟产品比从零设计节省 60%-80% 的"决策时间",但仅节省 10%-20% 的"实现时间"。这意味着克隆的最大价值,集中在前端的"想清楚"环节,而非"写出来"环节。Vibe Coding 时代,这 60%-80% 的"想清楚"时间,会被工具进一步压缩,但前提是你已经"想清楚"——而所谓想清楚,正是这一步里你从成熟产品骨架里偷师到的东西。
第二步下: Deep Research Skill 识别可复用组件
在 Claude Code 的能力图谱里,Deep Research 是一项默认装载的设计调研技能。它并不像插件市场里那些需要手动安装的 extension,而是与 Slash Commands、Plan mode、Review mode 一样,在安装完 Claude Code 之后就可以直接调用。可以把它理解成 Agent 内置的一个"反向工程浏览器"——给定一个站点地址,它会代替人去完成原本需要手动打开 DevTools、扒 Network 面板、查 HTML 源码、再去 GitHub 搜索类似实现这一整套动作。整套调研流程从触发到落盘,通常只需要几分钟,这是手工方式无法企及的速度。
触发方式非常朴素。打开一个新的 Claude Code 会话,把目标站点的首页 URL 直接粘贴进对话框,Agent 便会自主发起调研。它会沿着首页的链接图向下爬取若干层,把页面里出现的 CSS 类名前缀、JS 资源 hash、可访问的样式表、图标字体声明都收进上下文,再与已知开源组件的特征库做比对。最终输出的并不是一段阅读笔记,而是一份可以直接进入工程评审的清单。整个过程不需要用户额外编写 prompt 模板,这是 Deep Research 与一般网页摘要工具的核心差异。
典型产出会落在三个维度。第一是站点使用的 UI 库,例如检出 shadcn/ui、Radix UI、Mantine、Chakra、Material UI 等组件库的痕迹;第二是开源组件清单,即页面里那些看起来像是自研、但其实在 npm 上已经有现成实现的卡片、表单、模态框、Tab 切换、轮播图;第三是工程惯例,例如用了什么 CSS 方案(Tailwind / CSS Modules / vanilla-extract)、状态管理方案(Redux / Zustand / Jotai)、动画方案(Framer Motion / GSAP / Motion One)。这三类信息组合在一起,基本能还原一个站点 80% 左右的前端骨架,足以支撑下一步的 v1 合并。
工程价值落在"避免重造轮子"五个字上。组件复用不仅意味着少写代码,更重要的是合规与稳定。开源组件往往经过数千次 commit、上百个 issue 的打磨,在可访问性(a11y)、键盘导航、屏幕阅读器兼容这些细节上都有现成的兜底;而手写一个看似简单的 Dropdown Menu,常常会忽略 ARIA 属性、焦点陷阱、Esc 关闭、点击外部关闭等边界条件。复用即合规,复用即稳定,这两件事在产品上线阶段比"性能再快 5%"要重要得多,尤其是在面对合规审计与无障碍法规时,复用社区已审过的组件几乎是唯一的低成本路径。
把这份清单交接给下一步的方式也很直接:把 Deep Research 输出的 Markdown 报告原样带进 v1 合并阶段。Claude Code 在进入"合并多个候选站点方案"的会话时,会自动读取上下文里已有的组件清单,作为构建新骨架时的零件库。Agent 会优先从清单中挑选最匹配的现成组件,而不是凭直觉去 npm 上随机搜索;同时,清单中的版本号、依赖关系、潜在冲突点都会被一并带过去,避免在 v1 阶段出现"装上跑不起来"的尴尬。
[观察] 这一步实际上把前端选型自动化成了一次调研任务。传统流程里,前端 Lead 要花半天到一天翻 DevTools、找替代品、写选型文档;现在 Agent 一次会话就能给出可执行清单,人力从"执行选型"被上移到"评审清单"。工程师的注意力被释放到"这个组件是否符合品牌气质""这套交互是否符合目标用户心智"这些无法自动化的问题上,这是 Agent 时代工程师角色翻转的典型缩影。
[数据] 在一次典型调研里,Deep Research 通常会输出 20 到 40 个候选组件,覆盖导航、表单、反馈、数据展示、布局五大类。清单中大约 70% 的条目能在公开 npm 包里找到直接可用的实现,剩余 30% 才需要二次封装或局部自研。这意味着 v1 阶段的可复用率往往超过 60%,显著降低了从零起步的边际成本,也让原本一周起步的前端搭建压缩到一两天内即可完成初稿。
下面这段伪代码展示了如何在一个新会话里触发 Deep Research 并把产物落盘,作为 v1 合并阶段的输入:
# 在 Claude Code 新会话中触发 Deep Research
claude chat --new-session <<'EOF'
请对 https://example.com 做深度设计调研,输出 Markdown 格式的组件清单,
维度包括:UI 库、开源组件、CSS / 状态管理 / 动画方案。
请尽量给出每个候选组件对应的 npm 包名与最低可用版本。
EOF
# 把会话产物落盘,供 v1 阶段直接读取
claude export --last-session > research-report.md
接下来是一张常见的输出对照表,展示了 Deep Research 在不同类型站点上的识别表现与可复用率:
| 维度 | 典型识别项 | 可复用比例 | 主要工具 |
|---|---|---|---|
| UI 库 | shadcn/ui、Radix、Chakra | 90%+ | shadcn CLI、Radix Themes |
| 通用组件 | Dropdown、Modal、Tab | 70-80% | Radix Primitives、Headless UI |
| CSS 方案 | Tailwind utility class | 几乎 100% | Tailwind CSS |
| 动画方案 | Framer Motion / Motion One | 80% | Framer Motion |
| 状态管理 | Zustand / Jotai | 70% | Zustand |
下面是一份关于"复用 vs 自研"的取舍矩阵,这几乎是每个前端团队在 v1 阶段都会反复讨论的经典问题。表中把两种路线在五个维度上做了显式对比,便于在评审会上快速对齐决策:
| 取舍维度 | 复用开源组件 | 全自研组件 |
|---|---|---|
| 上线速度 | 快,几小时内接入 | 慢,通常需要数周 |
| 可访问性兜底 | 现成,经过社区验证 | 需自行测试与审计 |
| 品牌差异化 | 弱,容易"撞脸" | 强,可完全定制 |
| 长期维护成本 | 跟随上游版本升级 | 内部可控,但需投入人力 |
| 适用阶段 | v1 MVP、验证期 | v2+、品牌成熟期 |
取舍的核心在于阶段。在 v1 阶段,业务目标是用最小成本验证核心假设,复用能换速度;到了 v2 之后,品牌差异化与设计语言沉淀变得更重要,才开始考虑局部自研或对开源组件做深度二次定制。把这条原则写在团队的选型 SOP 里,可以避免无意义的反复争论。
官方文档里关于 Claude Code 的 Deep Research 默认行为可参考 https://docs.anthropic.com/en/docs/claude-code/overview 与 https://docs.anthropic.com/en/docs/claude-code/slash-commands,里面详细说明了 Agent 在拿到 URL 时会执行的步骤与可配置的输出格式。如果想把组件清单进一步结构化以便后续 Agent 解析,Model Context Protocol 官方文档 https://modelcontextprotocol.io/ 描述了如何把"调研输出"封装成可被下游 Agent 读取的结构化资源;GitHub MCP Server 仓库 https://github.com/modelcontextprotocol/servers 则给出了一组可立刻复用的工具实现,例如把"已识别的组件清单"作为仓库 issue 模板直接提交,从而让清单从一份文档升级为可编排的资源。
需要警惕的是,Deep Research 并不是万能的。它的识别依赖于站点本身没有做重度混淆(minified class names、随机 hash、SSR + hydration 后才注入的 DOM),对于那些刻意隐藏技术栈的站点,识别率会显著下降,甚至可能给出错误结论。此外,识别出的组件库版本可能滞后于最新发布,引入时务必通过 npm view <pkg> versions 或 GitHub releases 复核一次,避免把 deprecated API 带进新工程。同时也要注意版权与商标风险:借鉴视觉语言是常规做法,但逐像素复刻 logo 与品牌色块则属于另一回事,清单里如果出现品牌资产,务必在 v1 合并阶段做替换。
把这一步放在克隆流程里的意义,在于把"我看到一个好用的设计"翻译成"我拿到了一份可执行的零件清单"。下游 v1 合并阶段只需要做减法和组合,不再从零做加法,这是用 Agent 替代重复劳动的最直接体现。借骨架这件事,从此有了可复制、可审计、可交接的工程语义。
第三步: Spec 驱动的 Clone 改造工程
第三步:Spec 驱动的 Clone 改造工程
Spec-Driven Development(规格驱动开发)的核心思路非常朴素:不再把「自然语言需求」当成聊天式的提示词丢给 Agent,而是先把它落成一份结构化的 spec.md,再把这篇 Markdown 当成 Agent 的「输入契约」喂进去。这样做的工程价值在于,所有改造动作都可以回溯到 spec.md 中的具体字段——一旦 UI 文案、列名、详情页结构需要回滚,工程师不必重新叙述上下文,只需改 spec,再让 Agent 跑一遍相同的改造指令。
为什么把 spec.md 当成 Agent 的输入
在传统 prompt 工程里,我们习惯把需求写成「请把首页的标题改成 XX,把三张卡片改成 XX」这样的句子。这对一次性 demo 没毛病,但一旦要 clone 一个完整的站点并在此基础上做二次改造,这种零散对话会迅速耗尽 Claude Code 的上下文窗口,也会让 Agent 在第三轮、第四轮之后开始「幻觉字段」——比如它会臆造 spec 里没有的列,或者把已经约定好的字段悄悄改掉。spec.md 的作用就是把「单一事实来源」(single source of truth)从对话流中剥离出来,放进 Agent 的 file system 工具调用范围里——Claude Code 会主动用 Read 工具读它,而不是依赖对话记忆。Claude Code 的官方文档(见 https://docs.anthropic.com/en/docs/claude-code/overview )把这种「喂文件优于喂句子」的工作流列为推荐范式之一。
这份 spec.md 通常包含三块内容:
- 数据契约(Data Contract):表名、字段名、字段类型、可选枚举。例如
articles.title: string、articles.published_at: ISO8601。 - 视图契约(View Contract):每个路由对应的页面组件名、关键文案占位符、列表项字段映射。例如
/blog/[slug]路由对应BlogDetailPage组件,需要绑定title / author / cover / body四个字段。 - 改造禁区(Preservation Boundary):明确告诉 Agent,clone 来的 Tailwind class、shadcn 组件、版式布局不许动,只许动数据绑定层。
改造动作清单
把 spec.md 喂给 Agent 之后,Claude Code 会按 spec 走完一整套改造流水线,大致落成以下四类原子动作:
- 重命名列名:把 clone 源里的硬编码字段(比如
header_text、body_html、create_time)映射到 spec 里的语义化字段(比如title、content、published_at)。这一步直接落到 TypeScript 类型定义与所有引用点。 - 改文案:把 clone 源里的占位文案(
Lorem ipsum、Hello World、Sample Article 1)替换成 spec 里指定的业务文案。文案本身可能横跨 5 到 20 个组件,Agent 会借助grep与ripgrep等搜索工具批量替换。 - 替换模拟数据:把 clone 源里写死在组件内的 mock 数组,改成从
lib/data/*.ts读出来的真实结构。这是从「写在 JSX 里」到「数据驱动」的范式跳跃。 - 重建详情页:clone 源常常只有列表页骨架,详情页要么是死链要么是占位符。spec 给出详情页字段之后,Agent 会基于现有列表项布局派生详情页骨架,补上动态路由。
这四类动作的顺序在 spec 里也应当写明,因为它们之间存在依赖——先重命名列名,再替换模拟数据,最后才重建详情页。如果顺序颠倒,Agent 会陷入大量「找不到字段」的错误回环,白白消耗 token budget。
保留原则:不动 UI 组件与版式
这一步是整套工程里最容易翻车的点。Spec-Driven 不等于 Spec 支配一切。clone 源之所以值得 clone,是因为它的视觉密度、交互细节、栅格系统已经被原作者调过一遍——把这些当作「免费的设计资源」才是 Vibe Coding 的核心杠杆。所以 spec.md 里必须显式划定一个保留边界,告诉 Agent:
- 不许改
components/ui/*下任何 shadcn 组件的 props 与样式 - 不许改
tailwind.config.ts里的 theme 扩展 - 不许改
app/layout.tsx里的全局结构 - 只允许改
app/**/page.tsx与lib/**下的业务逻辑层
这种「组件不动、版式不动、只动数据层」的边界条件,本质上是一种单向数据流约束:UI 是 clone 来的固定面,数据是 spec 注入的变量面,二者在 page.tsx 这一个文件里完成对接。这样即使后续 spec 再迭代 v2、v3,UI 层都不用重做。
工程产物:web-1.0 目录
跑完 Spec 驱动的改造流水线之后,项目根目录下会出现一个 web-1.0 目录。这是 Vibe Coding 工作流里一个很有意思的工程惯例——它不是「最终产品」,而是「第一个可演示版本」的快照。所有后续的迭代都从这个目录派生:v1.1、v2.0 各自一个目录,互不污染。这种「按版本切片」的目录组织方式,在多轮 Spec 迭代时能避免 Agent 把 v2 的改动回灌到 v1。
进入 web-1.0 目录之后,执行以下命令即可在本地浏览器看到改造后的成品:
cd web-1.0
npm install
npm run dev
# 默认监听 http://localhost:3000
打开浏览器访问 http://localhost:3000,你会看到 UI 完全是 clone 源的样式,但所有文案、列表项、详情页都已经按 spec 替换完毕。这是「视觉继承 + 数据替换」的一次完整演示。Next.js 的 App Router(详见 https://nextjs.org/docs )在这一步会自动接管热重载,改一行 spec 再让
扫一扫
121
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
