It doesn't have to be this way.
AI is great at following patterns. AI is great at writing tests. AI is great at doing work that humans would consider drudgery and then applying "enough" judgement to it.
The problem is that most software teams and most engineers are very, very bad at the thing that AI needs to succeed: technical writing. Documenting the patterns, the rules, the heuristics, the SOP, the judgement; developers could barely be bothered to write comments before (which in the AI age are free, infrastructure-less memory that is always "line-of-sight" for the agent and can be used to enrich with keywords).
It's not that AI is the problem, it's that we humans are good at resolving these constraints in the real world at a human pace. AI makes that pace impossible for a human to keep up as a trailing activity. Rather teams need to invest more in technical writing and producing the corpus that AI relies on to learn the operational constraints and rules.
> The problem is that most software teams and most engineers are very, very bad at the thing that AI needs to succeed: technical writing.
Software engineers were at least pretty good at technical writing using the artificial languages we created to enable clear, unambiguous technical writing... programming languages. Seems like software engineers might do better using AI if they remembered this and started using pseudo-code as their language for spec writing (as many have recommended).
The urge to one-shot everything isn't helping. Getting people to push back on assumptions the model is making, and to have an actual conversation with it about the solution, would lead to more maintainable output.
Maybe part of it is laziness but for sure part of is low morale and hopelessness.
I absolutely agree, as a child of automotive industry I am looking on software development through the lenses of kaizen loop. If you can loop the development cycle so it can correct itself through tests, then errors, either human or AI made are never going to be a problem, they will get self corrected by the testing.
Where do you get the correct test results? First from the specifications, then gradually from the edge cases found by testers and eventually users. It is not one shot process it is a big loop which will get repeated over and over again until users will run out of things to break.
The software is breaking because nobody is bothered to write down what is software actually supposed to do, and from there to create a set of tests which will anchor the behavior of software.
I've been forming this hypothesis, too: that the thing that AI needs to succeed is technical writing, "documenting the patterns, the rules, the heuristics, the SOP, the judgement." Certainly, when I do it, it seems to help, and when AI goes off-track, it seems to often be traceable to me not doing enough technical writing.
But I wonder: am I possibly engaging in wishful thinking? I believe myself to be good at technical writing, so it would certainly be very flattering for my ego if technical writing were suddenly the thing that AI needs to succeed. So I'm a little skeptical of this perception of mine!
How would you convince someone skeptical that technical writing is the thing AI needs to succeed?
(QA, incidentally, is another thing I think I'm particularly good at, and I have the impression that it's also crucial to the success of current AI, and it's not the same thing as technical writing. AI can identify when code crashes, doesn't pass automated tests, or doesn't look like the wireframe, but it's not yet very good at identifying when it's difficult to use or confusing.)
That just follows from the fact that people can learn. Human organizations always have to balance between tacit knowledge and explicit documentation. Document too little, and onboarding new people will be more difficult, and you will lose information when people quit. Document too much, and you are just wasting time without doing anything productive, because people would have figured out that extra information in less time than it took to write it down.
The fundamental problem is that current AI tools don't learn. They make the same mistakes over and over again, unless you give them explicit instructions to avoid those mistakes. Maybe we need to accept that all work is now done by new hires, who have read all the documentation but have no experience in anything. Or maybe AI tools will get better, and all that tedious documentation effort was just a waste of time.
> developers could barely be bothered to write comments before (which in the AI age are free
I consider the comments AI writes to be far worse than the code. I am rewriting them a lot more often than I rewrite the actual code. They are overly wordy and include a lot of unnecessary asides that make it sound like a LinkedIn post. Or it will reference specific irrelevant things in the prompt that won’t matter when someone looks at it 6 months from now.
The problem is not the input (documentation) it's the evaluation of the output. Managing an AI is like managing a team of specialists, whose subjects you are not a master of. Most programmers did not have the problem of managing experts - we were the experts. There are those that do, but several of the levers you have over a team of humans (incentives, responsibility, even hiring and firing) are not available to control an AI, and the new levers ( fine tuning, training, reinforcement learning) are not in the hands of those relying on it. This is not solved by any amount of documentation.
You're asking ICs to become managers of a bunch of mid-level developers (agents). It's a skill that has to be developed like any other, and takes time.
It does have to be this way, unfortunately, because AI bros will press to have as much software produced at the absolute minimal cost possible.
I've seen it first hand. 70 people fired, 20 people left. The 20 that are left take on all the work that was done before, plus some extra, because every company now has a new AI product, obviously. AI agents make us so productive. Every review is a 30 second LGTM on 500 new lines of code. Confluence filling up with AI slop.
A few weeks back I saw, first hand, a DevOps lead getting ready to ship a big update to performance-critical product where Opus 5.5 suggested they completely turn off JIT everywhere because they were running into a HotSpot C2 optimizer bug that would make the first request after a restart fail with a 500. Actual fix was a one-line adjustment somewhere in a library.
People are scared of being replaced, so they need to appear as productive as possible.
This is hilarious. Just "document the patterns and the rules" guys, then AI can do the rest.
I agree that humans are the problem and their gullibility towards token prediction algorithms and CEOs blathering.
SOP and documentation is everything. You don’t want it going out of bounds and coming up with its own solutions, which are often just inefficient facsimiles of random stuff it finds that seems to makes sense. You also run the risk of not understanding the solution it puts in front of you. With an ironclad SOP and quality documentation, you know when it is straying from the best paths, because they are laid out for both of you.
Plus your documentation can often work very well alongside whatever skills you have created over time, because you basically have two sources it is drawing on telling it to do the same thing. I find it leads to less off book behavior.
I’ve always been perplexed by how people see AI as this creative tool or something to innovate with. That’s not how I see it at all. I see it as a device that can follow a template very well if you lay good tracks. They can archive and check hundreds of pieces of media way faster than I can. But I would never trust it to craft a story
"AI is great at following patterns", sure but if some attackers can "inject attack patterns" at a high rate in your training set (check "dataset poisoning") then it's going to be an issue...
I completely agree, and I’m building a tool to solve exactly that challenge.
Pathfinder lets you understand your product’s building blocks. So you and your team pilot your agents at the product level, not the code level.
It’s augmented product engineering: https://pathfinder.com.ai
I'm actually quite good at building robust systems, cleaning up messes, documenting things well.
As a result I get:
1) The enmity of my lead dev who prefers to do things more fast and loose.
2) Not promoted, due to the first reason and due to the fact that I don't have "impactful" metrics.
I'm not saying I'm perfect, there are definitely things I could have done better. But the fact still remains that the industry grossly undervalues maintenance and optimization that doesn't lead to easily measurable numbers that impact the bottom line.
That in turn is because it's hard to tell if SWEs are actually paying down critical debt or just wasting time. But that's the core problem, not that we're not good at it.
The good news is I can get AI agents to do this kind of work so I can now chase after metrics.