Claude Code/Codex 新手提示词指南：5 个实用模式

先理解一件事：好提示词其实是清楚的任务说明

Claude Code 或 Codex 给出糟糕结果时，原因往往不是“AI 不会写代码”，而是任务说明缺少边界。提示词不是一句神奇咒语，而是给 AI 编程代理的工作 brief：要改什么、不能碰什么、什么算完成、要留下什么验证证据、下一位接手的人需要知道什么。

这篇文章把新手最容易漏掉的内容整理成 5 个模式：范围、仓库上下文、验收标准、验证证据、交接。它们适用于修 bug、小功能、文章生成、仓库调查、代码 review 等日常任务。目标不是写出花哨的 AI 术语，而是减少猜测。

官方能力会持续变化，所以具体设置要看原文档。Claude Code 可从 Claude Code overview、Memory、Settings 开始。Codex 和 OpenAI 的代码生成工作流可参考 OpenAI code generation guide。如果你还没上手工具本身，可以先读 Claude Code 入门指南 和 CLAUDE.md 最佳实践。

5 个模式总览

模式	通俗解释	缺少时会发生什么
范围	这次任务的边界	代理可能修改无关文件
仓库上下文	项目规则和参考实现	输出不像当前项目
验收标准	什么叫做完成	你和代理对“完成”的理解不同
验证证据	检查结果的记录	停在“我已经实现了”
交接	给下一次会话的摘要	之后没人知道为什么这么改

验收标准就是你愿意接受这次改动的条件。验证证据就是收据，例如运行了哪些命令、检查了哪个页面、哪些内容没法确认。交接则是让明天的自己、同事或另一个代理继续工作的短说明。

模式 1：先把范围切小

差的提示词通常太宽。

把这个应用优化一下，做得更好。

这句话没有说明能不能改 UI、API、测试、文案、数据库、依赖或部署设置。Claude Code/Codex 可以推测，但推测越多，风险越高。

更好的写法是：

只编辑 site/src/content/blog-zh/5-tips-for-better-prompts.mdx。
目标：让文章对 Claude Code/Codex 新手更实用。

可以修改：
- frontmatter 的 title, description, updatedDate, tags
- 正文

不要修改：
- heroImage
- slug
- 其他文章
- 构建配置

这对有商业转化路径的网站尤其重要。过大的改写可能误删内部链接、产品 CTA 或统计属性。范围写清楚后，代理可以放心工作，但不会把一篇文章更新变成全站重构。

如果只是调查，边界要更明确：

先读取相关文件，只提出修改计划，不要编辑。
列出你建议修改的文件、原因和每个修改对应的验证命令。

常见失败是说“先看看”，但同时允许代理直接编辑。仓库不熟时，请把调查和实现分成两步。

模式 2：提供仓库上下文

Claude Code/Codex 能读文件，但不会自动知道你的业务目标、写作风格或过去踩过的坑。仓库上下文就是告诉它“这里的做法是什么”。

这个站点用 Astro content collections 管理多语言 MDX 文章。
质量参考文章是 site/src/content/blog-zh/claude-code-productivity-tips.mdx。

项目上下文：
- 文章应是常青实战教程，不要写成很薄的 AI 总结。
- 至少包含 3 个具体 use case。
- 同时包含官方外部链接和内部链接。
- 保留转化路径：/zh/thanks/, /zh/products/, /zh/training/。
- frontmatter 必须保持有效。

没有上下文时，你可能得到一篇语句流畅但不适合 ClaudeCodeLab 的文章。这个站点更需要可复制提示词、失败示例、验证习惯，以及自然引导到 cheatsheet、产品或 training 的下一步。

如果这些上下文经常重复，就把稳定规则写进 CLAUDE.md。相关思路可以读 Claude Code 生产力技巧：项目记忆、安全命令和验证习惯会减少反复解释。

模式 3：先写验收标准

验收标准可以避免“再优化一点”的无限循环。弱提示词是：

让这篇文章更易读，SEO 更强。

这两个目标都重要，但不够可检查。要拆成具体条件：

验收标准：
- 只修改目标文件。
- description 不超过 120 个字符。
- 5 个模式都包含 Before/After 提示词示例。
- 包含 bug 修复、功能开发、文章生成模板。
- 具体列出失败场景和避免方式。
- 加入官方外部链接、内部链接和清楚的 CTA。
- 最后报告验证结果和剩余风险。

功能开发时，验收标准应更偏技术：

验收标准：
- 不破坏现有 UI 布局。
- TypeScript 没有类型错误。
- 添加验证逻辑和面向用户的错误状态。
- 新增或更新至少一个相关测试。
- 报告 npm test 和 npm run build 的结果。

关键是每一项都能被检查。如果代理无法验证，就应该明确说“未确认”，而不是假装已经通过。

模式 4：要求验证证据

“已经实现”不够。请要求 verification receipt，也就是验证收据。

最后请返回 verification receipt：

- 修改文件：
- 执行命令：
- 结果：
- 手动检查：
- 未检查内容：
- 剩余风险：

这个习惯能抓住很多新手问题。它也能让代理在无法运行命令时说明原因，例如依赖缺失、测试太慢、本地服务不可用。然后你可以判断风险是否能接受。

不要把错误信息过度概括。下面太弱：

构建失败了，修一下。

下面才有用：

命令：
npm run build

错误：
Type error: Property 'name' does not exist on type 'User | undefined'.
File: src/components/Profile.tsx:15:22

请求：
先解释可能原因，用最小安全差分修复，然后重新运行 npm run build。

更完整的流程可看 验证收据工作流。格式可以调整，但不要让工作在没有证据时结束。

模式 5：要求交接说明

AI 代理的工作经常不是一次会话完成。交接说明可以避免下一次会话重新摸索。

最后写一段 handoff note，包含：
- 目标
- 改了什么
- 没改什么
- 验证结果
- 下一步要看的文件
- 未解决的风险或决策

这对文章、SEO、支付流程、团队仓库都很有用。diff 能说明改了什么，但通常解释不了为什么把 CTA 放在某一段，或者为什么选择小修而不是大重构。

团队使用时，建议配合 Claude Code 团队交接规则。固定格式会让 AI 会话更容易 review。

可复制模板

Bug 修复模板

目标：
  用最小安全差分修复 bug。

症状：
  发生了什么：
  期待行为：
  实际行为：

复现步骤：
  1.
  2.
  3.

范围：
  可以编辑的文件：
  不能编辑的文件：

仓库上下文：
  参考的相似实现：
  需要保留的本地规则：

验收标准：
  编辑前先说明可能原因。
  修复根因，不只隐藏表面症状。
  可行时新增或更新相关测试。
  返回验证证据和剩余风险。

新功能模板

目标：
  安全添加一个小功能。

功能：
  用户能看到的变化：
  API/数据库/配置是否变化：

约束：
  保留现有 UI 风格。
  遵守当前命名和文件模式。
  如果需要更大的设计变更，先解释原因再实现。

验收标准：
  包含实现、类型、错误状态、测试和验证收据。

文章生成模板

目标：
  把文章改成适合新手的 evergreen 教程。

读者：
  刚开始使用 Claude Code/Codex 的个人开发者或小团队。

必备元素：
  至少 3 个具体 use case。
  Before/After 提示词示例。
  具体失败场景和修正方式。
  可复制模板。
  官方链接、内部链接和 CTA。

验收标准：
  description 不超过 120 个字符。
  frontmatter 有效。
  代码围栏成对闭合。
  最后给出简短自检。

3 个实务用例

第一个用例是登录后的白屏。不要只说“修 dashboard”。请给出复现步骤、期待结果、实际 console 错误、可以编辑的文件和验证命令。这样更容易修到根因，而不是只遮住症状。

第二个用例是在 lead form 中添加“咨询类型”。好的提示词会写清选项，例如 training, consulting, other，还会写验证规则、API contract、analytics event 和测试期望。这样能保护商业转化路径，同时保持 diff 很小。

第三个用例是文章生成。对 ClaudeCodeLab 来说，提示词应明确正文深度、具体例子、失败模式、官方链接、内部链接、CTA，以及“实际试用结果”的结尾段落。这样才不会生成泛泛的 AI 摘要。

小型提示词 QA 评分表

发送前给自己的提示词打 10 分。

分数	维度	自问
0-2	范围	可编辑和受保护文件是否清楚？
0-2	上下文	是否包含本地示例、读者和业务目的？
0-2	验收	代理能判断任务何时完成吗？
0-2	验证	是否指定命令或手动检查？
0-2	交接	是否说明最后要报告什么？

8 分以上通常可以直接发送。5 分以下时，问题多半不是工具能力，而是人类上下文没有给够。

可直接运行的任务说明生成器

不要每次只写“帮我优化一下”。先用固定格式生成 prompt-brief.md，再把目标文件和验收条件改成这次的内容。这样交给 Claude Code 或 Codex 时，范围、限制和验证方法一开始就很清楚。

cat > prompt-brief.md <<'EOF'
# Task brief for Claude Code / Codex

Goal:
- Improve one article or feature without changing unrelated files.

Scope:
- May edit: site/src/content/blog/example.mdx
- Do not edit: hero images, routes, unrelated articles, billing code.

Context to read first:
- AGENTS.md
- A similar high-quality article
- The target file

Acceptance criteria:
- The intro explains who the reader is and why this matters.
- The draft includes at least three concrete examples.
- Code or prompt templates are copy-pasteable.
- Pitfalls and verification steps are explicit.
- Internal links and a natural CTA are included.

Verification:
- npm run build
- node scripts/check-code-fences.mjs
- Read the changed file once as a reviewer.

Return:
- What changed
- Checks run
- Remaining risks
EOF

CTA：把这个模式固定成自己的工作流

你不需要每天从零写这些模式。先用 免费 Claude Code cheatsheet 熟悉日常命令和安全习惯。如果需要现成提示词包和设置教材，可以查看 ClaudeCodeLab 产品。如果团队需要一起整理 CLAUDE.md、权限、review policy、verification receipt 和上线培训，请看 Claude Code training 与咨询。

在 ClaudeCodeLab 的文章和站点任务中实际使用后，提升最大的做法是：编辑前先写范围、验收标准和验证证据。交接说明也明显缩短了第二天 review 的时间，因为每个 CTA 和链接背后的理由还留在上下文里。