IDR（実装決定記録）を意図の記録として

Writing the Docs: 2026 Editionで、IDR（Implementation Decision Records、LLM採用以前のArchitecture Decision Recordsのもじり）について少し話しました。 復習になりますが、私はそれらをいくつかの目的のために作成しました。 LLMからより良い出力を得るため 機能の実装中に下された決定の永続的な記録を提供するため 自分で適当にやらせると、LLMは曖昧なプロンプトに対して、とにかく実装しようとしていたことのテキスト記述で埋めようとしがちであることがわかりました。[1] これは、意図の記録としてはかなり情報が失われやすく（基本的にdiffより少し良い程度で、むしろ悪いとさえ言える）、出力の改善にもあまり役立たないのではないかと懐疑的です。せいぜい、コードが書きすぎられる前に、より良い結果に誘導できるかもしれません。 その良い例がこれです。エージェントに、中間表現としてDuckDBを使用するようにrepo-parserを更新するように依頼しました。 # DuckDBシリアライゼーション オーナー: Will Lachance <will@lachance.tech> ## 概要 ### 問題提起 repo-parserはリポジトリからメタデータと構造をインメモリの`Resource`ツリーに抽出しますが、この一時的な表現は各コンシューマーのために再作成する必要があります。リポジトリを再スキャンすることなく、複数のツールが抽出されたメタデータを消費できる、永続的でクエリ可能なシリアライゼーション形式が必要です。 ### コンテキスト <非常に長文で、ほとんど不可解なLLMコンテキスト> …リンク 問題提起はひどいものではありませんが、かなり曖昧でもあります。「duckdbを何らかの形で使用して」他のメカニズムを置き換えるという目標以外、エージェントにあまり多くの目標を与えなかったと思います。結果はまあまあだったと思いますが、IDRがそのプロセスにどれほど価値があったのか疑問に思います。repo-parserのDuckDB出力が実際に何に役立つのか（リポジトリの内容のBM25検索インデックス、おそらくTUI検索ツール）を説明するのには役立ちません。そして、後で読み返したいものでは決してなく、今見ると身の毛がよだちます。 私がますます気づいているのは、IDRが本当に効果的であるためには、意図とそれをサポートするために取られた決定に戻り続ける必要があるということです。これがないと、単にdiffを英語で言い換えるための冗長な方法にすぎません。 私はこちらの方がはるかに満足しています。 # GitHub ActionsからPyPIに公開する オーナー: Will Lachance <will@lachance.tech> ## 概要 ### 問題提起 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/main/.github/workflows/pypi-package.yml)（おそらくベストプラクティス） リンク 問題提起は、介入を行いたいと思った「かゆみ」を説明しています。目標、非目標、ソリューションは短く、簡潔で、実装の詳細に踏み込むことなく最終結果を説明しています。後でリポジトリを見返したときに、見たいのはこのようなものです。 ボーナス：LLMを使用する場合、より明確なガードレールを提供します。各文は、誤解される可能性のある指示のセットではなく、私が実際に見たい結果に向かって行動を誘導する仕事をします。より詳細が必要な場合は、diffを見るだけです。 また、強力なガードレールなしでコミットメッセージを作成するように依頼した場合も同様です。 ↩︎