Working with an agent

An AI coding agent, such as the one in Antigravity, reads and writes the files of a project and runs commands. It follows the requests you type in a chat. It works fast, and it knows nothing about you. It has never seen your brief, it doesn't know that recruiters are your audience, and it can't guess that you dislike rounded cards. It works from what you give it and from the files it reads.

So give it the brief, the mockups, the limits and the tone. Put the rules that must always apply in a file of permanent instructions in the project. Many agents look for a file called AGENTS.md. Others use a different file name, so check which one your agent reads. The agent reads this file again each time it starts work. So a rule such as "use only the colours in the design file" is still followed at the end of a long session.

Some things never go into the chat: secret keys, passwords and customers' personal data. What you type is sent to the AI company's servers. The agent may also copy it into a file that later becomes public. So if you paste a key "just to test", treat it as leaked, and replace it.

"Build my portfolio from this brief" is one giant request. It gives you a whole site at once, with dozens of decisions you never saw. Its mistakes are mixed together, so you can't fix them one by one. Working in a loop lets you see each decision when it's made.

First, ask for a plan and say "don't change anything yet". Read it: which pages and components it will make, and in what order. Does the plan write the project texts directly into the page code? Does it add a library (ready-made code written by others) that you never asked for? If so, say so now. Fixing a plan takes one sentence. Fixing code built on a wrong plan can take an afternoon.

Then ask for one step at a time: the colours and fonts, then the header, then the project cards, then the project page. After each step that works, save a version, or ask the agent to save it. That saved version is a commit, with a short message saying what changed and why. If the next step goes wrong, you return to the last commit and lose only that one step. "Make it better" gives the agent no goal. Instead, say what's wrong, using the words from the lesson "Words for a design", and say how you'll know it's right.

When the agent says a step is done, it only means that it believes so. Agents report success easily, sometimes for work they never checked.

First, look at what changed. The editor lists each file the agent changed. It shows removed lines in red and added lines in green, in a view called a diff. You don't need to read the code to see how big the change is. If a request to change a button's colour changed 40 files, that is a warning sign. Ask why before you continue.

Next, try it yourself on the preview. The preview is the version of the site that runs on your computer or at a private link. Use it as a recruiter would, then again with the window as narrow as a phone.

Then ask for proof. Ask for the test the agent ran (a small program that checks the code) and its result. Ask for a screenshot at a phone's width. Ask to see the browser's console (the F12 key opens it) with no errors in red. And ask to see each line of your "done when" list from the brief, checked. Only then accept the step, and save it.

At some point, a step will break something. Your contact form, which worked yesterday, now does nothing when you press Send. "It doesn't work, fix it" makes the agent guess. Its guess is often to rewrite the whole form, which brings new bugs.

Give it what a developer would ask for. Open the console (press F12, then choose the Console tab) and copy the exact error message, with its file name and line number. Then describe what you did, what you expected and what you saw. For example: "I typed my email in the form and pressed Send. I expected a confirmation message. Nothing happened, and the console says 'Cannot read properties of null' at line 12 of contact.js."

Ask the agent to explain the cause in one sentence before it changes anything. Then ask it to fix only that cause. If it proposes to rewrite everything, say no. If it keeps making the same mistake after two or three tries, return to the last commit. Then start that step again in a new session, and tell the agent what you've learned.

Agents fail in a few ways that happen again and again. Each one has a simple defence.

They state invented facts with confidence. For example, they name a package (a ready-made piece of code the project downloads) that doesn't exist, or a setting the hosting service never had. Ask where it's documented, and be careful when an installation fails with the message "not found". In a long session, they slowly forget the rules you gave at the start, because so much has been said since. The colours or the tone then move away from the brief. Start a new session, and give it a short summary of the project so far. They fix one bug and break something else. So after each fix, test again the parts that already worked. And sometimes they make an error disappear by removing what caused it, such as a feature or a test, without saying so. Reading what changed is how you notice this.

Whoever wrote the code, you are responsible for what goes online. A recruiter who finds a broken link on your portfolio won't wonder whether an agent wrote it.

Ask the agent these questions. A colleague or freelancer who works with an agent should be able to answer them too.

Before any change, ask for the plan, and for what's unclear in the brief. After each step, ask which files changed and why. If the number of files seems high for the request, ask about that too, and ask whether anything was removed. When the agent says "done", ask how it checked: the test it ran, a screenshot at a phone's width, the console. When it names a package, a setting or a fact you can't verify, ask where it's documented, and go and check it yourself.

With a colleague who built something with an agent, the questions change a little. Did you read what it changed, or only its summary? Did you try it on a phone yourself? Can we return to the version before this change? Did a key, a password or anyone's personal data go into the chat? If a key did, it must be replaced at the service that issued it.