提示词包 · 个人品牌站实战

📎 使用方式：把这份文档放在浏览器的另一个标签页，跟着 新手教程 做时，直接从这里复制提示词粘贴到你的 AI 编程工具。

📌 占位符约定：本文所有 <xxx> 尖括号内容都是占位符，粘贴前请替换成你自己的值。常见占位符：

占位符 替换为
<你的名字> 你自己的名字（例：李雷）
<YOUR_USERNAME> 你的 GitHub 用户名
<change-name> 具体的 change 名字（例：add-hero-section）
<原change名> 你想撤销的那个 change 的名字

⚠️ 每次 apply 前先 git commit——留个回滚点，比什么救援手段都有效。

目录

第 3 章 · Hello World 闭环

前置：假设你已经在工作目录（例如 ~/openspec-tutorial）里，并且这一步开始前没打开 Claude Code。

Step 1 · 建 React 脚手架（Claude Code 里粘贴）

先在终端 claude 打开 Claude Code，然后粘贴：

帮我创建一个 React + Vite + TypeScript 的项目，项目名叫 hello-app。
创建完成后启动 npm run dev，告诉我访问地址。
不要额外装样式框架，用最基础的即可。

Step 2 · 退出 Claude Code，终端执行

/exit 退出 Claude Code，然后：

cd hello-app
openspec init          # 用空格选中 Claude Code，回车
claude                 # 重新打开 Claude Code

Step 3 · Propose

propose 一个 change，名字叫 add-hello-message。

需求：在首页显示一行大字 "Hello, I am <你的名字>"。
样式简单即可，居中显示，字号大一点。

不做：不需要样式框架、不需要动画、不需要图片。

Step 4 · Apply

apply add-hello-message

Step 5 · Archive

archive add-hello-message

从 Hello World 过渡到品牌站

Hello World 跑通后，做以下动作把工作区切回上一层，重新开一个 Claude Code 会话再进入 Phase 1：

# 在 Claude Code 里
/exit

# 在终端里
cd ..                    # 从 hello-app 退回上一级
claude                   # 重新打开 Claude Code

Phase 1 会在这一级目录里新建 my-portfolio/，与 hello-app/ 平级。

Phase 1 · 项目初始化

1.1 · 建脚手架（Claude Code 里）

帮我在当前目录创建一个 React + Vite + TypeScript 项目，
项目名叫 my-portfolio。

安装并配置 Tailwind CSS V4（最新版）。

确保项目可以正常启动：
- 通过 npm run dev 启动
- 如果 5173 端口被占，改成 3000
- 启动后告诉我访问地址

1.2 · 退出 Claude Code，终端执行

cd my-portfolio
openspec init          # 选 Claude Code，按空格 + 回车
claude                 # 重新打开

Phase 2 · Hero 英雄区

2.1 · Propose

propose 一个 change，名字叫 add-hero-section。

需求：
在首页最上方添加一个 Hero 英雄区，占满一屏（100vh），包含：
- 左半边：头像图片（先用占位符 https://placehold.co/400x400）
- 右半边：
  * 大标题："你好，我是 <你的名字>"
  * 副标题："一名前端工程师 / AI 编程爱好者"
  * 一句话简介："热爱把想法变成产品"
  * 一个圆角按钮："查看我的项目"，点击滚动到项目区

布局：
- 桌面端左右并排，移动端上下堆叠
- 使用 Tailwind flex + responsive 类
- 背景使用浅色渐变

技术要求：
- 组件文件放在 src/components/HeroSection.tsx
- 在 src/App.tsx 中引入

不做：
- 不做动画效果（下期加）
- 不做深色模式切换
- 不添加实际的项目图片，用占位符即可

2.2 · Apply

apply add-hero-section

2.3 · Verify（可选，复杂 change 建议跑）

不放心 apply 结果是否匹配 spec？跑一次 verify：

verify add-hero-section

细节参考救援 3 · Verify 三维检查。

2.4 · Archive

archive add-hero-section

Phase 3 · 顶部导航栏

3.1 · Propose

propose 一个 change，名字叫 add-navbar。

需求：
在页面顶部添加吸顶导航栏（sticky top-0）：
- 左侧：Logo 显示我的名字"<你的名字>"
- 右侧：4 个锚点链接：首页 / 项目 / 关于 / 联系
- 点击链接平滑滚动到对应区域（各区域用 id 标记）

样式：
- 白色半透明背景（bg-white/80 backdrop-blur）
- 底部一条细线（border-b）
- 桌面端水平排列，移动端折叠为汉堡菜单

技术要求：
- 组件文件放在 src/components/Navbar.tsx
- 在 App.tsx 顶部引入
- 给现有的 Hero 区块加 id="home"
- 其他 3 个区块（projects / about / contact）目前还不存在，本次**不要**创建空占位 div；
  后续 Phase 4/5 添加对应区块时会同步补上 id
- 导航栏 4 个锚点链接的 href 全部先写好（#home / #projects / #about / #contact），
  点击暂时跳不到的锚点是正常现象

不做：
- 不做多语言切换
- 不做深色模式
- 不为不存在的区块创建占位符 div
- 移动端汉堡菜单可以先做一个静态图标，展开逻辑后期再做

3.2 · Apply

apply add-navbar

3.3 · Verify（可选）

verify add-navbar

细节参考救援 3 · Verify 三维检查。

3.4 · Archive

archive add-navbar

Phase 4 · 项目展示区

4.1 · Propose

propose 一个 change，名字叫 add-projects-section。

需求：
在 Hero 区下方添加"项目展示"区块（id="projects"）：

区块结构：
- 区块顶部大标题："我的项目"
- 副标题："这里展示我最近做的一些东西"
- 下方是项目卡片网格

数据来源：
- 项目数据先写死在 src/data/projects.ts 里，定义一个数组
- 数组元素结构：{ id, name, description, image, tags: string[], link }
- 请你先造 6 条示例数据（假项目名假描述都可以，用占位图 https://placehold.co/600x400）

卡片样式：
- 桌面端 3 列，平板 2 列，移动端 1 列
- 卡片有圆角、阴影、悬停放大效果
- 卡片包含：图 / 项目名 / 描述 / 标签（tag 用小圆角胶囊样式）/ 查看详情按钮

技术要求:
- 卡片组件放在 src/components/ProjectCard.tsx
- 项目区容器组件放在 src/components/ProjectsSection.tsx
- 数据文件放在 src/data/projects.ts

不做:
- 不做筛选功能（按标签过滤等）
- 不做搜索功能
- 不接后端，纯静态数据

4.2 · Apply

apply add-projects-section

4.3 · Verify（推荐，本 Phase 涉及多文件）

verify add-projects-section

细节参考救援 3 · Verify 三维检查。

4.4 · Archive

archive add-projects-section

Phase 5 · 关于我 + 联系方式

5.1 · Propose

propose 一个 change，名字叫 add-about-and-contact。

需求 1 · 关于我（id="about"）：
- 大标题："关于我"
- 一段 2 – 3 行的自我介绍（用占位文案，我后期改）
- 下方技能标签区：展示 8 个技能（React / TypeScript / Node.js / Tailwind CSS / Git / Figma / Python / AI 编程）

需求 2 · 联系方式（id="contact"）：
- 大标题："联系我"
- 3 个圆形图标按钮（可用 emoji 代替）：
  * 邮箱 ✉️（mailto: 链接）
  * GitHub 🐙（GitHub 链接）
  * X（原 Twitter）✖️（X 主页链接）
- 链接目标先用 # 占位，我后期改

技术要求：
- 分成 AboutSection.tsx 和 ContactSection.tsx 两个组件
- 都在 App.tsx 里引入
- 保持整体色调一致

不做：
- 不做联系表单
- 不做真实的社交平台 API 集成

5.2 · Apply

apply add-about-and-contact

5.3 · Verify（可选）

verify add-about-and-contact

细节参考救援 3 · Verify 三维检查。

5.4 · Archive

archive add-about-and-contact

Phase 6 · 部署到 GitHub Pages

6.1 · Propose 部署配置

propose 一个 change，名字叫 setup-github-pages。

需求：
配置项目以便通过 GitHub Actions 部署到 GitHub Pages（不使用 gh-pages 本地脚本）。

具体做什么：
1. 修改 vite.config.ts，设置 base 为 "/my-portfolio/"
   （因为部署后的路径是 https://<username>.github.io/my-portfolio/）
2. 确保 package.json 中已有 "build" script（内容为 "tsc && vite build"），
   如果没有就补上。
3. 创建 .github/workflows/deploy.yml：
   - 触发条件：push 到 main 分支
   - 步骤：checkout → setup-node@v4 → npm ci → npm run build → 上传 dist 为 Pages artifact → deploy-pages
   - 使用官方 actions/upload-pages-artifact 和 actions/deploy-pages
   - 权限声明 pages: write, id-token: write

不做：
- 不安装 gh-pages 依赖（本次统一走 Actions）
- 不在 package.json 加 "deploy" script
- 不做自定义域名配置
- 不做多环境部署

6.2 · Apply

apply setup-github-pages

6.3 · Verify（强烈推荐，配置错了部署会挂）

verify setup-github-pages

细节参考救援 3 · Verify 三维检查。重点确认：

6.4 · Archive

archive setup-github-pages

6.5 · 终端里推到 GitHub（OpenSpec 帮不了这步）

git init
git add .
git commit -m "initial commit: my portfolio with openspec"

# 去 https://github.com/new 建一个新仓库，名字叫 my-portfolio
git remote add origin https://github.com/<YOUR_USERNAME>/my-portfolio.git
git branch -M main
git push -u origin main

6.6 · GitHub 网页操作

  1. 打开你的仓库页面
  2. 点 Settings → 左侧 Pages
  3. Source 选 GitHub Actions（不要选 Deploy from a branch）
  4. 保存
  5. 等 2 – 3 分钟，访问 https://<YOUR_USERNAME>.github.io/my-portfolio/

常用救援提示词

救援 1 · AI 一口气改了太多，想撤回

⚠️ 警告：git checkout . 会把所有未提交的改动全部炸掉——包括跟本次 change 无关的、你手动改的其他文件。如果你今天在多个地方都改了东西，用下面的 git stash -u 方案更安全。

方案 A · 只想留个“以防万一”的备份，还没决定要不要保留改动

git status               # 先看看到底改了哪些文件
git stash -u             # 把所有未提交改动（含未跟踪文件）暂存起来
rm -rf openspec/changes/<change-name>/    # 删掉活跃变更目录
# 之后想恢复：git stash pop；确定不要了：git stash drop

方案 B · 确定要全部丢弃（危险，看清楚再执行）

git status               # 确认改动列表中没有你想保留的文件
git checkout .           # ⚠️ 撤回所有未提交改动，不可逆
rm -rf openspec/changes/<change-name>/    # 删掉活跃变更目录

核心心法：每次 apply 前先 git commit，就能永远退回到干净状态，也不用纠结用 stash 还是 checkout。

如果已经 push：propose 一个反向 change

propose 一个 change，名字叫 revert-<原change名>。

需求：撤销 <原 change 名> 引入的所有变更。

具体做什么:
- 删除 <文件路径 1>
- 删除 <文件路径 2>
- 从 App.tsx 中移除对应 import 语句
- 恢复代码到 <原 change 名> 之前的状态

Out of Scope:
- 不动其他任何 change 涉及的代码

救援 2 · 想让 AI 严格只改指定文件

在 propose 里加**技术要求（严格约束）**这一段：

技术要求（严格约束）：
- 只允许修改 src/components/<某组件>.tsx
- 只允许新建 src/data/<某文件>.ts
- 严禁修改 src/App.tsx（我会自己加引入）
- 严禁修改任何配置文件（vite.config / package.json / tsconfig 等）
- 严禁引入 change 描述之外的新 npm 包

⚠️ 注意：本教程 Phase 2 – 5 的 propose 都明确要求“在 App.tsx 中引入”。如果你把这份严格约束追加到那些 phase 的 propose 上，“严禁修改 src/App.tsx”这一条会和主 propose 冲突——AI 要么忽略约束改了 App.tsx，要么真的不改导致组件没被引入。

处理方式二选一：

  1. 从严格约束里删除“严禁修改 src/App.tsx”这一行；或
  2. 保留严禁，同时在主 propose 里把“在 App.tsx 中引入”改成“生成一段 import + JSX 片段贴到聊天中，我手动加进 App.tsx”。

救援 3 · Verify 三维检查

在 archive 之前跑一次，防止代码和 spec 不一致：

verify <change-name>

请从三个维度检查：

1. 正确性 (Correctness)
   - 对照 openspec/changes/<name>/spec.md 里每个 Scenario
   - 检查代码是否实现了对应行为
   - 用 [PASS] / [FAIL] 标注每一条

2. 完整性 (Completeness)
   - 代码里是否有 spec 没提及的额外功能
   - 列出这些"多余功能"
   - 建议是否应该加进 spec 或删除

3. 一致性 (Consistency)
   - 变量名、组件名是否和 spec 一致
   - API 签名（参数类型、返回值）是否匹配
   - 数据结构是否和 spec 定义一致

输出格式：三个维度分别一段，最后一行给出总体判断（PASS / NEEDS FIX）

看到问题后修：

根据刚才的 verify 报告，请修正代码使其与 spec 完全一致。
只改代码，不要改 spec。

救援 4 · Explore 决策型（不确定方案时用）

explore <topic>

我想给网站加 <某功能>。请对比 <N> 个方案:

方案 A: <描述>
方案 B: <描述>
方案 C: <描述>

对比维度:
1. 实现复杂度（1-5 分）
2. 后期扩展性
3. 与我当前 Tailwind V4 的兼容度

给我明确推荐并说明理由。不落盘,只对话。

救援 5 · Think 保留中间态（复杂 change 分多天做）

think <change-name>

今天的进度：
- Phase 1 完成: <描述>
- Phase 2 完成: <描述>
- 待办: Phase 3 (<描述>) 明天做

请同步中间态到 openspec/changes/<name>/spec.md,
但不要归档到 specs/。
明天我会继续 apply 完成剩余部分。

一次完整跑通的命令序列

注意：这一节是“实战冲刺路径”，跳过第 3 章 Hello World（Hello World 是教学练手，不影响品牌站产出）。如果你完全没跑过 OpenSpec，建议先跑一次 Hello World 再来这里。

按顺序执行（verify 步骤全部当作可选，赶时间可跳过）：

（终端）mkdir ~/openspec-tutorial && cd ~/openspec-tutorial
（终端）claude

（Claude）Phase 1.1 建脚手架提示词
（Claude）/exit
（终端）cd my-portfolio
（终端）openspec init  → 选 Claude Code
（终端）claude

（Claude）Phase 2.1 propose → 2.2 apply → 2.3 verify（可选）→ 2.4 archive
（Claude）Phase 3.1 propose → 3.2 apply → 3.3 verify（可选）→ 3.4 archive
（Claude）Phase 4.1 propose → 4.2 apply → 4.3 verify（推荐）→ 4.4 archive
（Claude）Phase 5.1 propose → 5.2 apply → 5.3 verify（可选）→ 5.4 archive
（Claude）Phase 6.1 propose → 6.2 apply → 6.3 verify（强烈推荐）→ 6.4 archive

（终端）Phase 6.5 git 命令序列
（浏览器）Phase 6.6 GitHub Pages 配置
（浏览器）访问 https://<YOUR_USERNAME>.github.io/my-portfolio/

预计总耗时：2 – 3 小时（AI 生成快慢有波动）。

配套文档：

← 返回 AI 编程