writing-lean

精简写作

代码及其规范是首要事实来源：新读者应该通过阅读它们来了解项目。只有在无法通过代码和规范表达时才写入文档，这就是精简。

• 代码优先。 在写更长的说明之前，先考虑取一个更清晰的名称、编写一个更小的函数或完善规范。
• 一个概念，一个词。 每次都使用项目中表示某个概念的术语，该术语应来自 GLOSSARY.md 或代码；使用同义词会让人以为是另一个概念。
• 说明该怎么做。 写明目标（“单行注释”），而不是禁令；只有在禁令是必须遵守的硬性约束，且同时说明替代做法时，才值得写出来。
• 写一次，放在关键处。 每条事实都只有一个事实来源，如下所示；其他地方都链接到该来源。
• 历史留给记录。 权衡过程和被否决的方案应写在 issue、pull request 或 commit 中，讨论和差异就在旁边，git blame 也能追溯到相关记录。

删除测试是你撰写或修改每句话时都应遵循的标准：删掉它，看看有能力的读者会失去什么。如果什么都不会失去，那代码已经表达了它的意思，应当将其删除。

内容放在哪里

渠道	唯一职责
代码	清晰流畅：使用简洁的函数和变量名称说明其用途
代码注释	在约束、陷阱、引用或不明显的原因影响代码的位置说明它们
文档注释	用一句话说明成员的用途
README	常见路径：项目是什么、如何使用、接下来去哪里
仓库文档	记录代码无法体现的决策或背景
Issue	在 issue 表单的字段中说明需求及其原因
Agent 简报	约定：行为、验收标准、范围
Pull request	说明改了什么及原因，并链接到对应 issue
Commit 消息	说明改了什么；如果差异无法体现原因，也说明原因
Review 评论	指出一项问题及其修复方法
讨论串评论	说明新事实或决策，并链接到它所回应的内容
技能、AGENTS.md	说明 Agent 如何完成工作：步骤及其依据的参考资料

代码中的链接

只有当某个 issue 会影响代码日后的修改方式时，才在代码中引用它：例如，clhbid/api#123 发布后应移除的变通方案，或尚未解决的决策所要求遵守的约束。其他情况下，git blame 会引导你找到对应的 pull request 和 issue。