IDRs as Records of Intent

This explains why Implementation Decision Records (IDRs) should be written as explicit records of intent rather than loose, machine-generated step-by-step plans. IDRs were created to both improve outputs from language models and to provide a durable record of why implementation choices were made. In practice, vague prompts lead LLMs to fill IDRs with prose that simply describes the code changes they intend to make, producing documents that are little better than diffs and that fail to capture the motivating problem, the tradeoffs considered, or the downstream uses that justify the change. An example about serializing repository metadata into DuckDB is criticized for being fuzzy about goals and benefits and therefore not useful as a later reference.

The recommended approach is concise, intent-first IDRs that repeatedly connect decisions back to the original itch: a clear problem statement, explicit goals and non-goals, and a short proposed solution. A contrasting example - automating PyPI uploads from GitHub Actions - shows how a focused problem statement and guardrails steer both human readers and agents toward the intended outcome without drowning the record in implementation detail. Implementation diffs should live in commits; IDRs should capture why the work was done and what success looks like.