提示词工程场景实战：写测试、Code Review、重构与中文技术文

完全指南 讲原则；这篇讲 怎么开口。
四个场景都来自本站真实工作流（VitePress 博客 + Playwright + 中文技术写作），模板可整段复制后改路径与验收条件。

和 Claude Code 配合时，可先对照 常见工作流；若任务已固定成项目流程，再考虑落成 Skill。

---

共用骨架（先记住这五块）

无论场景，好提示词通常具备：

块	作用
角色	限制语气与默认假设
目标	一句话说清「交付物是什么」
约束	别碰的目录、风格、兼容性
材料	文件路径、报错、现有测试、范例文
验收	怎样算做完（可观察、可复跑）

材料不够时，先让模型 只读不改，再动手：

先只读以下路径并总结现状，不要改文件：
- docs/.vitepress/theme/
- tests/e2e/content.spec.ts
读完用 5 条 bullet 说明：入口在哪、列表数据从哪来、测试在守什么。

---

场景 1：写 E2E / 组件测试

什么时候用

• 刚加了功能（标签页、文末导航、元信息）
• 修过 flaky，想锁回归
• 不想手点一遍确认列表是否漏文

模板

你是熟悉 Playwright 的前端工程师。请为「标签页可点击 chip」补 E2E。

目标：
- 浏览器里验证：首页 post 的 .tag 可点，跳到 /tags#某标签 或可见对应分组
- 不验证实现细节（class 名可改），优先 getByRole / 可见文案

约束：
- 测试跑在 dev server（见 playwright.config.ts 的 webServer）
- 禁止 npm run docs:build（会清空线上 dist）
- 不要用 allTextContents() 在未 wait 的情况下断言列表（本站踩过坑）
- 参考 tests/e2e/content.spec.ts 的写法

材料：
- docs/tags.md
- docs/.vitepress/theme/PostList.vue
- tests/e2e/content.spec.ts

验收：
1. 新增或修改的 spec 在 chromium 下通过
2. 至少覆盖：桌面可见 chip；若有移动端差异用 test.skip(!!isMobile) 写清楚
3. 在回复里贴：改了哪些文件、怎么跑、预期断言一句人话

常见翻车

现象	原因
断言过了但什么都没验	只检查「元素存在」，没检查 跳转/文案/数量
列表偶发 0 条	没先 expect(locator).toHaveCount(...) 再读文本
本地绿、线上红	测了只在 dist 才有的东西却走 dev server

本站更完整的测试叙事见 给博客加自动化测试。

---

场景 2：Code Review（读 diff / 读文件）

什么时候用

• 自己改完想找回归风险
• 审别人的 PR（贴 diff 或文件列表）
• 不信任「看起来能跑」

模板

你是严格的代码审查员。只做审查，不直接改代码，除非我明确说「按你的建议改」。

审查范围：
- docs/.vitepress/theme/PostNav.vue
- docs/.vitepress/theme/index.ts
- docs/.vitepress/theme/custom.css（仅与 post-nav 相关）

关注优先级（从高到低）：
1. 错误行为 / 边界：无上一篇、标签为空、非 notes 页是否误渲染
2. a11y：链接名是否可理解、对比度是否沿用品牌 token
3. 性能：构建期能算的别放到客户端
4. 可维护性：是否重复 posts 数据源

输出格式：
## 阻断（必须改）
- [文件:说明]
## 建议（可合并改）
- ...
## 可忽略
- ...
每条给：现象 → 风险 → 建议改法（一两句，不要重写整文件）

加分约束

• 禁止「整体看起来不错」这类空话；没有发现就写「未发现阻断问题」并列出你检查过的路径。
• 要求它 先复述变更意图 再挑刺，减少「审错文件」。
• 和 项目说明书 冲突的改动（例如手改 dist/）直接标阻断。

---

场景 3：安全重构（行为不变）

什么时候用

• 抽公共组件、合并重复 CSS
• 换数据源写法（例如列表统一走 posts.data）
• 怕一改全站布局

模板

目标：把首页与笔记索引的文章列表抽成共用组件，行为必须与现在一致。

不变式（违反任一则失败）：
- 列表篇数 = docs/notes 下非 draft 的 md 数
- 每项仍有：标题链接、description、日期、可点 tags
- 排序仍为 date 降序
- 不引入新依赖

允许改：
- docs/.vitepress/theme/ 新增组件
- docs/index.md、docs/notes/index.md 的 script setup
- 相关 CSS 只进 custom.css，不要复制到 index 的 <style>

禁止：
- 改 docs/.vitepress/dist/
- 改文章正文 md 内容
- 为了「好看」调整间距以外的信息架构

步骤：
1. 只读相关文件，列出当前两处列表的差异
2. 提出最小方案（3～5 条）等我确认
3. 我回复「做」之后再改
4. 改完说明如何用现有 Playwright 验证（点名 spec）

为什么要「先方案后改」

重构类提示词最容易变成 顺手重写。把「步骤 2 等人确认」写进提示词，比事后回滚便宜。

---

场景 4：写中文技术博客（本站体例）

什么时候用

• 要把一次踩坑整理成 docs/notes/*.md
• 需要 frontmatter、侧边栏、学习路径是否挂靠

模板

按本站约定写一篇笔记，主题：XXX。

frontmatter 必须包含：
title, description, date(YYYY-MM-DD), readingTime, tags

文风：
- 中文正文，专有名词可英文
- 先结论或可运行片段，再解释
- 真实路径与现象（如 dist 即 Nginx 根、cleanUrls 依赖 $uri.html）
- 禁止在 nav/sidebar 文案里塞 emoji
- 不要空喊「赋能」「闭环」

结构建议：
1. 开头 2～3 句：读者读完能得到什么
2. 正文分节，可含表格对比
3. 与本站已有文章交叉链接（给具体 slug）
4. 结尾：可执行的下一步（一条命令或一个检查清单）

完成后：
- 给出建议 slug（英文短横线）
- 建议挂在侧边栏哪一组
- 是否需要改 claude-code-path（仅 Claude Code 线）

项目里已有 skill add-blog-note，发文流程可直接说「按 add-blog-note 发一篇…」。

---

怎么组合这些场景

真实任务往往是串起来的，而不是单点：

1) 探索：只读 theme 与 posts.data，说明列表与文末导航数据流
2) Review：按「阻断 / 建议」审 PostNav 的边界情况
3) 测试：为相关行为补 chromium 用例（禁止 docs:build）
4) 成文：把「为什么 doc-after 而不是 markdown 组件」写成工程笔记草稿

每一步 单独开一句验收，比「帮我做好列表相关所有事」可控得多。上下文变长时，参考 上下文预算：砍无关 skill，把约束写短、写硬。

---

快速对照

场景	提示词里最不能省的	完成信号
写测试	跑在 dev 还是读 dist；禁 build	指定 spec 绿 + 断言说人话
Code Review	只审不改；分级输出	有路径、有风险、无空话
重构	不变式列表；先方案	diff 小、行为测仍过
写中文文	frontmatter + 文风 + 交叉链接	可直接落 docs/notes/*.md

---

和「完全指南」怎么分工

文	解决什么
完全指南	清晰、Few-Shot、XML、格式、链式
本文	具体职业场景下的开口方式与验收
Claude Code 工作流	在仓库里探索 / 开发 / 提交的话术
自己写 Skill	同一套提示词重复第三次时如何固化

原则会过时得慢；场景模板会跟着你的仓库变。本站模板里的路径、禁 build、tags 可点，换项目时请整段替换材料与约束，不要只改第一句角色扮演。