The Lie We Tell About the Code
Every codebase has two states: the code, and the lie we tell about the code. Most documentation systems make the lie comfortable. One I came across recently doesn’t. Documentation has always been the thing engineering teams promise to do and quietly skip. Sprint deadlines win, the wiki rots, the README becomes archaeology. We all know the cycle. Recently I came across a project (by Franco Dominguez Noriega) that does it differently — and the difference is not just “we tried harder this time.” It’s a structural change that only makes sense in a world where AI agents are part of the development loop. After spending some time with it, I’m convinced the pattern is worth sharing, because it solves the documentation-decay problem in a way I haven’t seen before. ...