This is quite good actually. I would add that some elements of design are worth keeping up, like a general architectural overview and the details of some thing

This is quite good actually. I would add that some elements of design are worth keeping up, like a general architectural overview and the details of some things, like state-machines or specific kinds of statefulness. It can be done in the comments, at the package level, that way developers can keep it up to date without much fuss.