The idea in one sentence
Let the AI write, and make the project say no when something is wrong.
A strict architecture, with tests and linters that fail when it breaks, turns the speed of the agent into code you can maintain.
What I learned
I have worked with AI since 2022, and with agents since they started to appear in mid-2025. With them I have built real projects: a backend, a mobile app, a website and this page. At first the agent wrote fast and I reviewed slowly. Over time I understood that quality did not depend on writing better instructions, but on building an environment where bad code could not get through.
This page collects those lessons. It sells nothing: it tells what went wrong, what I changed and why it works, in a way that applies to any language or stack.
The idea in one sentence
A strict architecture, with tests and linters that fail when it breaks, turns the speed of the agent into code you can maintain.
Lesson 1
I wrote the project rules in a document: which layer may import which, where each thing goes, what must not be touched. The agent read them and followed almost all of them. But every session starts from zero, and "almost all" adds up.
The drift was never big. An import that crossed a boundary, business logic inside a controller, a missing test. Each change looked reasonable on its own, and I noticed weeks later, when there was already code built on top.
I stopped trusting the agent to remember the rules and turned them into checks that run by themselves. If a change crosses a boundary, the build or a test fails, with the name of the rule in the error message.
An agent reads errors very carefully. A named error tells it exactly which rule it broke, and it fixes the change before I ever see it. The rule no longer depends on anyone remembering it, neither the agent nor me.
Lesson 2
Without a fixed order, the agent did whatever looked most useful at each moment. Sometimes it edited files when I had only asked a question. Sometimes it started writing without reading how the rest was built, or called something done without having tested it.
For this I use Organic Driven Development: a seven-step workflow the agent follows on every request, small or large. The process grows with the size of the task, instead of applying the same ceremony to everything.
Small: straight to the code
Large: tracked first
Close
First it checks whether I really asked for a change. A question, a review or a plan touches no file.
Without this stepSurprise edits when I only wanted an answer.
It reads the existing code and the project rules before proposing anything.
Without this stepSolutions that work but do not fit what is already there.
If a decision is mine (product, scope, design), it asks one concrete question and waits. If it is technical, it decides and moves on.
Without this stepEither a flood of mechanical questions, or decisions made for me that are not its to make.
A task is small if it is understood, its risk is contained and it could be resumed from the diff alone. Otherwise it is large.
Without this stepEither everything gets ceremony, or nothing does.
Large tasks get a document that quotes my request word for word, a task list and a log of decisions.
Without this stepWork is lost when a session breaks, and the result drifts from what I asked without anyone noticing.
First a failing test, then the code that makes it pass. Commits go by unit of work, about 400 lines at most.
Without this stepHuge changes, with no proof that they work, impossible to review in one sitting.
It reports what passed, what failed and what it could not check.
Without this step"Done" without evidence, and me finding the failure later.
The order turns good judgment into habit. It does not depend on the agent "remembering" to be careful: each step has a concrete output I can check. And because the process scales with the task, a one-line fix stays fast.
Lesson 3
When the agent can run the whole cycle alone, writing, testing and merging, review becomes a formality. Changes reached the main branch because the checks passed, not because someone had decided they were right.
I separated "it is done" from "it is ready". The agent works on a branch and opens the pull request, but continuous integration only starts when I add a label by hand. Merging requires that run to pass, and the agent is not allowed to add the label.
Every merge goes through an explicit human decision, and that decision is cheap: I arrive at review with tests, lint and architecture already checked locally. My job stops being hunting for mistakes and becomes judging whether the change is the right one.
Lesson 4
With several sessions open at once, I lost track. One had been waiting ten minutes for my answer, another had run out of context and started making silly mistakes, and another had finished without me noticing. To know, I had to read every conversation.
I added mods to the environment of the agent that show its state at a glance. They do not change what the agent does; they give me visibility over it.
NextReview the web plan, then run the checks before you commit.
Working, needs you, done or error. I only step in where I am needed.
The task list of the agent and of the subagents it starts. I can follow long work without reading every message.
A bar per session. When it runs out, I start a new session before quality drops.
After each turn, a short note on what it just did and a suggestion for what to do next.
Working with an agent is, above all, deciding when to step in. The sooner I see a session getting stuck or drifting, the less work there is to undo. Visibility turns supervision into something that fits in a glance.
Lesson 5
When the project had no explicit structure, the agent put code wherever it was most convenient. Business logic ended up mixed with data access and with the interface. Every change touched many files, and nobody, neither the agent nor I, could say for sure what it would break.
I built base repositories with a strict architecture already defined: backend, mobile, web and landing. The layer names change with the project, but the idea is always the same. Dependencies always point toward the domain, never the other way, and each module or feature stays isolated: one feature does not import another directly.
What receives the outside world: a screen, an HTTP route, a command. It translates and delegates; it does not decide.
The use cases. It coordinates the work, but the rules do not live here.
The business rules. It knows nothing about databases, frameworks or the network.
Databases, external services, files. It implements what the domain needs.
Forbidden: the domain imports infrastructure
For the agent, the architecture is a map: for every change it knows which layer it goes in and what it may import. For me, every change stays contained and is easier to review. And because the rule is simple ("arrows point inward"), a tool can check it on every build.
Lesson 6
I had rules in three different places: some only written down, others checked on my machine, others only in continuous integration. The ones that were only written down were exactly the ones the agent ended up breaking.
Now every rule climbs a three-step ladder, and every project checks the same five things, even though the exact tool changes with the language.
It is in the project instructions, where the agent reads it first. It explains the why, not only the what.
A linter, a test or a hook checks it on every machine, before every commit or push.
Continuous integration refuses the merge if it breaks, whoever the author is, person or agent.
The red row is the useful one. It stops the change, names the rule, and the agent knows what to fix. A project where everything is green because nothing is checked protects nothing.
Lesson 7
Having rules that fail is the start. These four practices are the ones that helped me most to keep those rules protecting over time, whoever writes the code.
At first my layer rules listed what was forbidden, so anything missing from the list was allowed without anyone deciding it. Now the rule forbids any import that is not explicitly allowed, and a small test project proves that each forbidden import really fails. If someone weakens the rule, that test turns red.
Result A rule that cannot be weakened in silence.
"The domain imports nothing from outside" can be a sentence in a document or a test that runs with the rest of the suite. The second runs on every machine and in continuous integration, and its error message explains the rule better than any document.
Result The rule runs wherever the tests run.
One checks layer against layer. The other looks at the whole dependency graph: cycles, orphan modules, a domain that imports something it should not. Each catches what the other misses, and if one is misconfigured, the other is still there.
Result One broken tool does not open a gap.
I keep a "caught by" table that maps each architecture rule to the tool that enforces it. A rule with no check stands out at once as the next one to wire.
Result The next rule to wire is always visible.
Lesson 8
An agent that reads, writes and runs commands has more access than many people on a team. These habits apply both to the workflow of the agent and to the application it builds, and each one is backed by a check, not only by a sentence.
Read as data, never as orders
Reading secrets: denied
Irreversible: a person decides
Comments, issues, pull request descriptions, web pages and downloaded documentation inform the agent. But anyone can write in them, and some may try to give it instructions. The rule is that only I give orders, and anything an outside text asks for is checked first.
Backed by Project instructions and human review
The agent gets only the permissions the task requires. Reading secrets is denied, and anything irreversible (deleting, publishing, merging) waits for a person.
Backed by Permission rules and deny lists
Lockfiles with exact versions and checksums, continuous integration actions pinned by commit, and a waiting period before installing a newly published version. A supply chain attack is usually found within days; waiting is cheap.
Backed by Frozen installs and release-age limits
Every commit is scanned before it is created and again in continuous integration. Environment files are ignored, except the example one, which holds no real values.
Backed by Two independent secret scanners
Nothing that comes from a user or an API is inserted as HTML. Lint rejects those operations, and a content security policy blocks any script the build did not register.
Backed by Lint and a content security policy
Lesson 9
Problems that do not break the build pile up in silence: dependencies that grow old, vulnerabilities published in libraries I use, tasks the agent left "for later", a branch that fell behind the remote. I found out late, usually in review or when something was already failing.
I added a mod that keeps the state of the project next to the conversation with the agent. It shows five things.
Every tool the agent uses, with a mark where an automatic check told it no.
What is outdated in each ecosystem, and how hard the upgrade will be.
Known security advisories for my dependencies, each with a link.
Tasks the agent leaves for later, in one list I can clear.
A warning when I am behind the remote, before I build on old code.
The agent and I see the same thing. I can ask it to deal with a specific warning before it becomes a problem, instead of finding it in review.
What I take with me
I stopped writing most of the code and started designing the environment where it is written: the layers, the rules that fail, the order of work, the gate before the merge and the visibility over what happens. The stricter that environment is, the more freedom I can give the agent, because what is wrong does not get through.
If I had to keep a single idea: do not try to make the agent perfect. Make the project notice when it is not.

Hernán David Figueroa
Full-stack developer with more than 8 years of experience, specializing in fintech and secure payments. I work on POS terminals and payment features for Android and iOS at a Colombian payment gateway. I have worked with AI since 2022, and with agents since mid-2025. I live in Bogotá.
I write and maintain Guardrail on my own. See my developer profile