Good vibe coding is good coding

I like opening an unfamiliar library or project and finding a README that gets me going. Within a few minutes, I understand what it's for and have an example running. I can start exploring, and there's somewhere to look when I get stuck.

A missing or outdated README makes that first visit much harder. Even getting started means guessing which instructions still apply.

I think this is a useful starting point for working with LLMs. A project that's easy for a person to understand and build on is also easier for an LLM to work in. Before adding more instructions for the agent, I'd look at what we're handing it.

Start with a project someone can understand#

A good README provides an introduction and a way in. It explains what the project is for, how to run it, and where the important parts live. A few conventions and links to useful examples can be enough to get someone working. From there, they should be able to learn by browsing the code.

That puts some responsibility on the code itself.

Good names and clear boundaries help someone follow a feature without having to hold the whole application in their head. Consistent patterns give them an example to build from. The details of behaviour belong in the implementation and its tests, where they can be understood and changed together. If that structure is confusing, documenting every turn won't make it much nicer to work in.

An LLM has more to work with when those patterns are clear, too. If there are several competing approaches and no obvious reason for the differences, it has to choose among them. We can write another instruction explaining which one to use, but consolidating the code would also resolve the confusion for the next developer.

This is why I'm reluctant to build up a separate collection of instructions for agents. A short file pointing to the README, the relevant guides, and any essential constraints can be useful. I wouldn't want it to become another account of how the whole project works. Each change would then need checking in two places.

I'd rather give the person and the agent the same useful material. Keep it current, remove what no longer helps, and let the code explain what it can.

Give them something to build with#

The same idea reaches beyond documentation. When I'm working on a web interface, I want the project to have some design decisions already made. A theme and reusable components let me build within a visual direction instead of choosing typography, colours, and spacing again on every page.

Those choices need to be available to use. A design system hidden in scattered files is easy to overlook. A browsable set of components, with examples and a little guidance, lets someone see what exists and how it fits together. An agent can use those same examples when adding to the interface. Keeping the design consistent becomes easier because the project offers a clear pattern to follow.

I still want to be able to try it.

Easy setup, debugging tools, and repeatable sample data make that practical. I can explore different states, inspect a change, and reproduce a problem without spending half the session arranging the conditions. An agent can use those tools to check its work, and I can use them to review the result. The effort goes into understanding the interface instead of getting it into a state where there's something to understand.

Tests provide another part of that feedback. Unit tests for important logic and integration tests for the parts that work together help establish what the application expects. Keep the coverage appropriate to the product and current as it changes. A check that anyone can run is more useful than a behaviour only the original author remembers to verify.

These are ordinary qualities of a project I'd enjoy working on. They also give an LLM clearer examples, fewer things to guess about, and ways to find out when a change is wrong.

Use the help to improve the project#

It's easy to keep prompting for features and leave all of this for later. Each addition works well enough, so you move on. Eventually the project is spaghetti, and every small change needs an explanation of all the exceptions around it. Using an LLM hasn't made those exceptions any easier to live with.

The cleanup is work we can give the LLM, too.

The agent can consolidate duplicated code, bring the README up to date, and remove old guidance. It can help build the design system and its examples, fill gaps in the tests, or make the development tools you've been putting off. You can give it this work just as you would a feature.

Your part is to review whether the project has actually improved. Read the docs, browse the components, and try the tools. Check that the tests protect the behaviour you intended. More files and more rules aren't much of an achievement if the result is harder to understand.

I'd judge the result the same way I judge that unfamiliar library. Someone should be able to get started, find a useful example, and make a change they know how to check. That is a good project to hand to another developer. It's also a good project to hand to an LLM.

That's where I'd put the effort before writing another page of agent instructions. The readable code, useful docs, and shared tools that welcome a person into the project give the LLM a better starting point as well. Good vibe coding is good coding, with more help available to do it.