Part 1 of 6. The whole series uses one running example: this website, and the
real git history behind it.
Someone recently asked me: "When you use AI tools, what do you do differently than most people?"
I thought about it. Then I realised the best answer wasn't a paragraph. It was this entire website. So here's the story.
This is the first of six posts. By the end of the series you should be able to
go from chatting with an AI to running an agent that can touch a real codebase,
use real tools, read your real content, and be stopped from doing anything
stupid. Every example comes from this site's repository, including the parts
that broke.
Let's start with what most people do
I'm not judging. I've done it too. But let's be honest about the pattern.
You open a chat window. You type "Build me a portfolio website." You get a wall
of code. You copy it. You paste it. Something breaks. You go back and say "Fix
this error." You repeat that about fifteen times. You end up with something that
kind of works but you have no idea how. You can't change it. You can't fix it.
You're stuck.
I call this vending machine mode. You put in a request, you get something
out, and you have no idea what happened inside the machine. The moment it gives
you the wrong thing, you are lost.
That works for small stuff. Need a quick script? Fine. Building a real product?
That needs something else.
So what actually is an agent?
Here is the difference, in one line.
A chat window can only talk. An agent can do things and see what happened.
That is genuinely most of it. A chat window takes your text and returns text. An
agent has a loop: it can take an action, look at the result, and decide what to
do next.
The loop is the whole thing. It is why an agent can run your build, read the
error, fix the file, and run the build again, while a chat window can only tell
you what the error probably means.
Three words you will keep meeting, in normal English:
Context is everything the model can see when it answers. Your question, your
files, the error message, the instructions you gave it earlier.
Context window is how much of that it can hold at once. Think of it as desk
space, not memory. When the desk is full, something falls off the edge.
Tokens are how that space is measured. Roughly, a token is a chunk of a word.
You pay per token, and you run out of desk per token, which is why "just paste
the whole codebase in" is not a strategy.
Step 1: I told it what I wanted, not how to build it
I didn't know I was going to use Next.js. I didn't pick React. I didn't choose
Tailwind. The agent recommended all of that. But I knew exactly what I wanted the
result to be.
I said things like:
"I want a portfolio site that feels like a space observatory. Dark background. Glowing particles that look like neural networks. When someone visits, they should feel like they're looking into something intelligent."
"I need a blog where I can write technical posts with code examples and math equations. I want the posts to just be files I write in a folder. No database for the blog."
"I want an AI chatbot on the site that sounds like me. It should know about my career, my projects, my philosophy."
Notice what I did not say. I did not say "use Next.js". I did not say "use MDX".
I described what I wanted the thing to do and how it should feel.
It came back with: Next.js with the App Router, because I needed both static
pages and dynamic API routes. MDX for the blog, so posts stay as files with code
blocks and maths. The Vercel AI SDK for streaming chat responses.
I said yes, and we started building.
You don't need to know the tools. You need to know what you want. The model
has the technical knowledge. What it does not have is your intent.
Step 2: I asked questions instead of giving orders
This is the part nobody teaches. The secret is not better prompts. It is better
questions.
"Build me X" is an order, and an order without context produces something
generic. So I asked:
"What's the best way to structure this so I can add new pages without rewriting the layout?"
"If I want the chatbot limited to 10 messages per person per day, where should that logic live? Client or server?"
"What happens when the blog gets to 50 posts? Will the build slow down?"
Each question taught me something, and each answer shaped the architecture. I was
not blindly accepting code. I was having a conversation about design. The agent
explained the trade-offs, I made the decisions, it wrote the code.
It is like working with a builder. You do not need to know how to pour concrete.
You do need to say "three bedrooms, open kitchen, living room facing the garden".
Step 3: I built one room at a time
Another common mistake: trying to get the whole thing in one prompt. "Build me a
complete portfolio with a blog, contact form, animations and an AI chatbot."
That is asking someone to build your house in an afternoon.
I built the layout first. Navigation, footer, background animation. Tested it.
Committed it to git. Then the homepage. Then about, work, blog.
Each piece I reviewed. "Why this approach and not that one?" "What happens on a
phone?" And each working piece got committed, which matters more than it sounds.
Git is an unlimited undo button that also keeps a diary. When an agent is writing
code fast, the ability to say "go back to the last version that worked" is the
difference between a bad hour and a lost day.
Why one giant prompt is never enough
Here is the thing that took me longest to internalise.
The model does not know your project. It knows programming. Those are very
different, and the gap between them is context.
When I started, I would explain the same things every session: this is a Next.js
site, posts are MDX files in content/blog, do not use a database for the blog.
Every time. That is your desk space going on repetition instead of work.
Two things fix it. Project instructions, a file the agent reads every time,
so the standing rules live somewhere permanent instead of in your typing. And
repository context, letting the agent read the actual code rather than
guessing from your description.
This is why an agent that runs in your terminal, in your project, beats a chat
window in a browser. Not because the model is better. It is the same model. It
can just see more of the truth.
Feedback is the whole trick
The single biggest difference between someone who gets good results and someone
who gets frustrated is whether the agent can find out that it was wrong.
If it writes code and nobody runs it, you have a very confident guess. If it
writes code and runs the build, the build fails, and it reads the failure, you
have engineering.
change
↓
run it
↓
read the result
↓
fix
↺
That loop is the spine of this whole series. Everything in the next five parts
is either giving the agent something to act on, or giving it a way to find out
whether the action worked.
The framework I use for knowing what to ask
I call it the Mom Test. If you can explain what you want to your mother, you can
explain it to an agent.
Don't say: "Implement a rate-limited streaming API route with Supabase-backed
IP tracking."
Say: "I want the chatbot to only allow 10 messages per person per day so
nobody runs up my bill."
The agent translates plain language into technical decisions. That is its job.
You bring the what and the why.
Four kinds of question that consistently work:
Vision: "I want it to feel like X."
Behaviour: "What happens when someone does X?"
Protection: "What if someone abuses this? How do I avoid a huge bill?"
Quality: "Will this work on phones? What if I have 1000 posts?"
You do not need to ask about React hooks or server components. You need to know
what you are building and care about getting it right.
What I actually contributed
Could I have built this without AI? Technically yes, in months rather than days.
Could it have built this without me? No. It would have produced a generic
template that looks like every other portfolio on the internet.
My side: the vision, the decisions, the quality bar, and the debugging context.
Its side: every line of code, every technical recommendation, and knowledge of
hundreds of tools I have never used.
The combination is the point. Not AI alone. Not me alone.
Where this breaks down
Everything above got me a working site. Then I hit a wall, and it is the wall
everyone hits.
The product does not live only in source files.
The database is somewhere else. The hosting platform is somewhere else. The
deployment logs are somewhere else. So the loop kept breaking at the same place:
the agent would make a change, and then I would become the courier, copying
error messages from a browser tab back into the terminal by hand.
An agent that cannot see the result of its own actions is back to being a chat
window with extra steps.
That is Part 2. How you give an agent hands, what it can safely touch, and why
the moment it becomes genuinely useful is also the moment it becomes genuinely
dangerous.
Try it yourself
Reading about agents only gets you so far, so I built a small companion kit you
can download and run: agent-roadmap-kit on GitHub. Each part of this
series is one stop in it. By Part 6 the pieces add up to one working assistant
that answers customer questions for a made up Soshanguve home kitchen, Mama
Dineo's Kitchen, from a folder of its notes. Swap in your own notes and it
answers about yours.
It costs nothing to run. You need Node 22.18 or newer and one of three free options: a Gemini key from Google AI Studio (no credit card), a small model on your own machine through Ollama, or the built in mock, which needs no key and no internet at all.
git clone https://github.com/LeparaLaMapara/agent-roadmap-kit
cd agent-roadmap-kit
npm install
npm run check
This first stop is the chat half of "chat versus agent", plus the templates I
actually use. It lives in the Part 1 folder of the kit.
npm run part1 -- --once "Do you deliver to Block L?"
- Ask the chat a question the notes can answer. With no tools it cannot see them, which is the whole point of Part 2.
- Keep a chat going for ten turns and watch the tokens sent grow every turn. That is the context window filling up.
- Copy the brief template and fill it in for your own project, saying what you want and why, never how.
- Copy the starter instructions file into your project and write the "how to run and check it" section first. It is how an agent finds out it was wrong.
Next: Part 2: Giving an Agent Hands.
If you want the argument for why this changes the job itself rather than just
the tooling, that is in The Modern Data Scientist.
Originally published at www.tmashininisekgoto.com.
I write about machine learning engineering, MLOps and building AI systems in South Africa. More at www.tmashininisekgoto.com.
Top comments (0)