“We’ve got to optimise for AI”
There’s a phrase I keep seeing recently. We need to update our documentation so AI can understand the components better. The repo needs a suite of agent skills so the robots know our internal conventions that aren’t written down anywhere. We need to add an llms.txt because agent crawlers don’t understand our HTML. We need a ChatGPT app because it’s easier to use than our website.
There’s a huge drive to add tons of extra documentation and functionality to help AI agents use our code, our internal systems, our websites, but optimising for humans seems to have drifted to the wayside.
Give an AI Agent raw access to your codebase and it will write some terrible code that ignores half your conventions. Human developers figure it out, some faster than others, but it takes time for them to get up to full speed. The agents start at full speed, they’re just often going in the wrong direction.
So we add documentation for the agents on how we like to do it as humans.
- Handling accessibility
- Adding components
- Structuring props
- Tone of voice
- Writing migration guides
- etc, etc, etc
It makes me think, why did we never do this for us? For humans? Why are the robots so much more deserving of our guidance and attention than people were?
I think the answer might be speed. A robot can make an awful mess, awfully fast, but so can a team of developers without enough documentation.
What’s interesting is that a lot of the solutions we are given are only there to help robots. Agent skills are for agents, not for people. An AGENTS.md is not a README.md. An llms.txt is never read by a human, it’s only for robots.
What about on the end user side? Did we break the internet?
It’s become a bit of a meme. You load up a website, things jump around as 5MB of JavaScript kicks in, a giant cookie banner pops up asking you to agree to tracking from 150 different services and you dismiss it without reading it (or use a plugin to auto remove it). You’re asked to sign up to the newsletter (grab a 10% discount now!), then notifications, maybe an SMS service. You close a couple of adverts that float over the content and finally you might be able to get to the content you wanted to read, if you aren’t redirected to your regional site and bounced away.
I can understand why using the internet through a filter of an agent is a nicer experience. The answer you need - in simple text format, with no adverts, no cookie banners, no sponsored links, no SEO keyword stuffing to wade through. Just the content you wanted, served straight away.
And the robots get given that nice version of the internet too, an llms.txt that doesn’t have all the nonsense associated with visiting a modern website.
Why are we giving all the nice things to the robots and leaving humans in this undocumented, popup filled mess of JavaScript?
Let’s fix the internet for everyone.
Write documentation for people, gently point the agents at it. If your robots don’t understand your codebase, neither do new developers on your team.
Write websites for people, let the agents use them directly. If the robots can’t get the information from your HTML, neither can your users.
Ask yourself, does what I’m creating only benefit AI, or does it benefit everyone?
If we only write for AI agents, only the AI agents will ever be able to use the services we provide, and all we’ll have is a filtered version of the internet where the agents are in control of everything we see.