“AI 帮我建了一个烂网站”的故事，本质都是”我写了个烂 prompt”。模型没问题，规格不清。下面是怎么写 prompt 让 Agent 一整轮建站都在轨上——附可直接抄的 CLAUDE.md 模板和单任务 prompt 结构。
问题背景
用 AI 建站的时候，drift（漂移）是最大敌人。漂移就是 Agent 一声不响地改了你的设计系统、路由约定或内容 schema。这不是模型不行，是每个任务都缺”前面发生了什么”的锚。好的 prompt 设计就是把规格变成显式、持久、窄的。
判断标准
- Agent 生成的代码和前一个任务自相矛盾。
- 每次新对话都要重新介绍一遍技术栈。
- 文件结构慢慢偏离你最初的设计。
- 它发明你没要求的 UI 组件或路由。
- 同一个 prompt 在不同 session 产出不同结果。
快速结论
用持久化的规格文件（CLAUDE.md、AGENTS.md 之类）+ 窄的单任务 prompt。任何需要跨 session 保留的东西都不要只靠对话记忆。
开始前准备
- 选好工具会读的规格文件名（Claude Code 读
CLAUDE.md，OpenAI/codex 读AGENTS.md）。 - 仓库的技术栈和约定已定下来——写出来，不要再去发现。
- 给规格留 30-60 分钟初稿时间；一周内回本。
实操步骤
- 仓库根建一个单一权威规格文件。 控制在一页。模板：
# CLAUDE.md
## 技术栈
- Framework: Astro 5（Content Collections + MDX）
- Styling: Tailwind v4（不要 CSS modules，不要 styled-components）
- Hosting: Firebase Hosting（静态；`firebase.json` 是权威）
- Languages: en、zh —— 并行 src/content/articles/ 下
## 约定
- Slug: `^[a-z0-9-]+$`，kebab-case，无日期，无分类前缀
- 目录: src/content/articles/{en,zh}/<hub>/<slug>.mdx
- 内容 schema: 写在 src/content/config.ts，不显式要求不要改
- 图片引用: 用 `image()` helper，不要 `/public/...`
## 文章形态（mdx 文件）
- schema 要求的 frontmatter 字段: title, description, urlSlug, category, tags, publishedAt, lang, translationKey
- 正文按顺序: Lead, Background, How to tell, Step by step, FAQ, Related
## 禁止
- 未询问就加 npm 包
- 编辑用户指定路径之外的文件
- 重命名任何 frontmatter 字段
- 在 src/components/mdx/ 已有组件时还发明新组件- 每个任务写三段式 prompt： context（指向规格）、task（一个具体交付物）、constraints（不能做什么）。模板：
[CONTEXT]
仓库约定在 CLAUDE.md。文章 schema 在 src/content/config.ts。用 Astro Content Collections。
[TASK]
在 src/content/articles/zh/indie-dev/<slug>.mdx 加一篇文章，遵循 CLAUDE.md 的文章形态。标题: "<标题>"。主关键词: "<关键词>"。600-900 字。至少含一段 bash 代码块和一段配置代码块。
[CONSTRAINTS]
- 不要改 src/content/config.ts。
- 不要加 npm 依赖。
- 不要动其它文章。
- slug 必须与文件名一致并匹配 /^[a-z0-9-]+$/。
- 散文里不要用 {variable}（MDX brace bug）。需要字面 brace 就放进反引号。
只回文件内容，我来 commit。-
任务切到足够小，让 Agent 输出能在 2 分钟内 review 完。200 行 diff 是软上限。
-
负向约束写明。 “不要引入新依赖”、“不要改
src/components/之外的文件”、“不要修改内容 schema”。常备清单：
约束库
─────────────────────────────
不要加 npm/pip 依赖
不要改 <path> 之外的文件
不要改 <named-config-file>
不要给 <page-type> 加客户端 JS
不要重命名别处用到的 export/symbol
不要静默升级包版本
不要写注释解释显然的代码- 它做得接近但不对时，发 diff，不要重发 prompt。 模型对编辑指令的服从比”按这些要求重做”高。格式：
应用这个 diff 并产出更新后的文件：
@@ src/content/articles/zh/indie-dev/foo.mdx @@
- 有问题的句子
+ 改对的句子-
每次接受改动后，回头看规格文件是否隐式发生了变化。2 行的编辑省下一个月后 2 小时的 debug。
-
多文件重构先要计划，批准后再分步执行。 模板：
开始改任何文件前，列出：
1. 你打算改的文件
2. 每个改动的一句话描述
3. 风险 / 顺序依赖
我说 "go" 之后才出 diff。- 成功的 prompt 存模板。 建一个
prompts/目录，能用的就归档。你的 prompt 库复利会比代码库快。
执行检查清单
- 仓库根有
CLAUDE.md（或等价物）且和现状一致。 - 每个单任务 prompt 都有 context / task / constraints。
- 约束库存在一个共享笔记里。
- 成功的 prompt 存进
prompts/。 - 多文件改动走 plan-then-execute 流程。
上线后验证
- 新 session 用同一份规格 + 任务 prompt 跑出近乎一样的 diff（方差小 = 漂移小）。
- 任务违反规格时 Agent 会拒绝或反问。
- 规格文件的 diff 与已接受的特性改动匹配。
容易踩的坑
- 把 prompt 写成对话而不是规格。“能不能让 nav 好看点”会得到”感觉不错”的不可预测输出。
- 规格文件不更新。
CLAUDE.md还写着 Tailwind，但你已经换 CSS modules 了——下次它又会拉 Tailwind 回来。 - 一次问太多。“顺便改一下路由、加 OG 标签、更新 footer”，最后只对一个。
- 觉得”Agent 明显不会这么干”就不写约束。它就是会这么干。
- 相信它记得这个 session 早期说过什么。长 session 会丢早期上下文，要重述。
- 没看 diff 就批准。下一个任务会从你批准的内容上继续分叉。
FAQ
- 规格文件多长合适: 最多一页。再长就拆成分文件（
CONTENT.md、DESIGN.md），顶层文件引用它们。 - 用自然语言还是结构化格式: 都行但要统一。混风格的规格会让 Agent 搞不清哪部分是约束哪部分是描述。
- Codex 也适用吗: 适用。原则和模型无关，只要是在仓库上跑 Agent 就有用。
- 我不太懂技术写不出规格怎么办: 让 Agent 通过访谈你写第一版，你再编辑。bootstrap 没问题，但规格必须存在。
- 规格里要不要带例子？: 要。一个具体例子顶五条抽象规则。