# Agent Note: 具体表述说明执行者和记录的事实

Status: implemented

[English](2026-08-09-concrete-prose-names-actors-and-recorded-facts.md) | 中文

## 问题

仓库行文使用了抽象的类别名称，但读者需要知道的具体事实各不相同。同一个名称可能指替换操作引用的早期事件 seq、生成消息的提供方和模型、提供上下文的调用方、提供某行配置的文件，或构建某个二进制文件的 CI 任务。读者必须查看代码，才能知道句子承诺的是哪项事实。

用另一个宽泛名称替换原名称，仍会保留这种歧义。在行文整理中重命名类型、字段和协议成员，反而会改变与行文问题无关的约定。

## 决策

仓库维护的行文直接写明当前语境下的约定需要的执行者、动作、来源、事件、字段、文件或进程。句子说明记录了什么，以及由谁或什么记录。写作者还要检查自己是否会在向同事解释同一个问题时使用这些词；如果不会，就替换它们。

该规则适用于 Markdown、README、活跃 Agent Note、JSDoc 与注释、提示词、诊断信息和用户可见字符串。审查会分别判断每个句子，不会在整个仓库中用一个偏好的近义词统一替换某个术语。编辑后的句子保留执行者、动作、条件、顺序、情态、例外、归属、失败行为和后果。

注释只保留附近代码无法表达的事实。文档停留在内容归属的层级；除非私有控制流或罕见实现情形会改变受支持行为、安全使用、兼容性、数据完整性、安全保障或另一项持续维护的约定，否则文档不描述它们。[简化工作流](../../../skills/dsh-find-simplifications/SKILL.md)在同时巡查代码与行文时应用此规则。

除非另一项独立需求明确要求协调重命名约定，否则确切的代码标识符、公开 API、持久字段、协议成员、类型名、带有外部引用的标题和文件名均保持不变。它们周围的行文直接说明其字段或行为。生成的文档和目录在维护它们的源文件修改后更新。

使用 `contract`、`boundary` 或 `shape` 之前，写作者要确认句子是否实际指更具体的规则、操作、数据结构、字段集合、校验点、时间点、API、类型或失败条件。调用方、被调用方、实现方、提供方、生产方或消费方依赖的前置条件、后置条件、不变量、兼容性承诺及其他义务仍可准确称为 `contract`。真实的安全、信任、wire、进程、序列化、事务或生命周期分界仍可准确称为 `boundary`。当结构形式本身就是主题，且字段、schema、类型、联合变体、文件布局或导出形式等更窄的词无法说明事实时，仍可使用 `shape`。除非另一项独立需求要求协调重命名，否则包含这些词的代码和 API 名称保持不变。

该决策补充了[文档层级与字数预算](2026-07-04-doc-tiers-and-budgets.zh.md)决策；后者继续规定内容位置、文档形式和字数预算。

## 曾考虑的替代方案

**禁止一份固定词表中的所有词。** 不予采纳：某个词可能是确切的标识符，也可能是另一项约定中最清楚的用词。例如，调用方与被调用方依赖的不变量属于真实的约定，进程边界或协议边界也表示真实分界。逐句审查可以找出歧义，且不会拒绝有效名称。

**将每个抽象名称都替换为“来源”、“起源”或“元数据”。** 不予采纳：另一个宽泛名称仍会让读者自行推测句子指的是文件、调用方、事件 seq、提供方／模型组合、commit 还是构建任务。

**在修改行文时重命名所有匹配的标识符。** 不予采纳：让行文更清楚，不能作为进行无关 API、协议、持久格式、类型或文件迁移的理由。这些改动需要各自的消费方审查和决策。

## 后果

文档和诊断信息可能会多用几个词，但每条说明都会告诉读者哪个值或哪个执行过程有关，无需查看源码。全仓库行文审查必须根据句子的具体含义分类，不能盲目替换。双语对侧文件保留相同的具体事实；生成的副本只会在其归属源文件更改后刷新。
