IDR 作为意图记录

# IDR 作为意图记录 来源：https://wrla.ch/log/2026/10/idrs-as-records-of-intent/ 2026 年 10 月 10 日 idrs (https://wrla.ch/tags/idrs.html)recurse (https://wrla.ch/tags/recurse.html) Beaver Pond 在《编写文档：2026 年版》(https://wrla.ch/log/2026/08/writing-the-docs-2026-edition/)中，我简单谈了一下 IDR (https://github.com/wlach/idr-tools)\（Implementation Decision Records，实施决策记录，是对早于 LLM 普及的“Architecture Decision Records”（架构决策记录）的双关用法\）\。回顾一下，我创建它们是为了实现两个目的：1. 让 LLM 产出更好的结果 2. 为功能实现过程中做出的决策提供持久的记录 我意识到，如果只给出一个模糊的提示，让 LLM 自行发挥，它往往只会用文字描述自己原本就打算实现的内容，以此填充一份 IDR\。[\[1\]](https://wrla.ch/log/2026/10/idrs-as-records-of-intent/#fn-idrs-as-records-of-intent-1)这使它们作为意图记录时丢失了相当多的信息\（基本上并不比 diff 好多少，甚至可以说更差\），而且我有些怀疑它们能在多大程度上改善 LLM 的输出\。充其量，它们或许能让你在写出太多代码之前，引导 LLM 朝着更好的结果前进\。一个很典型的例子是这份记录，当时我要求智能体更新 repo\-parser (https://github.com/wlach/repo-parser)，使用 DuckDB 来存储中间表示：`` # DuckDB 序列化 负责人：Will Lachance <[email protected]> ## 概述 ### 问题陈述 repo-parser 将仓库中的元数据和结构提取到内存中的 `Resource` 树中，但这种临时表示必须为每个使用方重新创建。我们需要一种持久、可查询的序列化格式，让多个工具能够使用提取出的元数据，而无需重新扫描仓库。 ### 背景 ... `` 链接 (https://github.com/wlach/repo-parser/blob/main/idrs/202601030409-duckdb-serialization-and-interactive-ui-architecture.md) 这份问题陈述算不上糟糕，但也相当模糊\。我觉得，除了“以某种方式使用 duckdb”来替代另一种机制之外，它并没有真正给智能体提供什么目标\。我觉得结果还算可以，但也有点怀疑 IDR 在这个过程中是否有多大价值\。它显然无助于解释 repo\-parser 的 duckdb 输出究竟有什么用\（为仓库内容建立 BM25 搜索索引，或许还能用于 TUI 搜索工具\）\。而且这绝对不是我以后想重新阅读的东西，现在看着它我都觉得尴尬\。我越来越意识到，要让 IDR 真正有效，就必须不断回到**意图**以及为实现这一意图而做出的决策\。否则，它就只是用英语冗长地复述 diff\。下面这份让我满意得多：`` # 通过 GitHub Actions 发布到 PyPI 负责人：Will Lachance <[email protected]> ## 概述 ### 问题陈述 repo-parser 软件包目前只能手动发布到 PyPI，这很耗时、容易出错，而且安全性不如通过 GitHub Actions 发布。 ### 背景（按需填写） ### 目标 - 更方便地发布新版本 - 提高安全性 ### 非目标 - 自动递增版本号（仍需单独提交一次更改来递增版本号） ### 建议方案 按照官方打包指南，采用惯用的最佳实践来完成这项工作：https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ 总体而言，这意味着添加一个新的 GitHub 工作流，将上传到 PyPI 与发布新版本关联起来。 ## 其他参考资料（按需填写） - 官方指南 (https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/) - Stamina 的实现 (https://github.com/hynek/stamina/blob/b25d4bc359ff603496aafbb217ab82c5a43715a6/.github/workflows/pypi-package.yml)（很可能是最佳实践） `` 链接 (https://github.com/wlach/repo-parser/blob/main/idrs/202512310404-publish-to-pypi-from-github-actions.md) 这份问题陈述描述了促使我想要动手改进的那个“痛点”\。目标、非目标和方案都简短有力，解释了最终结果，又没有深入实现细节\。当我以后回头查看一个仓库时，**这**才是我想看到的东西\。额外的好处是：使用 LLM 时，它提供了更清晰的约束\。每一句话都在引导它的行为朝着我真正想看到的结果前进，而不是给出一组它可能误解的指令\。如果我需要更多细节，直接看 diff 就行了\。1. 如果你让它们生成提交消息，却没有设置明确的约束，它们也会这么做↩︎ (https://wrla.ch/log/2026/10/idrs-as-records-of-intent/#fnref-idrs-as-records-of-intent-1) ---