Coding with Claude Code or Codex

Claude Code and Codex are agents, not chats. The difference is not marketing: a chat hands you text that you paste; an agent opens your project, reads the files, writes, runs the tests and writes again. It works on its own for minutes at a time.

And that is the whole change: what it writes no longer passes through your hands. Before, for a mistake to reach production you had to copy it there yourself. Now the path from "it decides to" to "it is live" can have nobody in the middle. Your job is to put yourself in the middle, in the right place.

What it is good at and what it is not, measured

The job	How it goes
"Add a field to the form and save it"	Very well. This is what it does best: copying a pattern that already exists in your project and repeating it properly.
"Translate this page into Spanish"	Well, and it drops things. The text comes out; what falls off is a button, an identifier, or the block you cannot see.
"Fix this error" with the error pasted	Very well if you give it the whole message. With "it does not work" on its own, it guesses.
"Build me the pharmacy website"	Badly. You get something that looks like a website and has to be redone, because it decided nothing with you.
"Is this right?"	Badly. It leans towards yes. Ask what is wrong with it, not whether it is right.

Claude Code or Codex: what actually differs

Both do the same thing and both are good. Comparing specific versions is pointless — whatever one does better today the other does in three months — so what is useful is knowing how alike they are, which is in almost everything: both install on your machine, work inside your folder, read and write files, run commands and show you what they changed before saving it.

What is worth looking at when choosing, and does not go stale: which subscription it comes with (you may well already pay for one of them), whether it lets you work in your editor or in the terminal depending on how you work, and whether you can leave it a project instructions file that it always reads. The third pays off most over time and almost nobody uses it.

That instructions file is the most underrated tool here. It is a text file at the root of the project where you write down how things are done: what is not to be touched, what gets checked before anything is called done, which mistake has already been made once. The agent reads it every session. Every time you get something wrong, write it in there — it is the difference between repeating a mistake five times and repeating it once.

The method: four rules

One thing per job

"Add the field, change the colours and fix it on mobile" comes out badly three times over. And there is a reason that is not about quality: when something breaks, with three changes bundled you cannot tell which one did it. With one, you can.

Rule of thumb: if the request contains an "and", split it.
Tell it what exists, not just what you want

The agent sees the files, but it does not know what matters. "This page gets used on a phone", "this is patient data", "I tried this and it failed because…" change completely what it writes.

It is the same piece that lesson 1 of Level 2 calls context, and it is still the one that pays most.
Ask it to check the work, and look at HOW it checks

"Write a test" is a good instruction. But a test written by whoever wrote the code has an obvious bias, and it shows up in one very specific way: it checks that the function exists, not that it is right.

This happens for real and it is hard to see. On this site a detection function returned "false" EVERY time because of a one-line mistake: every correct call was logged as a failure for weeks. Its test was green — it checked that the function had been written. The rule that came out of it: for code that can only be wrong at run time, a test that reads the file is worthless. It has to run it with an input and look at the output.
Read the diff before publishing

Not the whole codebase: the diff, which is only what changed. It is the one part of the method you cannot skip, and it is usually thirty lines.

What you are looking for, in this order:
- Files you were not expecting. That is the number one sign it "fixed" something along the way.
- Deletions. A line that disappears does not catch the eye and is what breaks most.
- Keys, URLs and email addresses written inside the code.
- Numbers. If a figure appears that you did not supply, it came out of its memory — and this site once had a one-cent discrepancy spread across 32 files.

Five traps you cannot see by reading the code

What it looks like	What is happening
"It is deployed, so it is visible"	No. It can be published and still serving the old copy from a cache, or sitting in a tab nobody opens. Open it in a browser before assuming.
"The comment says it checks that"	The comment says what was intended. This site had an endpoint whose comment said the server validated the quota — and nobody validated it. Check the code, not what it says about itself.
"There was no error"	The worst failures raise no error: they return a plausible value. A delete that deletes nothing, a translation missing a button, a figure that filled itself in.
"I tested it and it works"	At what width? Almost every layout problem breaks at 390 px and looks perfect on the laptop you wrote it on.
"I will just undo the change"	A command that reverts "everything" takes whatever you had not saved with it. Commit before trying anything odd.

What NOT to delegate

Three things, and none of them is technical: what data you keep, who can read it, and what the page claims. The agent will happily write a query that pulls the whole table, a table with no RLS, and a paragraph promising that a product prevents colds. None of the three will strike it as wrong — and all three carry your name.

The file that changes the result more than any prompt

A coding agent opens your project knowing nothing about it. Every session starts from zero: it does not remember the last one, it does not know why you decided something three months ago, and it does not know what is forbidden here. And because it does not know, it invents something reasonable — which is the worst way to be wrong, because the result looks right.

The answer is a context file at the root of the project (CLAUDE.md, AGENTS.md, depending on the tool) that the agent reads before every task. It is what turns "an AI that writes code" into "somebody who knows this project". And it is by far the best-value hour in this whole lesson.

What it actually needs to contain

# What this project is
A pharmacy website. HTML, CSS and JavaScript, no frameworks, on purpose.
Deployed to Vercel from the main branch. Data lives in Supabase.

# Rules that are not bent
- No patient data in the code or in the repository.
- Every new table gets RLS and all FOUR policies.
- Keys go in environment variables. Never in a file in the repo.
- Calculations live in /calculos/*.js and never touch the DOM.

# How we work here
- One branch per change. Never straight to main.
- Before calling anything done: `npm test`.
- Copy is in Spanish, and in English only where an /en/ page exists.

# Mistakes we have already made (do not repeat)
- A Supabase delete reports success without deleting when the FOR DELETE
  policy is missing. Ask for `.select('id')` and check something came back.
- A cached stylesheet hid a fix: when touching the shared CSS you must
  bump the service worker version.

That last block is the one nobody writes and the one worth most. An agent that does not know which mistakes have already been made will make them again, because they are reasonable mistakes — that is why they were made. Every time something breaks and you fix it, add two lines there. In three months that file is worth more than any documentation, and you did not write it in one sitting: you paid for it with mistakes you were going to make anyway.

How to write a task that works first time

A task for a coding agent has four parts, and the one nearly everybody leaves out is the fourth:

Part	What it is	If it is missing
1. What	The change, in one sentence	There is no task
2. Where	The file or the area	It goes hunting and touches things that were not in scope
3. How it gets checked	What has to happen for it to count as done	You get something plausible and test it by hand yourself
4. What NOT to touch	The boundaries	It refactors along the way, and a two-line change arrives with forty

The same task, badly and well

// ❌ What comes out first
"fix the contact form, it doesn't work"

// ✅ What saves three rounds
"In contact.html the form sends nothing: the console shows a 404 calling
 /api/contact. Find out why and fix it.

 How it gets checked: submitting with valid data must show the success
 message, and an empty email must be reported before submitting.

 Do not touch the design or any other page. If the fix requires changing
 anything outside contact.html or that function, STOP and tell me what
 is needed."

That last sentence — "if you have to leave this area, stop and tell me" — is what prevents the worst case. An agent that discovers the real fix is somewhere else does not stop: it carries on, because you asked it to fix the thing. And you end up with a change touching six files when you were looking at one. Stopping and asking is always cheaper — for you, who has to review it, and for it, which does not get lost.

The working cycle, and why step size decides everything

Ask for a plan before code

"Before touching anything, tell me what you are going to change and in which files." Reading five lines of plan costs twenty seconds and lets you correct course before anything is written. It is the point in the cycle where one sentence from you is worth half an hour.
One change, one commit

The moment something works, save it. Not at the end of the afternoon: the moment it works. That way there is always a good point to come back to, and coming back costs one command instead of a rebuild.
Check it yourself, every time

"It is fixed now" is a claim by the agent, not a fact. Open it in the browser. It is the most-skipped step and the most expensive: an agent that calls something done without running it is not lying — it simply has not looked.
If it is going wrong, roll back and rewrite the task

Do not correct it five times in a row. Each correction piles onto an earlier misunderstanding and the result becomes a patch of patches. Throwing it away and restarting with a better task is faster nearly always, and always comes out cleaner.

Step size is the variable that rules everything. "Build the pharmacy website" and "add the cookie notice" have exactly the same chance of going wrong on the first answer; the difference is that you find out about the second in two minutes and about the first once there are forty files you do not understand. If a task does not fit in one commit with a one-line message, it is two tasks.

Reviewing a change without knowing how to program

This sounds impossible and is not. It is not about understanding every line: it is about looking at five specific things you can see without reading code.

What you look at	What you are looking for
How many files it touches	You asked for one change and it touched nine? Ask why before going on
Whether anything looks like a key	A long odd string in quotes. Never. It goes in an environment variable
Red (deleted) lines you did not expect	Deleting is the one thing that does not undo itself. Ask about every red block you do not understand
Whether it touched the dependency file	It has pulled in a third-party library. Was it needed? Almost never
Whether there is a new URL	Open it. An invented link looks exactly like a real one (it is the most repeated failure there is)

And there is one question that works surprisingly well: "explain this change as if I could not program, and tell me what it might break". An agent that did something odd usually gives itself away while explaining it — and if the explanation does not match what you asked for, there is your signal without having read a single line.

When it gets stuck: the three ways out, in order

Give it the EXACT error, copied

Not "it errors": the whole text, with the line number if there is one. Half of all stuck-ness resolves right there, and "still not working" is the phrase that burns the most rounds while adding nothing.
Ask it to add traces and run it

"Add console.log wherever needed to see what arrives, run it and tell me what comes out." It forces it to look at real behaviour instead of reasoning about the code — which is exactly what a programmer does when stuck.
Throw it away and rewrite the task

If three rounds have passed with no progress, the problem is not the code: the task does not say what is needed. git checkout HEAD -- . — with a recent commit behind you — and start again with what you have learned.

And a rule that looks like style and is about safety: never paste a file with real data into the chat so it "understands better". Not a sales export with names, not a customer email, not a payslip. If it needs to see the shape of the data, make up three rows. The agent works just as well and you have not sent a third party something that was not yours to send.

What NOT to ask a coding agent for

Do not ask for	Why
"Improve the project"	With no goal, "improve" means rewrite. You will get changes in places that worked
"Apply this migration to the database"	Writing the SQL, yes. Running it against real data, no: there is no undo
"Push this to production"	Publishing is a decision, not a task. And keeping it is free
"Add tests to everything"	You get a hundred tests checking that the code does what the code does. They catch nothing
"Update the dependencies"	It is the change that breaks the most and is the hardest to review

The fourth row needs a caveat because it sounds like laziness and is not. Tests are worth a great deal — but a test written from the code checks that the code does what it does, which is a tautology. A useful test is written from what has to happen: "if the supplier does not respond, the user sees a message and not a blank screen". That you can ask for, and you have to hand it over phrased like that.

And there is a one-minute way to check whether a test is worth anything: break the code on purpose and see if the test notices. If it stays green with the code broken, that test was not checking anything — and that happens far more often than you would think. It is the only way to tell a test from decoration.

Before you call this learned

I split the request as soon as it contains an "and".
I give it the context, not just what I want.
I check whether the test RUNS the code or merely checks that it exists.
I read the diff looking for unexpected files, deletions, keys and numbers.
I open it in a browser — and at 390 px — before calling it done.
I keep a project instructions file and write every mistake into it.

← Previous: the stack Next: Analytics and Search Console →

What it is good at and what it is not, measured

Claude Code or Codex: what actually differs

The method: four rules

One thing per job

Tell it what exists, not just what you want

Ask it to check the work, and look at HOW it checks

Read the diff before publishing

Five traps you cannot see by reading the code

What NOT to delegate

The file that changes the result more than any prompt

How to write a task that works first time

The working cycle, and why step size decides everything

Ask for a plan before code

One change, one commit

Check it yourself, every time

If it is going wrong, roll back and rewrite the task

Reviewing a change without knowing how to program

When it gets stuck: the three ways out, in order

Give it the EXACT error, copied

Ask it to add traces and run it

Throw it away and rewrite the task

What NOT to ask a coding agent for

Before you call this learned