Claude Code/Codex 高级提示词工程：把任务简报写到可交付

Claude Code 或 Codex 的输出不稳定时，问题往往不是模型不够聪明，而是任务交接太含糊。 高级提示词工程不是写一句神奇咒语，而是设计工作流：目标、范围、上下文、约束、验收标准、验证和交接必须放在同一个包里。

本文介绍一个可以直接复制使用的“提示词包”。初学者可以照着模板用，团队也可以把它放进真实仓库、并行任务、发布前审查和内容运营流程中。如果你还在补基础，可以先读 Claude Code/Codex 提示词入门 和 CLAUDE.md 最佳实践。

工具行为会变化，涉及功能和配置时要看官方资料。Claude Code 可从 Claude Code overview、Memory 和 Anthropic 的 prompt engineering overview 开始。Codex 侧请参考 OpenAI Codex docs 和 AGENTS.md guidance。

高级的本质是工作契约

差的提示词不只是短。它没有判断规则，没有说明哪些文件不能碰，没有定义“完成”，也没有要求证据。缺少这些内容时，AI 只能猜。

实战提示词应该像一份小型工作契约。

要素	要写什么	缺失时的失败
Goal	需要达成的结果	看起来合理，但解决错问题
Scope	可以改和不能改的范围	夹带无关重构
Context	文档、相似实现、官方资料	复制旧模式或编造行为
Constraints	规则和禁止事项	依赖、API、文风被意外改变
Acceptance criteria	如何判断完成	只能凭感觉评审
Verification	命令和人工确认	没有证据就结束

Anthropic 的提示词工程说明把成功标准和经验性测试放在前提位置。对 Claude Code/Codex 这样的代码代理来说，这一点更重要，因为它们不仅回答问题，还可能读文件、改文件、运行命令并生成看似完成的差异。

把提示词包写成文件

每次在聊天框里输入长指令很难复用，也不方便评审。把任务写进 prompt-packet.md 会更稳定。下面的 Bash 片段可以直接生成一个最小模板。

cat > prompt-packet.md <<'EOF'
# Goal
Improve one published article so it is practical, accurate, and ready for review.

# Scope
May edit:
- site/src/content/blog/example-article.mdx

Do not edit:
- heroImage
- slug
- unrelated articles
- package or deployment files

# Context to read
- AGENTS.md
- site/src/content/blog/claude-md-best-practices.mdx
- Official docs relevant to the article topic

# Constraints
- Preserve existing frontmatter keys unless this task explicitly changes them.
- Use copy-pasteable examples, not pseudocode.
- Avoid unsupported claims. Link to official docs for tool behavior.
- Keep paragraphs short enough for mobile reading.

# Acceptance criteria
- updatedDate is 2026-06-02.
- The article has at least three concrete use cases.
- The article names specific pitfalls and how to avoid them.
- The article includes an internal link, an official external link, and a natural CTA.
- The final section explains what was actually verified.

# Verification
- node scripts/check-code-fences.mjs
- node scripts/check-updated-article-quality.mjs
- Read the diff once as a critical reviewer.

# Return format
- Changed files
- Key improvements
- Checks run
- Residual risks
EOF

交给 Claude Code/Codex 时，只需要再补一句：“先读取 prompt-packet.md，再检查目标文件和列出的上下文，只在 Scope 中工作。”这个文件不是形式主义。它能避免代理为了“帮忙”而修改邻近页面、替换图片、重构无关代码。

先检查提示词再运行

提示词是自然语言，质量容易漂移。一个小脚本就能发现结构缺失。保存为 check-prompt-packet.cjs。

// save as check-prompt-packet.cjs
const fs = require("node:fs");

const file = process.argv[2] || "prompt-packet.md";
const text = fs.readFileSync(file, "utf8");

const required = [
  "# Goal",
  "# Scope",
  "# Context to read",
  "# Acceptance criteria",
  "# Verification",
  "# Return format",
];

const missing = required.filter((heading) => !text.includes(heading));
const hasDoNotTouch = /do not (edit|change|touch)/i.test(text);
const hasCommand = /npm run|npm test|pnpm |yarn |node scripts\//i.test(text);

if (missing.length || !hasDoNotTouch || !hasCommand) {
  console.error("Prompt packet is not ready.");
  if (missing.length) console.error("Missing headings: " + missing.join(", "));
  if (!hasDoNotTouch) console.error("Add an explicit do-not-touch boundary.");
  if (!hasCommand) console.error("Add at least one verification command.");
  process.exit(1);
}

console.log("Prompt packet looks actionable.");

运行方式如下。

node check-prompt-packet.cjs prompt-packet.md

这个脚本很简单，但很有用。Masa 在文章运营中反复踩过的坑，通常就是没有写清“不能碰什么”，或者最后没有要求证据。产品代码也一样。如果请求没有完成定义，评审者只能按个人喜好判断。

把模糊目标改成验收标准

“写得更好”“SEO更强”“达到生产可用”都是合理意图，但不够可判定。要把它们改成能通过或失败的标准。

差的写法：

请改进这篇文章，也顺便加强SEO。

可执行的写法：

把文章改写成Claude Code初学开发者也能执行的实战指南。

Acceptance criteria:
- 标题包含 "Claude Code" 和 "prompt engineering"。
- description 少于120个字符。
- 正文包含至少3个具体用例。
- 至少包含2个坏提示词例子和2个改进版本。
- 包含官方文档链接和相关站内链接。
- 最后一节说明实际验证了什么。
- 编辑后运行代码围栏检查，并报告结果。

如果是功能实现，验收标准要更技术化。

Acceptance criteria:
- 不改变公开API类型。
- 增加输入校验和用户可见错误提示。
- 至少增加或更新一个失败路径测试。
- 运行 npm test 和 npm run build，并报告结果。
- 说明改动文件，以及检查过但没有修改的相关文件。

验收标准不是为了微操代理，而是为了在开工前共享评审基准。

管理上下文预算

Claude Code 的 Memory 文档说明，CLAUDE.md 和 auto memory 会作为上下文加载，而不是强制配置。指令更长不代表更容易遵守，反而可能把关键规则埋掉。

建议把上下文分成三层。

层级	例子	放在哪里
每次都需要	构建命令、命名规则、禁止区域	CLAUDE.md 或 AGENTS.md
当前任务需要	目标文件、相似实现、质量标准	prompt-packet.md
需要时再读	长规格、旧会议记录、原始日志	只给文件名，不要全文粘贴

常见陷阱是把所有材料都塞进提示词。旧设计、会议记录、日志、当前任务混在一起时，代理必须自己猜优先级。更好的做法是写清阅读顺序。

Context to read in order:
1. AGENTS.md for project rules.
2. The target article.
3. One similar high-quality article for tone and structure.
4. Official docs only for tool behavior.

Ignore:
- Old brainstorming notes unless they contradict the current implementation.
- Unrelated product pages.
- Generated files and build output.

这会减少无效探索。多人并行编辑时也更安全，因为代理不会把看到的所有文件都当作可以修改的文件。

分清示例和约束

示例说明要模仿的形状，约束定义不能越过的边界。二者混在一起会产生模糊指令。

差的写法：

把这个页面做成生产力技巧那篇的感觉。

更好的写法：

Reference style:
- Use site/src/content/blog-zh/claude-code-productivity-tips.mdx only for section density and CTA placement.
- Do not copy its examples or claims.

Constraints:
- Keep this article focused on prompt engineering.
- Do not introduce pricing claims.
- Preserve heroImage and slug.

不要只写“不要乱改”。同时写清允许范围。“不要加库”不如“只使用现有依赖”。“不要大改”不如“只改列出的文件，并保持公开API不变”。

指定安全迭代循环

严肃任务不适合一口气全交给代理。更稳定的方式是显式写循环。

1. 读取目标、规则和最近的好例子。
2. 简短说明计划。
3. 只在范围内编辑。
4. 用命令和人工检查验证。
5. 返回改动、证据和剩余风险。

可以直接写进提示词。

Workflow:
- First inspect the target file and the nearest quality reference.
- If the change is larger than two files, explain the plan before editing.
- Edit only the files listed in Scope.
- After editing, run the Verification commands if feasible.
- End with a verification receipt, not a general summary.

验证收据就是工作的凭证。完整模式可看 验证收据工作流，日常最小格式如下。

Verification receipt:
- Changed files:
- Commands run:
- Results:
- Manual checks:
- Could not verify:
- Residual risks:

四个具体用例

第一个用例是修 bug。把症状、复现步骤、期望行为、日志和允许修改的文件交给代理。要求它先解释可能原因，再用最小差异修复，并补失败路径测试。这样可以避免只修表面现象。

第二个用例是小功能。写清用户可见变化、API或数据库结构是否允许改变、要参考哪个现有UI模式、哪些测试能证明完成。比如给联系表单加分类字段，就要写选项、校验、提交字段、分析事件和本地化处理。

第三个用例是文章重写。给出读者、搜索意图、目标长度、必须包含的例子、失败案例、站内链接、CTA和官方资料。ClaudeCodeLab 常做这类工作，最重要的是避免把薄文章改成更顺的摘要，而是改成读者能实际执行的指南。

第四个用例是代码审查。审查提示词最需要固定输出格式。要求严重度、文件和行号、复现条件、修复方向、缺少的测试。不要写“帮我看看全部”，要优先安全、数据丢失、公开API变化和未测试的错误路径。

常见失败和避坑

失败一：把多个目标混在一起。“重构、提速、SEO、CTA 一起改”其实是多项任务。一个提示词包先处理一个目标。

失败二：只写禁止事项。“不要弄坏”没有说明可以做什么。每个禁止范围都要配一个允许范围。

失败三：把旧知识当成官方行为。Claude Code、Codex、memory、settings、AGENTS.md 都可能变化。涉及工具行为时链接官方文档，不要超出文档做强断言。

失败四：把验证变成可选项。命令跑不了也要报告。沉默比明确的验证缺口更危险。

失败五：好提示词只留在聊天记录里。有效指令应该沉淀到 prompt-packet.md、CLAUDE.md 或团队评审清单中。团队交接可结合 Claude Code 团队交接规则。

CTA：先标准化，再扩大使用

你不需要每天重新写这套提示词。个人使用可以从 免费速查表 开始；需要可复用材料时，查看 产品和模板；团队要把 CLAUDE.md、权限、审查、验证收据和文章质量规则落到真实仓库时，可以使用 Claude Code 培训与咨询。

本文实际确认了什么

本文用 Claude Code 官方 overview 确认了它可以理解代码库、编辑文件并运行命令；用 Memory 文档确认了 CLAUDE.md、auto memory 与强制配置之间的区别；用 Anthropic prompt engineering overview 确认了提示词优化前应先定义成功标准和测试方法；Codex 部分则对齐 OpenAI 的 Codex docs 与 AGENTS.md guidance。实务结论很直接：把提示词当成可评审的工作契约，而不是一次性的聊天消息。