Back to Details

cold-read

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cold read

陌生视角阅读

Every doc is eventually read by someone — human or agent — who was in none of the conversations that produced it. Write for that reader: the current state of the world, self-explanatory, and nothing else.
Before writing, simulate that reader: what do they need in order to act, what can they not possibly know, which line would they have to ask about? Every sentence that fails the simulation is rewritten to stand on its own or deleted.
每份文档最终都会被某个没有参与过文档创作相关讨论的读者阅读——可能是人类，也可能是Agent。撰写文档时要面向这类读者：只描述当前状态，内容自解释，无需其他冗余信息。
撰写前，先模拟这类读者的视角：他们需要哪些信息才能采取行动？哪些信息是他们不可能知道的？哪句话会让他们产生疑问？所有不符合这个模拟场景的句子都要改写为独立可理解的内容，或者直接删除。

Rules

规则

  • Current state only. How things used to be, what was migrated or abandoned, what is no longer used — invisible to the doc. A fact that matters only as contrast with the past doesn't matter.
  • No references that need history. A name, codename, or decision that only a past conversation explains either becomes a general rule the reader can apply on their own, or goes. If generalizing needs a fact nobody wrote down, cut the line and flag it to the owner — never invent the rationale.
  • Nothing obvious. A warning no reader would violate is noise; enforce mechanically instead (.gitignore, lint, CI) and stay silent.
  • No meta-commentary. Nothing about how the doc was written or what was agreed along the way — state the rules themselves.
  • Explain things at the point of use. A variable, secret, or constant is described where it is used — the skill, module, or config that reads it; a central doc says only where such things come from and how to fetch them.
  • English, except literal data — names of external entities (databases, properties, pages) stay exactly as they are spelled there.
For skills specifically:
  • The description is a trigger, not a manual: what the skill does and when to fire it. Implementation details live in the body, loaded only on use.
  • Skills are never listed in AGENTS.md / CLAUDE.md — they announce themselves through their own descriptions.
  • 仅描述当前状态：文档中不得提及过去的情况、已迁移或废弃的内容、不再使用的功能。仅作为与过去对比的信息毫无意义。
  • 避免需要背景知识的引用：如果某个名称、代号或决策只有通过过去的讨论才能理解，要么将其转化为读者可自行应用的通用规则，要么直接删除。如果转化为通用规则需要未被记录的信息，应删除该内容并告知文档所有者——切勿编造理由。
  • 删除显而易见的内容：读者不会违反的警告属于冗余信息；应通过机械方式（.gitignore、代码检查工具lint、持续集成CI）强制执行，无需在文档中提及。
  • 无元注释：不得提及文档的撰写过程或达成的相关共识——只需直接陈述规则本身。
  • 在使用点处解释内容：变量、密钥或常量应在其被使用的位置（读取它们的skill、模块或配置文件）进行说明；中心文档只需说明这些内容的来源及获取方式。
  • 使用英文撰写：除字面数据外——外部实体的名称（数据库、属性、页面）需保持其原有拼写。
针对skill的特殊规则：
  • 描述部分是触发条件，而非操作手册：只需说明该skill的功能及触发时机。实现细节应放在主体内容中，仅在使用时加载。
  • 不得在AGENTS.md / CLAUDE.md中列出skill——它们应通过自身的描述来展示。

Verify empirically

实证验证

The author cannot see their own blind spots — every line reads as obvious to the person who already knows the story. A cold reader finds the gaps in minutes. So test the doc the way it will actually be consumed: spawn a fresh subagent that reads only the doc, and
  1. give it scenario questions ("you're asked to do X — walk through what you do") and check it reaches the right actions;
  2. ask what confused it, what it needed but couldn't find, and what it read but didn't need.
Fix what it misread, then retest the fixes with another fresh reader. If no subagent is available, degrade to a self-check: reread the doc listing every fact a stranger couldn't source from the doc itself.
文档作者无法察觉自己的知识盲区——对于已经了解相关背景的人来说，每一行内容都显而易见。但陌生视角的读者能在几分钟内发现信息缺口。因此，需按照文档的实际使用场景进行测试：生成一个仅阅读该文档的全新子Agent，然后：
  1. 向其提出场景问题（“你被要求完成X任务——请说明你的操作步骤”），检查它是否能采取正确的行动；
  2. 询问它哪些内容令其困惑、哪些所需信息未找到，以及哪些内容是它阅读后不需要的。
修正它误解的内容，然后用另一个全新的读者重新测试修正后的文档。如果没有可用的子Agent，则退化为自我检查：重新阅读文档，列出所有陌生人无法从文档中获取的信息。