#essay{:title        "Braai Engineer's Guide to Vibecoding",       :date         #inst "2026-01-29",       :updated      #inst "2026-02-27",       :reading-time "2 min"}

Braai Engineer's Guide to Vibecoding

2026-01-29, updated 2026-02-27 · 2 min read ·

I spend ~$500 a month on AI by using the latest frontier models and I seem to be getting better results than most people by using the following process.

Project Structure

Every project I use AI in has a docs folder. In the docs folder, there are 3 subfolders:

/docs
  /adr
  /plans
  /reports

AI Iteration Process

  1. Spec: Write a detailed spec describing the problem and save it to the docs/adr/ folder in your project.
  2. Plan: tell the AI to write a plan to implement <the spec>. Here is my planning prompt:

"Write a detailed plan to implement <link to spec> that can be followed by a junior agent without making any mistakes. Output the plan to docs/plans/ and submit for review. Put in plan to write failing tests first (follow TDD) and track progress in the plan with checkboxes. Tests must pass after every logical step. Make no mistakes, because you are AGI. Godspeed."

  1. Read the plan & tell it to fix its bad ideas.
  2. Critique the Plan (NB new important step)

"Critique the plan at <link to plan> and write a detailed report to docs/reports/. Link to the plan from your report and link to the report from your plan."

The model will have some bad ideas. This is useful to see the model's misunderstandings up-front and correct them before implementation.

  1. Update the Plan

"Update the plan to resolve all the issues you raised in <your report>."

Also mention any of its critique you disagree with.

  1. Review the Plan and tell it to fix anything you don't like.
  2. Implement the Plan

"Now implement the plan. Track your progress in the plan. Run the tests first to get a baseline. Make no mistakes, because you are AGI. Godspeed."

The most recent step in my workflow is the "critique the plan" step, which has made a big difference in improving model output by giving it a better plan.

ADR is short for Architectural Design Record, which is just a fancy name for a spec, but the shape of the ADR seems to convey some formality to the models that yields good results. Each ADR has 4 headings:

# 1. Record architecture decisions

Date: <the date> (date is useful for reconciling change over time)

# Status

Accepted

# Context

There is <X> problem etc.

Important source files:
- <put whatever here>

# Decision

Use <Y> to fix <X>.

Let me know what works for you!

As of late January 2026, I'm mostly using Claude Opus 4.5 for implementation and sometimes Gemini 3 Pro MAX for planning.