我是如何用 Claude Code + Superpowers 从 0 到 1 搭建这个博客的

techAIClaude工程化

距离写出来这个博客已经有一段时间了，我想把整个过程记录下来：我是怎么用 Claude Code + Superpowers 这套工具和流程，从 0 到 1 把一个模糊的想法变成一个可以上线的东西的。

我是如何用 Claude Code + Superpowers 从 0 到 1 写出这个博客的

这次做博客，我没有直接让 AI 一次性生成一个完整项目。刚开始我就意识到，如果只输入一句“帮我写一个博客”，AI 很可能会直接输出一堆代是怎码，短期看起来很快，但我很难真正理解项目么搭起来的，也很难控制它是否过度设计。

所以我这次采用的是 Claude Code + Superpowers 的工程化工作流。整个过程更像是我和一个 AI 工程师一起协作开发：我负责提出目标、确认方向、控制范围、验收结果；Claude 负责分析、规划、编码、解释和验证；Superpowers 则帮助我们把开发过程拆成更清晰的阶段。

这次我最大的收获不是“得到了一个博客”，而是学到了一套可以复用到其他项目里的 AI 协作开发流程

1. 第一阶段：不是直接写代码，而是先让 AI 进入工作流

一开始，我没有直接对 Claude 说：帮我做一个博客。

而是先给它设定了工作方式： **我想从 0 到 1 搭建一个个人博客，但我的目标不是只拿到成品，而是学习完整的软件开发工作流。请使用 Claude Code + Superpowers 的工程化流程，不要直接写代码，先需求访谈，再写 spec，再做技术选型，再拆 implementation plan，最后小步实现。 **

如果一开始就让它写代码，它可能会凭经验直接开干，但我并不知道它为什么这样选技术、为什么这样设计目录、为什么这样写组件。通过先规定流程，我可以让它每一步都解释清楚。

这一阶段我学到的是：AI 协作开发的第一步不是写代码，而是设定协作规则。

2. 第二阶段：需求访谈，把模糊想法变成清晰需求

接着，我让 Claude 先做需求访谈。 它会问我一些问题，比如：

-这个博客是技术博客、生活博客，还是作品集？-需要哪些页面？-文章用 Markdown 还是 MDX？-是否需要登录？-是否需要数据库？-是否需要评论系统？-是否要 SEO？-是否需要 RSS 和 sitemap？-要部署到哪里？-偏向 Astro 还是 Next.js？

我根据自己的目标回答：这是一个个人技术博客，用来发布技术文章、项目笔记和学习记录。核心页面包括首页、文章列表页、文章详情页、标签页和关于页。内容用 Markdown / MDX 管理，不需要数据库、不需要登录、不需要后台管理。重点是简单、稳定、易维护。

这一步让我意识到，很多开发问题其实不是代码问题，而是需求问题。 如果需求没有说清楚，AI 后面写出来的东西就很容易跑偏。

这一阶段我学到的是：模糊需求不能直接进入开发，必须先变成明确的产品目标和功能边界。

3. 第三阶段：写 spec，确定什么做、什么不做

需求确认之后，我让 Claude 输出了一份产品规格说明，也就是 spec。

spec 里主要包括：

-项目目标 -目标用户 -页面清单 -核心功能（MVP）-暂时不做的功能 -技术约束 -内容模型 -frontmatter 字段设计 -SEO 要求 -验收标准

比如博客不是无限扩展的，它的 MVP 目标应该是：

-能写文章 -能展示文章列表 -能进入文章详情 -有标签 -有基础 SEO -有 RSS / sitemap -支持代码高亮 -能部署

同时我也明确了哪些东西暂时不做：-不做登录 -不做数据库 -不做 CMS -不做评论系统 -不做复杂状态管理 -不做主题切换

这一步避免了 AI 过度工程化。 如果没有这份 spec，AI 很可能会主动给我加数据库、后台或者复杂依赖，看起来高级，但对个人博客来说其实没必要。

这一阶段我学到的是：spec 的作用不是让项目变复杂，而是限制项目不要跑偏。

4. 第四阶段：技术选型，不是跟风，而是结合场景

阶段 1：需求分析

我做了什么： 描述了我的模糊想法——"我想写博客，用 Markdown，简单一点"。

AI 做了什么： 追问我技术栈偏好、页面需求、功能优先级、内容结构。

产出： 一份清晰的功能清单 + 优先级排序（P0/P1/P2）+ 明确说好了 v1 不做什么。

为什么这么做： 如果一开始不说清楚"不做什么"，AI 会在开发中不停地给你加东西——"要不要加个全文搜索？""要不要做个管理后台？"——然后项目永远做不完。先画边界，再开工。

阶段 2：产品规格 spec

AI 生成了 SPEC.md，包括：项目目标、目标用户画像、页面清单（7 个页面）、核心功能（9 个大项 + 优先级）、显式声明的 v1 范围外功能列表、技术选型理由、内容模型、每篇文章的 frontmatter 字段定义、SEO 要求、15+ 条验收标准。

为什么这么做： Spec 是整个项目的"合同"。所有后续开发都对照 spec 来，避免跑偏。程序员都喜欢直接写代码，但 spec 的价值在于——你确认了它，就等于确认了最终要交付什么。

阶段 3：技术选型

这个在 CLAUDE.md 里定了下来：

Next.js 16 (App Router) + React 19 → Vercel 原生支持，SSG/SSR 内置 gray-matter + react-markdown + rehype-highlight → 手写组合，轻量可控 Tailwind CSS v4 → utility-first，不需要手写 CSS 文件 Giscus → 基于 GitHub Discussions，免费无后端 部署：Vercel + 自定义域名

为什么这么做： 选型不能只看"什么最好"，要看"什么最适合这个场景"。个人博客不需要 Remix 的服务端能力，不需要 Astro 的 Island 架构。需要的是——写得方便、部署简单、长期维护成本低。

阶段 4：Implementation Plan

AI 生成了 UI_IMPLEMENTATION_PLAN.md，把开发拆成 10 个小任务（D1-D10），每个任务：什么文件、为什么要改、改了之后怎么验证（curl 命令 + 预期输出）、完成标准是什么。

还画了依赖图：

D1 (CSS tokens)
 ├─ D2 (nav bar)
 ├─ D3 (footer)
 ├─ D4 (page bg)
 │    └─ D5 (PostCard)
 ├─ D6 (prev/next)
 ├─ D7 (back to top)
 ├─ D8 (unify headings)
 └─ D9 (like animation)

D10 (dark mode) depends on ALL above

为什么这么做： D1 是把设计变量定义好，后面所有任务都引用它。所以 D1 必须最先做。D10 暗色模式必须最后做，因为它依赖前面所有任务都用了正确的颜色变量。这个顺序不是随便排的。

阶段 5：MVP 开发

做了一个关键决策：每完成一个任务，停下来，等我确认，再做下一个。

比如 D1（CSS Design Tokens）做完之后，零视觉变化。只有一个构建成功的验证。但这一步是整个项目的基石。

D5（PostCard 卡片化）做完之后，AI 停下来了，问我："D6 是上一篇/下一篇导航，要继续吗？" 我说继续，它才继续。

中间发生过一次重要的事。D7 计划是"文章底部加标签行"，我开始之前讨论了一下，觉得这个设计不好，改成了"回到顶部按钮"。AI 没有坚持原计划，而是和我重新讨论了方案，然后才动手。

为什么这么做： 如果让 AI 一口气做完 10 个任务，中间某个任务理解错了，后面全白做。停下来确认的 30 秒，省的是几小时的重写。

阶段 6：部署前优化

MVP 做完后，我做了一件之前没想过会做的事：让 AI 做代码审计。

它从 7 个维度审计了整个项目：产品完整度、内容体系、UI/UX、SEO、性能可访问性、工程质量、部署运营。输出了评分（62/100）、10 个最严重的问题、P0/P1/P2 优先级分类。

然后分三轮修：

  • P0（上线前必须修）：删占位文章、补全 metadata、修 robots.txt
  • P1（应该尽快做）：删死依赖、完善 sitemap、RSS 输出全文、分页页加 noindex
  • P2（锦上添花）：About 页增强、JSON-LD 结构化数据、封面页移动端适配、README 补充

修复后再审计一次——评分从 62 升到 71，再升到 77。

为什么这么做： 写代码的人和审代码的人不应该是一个视角。AI 切到审计者角色之后，能发现很多开发者视角看不到的问题——比如"12 个页面里有 10 个缺少 metadata"。

阶段 7：错误修复和复盘

开发中遇到过一个典型的错误：有一次修复页面背景色的时候，AI 顺手改了硬编码的蓝色值。虽然颜色确实应该统一，但那次任务的目标只是改背景。我让它回滚，把颜色改动单独作为一次任务来做。

还有一个反复出现的问题：AI 有时候会在修复时多做事。修 bug 时顺手改 UI，或者"预防性"加配置。CLAUDE.md 里专门有一条规则应对这个：

Bug fixes must ONLY touch the files necessary to resolve the bug. No "preventative" config changes, no refactoring, no style tweaks.

为什么这么做： 这条规则是"踩坑踩出来的"。每次 AI 多做了事，git diff 都会变大。diff 越大，越难确认到底改了啥。修 bug 的时候，改动的文件越少越好——你能一眼看出修复了什么，而不是在一堆"优化"里找 bug 在哪里。

阶段 8：文档和最终验收

最后一步是让 AI 做最终验收：

  • pnpm lint → 0 errors, 0 warnings
  • npx tsc --noEmit → 零错误
  • pnpm build → 30/30 页，全 SSG/Static
  • 检查：每页有 title、分页页有 noindex、sitemap 完整、RSS 全文输出

最终评分 82/100。剩下扣分的是暗色模式（还没做，计划后续迭代）和内容偏少（需要持续写作）。

5. 具体做了哪些功能

根据当前代码确认：

已实现：

  • 封面页 — 全屏 MP4 视频背景 + 博客名 + 诗词文案 + 进入博客按钮，响应式字号
  • 文章列表 — 卡片式布局，白底 + 浅边框 + 靠间距分隔，按时间倒序
  • 文章详情 — Markdown 渲染，文楷字体，代码高亮（atom-one-dark），JSON-LD 结构化数据
  • 分页 — 路径分页（/posts/p/2），纯 SSG，每页 5 篇
  • 分类/标签筛选 — 分类页和标签页，标题格式统一，分页规则一致
  • 搜索 — nav 表单提交到 /search?q=xxx，服务端空格分词 AND 匹配
  • 关于 — 个人介绍、技术栈、社交链接
  • 404 — 友好提示 + 两个导航按钮
  • 导航 — 毛玻璃 sticky 导航，搜索框，About 和 RSS 图标带 tooltip
  • Footer — 版权、ICP 占位、订阅链接
  • 上一篇/下一篇 — 文章底部导航，首尾文章正确显示
  • 回到顶部 — 固定右下角按钮，hover 展开文字，自动显隐
  • Giscus 评论 — GitHub Discussions 评论 + Reactions 点赞
  • SEO — 全部页面 metadata、sitemap（含标签页和分页）、robots.txt、OG/Twitter Card
  • RSS — 全文输出，含分类
  • 浏览器兼容性 — browserslist + postcss-preset-env + CSS 变量 fallback
  • 环境变量 — SITE_URL 管理站点地址

计划中 / 待优化：

  • 暗色模式（D10，CSS 变量已定义但未落地到组件，计划后续迭代）
  • About 页头像是占位渐变（需要真实头像文件）

6. 我学到了什么

把模糊需求变成 spec

以前我以为"做一个博客"是一个清晰的需求。被 AI 追问之后才发现——"你要几个页面？""分类和标签有什么区别？""SEO 做到什么程度？"——每个问题背后都是一个我从来没想过的细节。Spec 的价值不是文档本身，是写文档的过程中逼你想清楚。

拆 implementation plan

D1 必须最先做（定义变量），D10 必须最后做（依赖前面所有）。拆任务不是随便拆——依赖关系决定了执行顺序。如果搞错顺序，后面会反复返工。

小步开发 + 每步验证

每做完一个任务停下来确认，看起来慢，实际快。因为一个任务出错了，回滚的范围只有那一个任务。如果一口气做完 10 个再检查，出错了不知道是哪一步的问题。

控制 AI 不要乱改

CLAUDE.md 里的协作规则不是装饰。"修 bug 只碰必要的文件""不要顺手优化""修完报告 diff"——每一条都是因为之前踩过坑才写上去的。你需要让 AI 尊重你的边界，而边界需要用具体的规则来表达。

做错误复盘

遇到了问题不跳过，而是回头搞清楚——为什么会发生？规则里哪里不够明确？然后更新规则。这是一个迭代的过程：不只是代码在迭代，协作方式也在迭代。

如何处理实际问题

比如分页——第一版用了 ?page=2 查询参数，结果三个列表页全变成了 Dynamic 渲染。回滚后改成路径分页 /posts/p/2，全部恢复 SSG。这个决策来自对 Next.js 渲染策略的理解，AI 提出方案，我做判断。

比如点赞——先用 JSON 文件 + API Route 自建，后来发现部署后会丢数据。讨论后直接删掉自建点赞，改用 Giscus Reactions。少 3 个文件，数据 GitHub 托管，零维护成本。

用 CLAUDE.md 管理上下文

CLAUDE.md 是给 AI 的"新手指南"。技术栈、项目结构、协作规则、边界约束——每次对话 AI 都先读这个文件，就相当于每次都有上下文。项目越复杂，这个文件的价值越大。

7. 遇到的问题和解决方式

问题 1：AI 有时会越界添加不需要的东西

场景： 修一个 CSS 背景色的 bug，AI 顺手改了硬编码的蓝色值为 CSS 变量，还调整了 PostCard 的间距。

为什么会发生： AI 倾向于"顺手优化"——它看到不完美的地方就想修。它的出发点是好的，但修 bug 和做优化不应该混在一次改动里。

怎么解决的： 我让它回滚，然后把 CLAUDE.md 里的规则强化为："Bug fixes must ONLY touch the files necessary to resolve the bug. No 'preventative' config changes, no refactoring, no style tweaks." 如果确实需要优化，单独提出来讨论，作为一次独立任务。

学到了什么： 每次 git diff 变大，检查变难。小 diff = 安全。

问题 2：分页方案第一次做错了

场景： 第一版分页用 ?page=2 查询参数。构建成功，但三个列表页全变成了 Dynamic 渲染。

为什么会发生： searchParams 导致 Next.js 无法在构建时确定页面内容，只能退化为按需渲染。个人博客用 Dynamic 渲染完全不合理——SSG 才是正确的选择。

怎么解决的： 回滚全部改动，改成路径分页 /posts/p/2。新增 4 个路由文件，但所有页面恢复 SSG。

学到了什么： 技术方案的后果有时候在 build 日志里才能看出来。"构建成功"不代表"构建正确"。路由设计是影响全局的基础决策，要多讨论几轮。

问题 3：点赞系统做了又删

场景： 一开始自建了点赞系统——JSON 文件存储 + API Route 读写 + localStorage 一人一票。逻辑完整，功能正常。

为什么会出问题： 在本地 pnpm dev 跑没问题，但部署到 Vercel 上，Serverless Function 的文件系统是临时的——点赞数据没法持久化。

怎么解决的： 讨论了几个方案（Vercel KV、GitHub Discussions API、Cloudflare D1），最后选择最简单的：直接删掉自建点赞，改用 Giscus Reactions。Giscus 的 reactionsEnabled="1" 一直开着，评论区上方就有点赞按钮。少 3 个文件，数据存 GitHub，永久免费，多用户实时同步。

学到了什么： 有时候最好的解决方案不是"修好它"，而是"删掉它，用已有的"。Giscus 你本来就要用来做评论，它顺带做了点赞。不引入新的依赖和 API 就是最好的架构决策。

问题 4：部署前才做审计，发现一堆问题

场景： MVP 开发完准备部署，让 AI 做了一次全面审计。结果：62 分。10 个严重问题——4 篇占位文章污染内容、12 页中 10 页缺 metadata、暗色模式失效、两个死依赖没删、站点 URL 硬编码 5 处。

为什么会发生： MVP 阶段的关注点是"功能能不能跑"，不是"做得完不完善"。SEO、性能、工程质量这些维度在开发时容易被忽略。

怎么解决的： P0/P1/P2 三轮修复，审计 → 修复 → 再审计，分数从 62 → 71 → 77。关键是把审计做成了一次独立流程，不是开发过程里的顺便看看。

学到了什么： 写完代码 ≠ 做完项目。审计是独立的一个步骤，它需要切换视角——从"创造者"切换到"检查者"。AI 在不同角色下看到的东西不一样。

问题 5：Google Fonts 被墙导致构建失败

场景： 有一次 build 突然挂了，报错 next/font: error: Failed to fetch Geist from Google Fonts。

为什么会发生： next/font/google 在构建时会下载 Google Fonts 文件。Google Fonts 在国内被墙了，不挂 VPN 就下载失败。

怎么解决的： 挂了 VPN 重新构建，恢复了。这个问题需要长期解决——计划把 Google Fonts 换成 npm 自托管包（geist npm 包），让构建不再依赖外部 CDN。

学到了什么： 开发环境依赖的外部服务都可能成为瓶颈。Google Fonts、GitHub API、CDN——在国内网络环境下，能自托管的东西都值得自托管。

8. 最终总结

这次我不是单纯让 AI 帮我生成一个博客。而是学习了一套 AI 协作开发方法。

Claude Code 负责执行和解释——它写代码、做审计、生成文档、跑验证命令。Superpowers 工作流帮我把整个开发过程结构化——需求访谈 → spec → plan → 小步开发 → 每步验证 → 部署前审计 → 最终验收。而我负责判断方向、确认计划、控制范围、验收结果。

过程中最深的一个体会是：AI 能做的事情很多，但"做什么"和"为什么做"还是得人来做决定。

比如分页用路径分页还是查询参数、点赞自建还是用 Giscus 替代、颜色用亮蓝还是深墨蓝——这些决策 AI 可以给你分析利弊，但最终拍板的人是你。AI 像一个执行力和知识储备都很强的搭档，但它不会替你对结果负责。负责的人还是你自己。

博客已经基本完成了。回顾整个过程，我真正学到的不是怎么写 Next.js，而是怎么和 AI 高效协作完成一个真实项目。 这个能力可能比博客本身更有价值。

也许多年以后回头看，这个博客很简陋。但它是我用新的工作方式做出来的第一个完整项目。就像第一篇 Hello World——不是为了证明什么，只是为了开始。

回到顶部