llm-friendly-context · diff
git:20260831.b183037 to git:20260901.fbc397a
32 added, 32 removed. Audit A to A.
---
name: llm-friendly-context
description: 明确输入、输出、成功标准、决策和未解决的条件，使下游智能体无需猜测即可执行。用于编写或修改面向 LLM 的提示词、交接、规划产物、评审、报告或生成的指令。
---
# 面向 LLM 的友好上下文
目标是实现稳定的下游执行：下一个智能体应当知道要读什么、要做什么、什么算成功，以及哪些未解决的决策会改变结果。
本技能规范面向 LLM 的输出，使提示词、交接和生成的产物清晰明确。调用方提供产物类型以及任何产物特定的模板或输入契约；只包含其使用方用来决策、行动或验证所需的信息。当使用方根据字段分支处理时，使用已声明契约的字段名和取值含义。
## 核心规则
1. **使用正向、可执行的指令**
- - 说明下一个智能体应当做什么。
- - 将质量策略转化为正向标准。
+ - 说明下一个智能体应当做什么
+ - 将质量策略转化为正向标准
- 示例：“在已记录的兼容性用例中保持现有公共 API 行为不变。”
- - 只有在禁令保护不可逆边界或已发布契约时才保留它；此时要同时说明受保护的条件和允许的行动。
+ - 只有在禁令保护不可逆边界或已发布契约时才保留它；此时要同时说明受保护的条件和允许的行动
2. **将模糊指令具体化**
- - 用可观测的条件、路径、命令、schema、示例或决策规则替代主观用词。
- - 以下用词在把决策留给下一个智能体时通常需要澄清：`appropriate`（合适）、`proper`（恰当）、`related`（相关）、`existing behavior`（现有行为）、`optional`（可选）、`as needed`（按需）、`if needed`（如有需要）、`per convention`（按惯例）、未解决的备选方案、`TBD`（待定）、`placeholder`（占位符）。
+ - 用可观测的条件、路径、命令、schema、示例或决策规则替代主观用词
+ - 以下用词在把决策留给下一个智能体时通常需要澄清：`appropriate`（合适）、`proper`（恰当）、`related`（相关）、`existing behavior`（现有行为）、`optional`（可选）、`as needed`（按需）、`if needed`（如有需要）、`per convention`（按惯例）、未解决的备选方案、`TBD`（待定）、`placeholder`（占位符）
3. **明确输出形态**
- - 定义使用方会用到的章节、字段、表格列、JSON 键或检查清单项。
- - 对于交接，仅在会影响下一步转换时才包含生成的产物路径和状态字段。
+ - 定义使用方会用到的章节、字段、表格列、JSON 键或检查清单项
+ - 对于交接，仅在会影响下一步转换时才包含生成的产物路径和状态字段
4. **提供必要的上下文**
- - 包含目的、来源产物、硬性约束、已接受的决策和未解决的条件。
- - 优先使用具体的文件路径和章节提示，而非宽泛的模块名。
- - 只要引用还能改变范围内的决策、行动或验证结果，就继续追踪；一旦下一个链接只是确认已经决定的内容，就停止。
+ - 包含目的、来源产物、硬性约束、已接受的决策和未解决的条件
+ - 优先使用具体的文件路径和章节提示，而非宽泛的模块名
+ - 只要引用还能改变范围内的决策、行动或验证结果，就继续追踪；一旦下一个链接只是确认已经决定的内容，就停止
5. **将复杂工作拆解为可验证的步骤**
- - 将有 3 个及以上目标或存在先后依赖关系的工作拆分为有序步骤。
- - 每个步骤都需要一个检查点：什么依据能证明它已完成。
+ - 将有 3 个及以上目标或存在先后依赖关系的工作拆分为有序步骤
+ - 每个步骤都需要一个检查点：什么依据能证明它已完成
6. **明确允许不确定性**
- - 在将某个缺失的操作细节视为未解决之前，先从约束性产物和具有代表性的仓库依据中解决它。
- - 记录剩余的不确定性及其对结果或证明的影响。在已确认的边界内做出可逆的、仓库本地的选择，并保留所用的依据。
- - 将阻塞下一步的未知项转化为继续所需的具体、可验证依据要求。仅当已确认的成果、目标状态需求与非目标无法在没有用户选择的情况下同时成立时，或不可逆的外部行动需要授权时，才询问用户。当只是证明不可得时，完成不受影响的工作，并准确报告哪些内容无法验证及原因。
+ - 在将某个缺失的操作细节视为未解决之前，先从约束性产物和具有代表性的仓库依据中解决它
+ - 记录剩余的不确定性及其对结果或证明的影响。在已确认的边界内做出可逆的、仓库本地的选择，并保留所用的依据
+ - 将阻塞下一步的未知项转化为继续所需的具体、可验证依据要求。仅当已确认的成果、目标状态需求与非目标无法在没有用户选择的情况下同时成立时，或不可逆的外部行动需要授权时，才询问用户。当只是证明不可得时，完成不受影响的工作，并准确报告哪些内容无法验证及原因
7. **保持约束的适度性**
- - 只添加能减少歧义或保护真实需求的约束。
- - 当目标行动、上下文和成功标准已经明确时，让简单的下游任务保持轻量。
- - 将明确表述的规模预期——`minimal`（最小化）、`a few lines`（几行）、明确的行数或文件数估算——视为覆盖整个已完成差异的单一预算，而非按文件或按步骤分摊。当工作无法满足该预算时，报告超出情况及原因，而不是悄悄超支。
+ - 只添加能减少歧义或保护真实需求的约束
+ - 当目标行动、上下文和成功标准已经明确时，让简单的下游任务保持轻量
+ - 将明确表述的规模预期——`minimal`（最小化）、`a few lines`（几行）、明确的行数或文件数估算——视为覆盖整个已完成差异的单一预算，而非按文件或按步骤分摊。当工作无法满足该预算时，报告超出情况及原因，而不是悄悄超支
## 改写模式
在将提示词、交接或产物视为完成之前，先应用以下改写。
| 模糊形式 | 改写为 |
|---|---|
| 作为未解决选择使用的 `optional` | 必需、省略，或仅在指定条件下必需 |
| 下一个智能体必须从中选择的多个备选方案 | 已选定的选项，或一条确定性的决策规则 |
| `as needed` / `if needed` | 触发条件和所需的行动 |
| `per convention` | 需要遵循的文件、函数、测试或已记录的惯例 |
| `related files` | 具体的路径、通配符或搜索提示 |
| `existing behavior` | 需要保持的可观测行为、源文件、测试、API 响应或 UI 状态 |
| `placeholder` | 确切的临时值/行为、允许的依赖，以及验证预期 |
| 作为必需信息占位符使用的 `TBD` | 它会影响的决策以及继续所需的具体、可验证依据；如果该项对下游没有影响则省略 |
| `appropriate` / `proper` | 可衡量的标准或检查清单 |
## 交接检查清单
在将提示词或产物发送给另一个智能体之前，请核实：
- - [ ] 目标行动是明确的。
- - [ ] 已指明所需的输入路径、来源产物和与决策相关的事实。
- - [ ] 已接受的决策和约束只陈述一次，没有替代措辞。
- - [ ] 已指定输出格式或预期的状态字段。
- - [ ] 成功标准是可观测的。
- - [ ] 模糊表达已被改写或标记为未解决。
- - [ ] 任何明确表述的规模预期都以覆盖已完成差异的单一预算形式表达，并说明了超支上报条件。
- - [ ] 下一个智能体能够根据提供的目的、来源、标准和依据完成其范围内的工作，或者明确返回继续所需的具体、可验证依据或权威工作流停止点。
+ - [ ] 目标行动是明确的
+ - [ ] 已指明所需的输入路径、来源产物和与决策相关的事实
+ - [ ] 已接受的决策和约束只陈述一次，没有替代措辞
+ - [ ] 已指定输出格式或预期的状态字段
+ - [ ] 成功标准是可观测的
+ - [ ] 模糊表达已被改写或标记为未解决
+ - [ ] 任何明确表述的规模预期都以覆盖已完成差异的单一预算形式表达，并说明了超支上报条件
+ - [ ] 下一个智能体能够根据提供的目的、来源、标准和依据完成其范围内的工作，或者明确返回继续所需的具体、可验证依据或权威工作流停止点
## 生成产物检查清单
在编写或最终确定生成的文档之前：
- - [ ] 每个需求、主张、任务、测试骨架或评审发现都有足够的来源上下文，可以追溯其存在原因。
- - [ ] 每条可执行指令都指明了目标、行动和预期结果。
- - [ ] 验证步骤说明了要运行或观察什么，以及什么结果证明成功。
- - [ ] 如果某个产物源自另一个产物，被复制的决策在措辞和含义上保持一致。
- - [ ] 任何明确表述的规模预期都以覆盖已完成产物的单一预算形式表达，并说明了超支上报条件。
- - [ ] 缺失的信息记录了它所影响的决策或证明；只有已确认的价值边界选择或不可逆外部行动的授权才构成阻塞性上报。
+ - [ ] 每个需求、主张、任务、测试骨架或评审发现都有足够的来源上下文，可以追溯其存在原因
+ - [ ] 每条可执行指令都指明了目标、行动和预期结果
+ - [ ] 验证步骤说明了要运行或观察什么，以及什么结果证明成功
+ - [ ] 如果某个产物源自另一个产物，被复制的决策在措辞和含义上保持一致
+ - [ ] 任何明确表述的规模预期都以覆盖已完成产物的单一预算形式表达，并说明了超支上报条件
+ - [ ] 缺失的信息记录了它所影响的决策或证明；只有已确认的价值边界选择或不可逆外部行动的授权才构成阻塞性上报