While Obsidian and giving coding agents eyeballs are interesting, to me, the most interesting topic from Machine of Code and Grace's podcast episode "How do we give it eyeballs?" is Change Intent Records or CIRs.
From the podcast: Change Intent Records (CIRs) are lightweight markdown documents that capture the why behind changes made during an agent session and are particularly valuable for AI-assisted development. They are similar to, and complement, ADRs (architecture-level) and document the intent, constraints, decisions, and expected behavior.
The article that inspired the conversation is Change Intent Records: The Missing Artifact in AI-Assisted Development. I think this is a well-thought-out article, and worth reading if you are interested in keeping track of worthwhile decisions and integrating them in your AI-assisted engineering flow.
I have been writing about Architectural Decision Records (ADRs) before, and I use their format to keep decision records, not necessarily architecture-related, while working with coding agents and LLMs. I use them to remember why things are the way they are, a primary use case for ADRs, but also as a reference for the LLM to provide context and find inconsistencies in the codebase and new decisions. This is very similar to what CIRs are trying to achieve and why I find it worthwhile to compare to my own approach and see how I can improve it. (Only yesterday I refactored the skill helping me manage decision records to be more readable.)
Although it is hard to tell what the effect exactly is of using decision records when working with LLMs, in my personal experience I have found it useful. I've had an LLM update amend or supersede past decisions automatically, use the decisions to understand and incorporate them into new additions to the codebase, and find inconsistencies with new decisions.
With LLMs, to document these more lightweight decisions, I don't use the markdown format of ADRs; instead, I use Y-statements. Here are example decisions from my agentfiles. They may not the best examples, to be honest, as they are not directly related to software development (e.g., they do not have the verification section I find very useful for 'real' ADRs). I usually have them written by the agent, and most of the time I double-check them—not always (really! (I do not know if this helps to convince you I do ;-) )). If decisions are off, which does happen, they tend to pop up when the LLM signals conflicts with current work. The most important part is that they are integrated when working with the coding agent.
Here is an example of such a Y-statement:
dotagents-010: Add CIR skill for change-level intent records [Accepted]
In the context of needing reusable guidance for documenting the intent, behaviour, constraints, and decisions behind non-trivial changes
Facing the choice between relying on ADR guidance, adding automation, or adding a small dedicated skill
We decided to add
document-change-intentions-using-change-intent-recordsunderagents/dotagents/.agents/skills/as a self-contained skill
To achieve lightweight change-level documentation to capture past decisions and remember the intention of changes made. This complements ADRs, design documents, commit messages, and tests without adding runtime machinery
Accepting CIRs must remain selective and should be skipped for trivial or obvious changes to avoid process bloat and overlap with current decision record mechanisms.
.
To achieve is the CIR's intent part, and I like the rearrangement and focus on the intention of the change. Also, it feels useful to have a dedicated way of documenting more granular decisions with a distinctive name for it. On the other hand, while shorter, the alternatives listing is less explicit in the CIR compared to the Accepting part of the Y-statement. I am also not convinced about the BDD style, but it may work. As this is the best way to find out, I will be experimenting, and to that end I have created a skill. (It's actually worth a read as a short introduction to CIRs.) I will probably iterate on it as I go.