The Problem Was Never the Framework

Every few weeks a new way of working with coding agents shows up. Spec-Driven Development and a growing list of variants, each with its own acronym. They all promise to solve the same thing: the agent understands what to build, doesn’t drift, and doesn’t burn more tokens than it should.

This post isn’t about wanting to name something. It comes from a certain fatigue with a debate I find unnecessary: which framework is the right one for working with agents. The way I see it, the difference isn’t made by the framework, but by the skills of the people using it: how well they define what they want and how well they guide the agent.

If I had to put a label on it, it would be Engineering-Driven Development, and I say that half-jokingly. It’s not a new methodology and it doesn’t try to be one; it’s a way of saying that engineering judgment was always the part that mattered.


💸 The token complaint

The most common complaint I hear is that agents spend too many tokens, with or without SDD. And when SDD is used, the complaint shifts: it’s bureaucratic, it generates too many files, and it forces you to redo work.

But when the agent asks questions, over-explores, or writes tests nobody asked for, it isn’t wasting tokens for fun. It’s doing the discovery work nobody did beforehand. SDD didn’t invent its own bureaucracy: it’s the cost of making explicit a definition that was always missing.


🔍 Where the tokens go

It’s worth looking at the mechanics. A coding agent doesn’t “think up” the solution and then write it: it works in a loop of reading, searching, running, and editing, and everything it reads or produces takes up space in its context window.

When the definition is vague, every open decision turns into exploration work:

  1. It infers what you didn’t say. Which columns does the report have? It opens the model, the controller, the views, and some similar export to work it out. That’s dozens of tool calls to answer something you knew in ten seconds.
  2. It builds on an assumption. If the assumption was wrong, so is the code, even if it compiles and passes its own tests.
  3. You correct it and it explores again. Your correction invalidates part of what it already read and did, so it re-reads files and redoes changes.
  4. The context fills up. In long sessions the history gets compacted and details are lost, so the agent re-reads what it had already read. It’s the same problem that led me to build ctx.

Comparison between a vague ticket, which falls into a loop of inferring, assuming, correcting, and re-reading, and a defined plan that moves in a straight line to a verifiable result

In my experience, the cost grows much faster than the ambiguity. Every open decision multiplies the possible paths, and the agent pays to walk the ones that were wrong. A spec doesn’t save tokens because it’s a document; it saves them because it closes those paths before the agent has to discover them. And it’s not the only source of waste: verbose tool output fills the context too, which is exactly what chop goes after.


🕰️ This was happening before agents

Anyone who has worked at a company has received a ticket like this one: “Add Excel export to the sales report”. It looks clear, but it doesn’t say which columns, whether it respects the applied filters, or whether we’re talking about 200 rows or 500,000. It doesn’t say who can export either, or whether the file downloads right away or arrives by email. Each of those questions changes the implementation, and none of them is answered in the ticket.

Consulting has the same problem at a larger scale. A client shows up and asks for “an app so my customers can book appointments”. Is it one location or several branches? Can appointments be canceled, and how far in advance? Are there reminders, upfront payments, web or mobile? Almost nobody asks all of that at the start, and half the answers show up at the first demo, when the client says “no, that’s not what I meant”.

In both cases the result was the same: rework. Sometimes because the requirement changed, sometimes because the implementation wasn’t what was expected. But nobody blamed the poor definition. It was “part of the process”.

The difference today is where that cost gets paid. It used to be paid in weeks of development that nobody measured. Now it’s paid in tokens, and because tokens show up on an invoice, it looks like a new problem. Handing that ticket to an agent doesn’t make it better; it only changes who does the guessing.


📝 The same ticket, well defined

Defining well doesn’t mean writing a ten-page document. This is the export ticket, turned into a plan an agent can execute without guessing:

# Export sales report to Excel

## Why
Finance builds the monthly reconciliation by copying the table by hand.

## Scope
- Export exactly what the user sees: same filters and order.
- Columns: date, invoice number, customer, subtotal, tax, total.
- Only `admin` and `finance` roles.

## Out of scope
- Formats other than .xlsx.
- Scheduled exports.

## Constraints
- Up to 5,000 rows: immediate download.
- More than 5,000: generated in a job and delivered by email.
- Amounts with 2 decimals; dates in the user's time zone.

## Acceptance criteria
- [ ] AC-1: the file respects the active filters.
- [ ] AC-2: a role without permission gets a 403.
- [ ] AC-3: 5,001 rows queue a job and don't block the request.
- [ ] AC-4: the totals in the file match the ones on screen.

It doesn’t say how to implement it: no libraries, classes, or structure. What it does is close the decisions the agent would otherwise have had to guess. The how is proposed by the agent, and that’s where review comes in.

It also didn’t have to go through a separate proposal, design, and task list. It’s a single page, and for most features that’s enough.


⚖️ Defining isn’t filling in templates

That said, part of the complaint is valid. Some frameworks require a proposal, a spec, a design, and a task list even when the definition is already clear, and they end up repeating the same thing across four files. That isn’t definition, it’s ceremony.

It helps to separate the two:

Not all rework is a sign of poor planning, either. Sometimes the requirement changes because seeing something working teaches you what you actually wanted. A quick prototype is also a way of defining.

The skill isn’t writing the perfect spec from the start. It’s knowing what you need to define up front and what’s better discovered by building. A spec can be vague or very complete; what matters is that whoever is guiding knows which one each case needs.


🧠 “Engineering” isn’t a job title

I say Engineering and not Engineer on purpose. It’s increasingly common to see people without a technical background, like analysts, designers, or product managers, building serious things with agents.

That confirms the idea: what makes the difference isn’t knowing how to code or holding a certain role. It’s thinking like an engineer when defining:

The agent can write the code. What it can’t do well on its own is decide what’s worth building, when something is done, and what level of risk is acceptable. That’s engineering judgment, wherever it comes from.

I’ve seen people with no programming experience build their own custom tools to solve tasks from their day-to-day work. They didn’t pull it off by using the right framework, but because they knew exactly what problem they wanted to solve and how to tell whether the tool worked.


🛠️ How I work

In my side projects the structure is minimal. I’ve built several tools with just three files:

My routine is almost always the same. I write the plan with what I know, ask the agent to read it and propose how to implement it, we discuss it, I approve it, and I let it work. Whatever I can’t watch myself is covered by tests and CI/CD: that’s my safety net, not the ceremony.

At work I use something more robust, because there are more people, more risk, and requirements I don’t define. But the foundation is the same: a plan, an approval before touching code, and reviews at the end. What changes is how much weight each step carries, not the flow.

I don’t write exhaustive plans either. I work iteratively and incrementally: I move in small steps, make checkpoints with git, test, use what I built, and adjust. If something doesn’t come out as expected, I go back to the last checkpoint and correct course by guiding the agent, not by switching methodologies.


🔁 The loop in practice

Work loop: PLAN.md, agent proposal, approval, small step, tests and CI; if it passes, checkpoint with git commit and move to the next step; if it fails, go back to the last checkpoint

CLAUDE.md doesn’t describe the project in the abstract. Its most valuable part is a handful of rules that correct the agent’s most common mistakes:

## Working rules
- Before editing code, propose a plan and wait for approval.
- If the scope changes mid-task, stop and ask.
- Don't add dependencies without asking.
- Don't mark anything as done without running tests and the linter;
  include the output.
- One logical change per step, so I can review it.

Every rule exists because at some point the agent did exactly the opposite. They’re few, they’re verifiable, and they don’t require any framework.

Git checkpoints are what let me iterate without fear. Every step that works gets saved, and every step that goes wrong gets thrown away without negotiating with the agent:

git switch -c feat/export-excel

# the agent finishes a step
git diff                 # review what changed
git add -A && git commit -m "checkpoint: export endpoint"

# the next step went wrong
git restore . && git clean -fd   # back to the last checkpoint

It has happened to me more than once: the agent solves the step, but on top of the wrong assumption, and every correction layered on top makes the diff worse. Instead of arguing with it, I go back to the last checkpoint and ask for the step again, with the missing decision written out explicitly.

Reverting and asking again with a clearer instruction is almost always cheaper than asking the agent to fix its own mistake on top of the mistake. At the end, the checkpoints can be squashed into clean commits before the PR.


✅ Tests and CI: the non-negotiable judge

An agent can say it’s done and be wrong with complete confidence. That’s why acceptance criteria don’t stay in the plan: they become tests, and the ID travels with them.

it('AC-2: rejects the export for roles without permission', function () {
    $user = User::factory()->create(['role' => 'sales']);

    $this->actingAs($user)
        ->get('/reports/sales/export')
        ->assertForbidden();
});

With the ID in the test name, knowing which criteria are covered is a grep, not a conversation. And if a criterion has no test, the feature isn’t done, whatever the agent says.

CI closes the loop. The model’s judgment is probabilistic; a pipeline that runs tests, the linter, and static analysis is deterministic. The agent might convince me on a bad day, but it can’t convince CI. That’s the difference between trusting the agent and verifying it, and it’s the part of the flow I don’t cut, not even on the smallest project.


🏛️ When a formal framework does make sense

I’m not against SDD or tools like OpenSpec or Spec Kit. There are cases where their structure pays for itself:

In those cases, the framework doesn’t replace judgment; it organizes it. But if the judgment isn’t there, no framework will supply it.


✳️ EDD isn’t a framework

EDD doesn’t need templates or commands.

Everything starts from a specification and a plan, whether vague or very complete. The effort and the result don’t depend only on that, but on whoever is guiding the agent: what they define, what they leave to be discovered, what they reject, and what they delegate to tests.

If there’s one thing I want to leave with this post, it isn’t a workflow to copy. It’s an invitation to build your own:


Frameworks will keep changing every few months. Knowing how to define a problem, verify a solution, and say “no, not this” in time is what lasts.