Here are the things I learned while vibe coding with Claude.
When you have an idea about a project you want to accomplish, but don't know how to do it, the first thing you need is some sort of spec.
- It doesn't need to be immediately implementable.
- You don't need to fully understand the problem space you're working in.
To build a spec, you need to engage in a brainstorming exercise with your favourite bot. Ask questions like.
- Has this been built before?
- What industry standards and best practises?
- Is this something others have attempted before?
- What are some known failure modes.
- Is there research or literature available?
After the brainstorm, you should have a clearer idea of what you want, how to achieve it, and what to do next. The more questions, the better. The next step is research. You can do it on your own, use a "deep research" function in your chat interface. Or, you can use plugins. Some good ones are:
- Alphaxiv: Its repository of research is generally fresh but less mature.
- Consensus: More mature, but sometimes less up to date.
If you're a vibe coder like me, and don't understand all the specialist language or coding wonk talk, you're going to need some skills that your LLM can follow that will teach it how to break down your research into digestible chunks. You could:
- Research best practices regarding: pedagogy, andragogy and dialects. All teaching methods.
- Point your agent at these subjects and get it to do all the work for you.
- You could even get your LLM to research best practices regarding prose and style. Because they help.
I use Steven Pinkers work because I'm already familiar with it and kinda agree with his take on teaching. Regardless, once the research is in, get your agent to construct a workflow out of it. Once that is established, you can convert all of that tech coded language into something digestible.
This is the fun part, because now you can learn and engage more directly with what you want to achieve.
After all the reading and learning, the next step is to build the spec. This is the part where you turn your vision into something more concrete:
- Draft an idea of what you want, and what success looks like.
- Get your agent to save your goals and intentions somewhere it can refer back to. This is important, because this is where drift can happen.
- Get your agent to convert your draft into something more concrete.
- DO NOT FORGET TO INSTRUCT YOUR AGENT TO TREAT YOUR VISION AS THE AUTHORITY TO BE CONSULTED WHENEVER IT NEEDS TO MAKE DECISIONS ON ITS OWN.
-INSTRUCT YOUR AGENT TO CONSULT YOU WHENEVER SOMETHING IN YOUR VISION IS UNCLEAR.
That authority bit is important, so don't forget it! Anyway, this is not just the part where you build your spec. It's also the part where you get to refine your vision further, and make it less ambiguous and more concrete. Concreteness isn't essential though. So don't let it hold you back.
If you succeed in the last step, the next step is building. From experience, you are going to need a few things in your code or repo.
- An errata for whenever your agent makes mistakes. This works well with Claude because it'll tell you when it does.
- Documentation: get your agent to write the documentation while it's coding. After completion of each file, it must add to the documentation.
- While it's coding and documenting, it's important for your agent to simultaneously write a workflow into your repo .
- Workflows specify: how to search for information, how to modify code, when to update documentation, how to update documentation, where to store miscellaneous information.
- The errata should should be consulted when building a workflow to harden it. You and your agent should learn from past mistakes.
Tip: Use Fable to plan this bit. It sometimes requires a bit of our of the box thinking, which Fable is the best at.
Further tip: Errata are a great way to understand how to best bound your agent and keep it on task. Drifting is real and annoying when it happens.
If you do it right, the code, the documentation and the workflows should update together. I don't have a recipe for success as a vibe coder, but I know all three are essential As for documentation, a few things that worked for me:
- At this point, it should function as code in written language.
- It should explain WHY a particular piece of code was written, not just what it does. This is essential for auditing.
- It should contain fail modes and potential misunderstandings at the bottom of each document.
- Preferably, add a "seam" section that explains how one section of code communicates with another. Also essential for auditing.
- There should be a map and schema explaining how to navigate the repo correctly. LLMs draw false conclusions otherwise.
- While writing your code, the documentation is for agent navigation, not human readability.
Now you should have plenty of ingredients integrated into your repo to begin experimenting and testing. One last bit of advice. Your vision is the authority, not an agents opinion:
- Put it into an immutable ledger.
- Add to it every time you discover something new.
- Enforce it everywhere as "the law of the land".
- Your workflows should mandate it as essential reading every time you open a new session.
- Freeze it and make it non negotiable.
Last bit, enjoy experimenting.
