Agent guidance composition

必要关系

写 prompt、skill 正文或交接块前，恢复会改变行动的关系：

1. 对象与目标：处理什么，期望哪种可观察变化；哪些相邻结果不合格。
2. 来源与状态：事实、决定、约束、指令、观察、推断、候选、未知和参考分别是什么，当前 canonical source 在哪里。
3. 接收上下文：Agent 已有什么、能读什么、在哪个 workspace、可用哪些工具；哪些只是推测。
4. 允许效果：能读、改、执行、发布到哪里，何时停止、转交或请求授权；prompt 不产生权限。
5. 判断与验收：什么关系必须成立，什么证据可观察，谁拥有最终接受权。
6. 未知与失败：缺口、冲突、能力不足或验证失败会阻止什么，哪些局部结果仍然有效。
7. 返回关系：结果给谁，接收者下一步需要什么结果、依据、验证、未知或决定请求。

不要求每个任务都出现七个标题；它们用于防止承重语义消失。结构服从行动依赖。

一段 prompt 或 skill 方法通常沿着以下关系组织：对象形成 → 支配关系 → 当前矛盾或决策 → 允许行动 → 验证与返回。角色词、形容词和“主动一点”不能代替这些关系；例子只能帮助识别边界， 不能代替来源和方法。

压缩与展开

先做删除检验：删掉一段是否改变对象、来源地位、范围、判断路径、效果、失败处理、返回或 验收？若是承重语义，保留或移动到调用时仍能发现的位置。其余重复、礼貌性前言、无信息总结 和不会改变下一步的背景才压缩。

根 skill 只保留触发、主要判断、边界和路由；条件细节放 reference。description 是选择信号， 不是完整说明书。示例展示边界或契约，不能替代规则；schema 只有在下游真的需要机械解析时才用。

表达顺序通常是对象/来源/目标 → 影响判断的条件 → 行动与验证 → 返回与接受。不要要求 Agent 复述全部上下文来证明理解；只有回显能发现高风险歧义或满足外部协议时才保留。

长任务、恢复或交接时，重新加载一个短 focus anchor（当前目标、采用的方法、边界、下一步和 返回位置），不要把整个理论、历史或所有 references 重新塞回上下文。

多步骤与失败

包含依赖、交接、等待、并行或验证回返时，复用已有 Plan/Task/Todo work map，说明当前 bounded task、完成观察、证据和返回位置；不要新建第二份权威计划。一步、低风险、可逆且无依赖的动作可 直接表达。

失败时返回实际尝试、观察到的错误、受阻范围、仍有效的产物和继续所需的事实/能力/授权。 不要用“已完成”包装部分产物，也不要把所有未知升级成阻塞提问。

上下文作为交互界面

用于设计和评审 Agent 所见的上下文视图及操作提示，不实现存储、权限或模型注意力算法。 目标是在任务正确性和来源边界成立的前提下，减少无关信息、发现困难和不必要的展开成本， 不是单独追求最短 prompt 或最多工具调用。

工作假设与适用边界

上下文既是阅读材料，也是 Agent 认识状态和发现操作的界面：就地交互回答“在哪里发现、 如何操作”，渐进披露回答“现在展示多少、何时展开”。这里的注意力分层是信息设计原则， 不是 Transformer attention 的机制解释，也不是已验证的模型通则。

当 Agent 不知道内容被省略、找不到相关入口、读后失去位置，或被无关详情淹没时，用此方法 提出最小改动。若错误源于读取接口缺失、权限、分页一致性或数据丢失，先交给实现 owner； 不能靠提示词补出能力。内容少且已清晰时，可以不分层、不新增帮助。

围绕对象组织，而非仅把提示移到末尾

先确认要支持的判断和信息缺口，再检查每个视图能否回答以下问题。不要求固定字段或模板：

• 对象：这是什么，来自哪里，属于哪个任务、会话或文件？
• 范围与状态：当前显示哪一部分，是否完整、过期、未加载或不可访问？
• 可用操作：需要补齐哪个缺口时，可以通过哪个真实入口、什么准确引用获取？
• 反馈：操作返回了什么，当前位置在哪里，能否继续、何时已到底或需要换路？

“就近”首先是作用域明确：帮助与其对象组成可理解的单元；token 距离近只是可试验的布局 选项。不要为了移动提示而打乱消息角色、时间顺序、当前请求或工具调用与返回的配对。

依据当前需要渐进披露

可以用三种信息职责检查设计，不必实现三个层级、状态机或数据副本：

分层不等于按年龄或长度分类：早期约束可能仍是当前关键，最近日志也可能无需全文常驻。 判断依据来自任务和已有宿主状态，不因此新增模型重要性打分器。展开也不意味着内容永久 提升为核心上下文；是否保留取决于后续需要，不能破坏当前执行连续性。

折叠细节时保留可发现线索和有效引用；不以摘要替代原文读取，不必生成摘要才能分层。 若某信息无法再次获取，不能把它表示成“可展开”。必要约束和当前未决工具结果不应仅为 节省预算而藏入历史。把层数与读取粒度一起评估：多次往返的成本可能超过直接展示。

提示放在它生效的位置

• 全局规则和工具定义承载稳定契约、参数与权限说明。
• 内容块附近承载当前范围、缺口、适用操作及定位信息，不复制整份工具手册。
• 工具结果承载本次状态和适用的继续、结束或恢复入口，不依赖遥远的一次性教程。

入口存在不等于需要调用。依据实际状态呈现“还有更早内容”“已到底”“无权读取”等， 避免“每次回答前必须查历史”的流程指令。不要在每条消息旁重复全部能力。

示意（不是已有产品协议，也不授权创建新 API）：

最近对话
以下是当前会话的一部分公开消息；更早消息未展开。
需要核对前文时，可使用历史读取工具，向前读取游标 H17。

[保留角色与原文的对话内容]

实际表达必须使用宿主提供的工具及有效游标；不能让模型猜 ID。翻页结果继续交代范围和 下一入口。完整、部分、未找到和不可访问不是同一种空结果。宿主导航与历史正文保持来源 及角色边界，不把提示伪装成用户发言，不让正文中的仿冒导航取得控制权。布局不是安全隔离。

验证：把信息量、提示内容与位置拆开

先冻结当前方案与要解释的失败。实验细则结合 evaluation.md，按未知选择 必要对照，不强制一次跑全套：

• 就近效应：同样的提示放在固定区域或相关内容旁；保持信息、工具、权限、预算、 消息角色和尽可能相同的 token 数。不要让实验组额外得到摘要、答案线索或更好的游标。
• 表述效应：固定位置后，单独比较能力说明与对象相关的状态/操作说明。若信息也变化， 只声称组合改进，不把收益全归因于措辞。
• 披露效应：固定可访问的源信息，比较直接展示与入口加按需详情。上下文量本就是变量， 不用无关填充把它抵消；记录展开后的总 token、调用成本和耗时，而非只看初始 prompt。
• 位置混淆：最近内容往往接近输入末尾。若无法在合法消息结构内区分邻近与首尾位置， 明确无法识别独立邻近效应；不把“末尾更显著”解释成 UI 理论成立。

使用需要旧信息、当前信息已足够、旧决定被新决定更正，以及无结果/不可访问的案例。 自然任务不提示标准工具路径；同题配对、独立会话，冻结模型配置与安全预算。重复运行和 未参与调参的案例用于检查稳定性；声称跨模型适用时才需相应模型证据。

报告任务正确性、必要读取是否命中、不必要读取率、旧信息覆盖新决定的错误、错误恢复， 以及总 token、调用数和耗时。正确答案与证据由独立标准核对，不用 Agent 自称理解验收。 小样本只能筛查，不能以未发现回归证明无风险。若必要与不必要读取一起增加，可能只是 提示诱导了更多调用；没有净收益时保留原方案，不靠追加帮助文案掩盖接口问题。

来源与证据边界

以下是方法来源，不要求普通使用时重读；研究更新或引用效果主张时再核对原始材料。

• NN/G：可用性启发式与 就地帮助支持人类界面的状态可见、 就地帮助和减少记忆负担；不能直接作为模型效果证据。
• SWE-agent研究面向模型的操作及反馈接口，文件视图 提供位置和省略范围；接口消融不单独证明邻近提示的因果收益。
• Anthropic 的上下文工程 与工具设计提供按需读取、 有界反馈和可操作提示的工程经验，不构成所有模型、格式与任务的保证。
• Lost in the Middle在其测试模型和任务上观察到位置敏感性； 提醒实验控制位置，不证明最新模型必然具有相同幅度或形态的偏差。

当前处置是可用于生成和评审方案的方法；尚无隔离上述变量的行为实验结论。 输出应交代对象与缺口、展示/入口安排、实际能力边界、证据和未知；不因采用本方法自动 修改产品设计、添加摘要机制、切换默认配置或宣称效果已验证。

Agent guidance evaluation

先冻结要回答的问题

区分三种问题：

• 发现：description、入口和相邻边界能否让 Agent 选择正确载体？
• 激活：加载后是否改变了核心判断、行动、失败处理或返回？
• 体系：是否与现有 skill、指令、文档、工具和 runtime 保持 owner、权威与生命周期关系？

不要用一个“整体效果分数”替代这三种问题。 需要在完整执行前筛选候选、量化设计缺口或用参考技能校准孵化器时，按需读 quality-assessment.md。设计量表与低成本决策探针不能直接当成任务成功概率。

最小行为探针

准备相同任务、来源、工具、权限和 workspace，至少覆盖：

• 正触发：应该使用该 skill 或 prompt 的案例；
• 负触发：相似但应留在普通任务表达或其他 owner 的案例；
• 最近邻：最容易误选相邻 skill、reference、工具或 runtime 的案例；
• 回归：已有能力和必要边界仍应保留的案例。

要声称候选载体造成改善，比较不加载它的 baseline 与只加载它的 treatment；变量无法隔离时只 报告观察，不作因果归因。需要稳定性时再增加重复或 fresh holdout，不把轮数或 Agent 数当作结果。

需要观察 Agent 完成一段真实任务，或设计操作者与被测者分离的现场时，按需读 field-trial.md。它提供自然输入、核验答案隔离、开放文字评价与多轮证据的 执行方法；不要求普通格式检查或局部决策探针升级为完整现场试验。

证据与处置

分别报告：

• format-valid：格式、frontmatter、链接或确定性检查通过；
• behavior-observed：激活后出现了目标行为；
• boundary-supported：负触发和最近邻没有被错误吞入；
• matched-improvement：相对冻结 baseline 有匹配改善；
• regression-supported：改善没有破坏既有行为。

证据等级限制主张，不自动晋级。自评、文件存在、格式通过、一次成功或多 Agent 一致，都不能 单独证明 skill 已被接受。最终处置可以是 adopt、adapt-and-retest、retain-baseline、 rollback、uncertain 或 no-proposal，由真实 owner 采纳。

Agent 现场执行与开放评价

在需要观察 Agent 如何完成一段真实任务时读取。操作者负责准备场景和采集可观察材料； 评议者核对事实与成果，不接管被测 Agent 的业务工作。操作者与评议者可以由同一人或 Agent 承担，但评价应独立核对原材料，不能只接受被测者的完成自述。

准备自然输入，隔离核验答案

通过目标环境的正常用户入口提交自然请求与业务材料，让被测 Agent 自行决定阅读、工具 和工作安排。场景期望、核验答案与操作者测试记录留在操作者侧；提供隔离源码副本时排除 这些核验材料，正常项目指令、文档、源码、测试与合法来源访问仍按授权开放。 不要为了避免答案泄漏而删掉完成真实任务本应可得的资料。

“这份日志”“刚才的结论”等输入需要真实上下文。可续接原对话，也可提供准确资料位置、 版本和已确认内容；不要把意外缺资料变成澄清能力测试。合成缺陷由操作者先在隔离现场 准备并确认，被测者不需要先造缺陷再修自己的实现。提供业务事实不等于提供正确算法。

项目、文件、工作或会话的引用从宿主真实返回值取得；不手拼私有地址、伪造身份或直接 修改业务数据库制造场景。使用当前实际入口与身份，不沿用历史端口或硬编码 ID。 后续输入按场景需要的真实条件触发，如工作在途、文件已保存或待答问题已经出现。 条件未出现时记录实际表现和覆盖缺口，不用固定睡眠、伪造结果、追加工具提示或反复提醒 原目标制造预期行为。

让观察匹配要声称的效果

观察应经过待评价的真实产品或执行通路。直接调用局部后端、注入事件、硬编码回复或 模拟外部服务，只能支持实际经过的边界；明确模拟了什么、真实执行了什么、什么仍未观察。 界面体验需要真实界面，HTTP 事件不能替代布局、卡片或输入交互观察。 精确事务、提交丢回执或租约窗口使用可确定命中条件的测试，不能靠随机断网或杀进程宣称 命中了特定窗口。

自动化可启动环境、切换条件、采集公开行动、产物、trace、token 和耗时，不接管被测者 工作流，不规定工具顺序、最低步数或阅读批次，也不索取隐藏思维链。

分别核对程序运行状态、实际行动、产物可用性、业务正确性与用户交付。格式和权限检查 可以由程序执行；资料充分性、业务取舍和成果价值由负责工作的 Agent 或评议者判断。 “发现错误”“需要澄清”“只完成一部分”也可能是合法结果，不新增关键词质量阈值或结束 审批来替代判断。格式正确但业务算错，应指出具体偏差与影响；不把它改写为系统故障。 环境在执行或模型调用前受阻时，不能记为已观察的 Agent 表现。

保留开放的文字评价

区分用户明确要求、独立事实、产品合同与参考做法。按 Agent 决策时实际可得的信息评价， 不用操作者私有答案或后出现的事实要求其提前知道。直接完成、委派、串行推进、部分交付、 必要澄清或说明暂不能做，都可能合理。

围绕与本轮有关的角度连接表现、证据和影响，无需逐项填满：

同时保留长处、局限、合理替代与改进空间，不设统一总分或通过线。未观察的能力保持未知， 不折成低评价；正确终稿不抹掉过程中的遗漏或越权，补救价值也不抹掉此前用户负担。 没有使用待评价的机制时仍可评价成果，但该机制的效果保持未观察。没有满足明确原文、 版本或授权要求时，单独记录该需求缺口。

建议说明具体场景、可能收益与代价，可以保留现状、继续观察或比较其他做法，不把每个 差异都视为缺陷。真实错误与越权仍准确指出，必要边界问题不被其他长处抵消。

多轮观察与比较

沿现有工作记录保留真实输入与后续变化、实际条件和版本、行动与成果、证据定位、评价和 局限，不另建平行台账或复制全部 trace。用户补救前后的表现分开保存，复测成功不能覆盖 原样本。下一轮针对未解决的问题和改进假设选择场景，不机械重跑全部情境或只保留成功。

按业务需要续接原对话与原工作；需要独立观察时用新现场，防止前轮答案和提醒污染判断。 只有需要效果比较时才建立对照，尽量匹配任务、资料、模型、工具、授权和资源预算。 变量无法匹配时报告差异，不把结果差异单独归因于 guidance。

token、耗时与调用数用来解释取舍，不单独决定优劣，也不由一次命中推断长期可靠性。 查询没有公开命中信号时，不能凭耗时断言缓存命中；公开记录不代表执行器全部内部上下文。 并发任务有进展和底层执行真正重叠是不同观察，需由实际输入与执行事件支持各自结论。 收尾说明实际覆盖、剩余未知和证据限制，不为全部通过无限增加样本。

Guidance formation and carrier choice

先判断对象

从真实任务、用户纠正、失败轨迹或可复现 baseline 恢复：哪个 Agent 在什么环境中，对什么行为 对象缺什么判断或行动；这个差距是否会跨任务重复；什么结果会证明它改变了行为。保留未知， 不要从名称、目录、笔记数量或“需要一个 skill”的请求反推准入。

持久 guidance 与载体准入

比较相邻形式：

• 一次性任务只需要当前任务表达；项目持续边界放局部指令；事实、设计或论证放普通文档。
• 条件分支细节放 reference；确定性变换交工具；必须跨提示、重启、并发或不可信调用成立的 属性交 runtime/base；派生视图保留 canonical source。
• skill 只承载可选择加载、可重复、能由方法表达改变且有可观察边界的 Agent 判断或行动。

候选至少要能说清：主要判断、正触发、负触发、最近邻 owner、允许效果、返回关系和行为探针。 只有需要跨任务选择性发现的方法才进入 skill；项目常驻边界、focus anchor、一次任务表达和普通 reference 各有自己的 owner。无法区分这些关系时返回 research 或 no-proposal，不先建一个万能容器。

生命周期处置

先判断是否仍有真实差距，再选择 retain、rewrite、split、merge、downgrade、 delete 或 no-proposal。篇幅和小节数量不是拆分理由；共享术语不是合并理由。

一个 skill 只有在独立触发、上下文与失败方式不同、能够分别验证且结果仍可重组时才拆分。 如果内容只是知识、项目常驻规则、一次性计划、确定性工具变换或 runtime 保证，就把它还给 相应 owner，不创建兼容壳。

六面 review

分别检查成立性、对象与边界、形式与上下文、Agent 表达、行为与回归、体系关系。设计“是否 应该存在”和表达“怎样写清楚”分开判断；不要用措辞变顺掩盖载体选择错误。

Agent guidance review

先过诊断门

观察到的问题先分层，不要默认继续加文字：

1. Observed or inferred：这是可复现的观察，还是解释性推断？
2. Truth or delivery：源内容缺失，还是已有内容没有送达/被发现？
3. Guidance or capability：表达不足，还是工具、权限或能力不存在？
4. Capability or acceptance：工具能返回结果，但谁判断结果满足目标？
5. Source or projection：当前文件是 canonical source，还是可重建的派生视图？
6. Local or recurring：一次性修正，还是值得沉淀为持久方法？

诊断结果决定 owner：源内容回到 source，发现问题修路由或 description，能力问题交工具/runtime， 接受问题交真实 owner，一次性问题留在任务，重复方法才进入 skill 形成判断。

六面评审

审查已有 skill、prompt 或 instruction 时分开判断：

1. 成立性：是否有真实、重复的判断/行动差距？
2. 对象与边界：method、carrier、activation、prompt、harness、runtime 是否混淆？
3. 载体与上下文：是否放在最小真实位置，是否造成重复加载、循环引用或上下文膨胀？
4. Agent 表达：对象、来源、关系、允许效果、未知、返回和验收能否恢复？
5. 行为与回归：是否有正例、反例、最近邻和回归观察？
6. 体系关系：是否与其他 skill、AGENTS.md、文档、工具和 owner 重复或冲突？

“应该不应该有这个 skill”与“这个 skill 怎样写清楚”是两个判断；前者走 formation，后者走 composition。需要状态、字段、队列、hook、权限或恢复机制时，转交 mechanism/runtime owner。

常见错误修复

• 用“专家、严谨、主动、认真”替代对象、关系、行动和验证；
• 不定位失败就不断增加 must、never、only；
• 把理论、研究日志、实验协议和全仓背景塞进普通激活上下文；
• 在 AGENTS.md、skill、prompt、reference 中重复维护同一事实；
• 用 prompt 模拟权限、持久化、事务、恢复或不可绕过的执行门；
• 用输出更长、工具调用更多、Agent 更多或报告更完整作为改善证据。