I don't understand. Code doesn't capture the context in which decisions were taken: why is code the way it is? What is important? What is not? How can agents make correct decisions without knowing context that cannot be inferred from code?
> If it's not, that's what commit messages are for.
Wouldn't this require that your commits would have to be as frequent as each new reasons why? That could easily end up being a commit per function, which seems crazy to me.
I always put any important why close to the code that I'm explaining. For architectural explanations, maybe at the top of the file, or for really high level "how it all works together", in an md.
I'm seeing ENORMOUS decision files and when I read them a lot of the decisions are self-evident. Or the decisions flip flop but the old decisions remain in the file, which fucks up context. It's often better to completely remove a reference to X rather than leave it and have an amendment later that says "don't do X". Because X is in context, now the LLM is more likely to stumble into doing X.
