本站诞生记

本站使用 Claude Code + Spec 驱动开发 从零构建。以下是完整的开发过程、迭代记录和经验总结。

构建方法

开发流程

阶段一：需求拆解

明确了站点的核心目标：

• 帮助开发者全面了解 AI 编程技术
• 提供工具对比和选择建议
• 讲解四种编程范式的区别和适用场景
• 介绍 Spec 驱动开发等工程方法论

阶段二：Spec 编写

为每个模块编写了结构化的 Spec 文档：

• 首页：Hero + 核心内容卡片 + 时间线 + 范式导航 + 用户分流
• 工具页：工具卡片网格 + 对比矩阵 + 需求决策引导
• 范式页：演进路线 + 四范式卡片 + 对比表格 + 代码示例
• 方法论页：分层结构（日常协作 → 规则配置 → 工程方法论）

阶段三：AI 生成

将 Spec 文档输入 Claude Code，AI 按规格生成：

• 页面组件（Vue 3 + Composition API）
• 内容文件（Markdown）
• 样式系统（Tailwind CSS + 自定义 CSS 变量）
• 路由和导航结构

阶段四：人工评审与迭代

检查并调整了：

• 内容准确性和专业度
• 视觉设计细节（颜色、间距、动效）
• 响应式布局适配
• SEO 基础配置

迭代记录

第一轮迭代：内容补齐

目标：从"框架"到"有肉"

1. 工具对比矩阵

在工具页新增了 8 款工具的完整对比表，包含：

• 开发商、定价、平台
• 代码补全、多文件编辑、智能体、中文支持的评级
• 适用场景说明

同时将「如何选择合适的工具」从主观的"按身份推荐"改为客观的"按需求决策"：

• 预算有限 → 优先免费工具
• 网络受限 → 国内直连工具
• 需要深度推理 → Claude Code / Cursor
• 团队协作 → Business 版本

2. 范式代码示例

为四个范式各添加了"同一需求，四种写法"的代码示例：

需求：构建一个天气查询页面，调用 OpenWeatherMap API

• Code Completion：开发者手写，AI 逐行补全
• Vibe Coding：一句话描述，AI 生成全部
• Spec Coding：先写 Spec 文档，AI 按规格实现
• Agentic Coding：描述目标，AI 自主规划 + 执行 + 测试

3. 本站诞生记

新增 /about 页面，记录站点的构建过程、踩坑经验和数据统计。

4. 首页用户分流

在 Hero 区域下方新增三档开发者分流：

• 🐣 编程新手 → 概念入门
• 🧑‍💻 有经验开发者 → 工具对比
• 🏗️ 团队负责人 → 方法论 + Spec 驱动开发

5. SEO 优化

• 添加 sitemap.xml（覆盖所有页面）
• 添加 robots.txt
• 工具页和范式页添加独立的 <meta> 标签

第二轮迭代：样式提亮 + 长页面优化

目标：解决"太黑看不清"和"长页面找不到章节"两个核心问题

1. 深色主题提亮

用户反馈"太黑了，看不清"。诊断发现核心问题是对比度不足：

核心原则：保持深色主题，但提亮 + 增加层次感。不需要大改，调 CSS 变量解决 80% 的问题。

2. 页面目录导航（TOC）

用户反馈"详细页面太长，找不到章节"。新增 PageToc 组件：

• 右侧粘性目录，跟随滚动
• IntersectionObserver 高亮当前章节
• 点击平滑跳转
• xl 以上屏幕显示，小屏隐藏

所有详情页集成：paradigms / tools / methodology / concepts

3. 回到顶部按钮

新增 BackToTop 组件：

• 滚动 300px 后显示
• 右下角浮动
• 平滑滚动回顶部

第三轮迭代：UI/UX 优化 + 范式去递进化

目标：基于专业评审反馈，修复 UI 细节问题，纠正范式页的递进暗示

1. 首页 Hero 区强化

原 Hero 区标题字号偏小，视觉冲击力不足，缺少数据背书。

2. 范式页去递进化（核心改动）

问题：原范式页使用 → 箭头将四个范式串成递进路线，暗示"从低级到高级"。但实际上四个范式是并列的场景选择，一个成熟团队会同时使用多种范式。

改动：

• 删除"演进路线"箭头图（→ 递进暗示的元凶）
• 替换为 "根据你的场景选择" 网格选择器，每个卡片标注适用场景
• 首页范式区增加 "🧭 如何选择？" 决策引导，四列直接告诉用户什么场景选什么
• 对比表格新增 "学习成本" 行
• 新增 "常见误区" 板块，直接纠正三个典型认知错误：
  • ❌ "范式越高级越好"
  • ❌ "Vibe Coding 不专业"
  • ❌ "选一个范式就够了"
• 描述文案从"四层演进"改为"不同场景下的最佳选择——像工具箱里的四把钳子"

3. 侧边栏"相关推荐"

问题：用户看完一个页面后不知道下一步该看什么，跨模块浏览路径断裂。

改动：在 SideNav 底部增加"相关推荐"板块：

• 概念页 → 推荐工具对比、编程范式
• 工具页 → 推荐概念入门、编程范式
• 范式页 → 推荐方法论、工具对比
• 方法论 → 推荐编程范式、概念入门

初版在浅色主题下对比度不足，后调整字号（text-[10px] → text-xs）和颜色（text-muted → text-secondary）修复。

4. 核心内容卡片层次

问题：三张核心卡片视觉权重相同，用户无法快速判断优先级。

改动：

• 第一张卡片（概念入门）增加 ring 边框 + "推荐起点"标签
• 卡片 hover 时显示 CTA 文字（"从这里开始 →"）
• 描述文字行高从默认调整为 leading-relaxed

5. 移动端侧边栏

问题：桌面端侧边栏在移动端不可用，小屏幕用户无法快速导航。

改动：

• 新增浮动切换按钮（左下角圆形，蓝色背景，带汉堡/X 图标切换动效）
• 新增遮罩层，点击遮罩关闭侧边栏
• 侧边栏增加 transition-transform 滑入/滑出动画
• 路由切换时自动关闭移动端侧边栏
• 内容区增加底部 padding-bottom 避免浮动按钮遮挡

6. 底部 CTA 区升级

从普通 section 改为带渐变背景的圆角卡片，标题改为更有行动力的"准备好开始了吗？"，按钮样式与 Hero 区统一。

第四轮迭代：工具信息核实 + 首页减负 + 交互增强

目标：基于 Code Lobster（AI 编程导师）的专业评审，修正工具信息错误，优化首页体验

本轮迭代由 AI 编程导师 Code Lobster 从专业性和用户体验两个维度对站点进行全面审查后驱动。

1. 工具信息核实与修正（关键修复）

问题：3 款工具信息存在事实错误，可能误导用户。

通过逐一访问各工具官网进行核实：

同步更新了 composables/useToolsData.ts 中的数据和 content/tools/ 下的 Markdown 文件。

2. Windsurf 信息补充

根据 windsurf.com 官网，补充了 Devin 云端智能体集成 和 Agent Command Center 等新功能描述。

3. 首页信息密度优化

问题：首页 7 个模块全部展开，用户需要滚动很久才能看完，容易疲劳。

改动：

• 发展历程 和 四大编程范式 改为可折叠区块，默认收起
• 使用 Vue <Transition> 组件实现平滑展开/收起动画
• CTA 区域精简 padding，减少滚动压力
• 折叠状态通过 ref 控制，用户点击标题即可展开

<button @click="showTimeline = !showTimeline">
  <h2>发展历程</h2>
  <span :class="showTimeline ? 'rotate-180' : ''">▼</span>
</button>
<Transition name="collapse">
  <div v-show="showTimeline">...</div>
</Transition>

4. 工具页交互增强

问题：能力光谱是静态的，工具卡片缺乏 hover 反馈。

改动：

• 能力光谱可交互：点击工具高亮筛选，再次点击取消
• 新增 selectedId prop 和 @select 事件，光谱与卡片联动
• 工具卡片 hover 动效：图标缩放（scale-110）、能力条变高、阴影加深
• 新增"✕ 清除筛选"按钮

5. 发展历程面包屑

问题：/concepts/history 页面缺少面包屑导航，用户无法快速返回上级。

改动：在页面顶部添加 <Breadcrumb :items="breadcrumbItems" />，路径：首页 / 概念入门 / 发展历程

6. 搜索窗口布局修复

问题：搜索触发按钮使用 position: fixed 直接钉在视口右上角，与导航栏的"方法论"文字重叠。

根因：按钮脱离了 NavBar 的 flex 布局流，导致位置计算错误。

改动：

• 新建 SearchTrigger 组件，作为 NavBar 的 flex 子元素参与布局
• SearchModal 移除 fixed 定位的触发按钮
• 两者通过 CustomEvent('open-search') 通信

踩坑记录

经验总结

✅ 做对了什么

• Spec 先行：先写清楚每个页面的结构和内容需求，AI 生成的代码质量明显更高
• 渐进式生成：先搭框架再填内容，比一次性生成整个项目更可控
• 及时 Review：每生成一个模块就检查，避免问题累积
• CSS 变量驱动：主题色通过 CSS 变量管理，提亮时只需改几行代码
• 组件化 TOC：目录导航做成通用组件，所有页面复用

⚠️ 注意什么

• AI 生成的内容需要事实核查（特别是工具定价、功能描述等）
• 样式细节需要人工微调，AI 倾向于生成"安全"但不够有特色的设计
• Spec 越具体，AI 输出越可控；Spec 太模糊会导致反复返工
• 长页面必须有导航，否则用户会迷路
• 信息架构的隐含假设要审视：箭头、数字、颜色都可能暗示不存在的递进关系
• 双主题必须同步测试：深色模式下完美的设计，浅色模式下可能完全不可见
• 移动端不是缩小版桌面端：需要独立的交互方案（浮动按钮、遮罩、动画）

💡 给后来者的建议

1. 先写 Spec 再动手——哪怕只是几行描述，也比直接让 AI 写代码好
2. 小步快跑——每次只让 AI 生成一个模块，验证通过再继续
3. 保留 Spec 文档——它是你和 AI 之间的"合同"，也是未来维护的参考
4. CSS 变量是你的朋友——主题色、间距、阴影都用变量，后期调整省力
5. 长页面要有 TOC——用户需要知道自己在哪、能去哪

💡 本站即案例：你正在看的这个网站，本身就是 Spec 驱动开发的实践。从需求拆解到 Spec 编写，从 AI 生成到人工评审，从内容补齐到样式优化——每一步都在验证这套方法论的有效性。