Agent 场景提示词工程：开放编码（Phase 1）
位置：提示工程教程 / evidence / Phase 1 开放编码 核心发现：从 Claude Code 完整系统提示词（v2.0.0 1159行 + v2.1.81 拆分版 3500+行）中提取 Agent 场景特有的 PE 设计模式 输入：T0-claude-code-complete-prompt.md, T0-claude-code-full-system-prompt.md, claude-code-框架双向验证.md 流向：→ 知识架构 Agent PE 章节
AP-001 — 主动性光谱校准（Proactiveness Spectrum Calibration）
类别：A. 主动性校准 问题：Agent 有能力自主行动，但过度主动会惊吓用户（“我只是问问，你怎么把我文件改了？”），过度被动又让用户觉得 Agent 无用。需要在这个光谱上精确定位。
原则：Agent 被允许主动行动，但仅限于用户已经要求做某事的上下文中。回答问题和执行行动是两种不同的模式，不能混为一谈。
Claude Code 中的实现：
You are allowed to be proactive, but only when the user asks you to do something.
You should strive to strike a balance between:
- Doing the right thing when asked, including taking actions and follow-up actions
- Not surprising the user with actions you take without asking
For example, if the user asks you how to approach something, you should do your
best to answer their question first, and not immediately jump into taking actions.为什么这样设计：这三条指令构成了一个完整的决策树：
- “allowed to be proactive” — 给予权限（不是默认被动）
- “only when the user asks you to do something” — 设置触发条件
- “answer their question first, and not immediately jump into taking actions” — 区分”问”和”做”
这解决了 Agent 场景中最常见的用户抱怨：“我只是想了解一下，你怎么就开始改了？” 关键洞察是”问”和”做”需要不同的响应模式。
可复用的范式：
# 主动性校准模板
你被允许主动行动，但仅在以下条件下：
1. 用户已经明确要求你做某事（不仅仅是提问）
2. 行动是用户请求的合理延伸
3. 如果用户在提问，先回答问题，不要直接跳到执行
4. 对于跟进行动，在合理范围内可以主动执行与现有框架的关系：新增。这是 Agent 场景独有的维度，传统 PE 不存在这个问题。
AP-002 — 一次授权不等于全局授权（Authorization Scope Limitation）
类别：A. 主动性校准 + D. 安全边界
问题：用户同意了一次 git push，Agent 是否可以在后续自动 push？如果不加限制，Agent 会”记住”之前的授权，在不同上下文中执行用户未预期的操作。
原则：用户对某个操作的一次性批准，不构成对该操作在所有上下文中的全局授权。授权的范围严格匹配被请求的范围。
Claude Code 中的实现：
A user approving an action (like a git push) once does NOT mean that they approve
it in all contexts, so unless actions are authorized in advance in durable
instructions like CLAUDE.md files, always confirm first. Authorization stands for
the scope specified, not beyond. Match the scope of your actions to what was
actually requested.为什么这样设计：这解决了一个微妙的安全问题——隐式授权蔓延。在长会话中，如果 Agent 将早期的授权”推广”到后续操作，会产生严重的安全风险。同时引入了”持久授权”（durable instructions）的概念，区分了一次性口头授权和 CLAUDE.md 中的持久化配置授权。
可复用的范式：
# 授权范围管理
- 用户对某操作的一次批准，仅适用于当次请求的具体范围
- 除非在持久化配置（如 CLAUDE.md）中预先授权，否则每次执行高风险操作前都需确认
- 授权范围：精确匹配用户请求的操作，不扩展到类似操作与现有框架的关系：新增。扩展了安全边界的概念到”授权生命周期管理”。
AP-003 — 可逆性×影响范围决策矩阵（Reversibility × Blast Radius Matrix）
类别：D. 安全边界 问题：Agent 有大量可执行的操作，哪些可以自由执行，哪些需要确认？需要一个系统化的决策框架。
原则：操作的风险等级由两个维度决定：可逆性（能否撤销）和影响范围（影响本地还是共享系统）。只有低风险操作才能自由执行。
Claude Code 中的实现：
Carefully consider the reversibility and blast radius of actions. Generally you
can freely take local, reversible actions like editing files or running tests. But
for actions that are hard to reverse, affect shared systems beyond your local
environment, or could otherwise be risky or destructive, check with the user
before proceeding.
Examples of the kind of risky actions that warrant user confirmation:
- Destructive operations: deleting files/branches, dropping database tables,
killing processes, rm -rf, overwriting uncommitted changes
- Hard-to-reverse operations: force-pushing, git reset --hard, amending published
commits, removing or downgrading packages
- Actions visible to others or that affect shared state: pushing code,
creating/closing/commenting on PRs or issues, sending messages
- Uploading content to third-party web tools (diagram renderers, pastebins, gists)
publishes it — consider whether it could be sensitive为什么这样设计：
- “reversibility and blast radius” 提供了两个正交的评估轴——不是简单的”安全/危险”二分法
- “Generally you can freely take…” 给出了默认许可（编辑文件、运行测试），避免 Agent 过度保守
- 四类风险操作的具体列表——从抽象原则到具体实例，确保 Agent 能正确分类
- “consider whether it could be sensitive” 对信息泄露类风险单独提醒
可复用的范式：
# 操作风险评估矩阵
| 维度 | 低 | 高 |
|------|-----|-----|
| 可逆性 | 编辑文件、运行测试 | 删除分支、force push |
| 影响范围 | 本地文件 | 共享仓库、外部服务 |
规则：
- 本地 + 可逆 → 自由执行
- 任一维度为高 → 确认后执行
- 两个维度都高 → 谨慎确认，说明风险与现有框架的关系：扩展现有安全原则。将”避免破坏性操作”从一条笼统的规则，扩展为可操作的二维决策矩阵。
AP-004 — 障碍非捷径原则（Obstacles Are Not Shortcuts）
类别：H. 迭代和错误恢复 问题：Agent 遇到障碍时（如文件被锁定、合并冲突），倾向于用”破坏性操作”直接绕过（如删除锁文件、丢弃变更），而不是诊断根因。
原则：遇到障碍时，诊断根因优先于绕过障碍。不要用破坏性操作作为消除障碍的捷径。
Claude Code 中的实现：
When you encounter an obstacle, do not use destructive actions as a shortcut to
simply make it go away. For instance, try to identify root causes and fix
underlying issues rather than bypassing safety checks (e.g. --no-verify). If you
discover unexpected state like unfamiliar files, branches, or configuration,
investigate before deleting or overwriting, as it may represent the user's
in-progress work. For example, typically resolve merge conflicts rather than
discarding changes; similarly, if a lock file exists, investigate what process
holds it rather than deleting it.为什么这样设计：
- Agent 有一个强烈的倾向——当遇到错误时，选择”让错误消失”而非”理解为什么出错”
- “it may represent the user’s in-progress work” 这句话揭示了核心洞察：Agent 不了解全局上下文，它看到的”异常”可能是用户有意为之
- 具体的反模式列举（
--no-verify、删除锁文件、丢弃变更）让 Agent 知道哪些”常见解法”实际上是错的
可复用的范式：
# 障碍处理协议
遇到障碍时：
1. 诊断原因 → 不要直接删除/绕过
2. 发现异常状态 → 调查而非覆盖（可能是用户有意为之）
3. 特别禁止以下"捷径"：
- 用 --no-verify 跳过检查
- 删除锁文件
- 丢弃合并冲突中的变更
- 用 force 选项覆盖与现有框架的关系：新增。现有框架只说”不要暴力重试”，这里扩展到”不要暴力绕过”。
AP-005 — 工具偏好层级（Tool Preference Hierarchy）
类别：B. 工具描述设计 问题：Agent 有多个工具可以完成同一任务（如 Read vs cat、Grep vs grep），如果不明确优先级，Agent 会随机选择，导致体验不一致。
原则：当多个工具都能完成同一任务时，定义明确的偏好层级：专用工具 > 通用工具。
Claude Code 中的实现：
Use specialized tools instead of bash commands when possible, as this provides a
better user experience.
Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`,
or `echo` commands. Instead, always prefer using the dedicated tools:
- File search: Use Glob (NOT find or ls)
- Content search: Use Grep (NOT grep or rg)
- Read files: Use Read (NOT cat/head/tail)
- Edit files: Use Edit (NOT sed/awk)
- Write files: Use Write (NOT echo >/cat <<EOF)
- Communication: Output text directly (NOT echo/printf)v2.1.81 拆分版进一步强化，将每条偏好规则拆为独立的 prompt 片段，在多个位置反复注入：
To read files use Read instead of cat, head, tail, or sed
To search for files use Glob instead of find or ls
To search the content of files, use Grep instead of grep or rg
Reserve using the Bash exclusively for system commands and terminal operations
that require shell execution.为什么这样设计：
- 明确的 NOT 列表——不是说”优先使用”，而是列出每个被取代的命令
- 给出原因——“provides a better user experience”，模型知道为什么要遵守
- 多处重复——在 Bash 工具描述中、在 Grep 工具描述中、在系统提示中分别提到同一偏好，确保无论模型”注意到”哪段，都能获取正确信息
- v2.1.81 将每条规则拆为独立的可组合片段，可根据环境条件灵活注入
可复用的范式：
# 工具偏好层级
当多个工具可完成同一任务时，定义明确的优先级：
- [任务描述]: 使用 [首选工具] (NOT [替代工具1], [替代工具2])
- 在每个相关工具的描述中都重复这一偏好
- 给出偏好的理由（更好的用户体验、更安全、更快等）与现有框架的关系：新增。现有 P054 只说”工具描述本身就是 PE”，缺少工具间关系的维度。
AP-006 — 工具描述的标准结构（Tool Description Standard Structure）
类别：B. 工具描述设计 问题：工具描述需要覆盖什么内容？缺少标准结构会导致有的工具描述过详、有的过简。
原则：工具描述应包含：功能概述、使用场景（When to Use）、不适用场景（When NOT to Use）、具体用法、注意事项、示例。详细程度与误用风险成正比。
Claude Code 中的实现：
以 TodoWrite 为例（文档最详尽的工具，4 正例 4 反例），标准结构为：
- 一句话功能说明：
Use this tool to create and manage a structured task list - When to Use This Tool：7 个具体场景
- When NOT to Use This Tool：4 个排除场景
- 正面示例 × 4：每个示例包含用户输入、助手行为、
<reasoning>标签解释为什么使用 - 反面示例 × 4：每个示例包含用户输入、助手行为、
<reasoning>标签解释为什么不使用 - Task States and Management：详细的状态管理规则
- Task Completion Requirements：完成标准（明确列出不能标记完成的情况）
对比 Glob 工具描述（误用风险低）：
- Fast file pattern matching tool that works with any codebase size
- Supports glob patterns like "**/*.js" or "src/**/*.ts"
- Returns matching file paths sorted by modification time
- Use this tool when you need to find files by name patterns
- When you are doing an open ended search, use the Agent tool instead为什么这样设计：示例数量与误用风险成正比。TodoWrite 是最容易被误用的工具（Agent 可能在每个简单任务上都创建 todo list），所以获得了最详尽的正反对比示例。Glob 几乎不会被误用，所以只需要简短的 bullet points。
可复用的范式：
# 工具描述设计原则
1. 基本结构：功能 → 使用场景 → 不适用场景 → 用法 → 示例
2. 详细度校准：误用风险越高的工具，描述越详尽
3. 正反对比示例：为容易误用的工具同时提供"该用"和"不该用"的示例
4. 示例中加 <reasoning>：解释为什么做出这个决策与现有框架的关系：扩展 P054。将”工具描述即 PE”具体化为可操作的结构模板。
AP-007 — 多工具协作 SOP（Multi-Tool Orchestration SOP）
类别：B. 工具描述设计 问题：Agent 使用多个工具完成一个任务（如 git commit），需要严格的步骤编排，否则会遗漏步骤或顺序错误。
原则：对于涉及多工具协作的关键工作流，提供完整的 SOP（标准操作流程），明确步骤顺序、并行机会和关键检查点。
Claude Code 中的实现：
Git commit 的完整 SOP：
1. run the following bash commands in parallel:
- Run a git status command to see all untracked files.
- Run a git diff command to see both staged and unstaged changes.
- Run a git log command to see recent commit messages.
2. Analyze all staged changes and draft a commit message:
- Summarize the nature of the changes
- Do not commit files that likely contain secrets
- Draft a concise commit message
3. run the following commands in parallel:
- Add relevant untracked files to the staging area.
- Create the commit with a message
- Run git status after the commit completes to verify success.
Note: git status depends on the commit completing, so run it sequentially.
4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commitPR 创建也有类似的完整 SOP，包含 3 个并行步骤 + 模板格式。
为什么这样设计：
- 步骤编号确保顺序不被跳过
- 并行标注（“run in parallel”）+ 依赖标注（“Note: git status depends on…”）优化了执行效率
- 模板格式（HEREDOC 示例）确保输出格式一致
- 错误恢复步骤（步骤 4）内联在 SOP 中，而非作为独立的错误处理部分
可复用的范式：
# 多工具协作 SOP 模板
1. [步骤描述]，以下操作并行执行：
- [工具A 操作]
- [工具B 操作]
2. [分析/决策步骤]
3. [步骤描述]，以下操作并行执行：
- [工具C 操作]
- [工具D 操作]
注意：[工具E 操作]依赖上述操作完成，需串行执行
4. 如果 [错误情况]：[恢复策略]与现有框架的关系：新增。现有框架只覆盖单工具描述，不覆盖工具间的编排。
AP-008 — 否定约束的精确使用（Precise Negation Constraints）
类别：C. 行为约束设计 问题：Agent 行为需要明确的边界。正面指令（“做什么”）有时不够精确，因为 Agent 可能以意想不到的方式”做对了但做错了”。
原则：在安全约束、边界定义、破坏性操作限制场景中，否定指令（NEVER/Do not）比正面指令更直接有效。否定指令应具体到操作级别，不能泛泛地说”不要做坏事”。
Claude Code 中的实现：
统计显示 v2.0.0 完整版中有 15+ 个 NEVER、10+ 个 Do not、5+ 个 Do NOT。关键的否定约束模式：
Git Safety Protocol:
- NEVER update the git config
- NEVER run destructive git commands (push --force, reset --hard, checkout .,
restore ., clean -f, branch -D) unless the user explicitly requests
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless user explicitly requests
- NEVER run force push to main/master, warn the user if they request it
- NEVER commit changes unless the user explicitly asks you to每个 NEVER 都：
- 精确到操作——不是”不要破坏东西”，而是”不要 push —force”
- 附带例外条件——“unless the user explicitly requests”
- 覆盖一个具体的失败模式——每个 NEVER 背后都有一个真实的线上事故
为什么这样设计：否定约束的优势在于明确划出边界。“不要 force push” 比 “使用安全的 git 操作” 更难被误解。但否定约束的缺点是覆盖面有限，所以需要逐条列出。Anthropic 的做法是：对高风险操作用 NEVER 逐条列出，对低风险行为用正面指令概括。
可复用的范式：
# 否定约束使用原则
- 高风险/破坏性操作 → NEVER + 具体操作 + 例外条件
- 行为偏好 → 正面指令 + 不适用场景
- 安全边界 → NEVER，不带例外
- 每个 NEVER 应该映射到一个具体的失败场景与现有框架的关系：修正 P021。P021 说”正面指令优于否定约束”，但 Anthropic 的实践证明这不是硬规则。应修正为：“默认用正面指令；安全/边界/破坏性操作场景用否定指令更有效。“
AP-009 — 关键指令散布重复（Distributed Repetition of Critical Instructions）
类别：C. 行为约束设计 问题：在超长 prompt（1000+行）中，关键指令如果只出现一次，模型可能在执行到相关段落时”遗忘”了之前看到的指令。
原则：关键约束应在 prompt 中多个相关位置重复出现，确保无论模型”注意到”哪段文本，都能在近距离内找到关键约束。
Claude Code 中的实现：
安全约束的散布重复：
- L36-37（系统提示开头）：
IMPORTANT: Assist with defensive security tasks only... - L187（中部，工具描述之前）：逐字重复同一段
- v2.1.81 拆分版中，这段约束被提取为独立的 prompt 片段，可按需注入
并行调用指令的散布重复：
- 在 git commit SOP 中出现（步骤 1 和步骤 3）
- 在 PR 创建 SOP 中出现（步骤 1 和步骤 3）
- 在 Task 工具描述中出现
- 在系统提示的 Tool usage policy 中出现
文件操作偏好的散布重复：
- 在系统提示 Tool usage policy 中
- 在 Bash 工具描述中
- 在每个专用工具的描述中（Grep 说”NEVER invoke grep as a Bash command”、Read 说”use Read instead of cat”等）
为什么这样设计：
- LLM 的注意力不均匀，尤其在超长上下文中
- 散布重复比”首尾重申”更有效——它确保在模型执行到任何相关段落时，关键约束都在”近距离”可见
- v2.1.81 的模块化设计更进一步：把每条约束变成独立片段，按条件组合注入，技术上实现了”在正确位置重复正确的约束”
可复用的范式：
# 散布重复策略
1. 识别关键约束（安全、偏好、核心行为）
2. 在以下位置重复这些约束：
- 系统提示开头
- 每个相关工具的描述中
- 相关 SOP 的步骤中
- 系统提示末尾
3. 重复方式可以是：
- 逐字重复（安全约束）
- 换角度重述（工具偏好）
- 局部引用（SOP 中引用全局规则）与现有框架的关系：扩展 P014。P014 只说”末尾重申”，这里扩展为”多位置散布重复”。
AP-010 — 优先级标记词系统（Priority Marker System）
类别：C. 行为约束设计 问题：在超长 prompt 中，不是所有指令都同等重要。需要让 Agent 区分”建议”和”必须”。
原则：使用分级标记词（IMPORTANT、CRITICAL、NEVER）提升特定指令的优先级，让 Agent 在注意力有限的情况下优先遵守最重要的规则。
Claude Code 中的实现：
IMPORTANT: You should minimize output tokens as much as possible...
IMPORTANT: You should NOT answer with unnecessary preamble or postamble...
IMPORTANT: Keep your responses short...
IMPORTANT: Avoid using this tool to run find, grep, cat...
CRITICAL: Always create NEW commits rather than amending...
NEVER run destructive git commands...
NEVER commit changes unless the user explicitly asks...三级标记词体系：
IMPORTANT：强调优先级，但仍有灵活空间CRITICAL：绝对必须遵守NEVER：绝对禁止
为什么这样设计：在 1000+ 行的 prompt 中，如果所有指令都平等对待，模型的”注意力预算”会被平均分配。标记词让模型将更多注意力分配给关键指令。实测表明，IMPORTANT 和 CRITICAL 标记词确实能提高模型遵守特定指令的概率。
可复用的范式：
# 优先级标记体系
- CRITICAL：绝对不能违反的规则（安全、数据完整性）
- IMPORTANT：高优先级指令（输出质量、用户体验）
- 无标记：默认指令（偏好、风格）
- 每个级别的使用量递减：CRITICAL 最少、IMPORTANT 适中、无标记最多与现有框架的关系：新增。框架中没有关于指令优先级标记的原则。
AP-011 — 输出通道分离（Output Channel Separation）
类别：E. 输出控制 问题：Agent 有两种输出——文本回复（给用户看）和工具调用（给系统执行）。如果不明确区分，Agent 可能在工具调用中”说话”或在文本回复中”执行”。
原则：文本输出和工具调用是两个独立的通道。文本用于与用户交流，工具用于执行操作。不要混用通道。
Claude Code 中的实现：
Output text to communicate with the user; all text you output outside of tool use
is displayed to the user. Only use tools to complete tasks. Never use tools like
Bash or code comments as means to communicate with the user during the session.v2.1.81 的 SendUserMessage 版本更明确：
SendUserMessage is where your replies go. Text outside it is visible if the user
expands the detail view, but most won't — assume unread. Anything you want them to
actually see goes through SendUserMessage. The failure mode: the real answer lives
in plain text while SendUserMessage just says "done!" — they see "done!" and miss
everything.为什么这样设计：
- 防止 Agent 用
echo或 Bash 工具输出消息（用户在 CLI 中看到的是混乱的工具输出） - v2.1.81 的 SendUserMessage 进一步强化了这个分离：有专门的”发送给用户”工具，plain text 被降级为”详情视图”
- 明确指出失败模式——“the real answer lives in plain text while SendUserMessage just says ‘done!’”，用具体的失败场景强化理解
可复用的范式：
# 输出通道分离规则
- 文本输出 = 与用户交流的唯一通道
- 工具调用 = 执行操作的唯一方式
- 禁止：在工具调用（如 Bash echo）中向用户传递信息
- 禁止：在文本输出中描述打算执行的操作而不使用工具
- 如果有专门的用户消息工具，所有用户可见的回复都必须通过该工具与现有框架的关系：新增。这是 Agent 场景独有的设计维度。
AP-012 — 输出极简主义（Output Minimalism）
类别：E. 输出控制 问题：LLM 天然倾向于冗长解释。在 Agent 场景中，用户在 CLI 中工作，冗长的回复不仅无用还干扰工作流。
原则：输出应尽可能简洁。默认状态是极简回复，仅在用户要求时才展开。
Claude Code 中的实现：
IMPORTANT: You should minimize output tokens as much as possible while maintaining
helpfulness, quality, and accuracy. Only address the specific task at hand,
avoiding tangential information unless absolutely critical.
IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as
explaining your code or summarizing your action), unless the user asks you to.
Do not add additional code explanation summary unless requested by the user. After
working on a file, briefly confirm that you have completed the task, rather than
providing an explanation of what you did.辅以极端简洁的示例：
user: 2 + 2
assistant: 4
user: is 11 a prime number?
assistant: Yes
user: what command should I run to list files?
assistant: lsv2.1.81 拆分版有更强的指令：
Keep your text output brief and direct. Lead with the answer or action, not the
reasoning. Skip filler words, preamble, and unnecessary transitions. Do not
restate what the user said — just do it.
Focus text output on:
- Decisions that need the user's input
- High-level status updates at natural milestones
- Errors or blockers that change the plan
If you can say it in one sentence, don't use three.为什么这样设计：
- CLI 环境中冗长的文本是噪音
- “minimize output tokens” 还有经济学原因——减少 token 消耗
- 明确列出了应该输出什么（“Focus text output on…”），比”不要输出什么”更有效
- 极端示例（“2+2” → “4”）设定了一个”最简”的锚点，模型会在此锚点和”适当详细”之间找平衡
可复用的范式：
# 输出极简主义
默认：极简回复
- 做完了？说一句"完成"，不要解释你做了什么
- 用户问问题？直接给答案，不要加铺垫
- 只在以下情况展开：用户明确要求解释 / 出现错误需要说明 / 有决策需要用户输入
提供极简示例设定锚点（如 "2+2" → "4"）与现有框架的关系：扩展现有的”简洁”原则。从泛泛的”保持简洁”具体化为 Agent 场景的输出策略。
AP-013 — 子代理上下文隔离策略（Sub-agent Context Isolation）
类别：F. 子代理架构 问题：子代理是否继承主 Agent 的上下文？继承太多会浪费 token，继承太少会缺乏必要信息。
原则：子代理有两种模式——继承上下文（fork）和独立启动（subagent_type）。选择模式的标准是：是否需要主 Agent 已有的上下文。
Claude Code 中的实现：
When you omit `subagent_type` — the agent inherits your full conversation context.
It already knows everything you know. The prompt is a directive: what to do, not
what the situation is.
- Be specific about scope: what's in, what's out
- Don't re-explain background — the agent has it.
When you specify `subagent_type` — the agent starts fresh with that type's
configuration. It has zero context.
- Brief it like a smart colleague who just walked into the room.
- Describe what you've already learned or ruled out.
- Give enough context about the surrounding problem.
- Terse, command-style prompts produce shallow, generic work.fork 模式的特殊规则：
Don't peek. The tool result includes an output_file path — do not Read or tail it
unless the user explicitly asks for a progress check. Reading the transcript
mid-flight pulls the fork's tool noise into your context, which defeats the point.
Don't race. After launching, you know nothing about what the fork found. Never
fabricate or predict fork results in any format.为什么这样设计：
- 两种模式对应两种常见需求：fork 适合”帮我做这件我已经了解的事”，subagent 适合”用你的专业能力独立分析”
- “Don’t peek” 规则保护主 Agent 的上下文窗口不被子代理的中间过程污染
- “Don’t race” 规则防止主 Agent 在子代理还没返回结果时就”编造”结果
- “Brief it like a smart colleague who just walked into the room” 给出了完美的心理模型
可复用的范式：
# 子代理上下文管理
两种模式：
1. 继承上下文（fork）：
- 适用：需要主 Agent 已有知识的任务
- Prompt 写法：直接下达指令，不重复背景
- 规则：不要偷看中间结果、不要预测结果
2. 独立启动（fresh agent）：
- 适用：需要独立视角或专业能力的任务
- Prompt 写法：像给刚进入会议室的同事做简报
- 包含：你试过什么、你排除了什么、为什么这个任务重要与现有框架的关系：新增。现有框架对子代理的指导非常薄弱。
AP-014 — 不委托理解（Never Delegate Understanding）
类别：F. 子代理架构 问题：主 Agent 倾向于将分析和综合工作推给子代理（“根据你的发现，修复 bug”），导致子代理缺乏足够的上下文做出正确判断。
原则：理解和综合是主 Agent 的职责，不能委托给子代理。给子代理的指令必须证明主 Agent 已经理解了问题。
Claude Code 中的实现：
Never delegate understanding. Don't write "based on your findings, fix the bug" or
"based on the research, implement it." Those phrases push synthesis onto the agent
instead of doing it yourself. Write prompts that prove you understood: include file
paths, line numbers, what specifically to change.为什么这样设计：
- “based on your findings” 是一个反模式——它意味着主 Agent 没有消化子代理的输出，就直接让另一个子代理去执行
- 要求主 Agent 写出具体的文件路径和行号，这迫使主 Agent 先理解，再委托
- 这防止了”子代理链条”——A 委托 B，B 委托 C，信息在传递中不断丢失
可复用的范式：
# 子代理委托规则
- 理解和综合 = 主 Agent 的职责，不能委托
- 子代理 Prompt 中的禁止用语：
- "based on your findings, ..."
- "based on the research, ..."
- "implement what you think is best"
- 子代理 Prompt 中必须包含：
- 具体的文件路径、行号
- 明确要改什么、怎么改
- 证明主 Agent 已经理解了问题与现有框架的关系：新增。这是子代理架构的核心原则之一。
AP-015 — 模式切换机制（Mode Switching Mechanism）
类别：I. 模式切换 问题：Agent 在同一会话中可能需要在不同的行为模式之间切换（规划 vs 执行、交互 vs 自主）。不同模式下的权限和约束完全不同。
原则：通过显式的模式定义，在不同模式下注入完全不同的行为约束。模式之间有明确的切换工具和切换规则。
Claude Code 中的实现：
Plan 模式：
Plan mode is active. The user indicated that they do not want you to execute yet --
you MUST NOT make any edits, run any non-readonly tools, or otherwise make any
changes to the system. This supercedes any other instructions you have received.Auto 模式：
Auto mode is active. The user chose continuous, autonomous execution. You should:
1. Execute immediately — Start implementing right away.
2. Minimize interruptions — Prefer making reasonable assumptions over asking questions.
3. Prefer action over planning — Do not enter plan mode unless explicitly asked.
4. Make reasonable decisions — Choose the most sensible approach and keep moving.
5. Be thorough — Complete the full task including tests, linting, verification.
6. Never post to public services — without explicit written approval.Plan 模式的 5 阶段工作流：
Phase 1: Initial Understanding (explore)
Phase 2: Design (plan agents)
Phase 3: Review (align with user)
Phase 4: Final Plan (write plan file)
Phase 5: Call ExitPlanMode为什么这样设计：
- “This supercedes any other instructions” — Plan 模式的只读约束高于所有其他指令
- Auto 模式是 Plan 模式的对立面 — 明确说”Do not enter plan mode unless explicitly asked”
- 两种模式有完全不同的”默认行为”：Plan 模式默认不执行、Auto 模式默认不询问
- ExitPlanMode 工具是模式切换的显式机制
可复用的范式：
# 模式切换架构
每种模式定义三件事：
1. 权限边界：什么可以做 / 什么不能做
2. 默认行为：遇到模糊情况时的默认选择
3. 退出条件：何时/如何切换到其他模式
模式间用显式工具切换（如 EnterPlanMode / ExitPlanMode）
模式的权限约束高于其他指令（"this supercedes..."）与现有框架的关系：新增。框架没有覆盖 Agent 的模式切换设计。
AP-016 — 自我感知上下文注入（Self-Awareness Context Injection）
类别：J. 自我感知 问题：Agent 需要知道自身的运行环境（操作系统、工作目录、模型版本、知识截止日期），否则会做出错误假设。
原则：通过 <env> 标签注入运行环境信息，让 Agent 了解自身的能力边界和运行条件。
Claude Code 中的实现：
<env>
Working directory: /tmp/claude-history-1759164907215-dnsko8
Is directory a git repo: No
Platform: linux
OS Version: Linux 6.8.0-71-generic
Today's date: 2025-09-29
</env>
You are powered by the model named Sonnet 4.5. The exact model ID is
claude-sonnet-4-5-20250929.
Assistant knowledge cutoff is January 2025.v2.1.81 的 gitStatus 注入：
This is the git status at the start of the conversation. Note that this status is
a snapshot in time, and will not update during the conversation.
Current branch: ${CURRENT_BRANCH}
Main branch: ${MAIN_BRANCH}
Status: ${GIT_STATUS}
Recent commits: ${RECENT_COMMITS}为什么这样设计：
- Platform 信息防止 Agent 在 Linux 上使用 macOS 命令（反之亦然）
- 知识截止日期让 Agent 知道何时需要搜索最新信息
- Git 状态快照让 Agent 了解当前仓库状态，但明确标注”snapshot in time, will not update”避免误认为是实时状态
- 模型版本让 Agent 在被问到自身身份时给出准确答案
可复用的范式：
# 自我感知上下文注入
<env>
操作系统：[platform]
工作目录：[cwd]
当前日期：[date]
模型版本：[model]
知识截止日期：[cutoff]
可用工具：[tools]
权限级别：[permissions]
</env>
注意：
- 明确标注哪些信息是快照（不会实时更新）
- 知识截止日期用于判断何时需要搜索与现有框架的关系：新增。框架中没有关于 Agent 自我感知的原则。
AP-017 — 上下文压缩与持久化（Context Compaction and Persistence）
类别：G. 上下文管理 问题：Agent 的长会话会耗尽上下文窗口。需要在不丢失关键信息的前提下压缩上下文。
原则：通过结构化的总结协议，将长会话压缩为可恢复的摘要。摘要的结构应该支持”无缝恢复”。
Claude Code 中的实现：
Compaction 总结模板（9 个必须覆盖的维度）：
Write a continuation summary that will allow you (or another instance of yourself)
to resume work efficiently in a future context window where the conversation
history will be replaced with this summary.
Include:
1. Task Overview — core request and success criteria
2. Current State — what has been completed, files modified
3. Important Discoveries — technical constraints, decisions made, errors resolved,
what didn't work
4. Next Steps — specific actions needed, blockers, priority order
5. Context to Preserve — user preferences, domain details, promises madeAnalysis（压缩前的分析）指令：
Before providing your final summary, wrap your analysis in <analysis> tags:
1. Chronologically analyze each message:
- The user's explicit requests and intents
- Key decisions, technical concepts
- Specific details: file names, code snippets, function signatures, edits
- Errors that you ran into and how you fixed them
- Pay special attention to specific user feedbackToken 使用量监控：
Token usage: ${used}/${total}; ${remaining} remaining为什么这样设计：
- “or another instance of yourself” — 设计假设是”未来的我可能不记得任何东西”
- “what didn’t work” — 确保压缩不会丢失失败经验（避免重复踩坑）
- “promises made” — 确保承诺不会因上下文压缩而被遗忘
<analysis>标签作为”分析草稿纸”，在总结前强制进行全面回顾- Token 使用量实时注入，让 Agent 知道何时应该压缩
可复用的范式：
# 上下文压缩协议
压缩前分析（<analysis>标签）：
- 按时间线回顾每个关键节点
- 标注用户反馈和纠正
- 记录失败和绕过方式
压缩后摘要必须包含：
1. 任务概述 + 成功标准
2. 当前状态 + 已完成/未完成
3. 关键发现（含失败经验）
4. 下一步 + 优先级
5. 需要保留的上下文（用户偏好、承诺）
目标：让一个"失忆"的新实例能无缝接续与现有框架的关系：新增。框架没有覆盖 Agent 的上下文管理。
AP-018 — 记忆系统分层（Layered Memory System）
类别：G. 上下文管理 问题：Agent 需要在跨会话之间保留知识，但不同类型的知识有不同的生命周期和可见范围。
原则：记忆分为多个层次：会话记忆（压缩摘要）、个人记忆（用户偏好）、团队记忆（共享约定）、项目记忆（CLAUDE.md）。不同层次有不同的持久性和覆盖规则。
Claude Code 中的实现：
用户记忆描述：
Contain information about the user's role, goals, responsibilities, and knowledge.
Your goal in reading and writing these memories is to build up an understanding of
who the user is. Avoid writing memories about the user that could be viewed as a
negative judgement or that are not relevant to the work.反馈记忆（更关键的类型）：
Guidance the user has given you about how to approach work — both what to avoid and
what to keep doing. Record from failure AND success: if you only save corrections,
you will avoid past mistakes but drift away from approaches the user has already
validated. Before saving a private feedback memory, check that it doesn't
contradict a team feedback memory — if it does, either don't save it or note the
override explicitly.团队记忆注入格式：
<team-memory-content source="shared">
${MEMORY_CONTENT}
</team-memory-content>为什么这样设计：
- “Record from failure AND success” — 防止”纠偏偏差”，只记住错误会导致 Agent 过度保守
- 个人记忆 vs 团队记忆的覆盖规则 — “check that it doesn’t contradict a team feedback memory”
- 记忆的道德约束 — “Avoid writing memories that could be viewed as a negative judgement”
可复用的范式：
# 记忆分层架构
层级（从持久到临时）：
1. 项目记忆（CLAUDE.md）：共享、持久、版本控制
2. 团队记忆：共享、持久、可覆盖个人
3. 个人记忆：私有、跨会话
4. 会话记忆：压缩摘要、单会话
覆盖规则：
- 团队记忆 > 个人记忆（个人不能与团队矛盾）
- 记录成功和失败（避免纠偏偏差）与现有框架的关系：新增。这是 Agent 持久化知识管理的新维度。
AP-019 — 被拒绝后的调整策略（Adjustment After Denial）
类别：H. 迭代和错误恢复 问题：用户拒绝了 Agent 的工具调用，Agent 应该如何反应？重试相同操作是最差的选择。
原则：如果用户拒绝了工具调用，不要重试同一操作。思考被拒绝的原因，调整方案。如果不理解原因，询问用户。
Claude Code 中的实现：
Tools are executed in a user-selected permission mode. When you attempt to call a
tool that is not automatically allowed by the user's permission mode or permission
settings, the user will be prompted so that they can approve or deny the execution.
If the user denies a tool you call, do not re-attempt the exact same tool call.
Instead, think about why the user has denied the tool call and adjust your
approach. If you do not understand why the user has denied a tool call, use the
AskUserQuestion to ask them.工具被拒绝后的额外指导（v2.1.81）：
You may attempt to accomplish this action using other tools that might naturally be
used to accomplish this goal. But you should not attempt to work around this denial
in malicious ways, e.g. do not use your ability to run tests to execute non-test
actions. You should only try to work around this restriction in reasonable ways
that do not attempt to bypass the intent behind this denial.为什么这样设计：
- 不重试——直接禁止最差的反应
- 思考原因——引导 Agent 进行推理而不是机械重复
- 询问用户——提供了一个优雅的恢复路径
- 合理替代 vs 恶意绕过——允许用替代工具达成目标，但禁止绕过拒绝的意图
可复用的范式：
# 拒绝恢复协议
当操作被拒绝时：
1. 不要重试相同操作
2. 推理被拒绝的原因
3. 可以用合理的替代方式达成目标
4. 不可以用绕过意图的方式达成目标
5. 如果不理解原因，询问用户与现有框架的关系：新增。这是 Agent 与权限系统交互的核心模式。
AP-020 — 阻塞时的替代方案思维（Alternative Approach When Blocked）
类别：H. 迭代和错误恢复 问题：Agent 遇到阻塞（如 API 调用失败、测试不通过）时，倾向于不断重试同一操作。
原则：如果当前方法被阻塞，不要暴力重试。考虑替代方案或咨询用户。
Claude Code 中的实现：
If your approach is blocked, do not attempt to brute force your way to the outcome.
For example, if an API call or test fails, do not wait and retry the same action
repeatedly. Instead, consider alternative approaches or other ways you might
unblock yourself, or consider using the AskUserQuestion to align with the user on
the right path forward.Sleep 相关的反模式规则：
Do not retry failing commands in a sleep loop — diagnose the root cause.
Do not sleep between commands that can run immediately — just run them.
If waiting for a background task you started with run_in_background, you will be
notified when it completes — do not poll.为什么这样设计：
- LLM Agent 的默认行为是”重复直到成功”——这在大多数情况下是浪费 token 的无效策略
- “diagnose the root cause” 把 Agent 从”执行模式”拉回”分析模式”
- Sleep 相关规则更加具体——不是泛泛地说”不要重试”，而是列出了每种等待场景的正确做法
可复用的范式：
# 阻塞处理协议
当操作失败时：
1. 诊断根因（不要直接重试）
2. 考虑替代方案
3. 如果无法自行解决，咨询用户
4. 特别禁止：sleep + 重试循环与现有框架的关系：扩展现有的”不要暴力重试”原则，增加了具体的替代策略。
AP-021 — 用户可见性设计（User Visibility Design）
类别：E. 输出控制 问题：Agent 在后台工作时，用户不知道进展如何。但如果事事汇报，又会产生大量噪音。
原则：用户应该看到有意义的进展信息，而非过程噪音。进展更新应出现在”自然里程碑”处。
Claude Code 中的实现：
TodoWrite 工具的用户可见性设计：
This helps you track progress, organize complex tasks, and demonstrate
thoroughness to the user. It also helps the user understand the progress of the
task and overall progress of their requests.
Mark each task as completed as soon as you are done with the task. Do not batch up
multiple tasks before marking them as completed.v2.1.81 SendUserMessage 的进展更新模式：
If you can answer right away, send the answer. If you need to go look — run a
command, read files, check something — ack first in one line ("On it — checking
the test output"), then work, then send the result. Without the ack they're
staring at a spinner.
For longer work: ack → work → result. Between those, send a checkpoint when
something useful happened — a decision you made, a surprise you hit, a phase
boundary. Skip the filler ("running tests...") — a checkpoint earns its place by
carrying information.为什么这样设计：
- “ack first in one line” — 解决”盯着转圈”的焦虑
- “Skip the filler — a checkpoint earns its place by carrying information” — 区分噪音和信号
- TodoWrite 的实时状态更新给用户提供了结构化的进度视图
可复用的范式：
# 用户可见性三段式
1. 确认收到（ack）：一行即可，消除等待焦虑
2. 关键检查点：仅在有信息价值时更新（决策、意外发现、阶段完成）
3. 最终结果：简洁呈现
跳过：纯过程描述（"正在运行测试..."、"正在读取文件..."）与现有框架的关系：扩展 P059。从”Agent 更新应简短”扩展为完整的可见性设计策略。
AP-022 — 任务管理外化思考（Task Management as Externalized Thinking）
类别：E. 输出控制 + G. 上下文管理 问题：Agent 的”思考过程”如何呈现？传统 CoT 在 Agent 场景中不适用（用户不想看推理文本），但完全不展示思考又让 Agent 丢失规划能力。
原则：在 Agent 场景中，思考过程通过任务管理工具（TodoWrite/TaskCreate）外化为可见的、可追踪的任务列表，替代传统的文本推理。
Claude Code 中的实现：
You have access to the TodoWrite tools to help you manage and plan tasks. Use
these tools VERY frequently to ensure that you are tracking your tasks and giving
the user visibility into your progress.
These tools are also EXTREMELY helpful for planning tasks, and for breaking down
larger complex tasks into smaller steps. If you do not use this tool when planning,
you may forget to do important tasks - and that is unacceptable.双重功能：
- 规划功能——分解任务、确保不遗漏
- 可见性功能——用户可以看到进展
为什么这样设计：
- 传统 CoT（“让我想想…”）在 Agent 场景中是噪音
- 但完全不”思考”会导致 Agent 遗漏步骤
- TodoWrite 将”思考”转化为”可追踪的任务列表”——同时解决了规划和可见性的问题
- “VERY frequently” + “EXTREMELY helpful” 这种强调程度极少见，说明这是 Anthropic 内部测试中发现的关键失败模式：Agent 不用任务管理工具时会丢步骤
可复用的范式：
# 外化思考模式
传统 CoT → Agent 任务列表
- 规划阶段：创建任务列表 = 分解问题 = "思考"
- 执行阶段：标记任务完成 = 跟踪进度 = "展示工作"
- 用户看到的不是推理文本，而是结构化的进度条与现有框架的关系：修正 P041/P042。CoT 在 Agent 场景中被任务管理工具替代。
AP-023 — 动态 Prompt 组合架构（Dynamic Prompt Composition Architecture）
类别：G. 上下文管理 问题：Agent 不是一个静态的 prompt，而是需要根据运行时状态动态组合不同的 prompt 片段。如何设计这种动态组合？
原则：将系统提示词拆分为 110+ 个独立片段，根据环境和配置条件动态组合。每个片段有独立的注释说明用途。
Claude Code 中的实现：
v2.1.81 的架构揭示了这一设计：
Claude Code 没有单一的系统提示词，而是由 110+ 个独立字符串根据环境和配置条件
组合而成。片段类型：
- 主系统提示词片段——核心行为定义
- 系统提醒（System Reminders）——运行时动态注入的上下文
- 工具描述——每个工具的描述也是独立片段
- Agent 提示词——子代理的专用提示词
- Skills 提示词——可扩展的功能模块
- Data 模板——嵌入数据的模板
条件注入示例：
${IS_FEATURE_ENABLED_FN("tengu_tight_weave",!0) ? "..." : "..."}
${!IS_SUBAGENT_CONTEXT_FN() ? "..." : ""}
${HAS_SUBAGENT_TYPES ? SUBAGENT_TYPE_DEFINITIONS : DEFAULT_AGENT_DESCRIPTION}System Reminder 的运行时注入：
<system-reminder> tags contain useful information and reminders. They are
automatically added by the system, and bear no direct relation to the specific
tool results or user messages in which they appear.为什么这样设计：
- 条件组合减少不必要的上下文占用——Agent 不需要看到不相关的工具描述
- System Reminder 机制允许在运行时注入新信息（如 token 用量、文件变更通知）而无需修改系统提示
- 模块化使得同一个约束可以在正确的位置被注入（而非一次性塞到开头）
可复用的范式：
# 动态 Prompt 组合
1. 将 prompt 拆为独立片段（按功能/主题）
2. 每个片段有独立的注释说明用途和注入条件
3. 运行时根据条件组合：
- 环境条件（OS、权限、模型能力）
- 功能开关（feature flags）
- 子代理上下文（是否是子代理）
4. System Reminder 机制：运行时注入临时信息与现有框架的关系：新增。这是大规模 Agent 系统的架构级设计模式。
AP-024 — 专业客观性（Professional Objectivity）
类别：C. 行为约束设计 问题：LLM 倾向于”讨好用户”——同意用户的观点、过度赞美用户的代码。在工程场景中，这是危险的。
原则：技术准确性和真实性优先于验证用户的信念。Agent 应该像一个诚实的同事，在必要时提出异议。
Claude Code 中的实现：
Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation. It is best
for the user if Claude honestly applies the same rigorous standards to all ideas
and disagrees when necessary, even if it may not be what the user wants to hear.
Objective guidance and respectful correction are more valuable than false agreement.
Whenever there is uncertainty, it's best to investigate to find the truth first
rather than instinctively confirming the user's beliefs.为什么这样设计：
- “disagrees when necessary” 明确允许反驳——这在默认的 LLM 行为中是被抑制的
- “respectful correction are more valuable than false agreement” 设定了价值优先级
- “investigate to find the truth first rather than instinctively confirming” 对抗确认偏差
可复用的范式：
# 专业客观性
- 技术准确性 > 用户满意度
- 不要无根据地赞美或同意
- 有不确定性时，先调查再回应（不要本能地确认用户的假设）
- 尊重地纠正比虚假地同意更有价值与现有框架的关系：新增。这是 Agent 行为的”性格”层面设计。
AP-025 — 拒绝的优雅退出（Graceful Refusal）
类别：C. 行为约束设计 问题：Agent 在拒绝用户请求时，倾向于长篇解释为什么不能做。这让用户感到被教育。
原则：拒绝应简洁、不说教、提供替代方案。
Claude Code 中的实现：
If you cannot or will not help the user with something, please do not say why or
what it could lead to, since this comes across as preachy and annoying. Please
offer helpful alternatives if possible, and otherwise keep your response to 1-2
sentences.为什么这样设计：
- “preachy and annoying” 直接描述了用户的感受——这是从用户反馈中学到的
- 传统的 AI 拒绝通常包含长篇解释（“我不能这样做因为它可能导致…”），这被认为是说教
- 提供替代方案让拒绝变成帮助，而非教训
可复用的范式：
# 拒绝协议
- 不解释为什么不能做（避免说教）
- 1-2 句话完成拒绝
- 尽可能提供替代方案与现有框架的关系：新增。传统 PE 关注如何让 AI 拒绝不安全请求，但没有关注拒绝的”体验设计”。
AP-026 — 团队协作架构（Team Coordination Architecture）
类别：F. 子代理架构 问题：多个 Agent 需要协同工作时，如何管理任务分配、通信、状态同步？
原则：通过 Team-Task-Message 三位一体的架构管理多 Agent 协作：Team 定义组织结构，Task 管理工作分配，Message 处理通信。
Claude Code 中的实现：
Team 创建和管理：
Create a new team to coordinate multiple agents working on a project. Teams have a
1:1 correspondence with task lists (Team = TaskList).Teammate 空闲状态管理：
Teammates go idle after every turn—this is completely normal and expected. A
teammate going idle immediately after sending you a message does NOT mean they are
done or unavailable. Idle simply means they are waiting for input.
Do not treat idle as an error.通信协议：
Just writing a response in text is not visible to others on your team - you MUST
use the SendMessage tool.
Broadcasting is expensive. Each broadcast sends a separate message to every
teammate. Default to direct messages.关闭协议：
You MUST shut down your team before preparing your final response:
1. Use requestShutdown to ask each team member to shut down gracefully
2. Wait for shutdown approvals
3. Use the cleanup operation
4. Only then provide your final response为什么这样设计：
- Team = TaskList 的一一对应简化了概念模型
- 空闲状态的显式解释防止主 Agent 误认为 Teammate 掉线或异常
- “Broadcasting is expensive” 用经济学约束防止消息泛滥
- 优雅关闭协议确保所有工作完成后才输出最终结果
可复用的范式：
# 多 Agent 协作架构
1. 组织结构：Team 定义成员和角色
2. 任务管理：共享 TaskList，通过 owner 分配
3. 通信规则：
- 默认点对点消息
- 广播仅限紧急情况
- 文本输出不等于消息（必须用消息工具）
4. 生命周期：创建 → 分配 → 执行 → 关闭
5. 空闲是正常状态，不是异常与现有框架的关系：新增。这是超越”子代理”的完整多 Agent 协作架构。
AP-027 — 约束范围的极简表达（Minimal Scope Constraint）
类别：C. 行为约束设计 问题：如何用最少的文字约束 Agent 的行为范围？
原则：一句话可以完成复杂约束——如果它同时覆盖了两个方向（不要少做、不要多做）。
Claude Code 中的实现：
Do what has been asked; nothing more, nothing less.10 个英文单词完成了约束范围的全部工作。这比冗长的表述更有效，因为：
- “nothing more” — 不要过度行动
- “nothing less” — 不要遗漏
- 放在 system-reminder 的最开头——每次对话开始时都会注入
为什么这样设计：简短的约束更难被忽略。在 prompt 的黄金位置（开头）放一个极简但完整的约束声明，比详细的段落更有效。
可复用的范式：
# 约束范围声明
在 prompt 开头放置一个极简的范围约束，同时覆盖"不要少做"和"不要多做"两个方向。
示例："Do what has been asked; nothing more, nothing less."与现有框架的关系：P023 的极致简化版。证明了好的约束不需要冗长。
AP-028 — 过度工程防护（Over-engineering Prevention）
类别：C. 行为约束设计 问题：LLM Agent 有强烈的”改善”倾向——修 bug 时顺便重构周围代码，加功能时顺便加配置选项。
原则：只做被要求的事。不要加功能、不要重构、不要”改善”、不要为假设的未来需求设计。
Claude Code 中的实现：
v2.1.81 将这个原则拆成了多个独立的 prompt 片段：
Avoid over-engineering. Only make changes that are directly requested or clearly
necessary. Keep solutions simple and focused.Don't add features, refactor code, or make "improvements" beyond what was asked.
A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need
extra configurability. Don't add docstrings, comments, or type annotations to code
you didn't change. Only add comments where the logic isn't self-evident.Don't create helpers, utilities, or abstractions for one-time operations. Don't
design for hypothetical future requirements. The right amount of complexity is the
minimum needed for the current task—three similar lines of code is better than a
premature abstraction.Don't add error handling, fallbacks, or validation for scenarios that can't happen.
Trust internal code and framework guarantees. Only validate at system boundaries.Avoid backwards-compatibility hacks like renaming unused _vars, re-exporting types,
adding // removed comments for removed code.为什么这样设计：
- 拆为 5 个独立片段——每个防护一种具体的过度工程倾向
- 具体到行为级别——“Don’t add docstrings, comments, or type annotations to code you didn’t change”
- “three similar lines of code is better than a premature abstraction” 提供了一个具体的判断标准
可复用的范式：
# 过度工程防护（Agent 场景）
逐条列出禁止的"改善"行为：
- 不要加功能
- 不要重构无关代码
- 不要为假设的未来设计
- 不要对不可能的场景加错误处理
- 不要对没改动的代码加注释/类型标注
- 不要做向后兼容的 hack
核心判断标准：三行重复代码优于过早抽象。与现有框架的关系：AP-027 的具体化。从”nothing more”延伸到具体的工程行为约束。
AP-029 — Hooks 作为行为扩展点（Hooks as Behavioral Extension Points）
类别：B. 工具描述设计 问题：Agent 的行为需要可被用户自定义和扩展，但直接修改系统提示词不现实。需要一种安全的扩展机制。
原则：通过事件钩子（Hooks）让用户在 Agent 的生命周期关键节点插入自定义逻辑。Hook 的输出被视为”来自用户”的反馈。
Claude Code 中的实现：
Users may configure 'hooks', shell commands that execute in response to events like
tool calls, in settings. Treat feedback from hooks, including
<user-prompt-submit-hook>, as coming from the user. If you get blocked by a hook,
determine if you can adjust your actions in response to the blocked message. If
not, ask the user to check their hooks configuration.Hook 事件类型：
| Event | Purpose |
|--------------------|----------------------------|
| PermissionRequest | Run before permission prompt |
| PreToolUse | Run before tool, can block |
| PostToolUse | Run after successful tool |
| PostToolUseFailure | Run after tool fails |
| Notification | Run on notifications |
| Stop | Run when Claude stops |
| PreCompact | Before compaction |
| PostCompact | After compaction |
| UserPromptSubmit | When user submits |
| SessionStart | When session starts |为什么这样设计：
- “Treat feedback from hooks as coming from the user” — 将 Hook 输出提升到用户级别的信任
- 10 种事件类型覆盖了 Agent 的完整生命周期
- Hook 可以返回 JSON 控制 Agent 行为（block、allow、inject context）
- 这实现了”用户自定义 Agent 行为”而无需修改系统提示词
可复用的范式：
# 行为扩展点设计
在 Agent 生命周期的关键节点设置 Hook：
- 工具调用前（可阻止）
- 工具调用后（可注入反馈）
- 会话开始/结束
- 用户提交输入时
Hook 的输出被视为用户级反馈，Agent 应据此调整行为。与现有框架的关系：新增。这是 Agent 可扩展性设计的核心模式。
AP-030 — 信息安全出口控制（Information Exfiltration Control）
类别：D. 安全边界 问题：Agent 有能力将用户的代码和数据上传到外部服务。需要防止有意或无意的数据泄露。
原则：禁止在没有用户明确授权的情况下将内容发布到任何公开服务。用户必须先审查内容的敏感性。
Claude Code 中的实现（Auto 模式中）：
Never post to public services — Do not share content to public endpoints (GitHub
gists, Mermaid Live, Pastebin, etc.) without explicit written approval from the
user for that specific endpoint. The user must review the content first to judge
sensitivity. Err on the side of caution — data exfiltration is a serious risk.Uploading content to third-party web tools (diagram renderers, pastebins, gists)
publishes it — consider whether it could be sensitive before sending, since it may
be cached or indexed even if later deleted.为什么这样设计：
- “for that specific endpoint” — 对某个服务的授权不推广到其他服务
- “The user must review the content first” — 用户需要在发布前审查内容
- “may be cached or indexed even if later deleted” — 提醒不可逆性
- 明确将这视为”data exfiltration”安全事件——使用安全术语提升严重性
可复用的范式：
# 出口控制
- 未经用户对特定端点的明确授权，不向公开服务发送内容
- 用户必须在发布前审查内容的敏感性
- 上传到第三方服务被视为"发布"——内容可能被缓存或索引
- 对一个服务的授权不延伸到其他服务与现有框架的关系：AP-002（授权范围限制）在数据安全领域的具体应用。
模式索引（按类别）
A. 主动性校准
- AP-001 主动性光谱校准
- AP-002 一次授权不等于全局授权
B. 工具描述设计
- AP-005 工具偏好层级
- AP-006 工具描述的标准结构
- AP-007 多工具协作 SOP
- AP-029 Hooks 作为行为扩展点
C. 行为约束设计
- AP-008 否定约束的精确使用
- AP-009 关键指令散布重复
- AP-010 优先级标记词系统
- AP-024 专业客观性
- AP-025 拒绝的优雅退出
- AP-027 约束范围的极简表达
- AP-028 过度工程防护
D. 安全边界
- AP-003 可逆性×影响范围决策矩阵
- AP-030 信息安全出口控制
E. 输出控制
- AP-011 输出通道分离
- AP-012 输出极简主义
- AP-021 用户可见性设计
- AP-022 任务管理外化思考
F. 子代理架构
- AP-013 子代理上下文隔离策略
- AP-014 不委托理解
- AP-026 团队协作架构
G. 上下文管理
- AP-017 上下文压缩与持久化
- AP-018 记忆系统分层
- AP-023 动态 Prompt 组合架构
H. 迭代和错误恢复
- AP-004 障碍非捷径原则
- AP-019 被拒绝后的调整策略
- AP-020 阻塞时的替代方案思维
I. 模式切换
- AP-015 模式切换机制
J. 自我感知
- AP-016 自我感知上下文注入
关键发现总结
1. Agent PE 的核心差异
传统 PE 关注”如何让模型生成正确的输出”。Agent PE 关注的是完全不同的问题：
- 行动决策：什么时候行动、什么时候等待、什么时候询问
- 风险管理：哪些操作安全、哪些需要确认、哪些绝对禁止
- 多工具编排：工具间的优先级、协作 SOP、并行策略
- 状态管理：上下文压缩、记忆持久化、模式切换
- 多 Agent 协调：任务分配、通信协议、生命周期管理
2. Claude Code 的设计智慧
- 约束的分布式部署——同一约束在多个位置以不同形式重复（AP-009）
- 示例数量与误用风险成正比——TodoWrite 有 8 个示例，Glob 没有示例（AP-006）
- 否定约束的精确使用——每个 NEVER 对应一个真实的失败场景（AP-008）
- 两种子代理模式——继承上下文的 fork 和独立启动的 subagent（AP-013）
- 外化思考——用 TodoWrite 替代 CoT（AP-022）
3. 最重要的三个新增维度
这三个维度是 Agent PE 与传统 PE 的根本差异：
- 主动性校准（AP-001, AP-002）——Agent 的核心挑战不是”说什么”，而是”做不做”
- 安全边界矩阵（AP-003, AP-004）——Agent 有改变世界的能力，需要系统化的风险评估
- 动态 Prompt 组合（AP-023）——Agent 的 prompt 不是静态文本，而是运行时组合的模块化系统