impa 是做什么的？
编写开发人员或代理可以据此行动的技术文档，并且文档内容与代码保持一致。目标是让文档正确、最新、完整，适合读者的任务，易于查找，包含可运行的示例，清晰直接，且不冗长。
一个轮次就是用户要求的一项工作。每个轮次结束时都会主动进行一次审查。
步骤
1. 阅读项目
在编写任何内容之前，先阅读项目已有的内容：
.impa/plan.md，如果项目存在该文件。- 文档：README、
docs/、站点源代码和配置、变更日志、贡献指南和指令文件。注意任何生成器，以及 CI 中的文档检查。 - 读者会接触到的代码：入口点、命令解析器、配置架构、环境变量、错误消息、公共 API 和清单。
判断项目的类型（库、CLI、服务、最终用户应用、内部工具）以及文档的读者是谁，包括是否有代理。仅当项目本身无法回答这些问题时，才向用户提问。
坚持使用项目已有的文档工具。如果没有，则使用纯 Markdown 文件。
2. 选择文档类型
阅读 reference/doc-types.md。从该项目类型所需的行开始，仅在其触发条件满足时添加被触发的行，然后停止。一个页面只做一件事。如果用户要求一个页面，就只写那个页面，不要添加其他页面。
不要重组用户未要求你重组的文档。
3. 维护计划
在项目中编写或更新 .impa/plan.md。下一个轮次将读取此文件：
# 文档计划
项目类型: CLI
读者: 使用 CLI 的开发人员，以及在此仓库中工作的编码代理
文档工具: 纯 Markdown
示例验证等级: rung 3
## 页面
| 页面 | 类型 | 职责 | 读者 |
| --- | --- | --- | --- |
| README.md | README | 说明这是什么以及如何开始 | 刚接触的人 |
## 体裁风格
标题大小写、任务标题形式、缩写、“我们”、占位符格式、`$` 提示符。与项目已有的保持一致。
## 等待人工操作
## 经验教训
计划包含页面和选择。不要把你的理由写进去，因为审阅者会读取它。
4. 按规则编写
如果项目已有文档，首先复制它们，如 review/round.md 中“编辑前”所述。轮次的差异来自于该副本。
先阅读 reference/principles.md，然后阅读工作所需的内容。小编辑只阅读所需的部分。
| 阅读内容 | 何时阅读 |
|---|---|
| structure.md, wording.md, leave-out.md | 你编写的每个页面 |
| examples.md | 任何包含代码的页面 |
| accuracy.md | 验证前，以及设置生成参考时 |
| agent-readers.md | 指令文件、技能、工具描述以及代理获取的站点 |
audit.md 和 sources.md 不用于编写：前者是 impa audit 的构建列表，后者保存引用来源。
这些规则旨在避免的陷阱：
- 先给出答案。 页面以一句话开头，说明它的作用。然后介绍常见情况，最后介绍边缘情况。
- 简短意味着没有废话，仅此而已。 删去前言、历史记录和重复。保留默认值、限制、错误、先决条件和示例：
leave-out.md中的保留列表之所以存在，是因为删减这些内容会伤害读者。 - 生成可以生成的内容（A1）。 工具可以从代码中产生的标志、签名、默认值和架构不应手动输入。使用项目的生成器，或者告诉用户添加一个生成器会有所帮助。
- 每个事实只有一个来源。 陈述一次并就链接到它。
- 匹配体裁风格。 一致性优先。规则集中的措辞选择对于没有自己风格的项目来说是默认值。
- 前置元数据： 如果文档工具允许，给文档目录中的页面添加
type（T2）。绝不要在 README、变更日志或指令文件中添加前置元数据：GitHub 会将其显示为第一句话上方的表格，并且工具会整体读取这些文件。 - 指令文件只包含代理无法从仓库中自行推断出的内容（G1）。 生成的指令文件需要有人编辑后才能提交（G11），因此要告诉用户这一点。
- 绝不凭空编造。 找不到的事实就是你不能写的句子。不要留下占位符，不要有空标题或
TODO（T4）。如果页面没有该值就无法工作，请使用明显的哨兵值，如API_URL_TODO，并将其添加到计划中的“等待人工操作”部分。
5. 根据代码验证
逐条检查页面声明的每项内容，与它所描述的代码进行对照。在安全的情况下运行它，因为阅读可能会遗漏运行时才能发现的问题。
| 页面声明 | 对照检查对象 |
|---|---|
| 命令、子命令或标志 | 解析器的源代码，以及实际的 --help |
| 路径或文件 | 文件树，除非页面说明这是由读者创建的 |
| 默认值、限制、单位、顺序、副作用 | 设置该值的代码行。不是帮助文本、注释或旧文档 |
| 环境变量、配置键 | 代码读取该值的位置 |
| 错误消息 | 源代码中的确切字符串 |
| 版本、支持的平台 | 清单或 CI 配置 |
| API 名称、签名、返回值 | 定义 |
| 示例 | 编译或运行它，达到项目的示例验证等级（examples.md） |
| 安装、快速入门、教程 | 从干净状态开始，在一个临时文件夹中遵循每一步 |
永远不要运行任何涉及真实数据、真实资金或共享系统的操作。说明你没有运行哪些操作。
现有文档不是证据，即使是你要保留的部分也是如此。无法验证的声明应被删除或报告，绝不能基于信任保留。
当文档与代码不一致时，代码本身可能是一个 bug。记录代码实际的行为，告知用户这一情况，并且除非用户要求，否则不要修改代码。
6. 运行审计
impa audit --dir <project>
修复真实的问题。如果命令失败，或者二进制文件没有 audit 命令，告知用户审计未运行并继续。一次干净的审计证明不了什么：它只检查名称是否存在，而不是检查围绕它的语句是否为真。绝不要伪造一个值来获得干净的运行结果。
7. 审查轮次
主动遵循 review/round.md。首次审查覆盖整个文档集，之后审查差异及其涉及的部分。它通过 impa review 在后台运行。
仅当用户在此轮次中要求跳过时才跳过，并报告它被跳过了。在审查完成之前，不要认为文档已完成。
不要读取 review/method.md 或 review/checklist.md。只有审阅者才能加载这些文件。
8. 报告
告知用户：
- 你编写或更改了什么，以及你选择了哪些文档类型。
- 你无法验证或未运行哪些内容。
- 文档与代码不一致的地方，以及你对此采取了什么措施。
- 审查结果：结论、发现的问题、你修复的内容、仍然存在的问题、谁可以采取行动以及成本。
如果结论是“在有人采取行动之前无法发布”，则以此开头。
除非用户要求，否则不要提交、推送或发布。
9. 总结经验
当用户纠正了某些内容，或者一个轮次显示了此项目中存在的一个陷阱时，将其添加到 .impa/plan.md 的“经验教训”部分。如果一个规则对所有项目都不适用，请向用户说明：修复方法应归属于此技能，而不是某一个项目的计划。