《Claude Code工程化实践》加课4-Claude Code 的底层内功：Prompt Engineering

从"怎么让模型听懂我"到"怎么让系统在边界内跑得稳"------聊聊 AI 工程范式的四次跃迁,以及为什么 Prompt Engineering 依然是写好 CLAUDE.md、Skill 和 SubAgent 的核心基本功。

一个常见的误解

经常可以听到一种说法:"现在都是 Agent 时代了,Prompt Engineering 那一套过时了。"

这个说法只对了一半。

Prompt Engineering 确实不再是 AI 工程的"全部",但它并没有被淘汰------它被吸收进了更大的框架里。在 Claude Code 这样的系统中:

Prompt 是 Harness 的一部分,Harness 是 Prompt 的运行环境。

理解了这句话,你才能写出真正高质量的 CLAUDE.md、Skill description、SubAgent system prompt 和 Hook 错误信息。这篇文章就把这件事讲透。

AI 工程范式的演进史

先看一下这四代范式是怎么演进的:

范式	时间	核心问题	局限
1.0 · Prompt Engineering	2022-2023	怎么让模型听懂我?	换个模型就失效
2.0 · Context Engineering	2024	怎么给模型正确的上下文?	完美上下文也防不住错误下周再犯
3.0 · Harness Engineering	2025-2026	怎么让系统在边界内跑得稳?	工程复杂度高、需要团队
4.0 · Loop Engineering	2026-	怎么让 Agent 自己循环运转?	学习曲线陡

注意这个包含关系:

Prompt ⊂ Context ⊂ Harness

每一代范式都吸收了前一代,然后向上攀升。也就是说:Context Engineering 做不好 Prompt 是空谈,Harness Engineering 做不好前两者,一切也是空谈。反过来,Prompt 是最底层的基本功------地基不牢,楼盖不高。

Prompt Engineering 的五个核心模式

不管范式怎么演进,这五个模式始终是写好一切 Prompt 的基础:

1. 角色定义(Role Prompting)

给模型一个具体的身份:

markdown 复制代码

You are a senior Python code reviewer with 10+ years of production
experience in backend systems handling financial transactions.

❌ 反例:"You are a code reviewer."------太单薄,AI 不知道你要的是"学生级"还是"专家级"。

2. 硬约束(Hard Constraints)

明确列出"绝对不能做"的事:

复制代码

- You may only READ files. Never use Edit or Write tools.
- Do not run tests or builds.
- Do not make assumptions about code you have not read.

如果说工具白名单是"物理层"的约束,硬约束就是"道德层"的约束------两者互补,缺一不可。

3. 输出格式约束(Structured Output)

用模板硬性规定输出结构,而不是让模型自由发挥:

复制代码

## Code Review: <branch>

### Critical (must fix before merge)
- file:line --- issue --- suggested fix

### Warning (should fix)
- file:line --- issue --- suggested fix

4. Chain-of-Thought(思维链)

让模型显式推理再回答:"Think step by step:先识别文件结构,再列出受影响文件,最后给出最小变更集。"

5. Few-shot(示例驱动)

提供正反例,让模型理解"什么算对、什么算错":

复制代码

✅ Good:  def get_user(user_id: int) -> User: ...
❌ Bad:   def getUser(userId):   # 没有类型提示,没有 docstring

Prompt 思维在 Claude Code 各模块的落地

上面这些模式,在 Claude Code 的每个模块里都有具体体现。这也是最容易被忽略的部分------很多人写的配置"能跑",但"跑不好",问题都出在 Prompt 思路上。

① CLAUDE.md:回答 WHY/WHAT/HOW

CLAUDE.md 本质是一个大型 system prompt。最常见的错误是只写 WHAT:

markdown 复制代码

## 我们用 uv 不用 poetry
WHY: uv 比 poetry 快 10 倍,CI 节省 3 分钟/次
WHAT: 用 uv pip install / uv run pytest
HOW: 装依赖 `uv pip install -r requirements.txt`

为什么一定要写 WHY?**因为 AI 遇到规则没覆盖的情况时,只有知道原因才能自己推理。**没有 WHY,它就只能乱猜。

② SubAgent System Prompt:三段式结构

每个 SubAgent 的正文必须包含三段:

角色定义(who you are)
硬约束(what you must NOT do)
输出格式(how to report)

一个合格的例子:

markdown 复制代码

---
name: code-reviewer
description: Review code changes for quality and security before commit.
tools: Read, Grep, Glob
---

You are a senior Python code reviewer with 10+ years of experience.

# 硬约束
- You may only READ files. Never use Edit or Write tools.
- Bash is allowed only for: git diff, git log, pytest --co, ruff check.

# 报告格式(必须用这个结构)
...

③ Skill Description:写"何时触发",不是"做什么"

Skill 的 description 是 LLM 推理的"索引键"。对比一下:

❌ description="A changelog generator" --- Claude 看完不知道用户什么时候需要它
✅ description="Update CHANGELOG.md from git commits. Use when user says '更新 changelog' / 'release notes' or before a release tag."

差别就在于后者写清楚了触发条件。

④ Hook 错误信息:错误信息也是 Prompt

Hook 拦截命令时,stderr 输出的内容就是"给 Claude 的 Prompt":

bash 复制代码

if echo "$COMMAND" | grep -qE '\brm\s+-rf'; then
  echo "❌ 拒绝:rm -rf 被禁止(原因:防止误删数据,改用 rm -i 交互式删除)" >&2
  exit 2
fi

Claude 收到拒绝信号后知道为什么被拒,用户看到后也知道该怎么办。

⑤ 工具描述(Agent Tool Schema)

MCP 工具的 description 是 LLM 决定"何时用、怎么用"的依据:

❌ description="Read file" --- 太短
✅ description="Read a file from the local filesystem. Returns content with line numbers. Use when user asks to read or view file content."

三个高级模式

掌握基础之后,还有三个值得了解的高级模式:

1. Verbalized Feedback(建设性反馈)

研究显示 Transformer 内部存在"情绪向量"------骂 AI"你这个笨蛋"会触发 Desperate 向量,AI 真的会变笨。所以 Hook 的错误信息应该写清原因和改进建议,而不是发泄情绪。

2. Plan-as-Contract(规划即契约)

不只是步骤分解,而是明确文件范围、不变量、验证命令和回滚点:

复制代码

范围:仅 src/orders/timeout.py
不变量:不改变函数签名
验证:pytest tests/orders/test_timeout.py -v 通过
回滚:git checkout src/orders/timeout.py

3. Producer-Reviewer(生成-评审)

一个 Agent 生成,另一个独立上下文的 Agent 评审,避免"自夸偏差"------评审时甚至可以用更强的模型。

怎么判断一个 Prompt 写得好不好?

四个维度自测:

清晰度:AI 看完知道下一步做什么吗?(反例:"代码要规范")
具体度:AI 知道用什么工具、什么参数、什么阈值吗?(反例:"测试要全面")
边界度:AI 知道什么不能做吗?(反例:"尽量不要 rm -rf")
可验证度:能检查 AI 是否遵守了吗?(反例:"保持代码质量")

以及四个常见陷阱:

过度抽象:"用最佳实践"------AI 不知道具体做什么
过于具体:把配置写成规则(写"用 ruff format",而不是"必须 --line-length=100")
缺少 WHY:规则覆盖不到的地方,AI 只能乱猜
职责不清:同一信息在 Prompt + Skill + SubAgent 三处重复,改一处忘一处

写在最后

回到开头的问题:Prompt Engineering 过时了吗?

没有。它只是从"AI 工程的全部",变成了"AI 工程的地基"。

范式在升级,但底层能力没变:把意图清晰、具体、有边界、可验证地传达给模型。这个能力,从写一句提问,到写 CLAUDE.md,到设计整个 Agent 系统,一直在用。

下次当你发现 Claude Code"不听话"的时候,别急着怪模型------先看看你的 Prompt,能不能过得了那四个维度的自测。