#002-三份文档，构建你的产品蓝图

—— intent.md、spec.md、plan.md 的设计哲学 + 博客 v0.1 实现

系列导读：这是《用一份 .md，把想法变成产品》系列的第2篇。在上一篇中，我们理解了文档驱动开发的核心理念。这一篇，我们将真正动手，用三份文档构建博客的第一个版本。

开篇：从混沌到秩序

还记得卡比（我们的卡皮巴拉主角）吗？在上一篇中，它经历了三次失败的尝试，最后发现了文档驱动开发的力量。

现在，卡比站在一个新的起点。它手里拿着一份初步的 intent.md，但问题来了：

只有 intent.md 够吗？ 不够。意图很清晰，但具体要做什么功能？用户如何使用？
要不要直接写技术方案？ 太早了。还没想清楚"做什么"，就开始想"怎么做"，容易南辕北辙。
需要写多少文档？ 写太少，指导不足；写太多，维护成本高。

这时候，文档驱动开发的经典答案浮现了：三份文档，不多不少，刚刚好。

今天，我们将深入理解这三份文档的设计哲学，并基于它们，让 AI 帮我们生成博客的第一个版本：v0.1 - 一个优雅的 Landing Page。

一、为什么是三份，不是一份或五份？

1. 认知负载理论：分层思考降低复杂度

人类的大脑有个特点：不擅长同时处理多层次的复杂信息。

当你试图在一份文档里同时回答"为什么做、做什么、怎么做"，你会发现：

写的时候思绪混乱，不知道该聚焦哪个层面
读的时候抓不住重点，从宏观愿景跳到具体代码细节
维护的时候牵一发动全身，改个技术细节可能影响整体意图

三份文档的设计，本质上是一种认知负载的分层管理：

文档层次	回答的问题	认知层级	变化频率
intent.md	为什么做？为谁做？	战略层	很少变化
spec.md	做什么？如何使用？	产品层	偶尔变化
plan.md	怎么做？用什么技术？	技术层	经常变化

类比：就像盖房子，你需要三份图纸：

设计理念（为什么要盖这栋房子？给谁住？）→ intent.md
户型图（有几个房间？布局如何？）→ spec.md
施工图（用什么材料？如何施工？）→ plan.md

如果把这三份图纸混在一起，建筑师会疯掉。

2. 职责分离：不同文档服务不同决策点

在产品开发的不同阶段，我们需要做不同的决策：

早期阶段（立项）：

决策问题："这个项目值得做吗？"
参考文档：intent.md
决策者：创始人、产品负责人

需求阶段（设计）：

决策问题："用户需要哪些功能？"
参考文档：spec.md
决策者：产品经理、设计师

开发阶段（实现）：

决策问题："用什么技术方案？"
参考文档：plan.md
决策者：技术负责人、开发者

三份文档，各司其职，不越界、不缺位。

3. 演化灵活性：上层稳定，下层可变

产品开发是一个动态过程，需求会变，技术会变，但核心价值不会轻易变。

三份文档的稳定性递减：

intent.md  (最稳定，几乎不变)
    ↓
spec.md    (中等稳定，小幅调整)
    ↓
plan.md    (最灵活，经常优化)

举个例子：卡比的博客项目，从 v0.1 到 v1.0：

intent.md：几乎没变（核心愿景始终是"简洁、优雅、可演化"）
spec.md：增加了功能（搜索、多作者、SEO），但核心用户旅程不变
plan.md：改了好几次（从纯静态到增量生成，从本地搜索到 Algolia）

这种"上层稳定、下层灵活"的架构，让项目能够应对变化，而不失去方向。

二、intent.md：意图层文档

什么是 intent.md？

intent.md 是项目的"宪法"，它定义了这个项目的核心价值和边界。

三个核心问题：

Why：为什么要做这个项目？（核心动机）
Who：为谁做？（目标用户）
Success：成功是什么样？（验收标准）

三个明确的"不"：

❌ 不写"做什么"（那是 spec.md 的职责）
❌ 不写"怎么做"（那是 plan.md 的职责）
❌ 不写具体任务（那是 tasks.md 或 issue 的职责）

博客项目的 intent.md（v1.0）

在第1篇中，我们已经看到了完整的 intent.md。这里提取关键部分：

# 个人技术博客 - 项目意图文档

## 项目愿景
构建一个简洁、优雅、易于维护的个人技术博客，用于分享技术见解和方法论实践。
这不仅是一个博客，更是**文档驱动开发方法论的实践案例**。

## 目标用户
### 主要用户：我自己（内容创作者）
- 需要专注写作的环境，没有复杂后台
- 希望内容完全掌控（Markdown 文件存储）
- 需要快速发布（推送到 Git 就自动部署）

### 次要用户：技术社区读者（内容消费者）
- 希望快速找到感兴趣的文章
- 期望良好的阅读体验
- 可能想要评论和互动（但不是核心需求）

## 核心问题
**为什么不用现成的平台？**
- Medium/掘金：内容不完全属于自己
- WordPress/Ghost：功能太重，维护成本高
- Hexo/Hugo：主题定制复杂

**我真正需要什么？**
1. 完全掌控（内容、设计、技术栈）
2. 简单维护（专注写作，不折腾后台）
3. 可持续演化（能逐步添加功能）
4. 方法论实践（证明文档驱动开发的有效性）

## 成功标准
### 功能标准
- ✅ 快速添加新文章（< 5分钟）
- ✅ 文章渲染美观（代码高亮、公式、图片优化）
- ✅ SEO 友好（sitemap、结构化数据）
- ✅ 可扩展架构（未来可添加评论、多作者等）

### 性能标准
- ⚡ 首屏加载 < 2秒
- ⚡ Lighthouse 分数 > 90

### 代码标准
- 📝 代码总量 < 5000 行
- 📝 测试覆盖率 > 80%
- 📝 所有功能都有完整文档支持

### 文档标准（关键！）
- 📄 每个版本都有对应的三份文档
- 📄 文档和代码同步演化
- 📄 任何人看文档就能理解设计决策

## 非目标
明确**不做什么**同样重要：
- ❌ 不做社交功能（关注、点赞、私信）
- ❌ 不做付费订阅
- ❌ 不做复杂后台管理
- ❌ 不追求功能全面（只做必需的）

这份文档的价值

防止需求蔓延：每次有人提新需求，对照"非目标"就知道该不该做。
统一团队认知：所有人看完 intent.md，对项目的理解就一致了。
指导 AI 协作：AI 理解了核心意图，就不会生成偏离方向的代码。
项目复盘依据：完成后回头看，是否达成了当初定下的"成功标准"？

三、spec.md：规范层文档

什么是 spec.md？

spec.md 是产品的"蓝图"，它定义了产品的功能、用户旅程和验收标准。

四个核心内容：

功能列表：产品有哪些功能？
用户旅程：用户如何使用这些功能？
验收标准：如何判断功能做对了？
非功能需求：性能、安全、可访问性等要求

三个明确的"不"：

❌ 不写技术实现（用 React 还是 Vue？不管！）
❌ 不写数据库设计（用 MySQL 还是 MongoDB？不管！）
❌ 不写 API 定义（RESTful 还是 GraphQL？不管！）

博客 v0.1 的 spec.md

v0.1 是博客的第一个版本，目标是实现一个优雅的 Landing Page。

# 博客规范文档 v0.1

## 版本说明
**版本**：v0.1  
**目标**：实现一个简洁优雅的 Landing Page，让访问者了解博客主题  
**发布日期**：2025-01-15

---

## 功能列表

### 1. 静态首页 (Landing Page)
**描述**：展示博客的核心信息和个人介绍。

**包含内容**：
- 个人头像或 Logo
- 个人介绍（一句话概括）
- 博客主题说明（2-3 句话）
- 社交媒体链接（GitHub、Twitter、Email）
- 简洁的导航栏（预留位置，v0.1 暂无功能）

**不包含**：
- ❌ 文章列表（v0.2 再加）
- ❌ 搜索框（v0.5 再加）
- ❌ 评论系统（v0.5 再加）

---

## 用户旅程

### 旅程 1：首次访问者了解博客
**场景**：一个技术人员通过搜索引擎或社交媒体链接进入博客。

**步骤**：
1. 访问者进入首页
2. 看到清晰的个人介绍（"卡比，一只会写代码的水豚"）
3. 了解博客主题（"分享文档驱动开发和技术实践"）
4. 点击社交媒体图标，访问 GitHub 查看开源项目
5. （可选）记住博客网址，下次再来

**期望结果**：
- 访问者用 10 秒内了解博客的核心价值
- 访问者知道如何联系作者
- 访问者对博客产生好感，可能会收藏

---

## 验收标准

### 功能验收
- [ ] ✅ 首页能在所有主流浏览器正常显示（Chrome、Firefox、Safari、Edge）
- [ ] ✅ 响应式设计，移动端适配良好（iPhone、Android）
- [ ] ✅ 社交媒体链接可点击，跳转正确
- [ ] ✅ 导航栏存在但暂时无功能（占位）

### 性能验收
- [ ] ⚡ 页面加载时间 < 1秒（测试环境：4G 网络）
- [ ] ⚡ Lighthouse Performance 分数 > 95
- [ ] ⚡ 首次内容绘制（FCP）< 0.5秒

### 设计验收
- [ ] 🎨 整体风格简洁、现代
- [ ] 🎨 配色舒适，不刺眼
- [ ] 🎨 字体清晰易读（中英文混排）
- [ ] 🎨 间距合理，不拥挤

### SEO 验收
- [ ] 🔍 HTML 标题（`<title>`）正确设置
- [ ] 🔍 Meta Description 存在且描述准确
- [ ] 🔍 Open Graph 标签设置（分享到社交媒体时显示正确）

---

## 非功能需求

### 可访问性（a11y）
- 符合 WCAG 2.1 AA 标准
- 所有图片有 alt 文本
- 色彩对比度 ≥ 4.5:1
- 键盘可导航

### 浏览器兼容性
- 支持 Chrome/Edge（最新两个版本）
- 支持 Firefox（最新两个版本）
- 支持 Safari（最新两个版本）
- 移动端浏览器（iOS Safari、Chrome Android）

### 性能要求
- 页面大小 < 200KB（未压缩）
- 图片自动优化（WebP 格式，懒加载）
- 无第三方追踪脚本（尊重用户隐私）

---

## 未来扩展点（v0.2+）
以下功能在 v0.1 **不实现**，但架构上要为它们留好空间：
- 文章列表（v0.2）
- 文章详情页（v0.2）
- 分类和标签（v0.3）
- 搜索功能（v0.5）
- 评论系统（v0.5）
- 多作者支持（v0.8）

这份文档的价值

功能边界清晰：明确 v0.1 只做 Landing Page，不贪多。
验收标准明确：开发完成后，对照 checklist 逐项验收。
AI 理解友好：提供给 AI 时，它能精确知道要生成什么。
未来可扩展：预留了扩展点，为后续版本铺路。

四、plan.md：方案层文档

什么是 plan.md？

plan.md 是项目的"施工图"，它定义了技术实现的具体方案。

五个核心内容：

技术栈：用什么框架、库、工具？
系统架构：整体结构如何设计？
数据模型：数据如何组织？（如果有）
接口设计：API 如何定义？（如果有）
部署方案：如何上线和维护？

这份文档，AI 最爱看！

博客 v0.1 的 plan.md

# 博客技术方案 v0.1

## 版本说明
**版本**：v0.1  
**对应功能**：Landing Page  
**技术决策依据**：intent.md（简洁、可演化）+ spec.md（静态首页）

---

## 技术栈

### 核心框架
- **Next.js 14**（App Router）
  - 选择理由：SSG 支持，性能优秀，生态成熟
  - 版本：14.x（使用 App Router，为未来扩展做准备）

### 样式方案
- **Tailwind CSS 3.x**
  - 选择理由：实用优先，快速开发，体积小
  - 配置：自定义主题色、字体、间距

### 开发工具
- **TypeScript**：类型安全，减少 bug
- **ESLint + Prettier**：代码规范和格式化
- **Husky**：Git hooks，提交前自动检查

### 部署平台
- **Vercel**（推荐）或 **Netlify**
  - 选择理由：零配置部署，自动 CI/CD，免费额度够用

---

## 系统架构

### 架构图

┌─────────────────────────────────────┐
│         Landing Page (v0.1)         │
├─────────────────────────────────────┤
│  app/                               │
│   └── page.tsx       (首页组件)     │
│  components/                        │
│   ├── Header.tsx     (头部)         │
│   ├── Hero.tsx       (主区域)       │
│   └── Footer.tsx     (页脚)         │
│  public/                            │
│   └── images/        (静态资源)     │
│  styles/                            │
│   └── globals.css    (全局样式)     │
└─────────────────────────────────────┘

文件结构

blog-v0.1/
├── .next/              # Next.js 构建产物（忽略）
├── app/
│   ├── layout.tsx      # 根布局
│   ├── page.tsx        # 首页
│   └── globals.css     # 全局样式
├── components/
│   ├── Header.tsx      # 头部组件
│   ├── Hero.tsx        # 主区域组件
│   └── Footer.tsx      # 页脚组件
├── public/
│   ├── avatar.png      # 头像（占位）
│   └── favicon.ico     # 网站图标
├── docs/               # 文档目录
│   ├── intent.md
│   ├── spec.md
│   └── plan.md
├── .gitignore
├── package.json
├── tsconfig.json
├── tailwind.config.js
└── next.config.js

组件设计

1. Header 组件

职责：展示导航栏（v0.1 仅占位） Props：无样式：

固定高度 64px
半透明背景
居中布局

示例：

export function Header() {
  return (
    <header className="h-16 bg-white/80 backdrop-blur-sm border-b">
      <nav className="container mx-auto px-4 h-full flex items-center justify-between">
        <div className="text-xl font-bold">卡比的博客</div>
        {/* v0.1 暂无导航链接 */}
      </nav>
    </header>
  )
}

2. Hero 组件

职责：展示主要内容（个人介绍、社交链接） Props：无（v0.1 数据硬编码） 包含元素：

头像（圆形，128x128）
标题（h1）："卡比，一只会写代码的水豚"
简介（p）："专注于文档驱动开发和技术实践分享"
社交链接（3个图标）：GitHub、Twitter、Email 布局：垂直居中，最小高度 calc(100vh - 128px)

职责：展示版权信息样式：固定高度 64px，灰色背景

样式系统

Tailwind 配置

// tailwind.config.js
module.exports = {
  content: ['./app/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: '#3B82F6',    // 蓝色
        secondary: '#8B5CF6',  // 紫色
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
  plugins: [],
}

设计 Token

Token	值	说明
主色	`#3B82F6`	链接、按钮
文字色	`#1F2937`	正文
背景色	`#FFFFFF`	页面背景
边框色	`#E5E7EB`	分割线

性能优化

图片优化

使用 Next.js <Image> 组件
自动生成 WebP 格式
懒加载（默认行为）

字体优化

使用 next/font 优化 Google Fonts 加载
预加载关键字体

代码分割

Next.js 自动按路由分割
v0.1 只有一个页面，无需额外配置

部署方案

Vercel 部署（推荐）

连接 GitHub 仓库
自动检测 Next.js 项目
每次推送到 main 分支自动部署
预览分支：每个 PR 自动生成预览 URL

环境变量（v0.1 暂无）

未来版本可能需要：

NEXT_PUBLIC_SITE_URL：网站 URL
NEXT_PUBLIC_GA_ID：Google Analytics ID

开发流程

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问 http://localhost:3000

代码规范

提交前自动运行 ESLint 和 Prettier
使用 Husky pre-commit hook

Git 工作流

main (生产分支)
 └── develop (开发分支)
      └── feature/v0.1-landing-page

测试策略（v0.1 简化）

手动测试

在 Chrome、Firefox、Safari 测试
在 iPhone、Android 测试
检查所有链接可点击

性能测试

运行 Lighthouse（目标 > 95）
检查页面大小（目标 < 200KB）

自动化测试（v0.2+ 再加）

v0.1 暂不引入 Jest/Playwright

最后更新：2025-01-15
负责人：卡比（Capybara Dev）

这份文档的价值

技术决策有据可依：为什么选 Next.js？为什么用 Tailwind？文档里写得清清楚楚。
AI 生成代码精准：提供给 AI 后，它能生成完全符合架构的代码。
团队协作无障碍：新人看 plan.md，15 分钟就能理解技术方案。
未来重构有参考：如果要迁移技术栈，对照 plan.md 就知道改哪些地方。

五、三份文档的协作关系

现在我们有了三份文档，它们如何协作？

流程图

graph TB
    A[开始: 有个想法] --> B[写 intent.md<br/>为什么做?为谁做?]
    B --> C{意图清晰?}
    C -->|不清晰| B
    C -->|清晰| D[写 spec.md<br/>做什么?如何使用?]
    D --> E{功能合理?}
    E -->|不合理| D
    E -->|合理| F[写 plan.md<br/>怎么做?用什么技术?]
    F --> G{方案可行?}
    G -->|不可行| F
    G -->|可行| H[AI 生成代码]
    H --> I[代码评审]
    I --> J{符合预期?}
    J -->|不符合| K[回溯到对应文档]
    K --> L{问题在哪层?}
    L -->|意图| B
    L -->|功能| D
    L -->|技术| F
    J -->|符合| M[提交并部署]
    M --> N[文档归档<br/>版本标记]

反馈循环

关键原则：当代码出问题时，不要直接改代码，先回溯到文档。

案例：假设 AI 生成的首页样式过于简陋。

错误做法：

直接改代码 → 改完了 → 下次迭代 AI 又生成简陋的样式（因为文档没改）

正确做法：

发现问题 → 回溯到 spec.md（是验收标准不够明确？）
         → 更新 spec.md："页面需要有视觉层次，使用阴影和渐变增加深度感"
         → 更新 plan.md："使用 Tailwind 的 shadow-lg 和 bg-gradient-to-br"
         → 重新让 AI 生成代码
         → 这次符合预期了

版本同步

# 文档和代码一起提交
git add docs/spec.md docs/plan.md app/page.tsx
git commit -m "feat: implement landing page (v0.1)

- Updated spec.md with v0.1 requirements
- Updated plan.md with Next.js architecture
- Implemented Hero component with social links"

六、实现博客 v0.1

理论讲完了，开始真正动手！

步骤 1：初始化项目

# 使用 create-next-app 创建项目
npx create-next-app@latest blog-v0.1 --typescript --tailwind --app

# 进入项目目录
cd blog-v0.1

# 创建文档目录
mkdir docs

步骤 2：编写三份文档

将前面的 intent.md、spec.md、plan.md 保存到 docs/ 目录。

步骤 3：让 AI 生成代码

Prompt 模板：

我正在开发一个个人博客项目，现在要实现 v0.1 版本（Landing Page）。

我已经准备好了三份文档：

【intent.md】
[粘贴 intent.md 的关键内容]

【spec.md】
[粘贴 spec.md 的完整内容]

【plan.md】
[粘贴 plan.md 的完整内容]

请基于这三份文档，生成以下文件：

1. app/page.tsx - 首页组件
2. components/Header.tsx - 头部组件
3. components/Hero.tsx - 主区域组件
4. components/Footer.tsx - 页脚组件
5. app/globals.css - 全局样式（只保留必要的重置样式）
6. tailwind.config.js - Tailwind 配置

要求：
- 严格按照 spec.md 的功能需求实现
- 严格按照 plan.md 的技术方案实现
- 代码要简洁、可读、符合 Next.js 14 App Router 规范
- 使用 TypeScript
- 样式使用 Tailwind CSS，不写自定义 CSS
- 包含必要的注释

步骤 4：核心代码展示

package.json（关键依赖）：

{
  "name": "blog-v0.1",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "14.0.4",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "eslint": "^8",
    "eslint-config-next": "14.0.4",
    "postcss": "^8",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

tailwind.config.js：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: '#3B82F6',
        secondary: '#8B5CF6',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
}

app/layout.tsx（根布局）：

import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: '卡比的博客 | 文档驱动开发实践',
  description: '一只会写代码的水豚，专注于文档驱动开发和技术实践分享',
  openGraph: {
    title: '卡比的博客',
    description: '文档驱动开发实践案例',
    type: 'website',
  },
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh-CN">
      <body className={inter.className}>{children}</body>
    </html>
  )
}

app/page.tsx（首页）：

import { Header } from '@/components/Header'
import { Hero } from '@/components/Hero'
import { Footer } from '@/components/Footer'

export default function Home() {
  return (
    <div className="min-h-screen flex flex-col">
      <Header />
      <main className="flex-1">
        <Hero />
      </main>
      <Footer />
    </div>
  )
}

components/Header.tsx：

export function Header() {
  return (
    <header className="h-16 bg-white/80 backdrop-blur-sm border-b border-gray-200 sticky top-0 z-10">
      <nav className="container mx-auto px-4 h-full flex items-center justify-between max-w-4xl">
        <div className="text-xl font-bold text-gray-900">
          🦫 卡比的博客
        </div>
        {/* v0.1: 导航占位，未来版本添加链接 */}
        <div className="text-sm text-gray-500">
          v0.1
        </div>
      </nav>
    </header>
  )
}

components/Hero.tsx：

import Image from 'next/image'
import { Github, Twitter, Mail } from 'lucide-react'

export function Hero() {
  return (
    <section className="min-h-[calc(100vh-8rem)] flex items-center justify-center px-4">
      <div className="max-w-2xl text-center">
        {/* 头像 */}
        <div className="mb-8 flex justify-center">
          <div className="relative w-32 h-32 rounded-full overflow-hidden border-4 border-primary/20">
            <Image
              src="/avatar.png"
              alt="卡比的头像"
              width={128}
              height={128}
              className="object-cover"
              priority
            />
          </div>
        </div>

        {/* 标题 */}
        <h1 className="text-4xl md:text-5xl font-bold text-gray-900 mb-4">
          卡比，一只会写代码的水豚 🦫
        </h1>

        {/* 简介 */}
        <p className="text-lg md:text-xl text-gray-600 mb-8 leading-relaxed">
          专注于<span className="text-primary font-semibold">文档驱动开发</span>和技术实践分享
          <br />
          用 .md 文件管理整个产品生命周期
        </p>

        {/* 社交链接 */}
        <div className="flex justify-center gap-6">
          <a
            href="https://github.com/capybara-dev"
            target="_blank"
            rel="noopener noreferrer"
            className="p-3 rounded-full bg-gray-100 hover:bg-gray-200 transition-colors"
            aria-label="GitHub"
          >
            <Github className="w-6 h-6 text-gray-700" />
          </a>
          <a
            href="https://twitter.com/capybara-dev"
            target="_blank"
            rel="noopener noreferrer"
            className="p-3 rounded-full bg-gray-100 hover:bg-gray-200 transition-colors"
            aria-label="Twitter"
          >
            <Twitter className="w-6 h-6 text-gray-700" />
          </a>
          <a
            href="mailto:capybara@example.com"
            className="p-3 rounded-full bg-gray-100 hover:bg-gray-200 transition-colors"
            aria-label="Email"
          >
            <Mail className="w-6 h-6 text-gray-700" />
          </a>
        </div>

        {/* 下一步提示 */}
        <div className="mt-12 text-sm text-gray-500">
          📄 文章列表即将到来（v0.2）
        </div>
      </div>
    </section>
  )
}

components/Footer.tsx：

export function Footer() {
  return (
    <footer className="h-16 bg-gray-50 border-t border-gray-200">
      <div className="container mx-auto px-4 h-full flex items-center justify-center max-w-4xl">
        <p className="text-sm text-gray-600">
          © 2025 卡比的博客. Built with{' '}
          <span className="text-primary">Next.js</span> and{' '}
          <span className="text-secondary">文档驱动开发</span>
        </p>
      </div>
    </footer>
  )
}

步骤 5：本地运行

npm run dev

访问 http://localhost:3000，你会看到一个优雅的 Landing Page！

七、运行效果展示

实际效果

桌面端：

✅ 垂直居中的个人介绍
✅ 清晰的博客主题说明
✅ 可点击的社交媒体图标
✅ 简洁的头部和页脚

移动端：

✅ 响应式布局，自动适配
✅ 字体大小合理，易读
✅ 触摸友好的图标按钮

性能测试

运行 Lighthouse 测试：

npm run build
npm run start
# 在 Chrome DevTools 中运行 Lighthouse

结果：

Performance: 98 ✅
Accessibility: 100 ✅
Best Practices: 100 ✅
SEO: 100 ✅

页面大小：约 120KB（含图片），低于 200KB 目标 ✅

验收清单

对照 spec.md 的验收标准：

✅ 首页在所有主流浏览器正常显示
✅ 响应式设计，移动端适配良好
✅ 社交媒体链接可点击，跳转正确
✅ 导航栏存在但暂时无功能（占位）
⚡ 页面加载时间 < 1秒
⚡ Lighthouse Performance 分数 > 95
🎨 整体风格简洁、现代
🔍 SEO 标签设置正确

所有验收标准都通过了！ 🎉

结语：第一个版本的意义

恭喜！我们完成了博客的第一个版本 v0.1。

这个版本看起来很简单，只是一个 Landing Page。但它的意义远不止于此：

1. 建立了完整的文档体系

intent.md：定义了项目的核心价值
spec.md：明确了功能边界和验收标准
plan.md：制定了技术方案和架构

这三份文档，将成为后续所有版本的基石。

2. 验证了文档驱动的有效性

AI 基于文档生成的代码，完全符合预期
没有返工，没有方向偏移
从文档到代码，一次通过

这证明了：文档驱动不是理论，而是真正可行的方法。

3. 为演化预留了空间

架构清晰，组件职责明确
未来添加文章列表、详情页，只需扩展，不需重构
文档记录了所有决策，未来不会迷失方向

这个 v0.1，不是终点，而是可控演化的起点。

📌 核心要点

🏛️ 三份文档，各司其职 - intent（为什么）、spec（做什么）、plan（怎么做）
🧠 分层思考，降低认知负载 - 不要试图在一份文档里解决所有问题
📋 验收标准前置 - spec.md 中的 checklist 是开发的指南针
🤖 AI 最爱 plan.md - 提供清晰的技术方案，AI 能生成精准的代码
🔄 文档和代码同步演化 - 每次提交，文档和代码一起更新

📖 下篇预告

第3篇：让 AI 成为你的文档执行者 —— 从 Vibe-coding 到 Spec-coding + 博客 v0.2 演化

现在我们有了 v0.1，但如何让它演化到 v0.2（添加 Markdown 文章渲染）？我们将学习：

如何更新文档以支持新功能
如何设计 Prompt 让 AI 精确理解需求
如何处理 AI 生成代码时的常见陷阱
真正实现博客 v0.2：从文件系统读取 Markdown，渲染成美观的文章页

你将看到：文档驱动的演化是如何一步步发生的。

🗺️ 系列导航

为什么我们需要文档驱动开发？
三份文档，构建你的产品蓝图 + 博客 v0.1（当前）
让 AI 成为你的文档执行者 + 博客 v0.2
从 v0.2 到 v0.4 的完整演化
文档的生命周期管理 + 博客 v0.5
规模化实践 + 博客 v0.8
反思与边界：什么时候该用，什么时候不该用
开始你的文档驱动之旅 + 博客 v1.0 完整交付

下一篇，我们将让这个博客真正"活"起来！ 🚀