This is good, however it’s unclear to me how to manage it in the long run. The list [0] will grow to hundreds of IDRs or more in the long run, and inevitably some will become inapplicable, contradict other IDRs, or become actively misleading when the software evolves. Since the IDRs are supposed to provide information the LLM can’t infer by itself, using the LLM to evaluate their continued applicability is likely not practical.
To effectively manage them, you’d need some sort of topical (?) index to be able to find the relevant IDRs that may need to be updated or removed. Sometimes they might be tied to a particular submodule, but many IDRs may have more crosscutting concerns.
In the end, it’s a form of documentation that needs to be maintained, instead of remaining one-offs limited to the task at hand.
I don't really know why it's important to "provide a durable record of a decision made during the implementation of a feature", but other than that I do something similar. I have the agent write a PLAN.md which looks just like this IDR template. It's written before implementation begins, and I approve it before the agent goes. I don't save them after the session ends.
For each project, I define "review surfaces": parts of the code that I have a strong opinion about. These get resolved in detail before implementation begins; the LLM can do whatever it wants to other parts of the code, but the parts I list can't change without another review. Typically, these are things like the public API or database schema.
> I don't really know why it's important to "provide a durable record of a decision made during the implementation of a feature"
How often have you looked back and said, "Why the hell are we using/doing X?" and it turns out, the obvious natural choice (now), Y, did not yet exist at the time the decision was made. Recording the why and attempting to capture some of the diligence performed before the decision is critical in understanding when decisions are worth re-evaluating in the future.
To effectively manage them, you’d need some sort of topical (?) index to be able to find the relevant IDRs that may need to be updated or removed. Sometimes they might be tied to a particular submodule, but many IDRs may have more crosscutting concerns.
In the end, it’s a form of documentation that needs to be maintained, instead of remaining one-offs limited to the task at hand.
[0] https://github.com/wlach/repo-parser/tree/main/idrs
For each project, I define "review surfaces": parts of the code that I have a strong opinion about. These get resolved in detail before implementation begins; the LLM can do whatever it wants to other parts of the code, but the parts I list can't change without another review. Typically, these are things like the public API or database schema.
How often have you looked back and said, "Why the hell are we using/doing X?" and it turns out, the obvious natural choice (now), Y, did not yet exist at the time the decision was made. Recording the why and attempting to capture some of the diligence performed before the decision is critical in understanding when decisions are worth re-evaluating in the future.