AI Coding

Almost everyone using AI to write code is doing it badly, vibe-coders and senior engineers alike. The biggest obstacle is your own culture: you keep forcing AI to work like a human instead of rebuilding how you work around it.

I see a lot of people attempting to use AI for coding with very mixed results. This ranges from vibe-coders that have no technical skills through to senior engineers who use AI to assist with things they understand well.

In nearly all cases, people are doing it in a way that is very inefficient or results in bad outcomes. The vibe-coders get the most grief for this, but honestly it's across the board. I'm going to create a bunch of posts on the topic. Sort of a “AI Coding 101”. It will help vibe coders the most, but is useful for everyone. These tips are things I have implemented in projects and use every day. So no bullshit or “best practice” theory, this is all real world actions you can implement, that make a material difference in how well AI coding will perform.

While I am going to demonstrate how to actually implement this stuff, the most important thing is to shift your way of thinking. You have to stop thinking of AI as a tool that you implement into your existing practices. Instead, throw out your existing practices and rebuild them to align with AI. If you don't, you're just burdening the AI with human centric limitations, company politics and general garbage it has no use for.

That shift in mindset and company/team culture will be the single biggest obstacle you have for effectively implementing AI into your organization. Whether it's generating code, completing business workflows or generating content, forcing the AI to align with humans is the least effective strategy.

Documentation

The first thing we'll tackle, is documentation

Ever since humans started writing code, there have been arguments about the need to document that code. This typically covers areas such as inline commenting or documents code stored in the version controlled and documentation locations such as wikis, file servers etc.

Beyond documenting the actual code, it was always considered a good idea to document your products, processes and business/product strategy. Actually making all this happen is big business, and there are hundreds of tools out there that are intended to help get it done. Nearly all of which fail miserably, either because the tooling sucks or the humans simply refuse to do it for a range of (somewhat legitimate) reasons.

This is manageable when humans are the intelligence in the workflow. Humans spend a great deal of time, managing context. We read in docs, validate/extend them on the fly and seek additional information if required. Mostly that works, even when the information is bad. People will work it out and hopefully make some common-sense decisions about what to do/not do with the information provided.

This all changes if you use AI as the intelligence component in the workflow. The AI will not behave like a human, and it will do some very unexpected things based on your documentation.

If you are using AI in your coding/product you have to take a different approach to documentation.

Don't write documentation for humans, write it for AI

There is no point creating documentation for humans, in a world where AI is doing most of the heavy lifting. It will cause far more problems that it solves.

• The change rate will be far too high. Even if humans wanted to read it, it will change faster than they can keep up. It’s a waste of time.
• The AI doesn't need all the fancy padding that humans need in the data. Documentation made for humans is written to be readable, to explain things to the lowest common denominator. AI has no use for this.
• AI needs the documentation to be as blunt and brutally honest as possible. It has no feelings too upset, so there is no point creating vagueness in an attempt to be polite / soften the messaging.
• You need to keep it very concise. AI has limited memory/context and you don't want it loading more data than necessary. Bullet points are your friend.
• Keep it heavily structured. Lots of headings and nested bullet points. Separate data into many smaller files. You want to create a pyramid that the AI can walk down to the relevant data
• Keep the documentation in Markdown format.
• Don't include images! If you need diagrams, use Mermaid

Most importantly of all, humans should not be writing the documentation, the AI should.

Every time code is changed, the AI should review and update all documentation that references the affected code and update it as required.