Beyond a certain size, the documentation becomes too large to ingest. Below a certain size, it can only contain a fraction of what is needed. If you take any sufficiently engineering project, and give every engineer amnesia; the project will go to shit for a undetermined amount of time, as it takes months or years go build-back the understanding that was lost.
This is clear enough then large companies fire and replace workers randomly to cut costs; a worker that has built up useful knowledge in the origination over a few years is more valuable than three cheap consultants from "low-cost countries" that are fired when the work package is over.
---
AI, looses its memory every time we press "new thread". No spec can bring that back until AIs become able to write and ingest whole books of context without getting confused.
The revenue for a new feature today is something sure. While the cost associated with supporting such feature will be up to debate in the coming quarters.
As often it is the case, we are moving on a long vs short term trade-off space. And I don't think any experience will generalize
When I worked at a big tech company on a large codebase (tens of millions of LOC across dozens of repos), it was extremely common to work on something in an area of the codebase I had zero familiarity with, and due to turnover, no one else at the company did either. As you say, docs were frequently missing or out of date.
However, with some effort over a couple hours, I could make a LOT of progress in understanding the history of the code. Every commit and PR were linked to JIRA tickets, most had eng design docs with comments, slack discussions, etc. I could step through the git history and watch the code change, alongside the artifacts of the human discussion and decisions that led to the changes. It wasn’t perfect, but I could make tremendous progress. Now, this was a remote company with pretty strong culture around using JIRA, design docs with review, etc. Probably the biggest gap was meeting transcripts.
Today, an agent can chew through years of history and artifacts on a large codebase in a half hour, documenting as it goes, and have way better understanding of it than I ever will.
It’s true that an agent can’t hold all of that in its head at once without context rot (though this is improving every year), but neither can any human!
If your goal is understanding how to do something, why something was done, why something wasn’t done, etc, and the codebase is large, mature, and extremely well-“artifacted”, I’m not at all convinced that you’re better off asking Bob who has worked on this section of the codebase for a decade than just asking a really good frontier-level agent. Maybe, but it feels like that won’t be true much longer.
At my last job we worked in a large, but publicly available code base. My experience was that just giving an agent the prompt to look at area X to figure out how it works would use up half or more of the context window. And that was thrown away every time we started again. We had docs, agent generated overviews but the agents still filled their context windows way too quickly to actually really be any use.
Like "if you're using this database, and the engine has these configurations, then do _x_, unless _x'_ and _y'_ are enabled, in which case, do _y_..."
Which, if you're already being THAT specific in your spec, you might as well, idk, write the code yourself?
Because at that point your human language is basically the code and AI is the compiler. A non-deterministic one.
Regardless, your business stakeholders won't understand what's going on anyway (nor should they), so we're back at square zero.
(I wrote Technical and Functional Requirements Documents as a business analyst in college. What's happening now _for most situations_ is more or less the same thing.)
AI abstracts effort and cognitive load away from code at a heafty rate, but it doesn’t abstract liability away from code at all.
My business is paid to produce artefacts for which it has liability in the case of error, so we need to do additional work to mitigate and eliminate the liability risk introduced with language models. So far I’ve not found a better way to do that than a plan/act/assert type approach on every feature.