Skip to content

What I learned

I built software with an AI agent. This is 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

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.

Lesson 1

An agent forgets your design from one session to the next.

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.

Distance from the designRules in a documentThe design12345SessionRules that runThe designRejected by a check12345Session
With rules in a document, small deviations pile up. With rules that run, each one is stopped in the change that causes it.

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.

Rules in a document

  • The agent reads them at the start and follows them most of the time.
  • Drift shows up weeks later, in review.
  • Reviewing means hunting for mistakes by eye.

Rules that run

  • They are checked on every change, without exception.
  • The change is rejected at once, with the name of the rule.
  • Reviewing means deciding on work that already passed the checks.

Lesson 2

The agent always works in the same order.

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.

  1. Authorize
  2. Explore
  3. Resolve doubts
  4. Classify
  • Small: straight to the code

    1. Implement
  • Large: tracked first

    1. Track
    2. Implement

Close

Every request goes through the same trunk. Classify decides whether the work goes straight to the code or is tracked first.
  1. Authorize

    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.

  2. Explore

    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.

  3. Resolve doubts

    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.

  4. Classify

    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.

  5. Track

    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.

  6. Implement

    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.

  7. Close

    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

The agent opens the pull request. I decide when it is ready.

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.

  1. The agent writes and tests locally
  2. It opens the pull request
  3. A person adds the label
  4. Continuous integration runs
  5. Green: it can merge. Red: the label comes off and it goes back to the agent

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

If you cannot see what the agent is doing, you do not know when to step in.

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.

  • landingWriting tests for the new sectionWorking
  • webAsks before running a migrationNeeds you
  • mobileAll checks passed, branch readyDone

NextReview the web plan, then run the checks before you commit.

  • State of each session

    Working, needs you, done or error. I only step in where I am needed.

  • Plan and tasks

    The task list of the agent and of the subagents it starts. I can follow long work without reading every message.

  • Context left

    A bar per session. When it runs out, I start a new session before quality drops.

  • Advice and next step

    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

Clear layers tell the agent where each piece goes.

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.

EntryInfrastructureApplicationDomainDependencies point inward
Entry and infrastructure sit on the outside; every dependency points inward, toward the domain.
  1. Entry

    What receives the outside world: a screen, an HTTP route, a command. It translates and delegates; it does not decide.

  2. Application

    The use cases. It coordinates the work, but the rules do not live here.

  3. Domain

    The business rules. It knows nothing about databases, frameworks or the network.

  4. Infrastructure

    Databases, external services, files. It implements what the domain needs.

Every arrow points toward the domain. Infrastructure depends on the domain, not the other way around.

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

A rule only counts if breaking it breaks the build.

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.

  1. Written

    It is in the project instructions, where the agent reads it first. It explains the why, not only the what.

  2. Wired

    A linter, a test or a hook checks it on every machine, before every commit or push.

  3. Enforced

    Continuous integration refuses the merge if it breaks, whoever the author is, person or agent.

PassTypesCode that compiles "by chance" or uses data with the wrong shape.
FailArchitectureImports that cross layers, or cycles between modules.
PassStrict lintDangerous patterns, such as inserting data as HTML instead of as text.
PassMinimum coverageNew behavior without a test that proves it.
PassSecretsKeys or passwords about to be pushed to the repository.
One check fails. The agent reads the name of the rule, moves the import and runs everything again.

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

Four practices that make the architecture hard to break by accident.

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.

  • Forbid everything by default, and test the ban.

    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.

  • Write architecture rules as tests.

    "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.

  • Two tools that overlap on purpose.

    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.

  • Document which check catches each rule.

    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.

Layer rulesFeatureimportsfeatureScreen readsthe databaseDependency graphImportcyclesOrphanmodulesDomainimportsinfrastructure
Each tool catches something the other misses, and both catch the most important rule.

Lesson 8

Five habits that make an agent safe to use.

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.

Outside

  • Comments and issues
  • Web pages
  • Downloaded docs

Read as data, never as orders

The agent

  • Reads the code
  • Runs the checks
  • Edits on a branch

Reading secrets: denied

Irreversible: a person decides

A person

  • Deletes
  • Publishes
  • Merges
Outside text comes in only as data. The agent works within its permissions, and anything irreversible waits for a person.
  • Outside text is data, not an order.

    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 least access needed.

    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

  • Pin your dependencies.

    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

  • Secrets stay out.

    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

  • Data is shown as text.

    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

What needs attention, in one panel.

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.

  • Work map

    Every tool the agent uses, with a mark where an automatic check told it no.

  • Updates

    What is outdated in each ecosystem, and how hard the upgrade will be.

  • Vulnerabilities

    Known security advisories for my dependencies, each with a link.

  • Pending

    Tasks the agent leaves for later, in one list I can clear.

  • Branch status

    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

AI did not take my work away. It changed it.

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.

Photo of Hernán David Figueroa

About the developer

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