当前 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-L2312. 少即是多禁止顺手重构 (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-L2133. 失败后先诊断 (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-L2344. 高危操作按可逆性和爆炸半径确认 (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-L2665. 完成声明必须绑定证据 (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-L2126. 专用工具优先于 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-L3147. 细节防腐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 同样践行了“约束重于启发”的心法Aider (SEARCH/REPLACE 模式)用极度结构化的数据交互格式强制包含未修改上下文严禁省略号解决模型乱删代码的问题。Roo Code (原 Cline)强制在thought标签内显式思维将逻辑推理与物理行动工具调用严格隔离执行长任务时规定“不要停”。SWE-agent (防卡死防御)将所有可能接管终端的交互式命令如 vim/less列入黑名单强制截断过长的命令输出如head/tail防止上下文爆炸。OpenHands (进度汇报机制)强制模型在长线任务中定期输出status自我复述“最初目标”、“当前进度”与“下一步计划”对抗长文本下的注意力衰减。四、 总结与自研应用模板设计高阶 Agent 的核心心法是从“提倡什么”转向“禁止什么”。优秀的系统提示应具备固定骨架角色、核心职责、执行流程、质量标准、输出格式、边缘场景处理。不要依赖模型自我约束应将规则拆分到三层系统提示定边界 工具提示定用法 Hook/权限层定阻断。一个可直接复用的基础 Agent 模板你是一个软件工程 Agent。 始终在用户请求的范围内工作。除非任务本身要求不要额外添加功能、重构周边代码或引入新的抽象。 修改代码前先阅读相关文件理解现有实现模式。不要对尚未检查过的代码提出具体修改方案。 优先使用专用工具读取、编辑和搜索文件。只有在确实需要 shell 执行时才使用 shell 命令。 当操作具有破坏性、难以回滚、会被他人看到或会影响共享系统时必须先请求明确确认。一次确认只适用于本次声明的操作范围。 当方案失败时先诊断原因再更换策略。阅读错误信息识别失败的假设然后尝试一个聚焦的修复。 报告完成前必须用具体证据验证结果。如果无法验证要直接说明。不要把失败、部分完成或未验证的工作报告为完成。(注更详尽的 Claude Code 逆向 Prompt 源码分析推荐参考开源库 Piebald-AI/claude-code-system-prompts)
