用 AI 扩展这个个人站点的真实记录

这个站点的 Blog、About、Contact 子页面，以及后来的分类筛选、星球背景、文章扩充，大部分是在 Cursor 里和 AI 结对完成的。不是演示项目，是我真实在维护的仓库——所以既有「AI 很省力」的部分，也有「不盯着就会翻车」的部分。

这篇文章不吹 AI 多厉害，只记录这次扩展里什么有效、什么无效，给同样在改老项目的的人一个参照。

任务怎么拆，AI 才不容易跑偏

我最开始犯过的错，是把需求扔成一句：「给主页加 blog、about、contact」。AI 会给你一个看起来像那么回事的方案，但很容易：

• 引入 Markdown 引擎或新框架（和项目「无依赖」原则冲突）
• 改掉首页 intro/main 的行为（回归风险）
• 在 gulpfile 里堆一坨看不懂的魔法

后来改成按 Task 拆：先 scaffold 目录 + loadData，再加 gulp task，再做一个页面，再 watch，再文档。每步验收标准是「npm run build 通过 + dist 里出现对应 html」。AI 每次只改一小块，我能在 diff 里看懂。

这次子页面扩展的设计文档和实现计划，就是按这个节奏写的。有文档在前，AI 不会凭空发明一套架构。

AI 做得好的部分

• 样板代码： Pug 模板结构、Less 卡片样式、gulp task 骨架——生成速度快，格式也整齐
• 样式统一： 让它「对齐主页暗色风格」，它能把颜色、字重、hover 发光效果抄得七七八八
• 内容扩充： 博客正文从几段扩到多章节，Spring Boot 那篇补全 DTO/测试章节，省了我大量打字时间
• 排查方向： 「Blog 链接点不了」它很快定位到 Canvas 挡住点击；「页面不能滚动」定位到全局 main { overflow: hidden }

我必须亲自把关的部分

• 路径层级： 文章页在 blog/posts/ 下，导航链接必须用 base 变量，写死 ../blog/ 会在详情页 404——这类 bug AI 会反复犯
• 配置是否被 watch： config.json 变更不触发重建，改完开关要重启 dev——文档里写了，但 AI 不会主动提醒你
• 真实联系方式： 邮箱、GitHub 用户名必须我指定，不能指望 AI 猜
• 交互语义： 分类一开始做成锚点滚动，我要的是筛选过滤——需求说清后它才改对

一次真实的迭代链

博客模块大概经历了这些轮次（简化版）：

1. 列表页 + 一篇文章 → build 验证
2. 左侧分类导航 → 先做错成滚动定位，后改成 JS 过滤
3. 背景从模糊光球 → 星球 + 鼠标视差
4. 内容区太靠左 / 太暗 / 不能滚动 → 各修一轮 CSS
5. 文章太短 → 五篇技术文逐一扩写

每一轮我都只做一件事：跑 build，浏览器点一遍，把不对的描述反馈给 AI。不要一轮塞五个需求，否则 diff 巨大，你不知道哪里引入了回归。

我会给 AI 的上下文

在这个仓库里，我会主动 @ 这些文件：

• CLAUDE.md / 设计文档 — 项目约定
• gulpfile.js — 构建真相
• config.json — 内容来源
• 正在改的 .pug 和对应 .less

上下文越少，AI 越爱「按通用 React 项目」给方案。把真实文件喂进去，它会老实很多。

结论

用 AI 扩展这个站点，省的是重复劳动和样板时间，省不了决策、验收和边界把控。它像一个很快的初级同事：让它写列表页样式很合适；让它决定要不要上 Next.js 不合适。

把 AI 当结对程序员，不是当产品经理。

如果你也在用 Cursor 改自己的老项目，建议从「一个 gulp task、一个页面」开始，每步可验证，再慢慢叠功能。这个站点就是这么做出来的。