IDR 如何成为记录意图的文档：Will Lachance 谈 Implementation Decision Records 的实践

2026年10月10日

Beaver Pond

在《编写文档：2026 年版》中，我稍微谈到了 IDR（Implementation Decision Records，实现决策记录，是对早于 LLM 普及之前的“架构决策记录”的双关）。

作为回顾，我创建它们是为了实现几个目的：

让 LLM 产出更好的输出
为功能实现过程中做出的决策提供一份持久的记录

我意识到，如果放任不管，只给一个模糊的提示，LLM 往往只会用一段文字描述它本来就打算实现的内容来把它填上。^[1] 这使得它们作为意图记录相当有损（基本上不比 diff 好多少，甚至可以说更差），而且我有点怀疑它是否真的能大幅改善它们的输出。往好了说，它们或许能让你在写太多代码之前把 LLM 引导向更好的结果。

一个很好的例子是这个，我让 agent 更新 repo-parser，改用 DuckDB 作为中间表示：

# DuckDB serialization

Owner: Will Lachance <[email protected]>

## Overview

### Problem Statement

repo-parser extracts metadata and structure from repositories into an in-memory `Resource` tree, but this ephemeral representation must be re-created for each consumer. We need a persistent, queryable serialization format that allows multiple tools to consume the extracted metadata without re-scanning the repository.

### Context

<very long winded, almost inscrutable LLM context>

...

链接

问题陈述不算糟糕，但也相当模糊。我觉得它并没有真正给 agent 一个明确的目标，除了“以某种方式使用 duckdb”来替换某个其他机制。我认为结果还算可以，但我有点怀疑 IDR 在这个过程中有多大价值。它当然无助于解释 repo-parser 的 duckdb 输出实际上有什么用（一个仓库内容的 BM25 搜索索引，可能是 TUI 搜索工具）。而且它绝对不是我想以后再读的东西，现在看着它我都觉得尴尬。

我越来越意识到，要让 IDR 真正有效，它需要不断回到意图以及为支持该意图而做出的决策上。没有这一点，它只不过是用英语把 diff 重新啰嗦一遍。

我对这个满意得多：

# Publish to PyPI from GitHub Actions

Owner: Will Lachance <[email protected]>

## Overview

### Problem Statement

repo-parser packages can only be published to PyPI manually, which is time consuming, error prone and less secure than doing so via GitHub actions.

### Context (as needed)

### Goals

- Make it easier to publish new releases
- Improve security

### Non-Goals

- Automate version bumping (will still entail a seperate commit to bump version)

### Proposed Solution

Use the idiomatic best practice way of doing this, using the official packaging guide:

https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

In general this means adding a new GitHub workflow which ties uploads to PyPI to new releases.

## Other reading (as needed)

- [Official Guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
- [Stamina's implementation](https://github.com/hynek/stamina/blob/b25d4bc359ff603496aafbb217ab82c5a43715a6/.github/workflows/pypi-package.yml) (likely best practice)

链接

问题陈述描述了我想要进行这次干预的“痒点”。目标、非目标和解决方案简短有力，解释了最终结果，而不深入实现细节。当我以后回头看一个仓库时，这才是我想要看到的东西。额外好处：在使用 LLM 时，它提供了更清晰的护栏。每一句话都在把行为引导向我真正想要看到的结果，而不是一组它可能误解的指令。如果我需要更多细节，我直接看 diff 就行了。

如果你要求它们在没有强护栏的情况下创建提交信息，它们也会这么做 ↩︎