Método CIV: cómo construimos software con IA sin perder el control

We've spent two years building ShephERP with artificial intelligence writing most of the code. Along the way, we learned that the bottleneck was never the model. It was everything else. We've given that way of working a name: the CIV method.

The problem nobody talks about

The promise of AI in development is real: an agent writes in twenty minutes what used to take two days. What almost nobody mentions is what happens by week six.

A language model is an astonishingly fast and astonishingly literal executor. Without context, it hallucinates: if you haven't told it that members with overdue fees lose the discount, it will apply the discount, because that's the most reasonable thing. And without boundaries, it breaks things: it will fix the bug you asked for and, along the way, touch four other things nobody asked it to.

The result is a project that starts at an spectacular speed and gets stuck after two months, with thousands of lines nobody has reviewed and a team that no longer dares to touch anything. Multiplying the speed of writing code without multiplying the ability to verify it is not productivity: it's debt at machine speed.

You don't develop faster with better prompts, but with better context and better boundaries.

Three pillars: Context, Iteration, Verification

CIV stands for the three things you need to put around the agent. They're not phases you go through one after another: they all work at the same time, and if you remove one, the system falls apart.

C — Context: documentation is the source code

In a CIV project, the docs/ folder exists before the code. Everything lives in there: the client's business, their exact vocabulary, the rules numbered one by one, the technical decisions with their date and discarded alternatives, and the minutes of every meeting written that same day.

We don't document to audit or to look good. We document because it is literally the executor's input. A meeting agenda is the most valuable asset that exists for an AI, because it contains the one thing no repository can deduce: intent. The code says what the system does; only the meeting notes say why it was done that way and what breaks if you change it.

That's where our first principle comes from, which is also the most uncomfortable one: if it's not written down, it doesn't exist. A decision that only lives in a call is not a decision; it's a rumor that the agent cannot respect.

I — Iteration: a ticket is a prompt

Work flows down at three levels — epic (one quarter), milestone (what can be shown in two weeks), and task (what fits in a single session) — and lands on tickets written for someone who wasn't in the conversation, doesn't remember anything, and is not going to ask.

That completely changes how you write a ticket. No more "fix the filter." Steps with real data, the exact URL, an annotated screenshot with an arrow pointing at what's wrong, the request and response pasted in, the expected result, the acceptance criteria as a checklist, and — the line that saves the most money — what NOT to touch.

We call it Definition of Ready for AI, and it has one golden rule: if the agent has to ask anything to get started, the ticket was poorly written and goes back to whoever drafted it. It's not bureaucracy. An incomplete ticket doesn't stall: it completes itself, with the model's most likely assumption. And the most likely assumption is almost never your client's business rule.

Every task then goes through six always-identical steps: read, plan, fence, execute, verify, and return. The most important one is the second: the plan is approved before the first line of code. Fixing a plan takes a minute; fixing an afternoon's work takes an afternoon.

V — Verification: the fence first, then let go

Here it's worth clearing up a very common confusion, because everything else depends on it. Many people talk about "unit tests, e2e, and Cypress" as if they were three things of the same kind. They're not: two different axes are being mixed. One is the level — how much real system you exercise — and the other is the tool you use to exercise it. Cypress is not a level: it's a tool for the end-to-end interface level. And "end-to-end" isn't just one thing either: testing the full API and testing the application in a browser are different things, with different costs and different utility.

In CIV there are six levels, from cheapest to most expensive: types and style, unit, integration, API end-to-end, interface end-to-end, and smoke testing in production. The question that decides where each test goes is always the same: what is the smallest piece where this failure can be detected? A miscalculated discount is a unit test, even if you discovered it while shopping.

Above all that, coverage above 95% and the rule that holds it together: the ratchet. Thresholds only go up. They never go down, never "temporarily." Pre-existing debt is frozen with a baseline and paid off in increments; new debt is blocked the same day. And no bug is closed until it leaves behind the test that would have caught it: no bug dies without a witness.

Why this pays for itself

A normal project degrades: every month it costs more to maintain. A CIV project tends toward the opposite, and for a specific reason. The context grows, so each new task arrives with more ground already resolved. The fence grows, so each change is less risky than the previous one. And the cost of onboarding someone — or another agent — goes down, because onboarding is simply reading a folder in order.

We measure seven things, but there's one that almost nobody measures and that says it all: the clean ticket rate, the percentage of tickets the agent resolves without having to ask follow-up questions. If that number drops, the problem isn't the model you're using. It's in your context and in how you write your tickets.

What CIV is not

It's not vibe coding. It's not vanity coverage — tests that execute a lot and verify nothing —. It's not ceremonial documents that nobody updates, which with AI are worse than having none at all, because the agent does read them and does believe them. It's not shortcuts that have been "temporary" for six months. And, above all, it's not letting an agent off the leash and calling it autonomy.

CIV didn't originate on a whiteboard: it emerged from building a complete ERP with AI, making mistakes, and noting down why. It's what we do every day.

Context. Iteration. Verification. Remove one of the three and it's not CIV: it's luck.