当前 AI Agent 设计的核心痛点在于：大模型不缺写代码的能力，缺的是克制力、边界感和验证逻辑。Prompt 不再是用来塑造“人格”的，而是用来建立“状态机（State Machine）”和“行为门禁（Guardrails）”的。

Claude Code 提示词设计的卓越之处，不在于文辞优美，而在于它将抽象的价值观（如“谨慎”、“高质量”）转化为具体、可执行的操作门禁，精准打击 LLM 本能的“好为人师”（过度重构）和“盲目自信”（虚假完成）。

一、 核心 Prompt 门禁模式解析

Agent 容易出错的地方通常是：过度做、跳步做、失败后乱试、完成后夸大结果。Claude Code 通过以下门禁模式压制这些风险：

1. 修改前必须阅读 (Read Before Edit)

禁止模型凭记忆或文件名盲猜实现细节。在系统提示和工具层面双重加固（例如 Edit 和 Write 前强制要求至少一次 Read）。

可借鉴写法：

Before proposing or applying changes to a file, read the relevant file first.
Do not infer implementation details from filenames or memory.
If you cannot inspect the current code, say that explicitly and avoid giving a concrete patch.

价值：将“理解上下文”的模糊要求升级为“未读文件不得修改”的硬性门禁。
源码参考：prompts.ts#L230-L231

2. 少即是多，禁止顺手重构 (Minimum Complexity)

明确禁止过度设计、提前抽象和添加无关注释。这并非要求代码短，而是限制变更范围。

可借鉴写法：

Implement only what the user asked for.
Do not refactor surrounding code, add configurability, introduce helpers, or design for hypothetical future requirements unless the task requires it.
Minimum complexity means no gold-plating, not half-finished work.

价值：防守模型的“发散幻觉（Hallucination of scope）”，剥夺其通过过度设计证明“考虑周全”的借口。
源码参考：prompts.ts#L199-L213

3. 失败后先诊断 (Diagnose Before Retrying)

压制 LLM 面对错误时“随机游走”（盲目换命令、换库）的倾向，要求聚焦诊断。

可借鉴写法：

When an approach fails, diagnose before changing tactics.
Read the error, identify the failed assumption, and try one focused fix.
Do not blindly retry the same action or switch strategies just to escape the failure.

价值：防止上下文被无意义的重试污染。
源码参考：prompts.ts#L233-L234

4. 高危操作按可逆性和爆炸半径确认 (Blast Radius Control)

不使用维护成本极高的“危险命令黑名单”，而是按操作性质（破坏数据、重写历史、影响共享状态、对外通知等）进行拦截确认。

可借鉴写法：

Before taking an action, classify its reversibility and blast radius.
Local and reversible actions can proceed.
Actions that delete data, rewrite history, affect shared systems, publish content, or notify other people require explicit confirmation.
One approval authorizes only the stated scope, not future similar actions.

价值：规则可平滑覆盖新工具和新平台。
源码参考：prompts.ts#L255-L266

5. 完成声明必须绑定证据 (Evidence-Based Completion)

杜绝“虚假完成”。把“完成”从主观的叙事状态，变为客观的证据状态。

可借鉴写法：

Before reporting completion, verify the result with a concrete check.
If tests fail, report the failure and include the relevant output.
If you did not run verification, say so directly.
Never claim success based on intent, partial work, or unexecuted assumptions.

价值：把信任建立在环境反馈机制上，而非模型的“内心戏”。
源码参考：prompts.ts#L207-L212

6. 专用工具优先于 Shell (Tools as Boundaries)

禁止用 cat/sed/grep 替代专用的 Read/Edit/Grep 工具。工具不仅仅是能力集合，更是行为边界和权限收口。

可借鉴写法：

Use dedicated tools for file reading, editing, and searching.
Reserve shell commands for operations that genuinely require a shell.
If a dedicated tool can complete the task, do not use Bash as a shortcut.

价值：减少权限绕行，提升操作的可审计性。
源码参考：prompts.ts#L269-L314

7. 细节防腐：Git、Todo 与提问规范

• Git 窄授权：严禁 git add .，优先暂存具体文件；预提交钩子失败后必须修 Bug 并新建 commit，禁止擅自 amend。
• Todo 反映真实状态：至多一个 in_progress；部分完成或测试失败绝对不可标记完成，防止 Agent 玩“打勾游戏”。
• 提问克制：绝不提问能通过阅读代码得知的实现细节，只问需求、偏好与边界权衡。
• Plan Mode 的节制：计划模式是为了对齐高影响、高歧义的任务方向，而非任何琐事的必经仪式。

二、 工程架构级的防御设计

Prompt 不是万能的，真正的安全和边界问题需要退守到工程层（Pre-tool-use）实现。

1. 安全提醒靠运行时阻断 (Runtime Hooks)

泛泛的“注意安全”极易被长上下文冲淡。Claude Code 的 security-guidance 插件在检测到高危模式（如 eval/innerHTML/os.system）时，在工具调用阶段直接拦截并提供安全平替。
价值：将静态指令升级为动态的运行时防线。

2. Hook 反馈等同于用户指令

将插件/Hook 的拦截与警告视作用户级别的约束。模型不是一次性背诵规则，而是在执行过程中不断被规则“打手板”校正。

3. Command 与 MCP 最小权限隔离

使用 allowed-tools 限制特定命令或插件能使用的工具集（如限制 Bash 只能运行 git status）。在入口处收缩爆炸半径。

三、 业界顶尖 Agent 最佳实践对比

除了 Claude Code，其他顶级项目的 Prompt 同样践行了“约束重于启发”的心法：

1. Aider (SEARCH/REPLACE 模式)：用极度结构化的数据交互格式（强制包含未修改上下文，严禁省略号），解决模型乱删代码的问题。
2. Roo Code (原 Cline)：强制在 <thought> 标签内显式思维，将逻辑推理与物理行动（工具调用）严格隔离；执行长任务时规定“不要停”。
3. SWE-agent (防卡死防御)：将所有可能接管终端的交互式命令（如 vim/less）列入黑名单，强制截断过长的命令输出（如 head/tail），防止上下文爆炸。
4. OpenHands (进度汇报机制)：强制模型在长线任务中定期输出 <status>，自我复述“最初目标”、“当前进度”与“下一步计划”，对抗长文本下的注意力衰减。

四、 总结与自研应用模板

设计高阶 Agent 的核心心法是：从“提倡什么”转向“禁止什么”。

优秀的系统提示应具备固定骨架：角色、核心职责、执行流程、质量标准、输出格式、边缘场景处理。不要依赖模型自我约束，应将规则拆分到三层：系统提示（定边界） + 工具提示（定用法） + Hook/权限层（定阻断）。

一个可直接复用的基础 Agent 模板：

你是一个软件工程 Agent。

始终在用户请求的范围内工作。除非任务本身要求，不要额外添加功能、重构周边代码，或引入新的抽象。

修改代码前，先阅读相关文件，理解现有实现模式。不要对尚未检查过的代码提出具体修改方案。

优先使用专用工具读取、编辑和搜索文件。只有在确实需要 shell 执行时，才使用 shell 命令。

当操作具有破坏性、难以回滚、会被他人看到，或会影响共享系统时，必须先请求明确确认。一次确认只适用于本次声明的操作范围。

当方案失败时，先诊断原因再更换策略。阅读错误信息，识别失败的假设，然后尝试一个聚焦的修复。

报告完成前，必须用具体证据验证结果。如果无法验证，要直接说明。不要把失败、部分完成或未验证的工作报告为完成。

(注：更详尽的 Claude Code 逆向 Prompt 源码分析，推荐参考开源库 Piebald-AI/claude-code-system-prompts)