Let's talk about specs
I’ve been hearing this lately: “Specs are useless, they go out of date instantly and code is truth”.
More concerningly, if you’ve got AI writing all the code (which you don’t read), and AI writing all the tests (which you don’t read), then “code is truth” means you have no clue what the truth is.
It’s something I believed as a fresh, inexperienced software engineer.
Well, it was a process over many years..
Phase: naive optimism
Whoah, specs are amazing!! We should document our intent before writing code!
Phase: cynicism
I hate specs. No one updates them once written; only the code contains the truth. Waste of time.
Phase: enlightenment
I need specs, because code doesn’t explain even 1/10th of the system’s behavior.
In a complex, battle-scarred codebase spread across many services both first and third party, the actual source code can lead to some extremely wrong answers.
Throwing more agents at the problem helps, to some extent. Have your agents search everywhere, go ahead and dump the prod DB while you’re at it, and make sure you’re looking at all those resources in the cloud provider too that no one’s touched since the middle-ages!
At the end of the day, I believe a human has to document intent. Use tests, prose, agents to also document how it works now. We need both.
Keeping a cache up to date and evicting from it is a hard problem.
Specs behave as a cache of your system. Treat it like a hard and serious problem; write tooling to keep them up to date and maintained.
Your future self, and all your fellow employees, will thank you later.