I recently joined a team with a very messy codebase. The devs were long gone, and even the ones maintaining it didn’t really understand large parts of the code. The bus factor was effectively zero.
What surprised me was how useful AI was. It helped me not only understand the code but also infer the probable intent behind it, which made debugging much faster. I started generating documentation directly from the code itself.
For me, this was a big win. Code is the source of truth. Developer documentation and even shared knowledge are often full of bias, selective memory, or the “Chinese whispers” problem where the story shifts every time it’s retold and never documented. Code doesn’t lie, it just needs interpretation. Using AI to cut through the noise and let the code explain itself felt like a net positive.
As a manager, I am considering to enforce a rule on my team that -- no README in any repo should ever go stale ever again --> it should be near-trivial for every dev to ask Claude Code to read the existing README, read/interpret the code as it practically currently stands, read what's changed in the PR, then update the README as necessary. This does not mean Claude will be perfect or that engineers don't need to check that its summaries make sense (they do, and the human is always accountable for the changes at the end of the day); but this does mean that, the typical amount of laziness that we are all guilty of often, should not be eliminated as a reason as to why READMEs go stale.
Why have such a rule if at any moment of time the LLM could update the readme ad hoc? Btw, your ingested readmes will affect your LLM's code generation and I made the observation that more often than not it is better to exclude the readmes from the context window.
What surprised me was how useful AI was. It helped me not only understand the code but also infer the probable intent behind it, which made debugging much faster. I started generating documentation directly from the code itself.
For me, this was a big win. Code is the source of truth. Developer documentation and even shared knowledge are often full of bias, selective memory, or the “Chinese whispers” problem where the story shifts every time it’s retold and never documented. Code doesn’t lie, it just needs interpretation. Using AI to cut through the noise and let the code explain itself felt like a net positive.