1. Tasks come in different genres
When Tommy put together his first TASK_SPEC, Alex notices that he writes every task in the same tone — as if everything in the world were “do something in the project.” So he gives him a quick crash course.
“Listen, have you noticed that tasks can be really different? Not different by topic — different by genre.”
“In what sense, genre?” Tommy really does not understand. “A task is a task. Just do something.”
“Nope. Look. ‘Add a new button,’ ‘fix a bug,’ ‘clean up the code,’ ‘figure out how everything works here’ — on the outside, all of that sounds like ‘do something in the project.’ But on the inside, these are four completely different jobs, with different risks. Mix them up — and you give the agent the wrong amount of freedom, and it will cause extra damage. Just like yesterday.”
“Wow. And how many of these genres are there?”
“Four. Let me show you with an apartment renovation example — that will make it click faster.”
2. Four genres in an apartment renovation
Alex lays it out on his fingers, and ties each genre to a clear renovation image.
A feature is adding new behavior. Build an extension onto the balcony: something appears that was not there before. The main question here is what exactly we are building and, more importantly, how the new thing connects to the old one: the balcony has to be attached to the wall, not left floating next to it in the air. It is the same in code — the new piece has to connect with what already exists at the join point, and not break the neighboring part.
A bugfix is fixing one thing without touching the rest. A faucet is leaking. The problem is in one spot, and the task is to remove it without disturbing anything around it. The most dangerous thing in a bugfix is “while you are at it.” You came to fix the faucet, and while you were at it decided to redo all the plumbing. Nobody asked for that. And there is a technical trap here: while fixing one thing, it is easy to accidentally break what was working nearby. That is why after a bugfix they always check not only “the faucet no longer leaks,” but also “is everything else still working as it was?” Fix it — and make sure you did not break the neighbor.
Refactoring is tidying up the inside without changing the outside behavior. Rearrange the furniture. The apartment looks the same from the outside, but it is more comfortable to live in. The key thing is nothing on the outside should change. The technical sign of real refactoring is exactly this: the behavior stays the same, and all the checks that were green remain green. You touch only the internal structure, not what the user sees. If something starts working differently after the “cleanup” — that is no longer refactoring, that is a breakage.
Reconnaissance is figuring things out before touching them. Call in a specialist to inspect the wiring before drilling into the wall. It is the same in code: sometimes first you need to understand how everything works — read the files, see what depends on what — and only then dive in. The main property of reconnaissance is that it does not change the code at all, not a single line. We only read and figure things out. The result of reconnaissance is not a fix, but understanding.
Tommy listens and recognizes his own mistakes in all of this:
“Listen, so yesterday really was a bugfix! I wanted to fix one thing. And the agent came in and ‘while he was at it’ demolished the neighbor. Fixed the faucet, but repainted the whole kitchen.”
“Well, there you go, you figured it out yourself. Now you understand why it is important to know the genre in advance.”
Tommy runs his past projects through this grid — and they suddenly line up differently.
“Listen, Snake was one big feature,” he says. “From scratch, on an empty canvas, nothing to break — so it was fine to give the agent complete freedom. But the portal is a completely different beast. There is someone else’s working code nearby, and any change smells like either a bugfix or a careful feature in tight quarters: touch one thing, and all the stuff around it must not go down.”
“Exactly.” Alex nods.
“So the portal is not ‘create whatever you want,’ like a blank toy. It is ‘step in carefully, there is someone else’s code nearby.’”
“Exactly. And for that kind of work, you hold the steering wheel very differently than for a toy from scratch.”
3. The genre determines how much freedom to give
“And now the main thing, the reason I brought all this up.” Alex gets to the point. “Mix up the genre — and you give the agent the wrong freedom. And that is what killed you yesterday.”
He goes back to the faucet:
“Imagine this. You call a worker: fix the faucet. That is a bugfix — one spot, one leak. And out of kindness you give him full freedom to act. And he fixes the faucet and, while he is at it, repaints the whole kitchen because ‘it looks better that way.’ Moves the cabinet, changes the tile — he is trying, after all. You did not ask for that, you asked for the faucet. But you gave him broad freedom — so he took the whole thing and ran with it. For a bugfix, you need narrow freedom: fix exactly this, do not touch anything else. The narrower the task — the shorter the leash.”
“And reconnaissance is the opposite then?” Tommy is already pulling on the thread himself.
“You are catching on. For reconnaissance, giving freedom to touch the code is not allowed at all. Its job is to understand, not to change anything. That is where ‘just look, keep your hands off’ applies.”
Tommy puts the whole map together himself, out loud, by genre:
“So it is like this. Bugfix — narrow fences, the agent stays in one place. Refactoring — make sure the outside behavior does not drift. Reconnaissance — do not let it touch anything at all, let it only figure things out. Feature — describe the new behavior and where it connects. And for each genre — a different amount of freedom.”
“Remember the reflex: before giving the agent a task, ask yourself — what genre is this? And based on that answer, decide how much freedom to give and what to write in the task brief. One question about the genre — and immediately it is clear both what to write and how to steer it.”
“One question.” Tommy rolls it around on his tongue, and there is that familiar glint in his eyes, the glint of a schemer who has found a shortcut. “Listen, that is convenient. No need to break your head over it every time. Ask ‘genre?’ — and half the job is already clear.”
“Now you are thinking.” Alex smirks.
For Tommy, this is not a classification exam, but a simple lens: one question — and TASK_SPEC becomes more precise right away, and it is clear how to hold that very steering wheel from the morning message. What he turns this wheel with — what buttons, what commands — he does not know yet. But he already understands why to turn it and which way for each task. All that is left is to find the wheel itself.
GO TO FULL VERSION