Working with agents
Puerto is built on one bet: the stricter the structure, the better an agent works inside it. An agent writing into a codebase where every project looks different has to guess, and its guesses look plausible. An agent writing into a Puerto project has rules it can read, generators that write the wiring, and a compiler that refuses architectural mistakes with a precise message.
The rules ship with the project
Section titled “The rules ship with the project”Every project has a root AGENTS.md and a one-line CLAUDE.md (@AGENTS.md), so Claude Code,
Codex, Cursor and the rest load the same instructions. contextos/AGENTS.md has the detail of a
context’s four crates, and presentacion/AGENTS.md that of the wiring and the binaries; a web
project adds web/AGENTS.md, and an events project presentacion/worker/AGENTS.md. Like
everything Puerto generates, they are written in Spanish.
The root file covers:
- the architecture and the dependency rule, with what each crate must never contain;
- the runtime crates and what each one owns, so the agent does not copy their code in;
- the
puertocommands, the field syntax, and which files are regenerated, which are patched and which are yours; - the order of work: generate, list the scenarios, the failing test, the rule in the domain, then the endpoint, API first;
- the sections for what the project has turned on: the frontend, domain events, auth, mail;
- the conventions: TDD, test names, error codes, logging, no
unwrap(); - the checks to run before saying “done”:
puerto validar,make test,make lint,make format; - how to work: one commit per piece, and which changes a human must read.
contextos/AGENTS.md lays out a context file by file, with the rules an agent is most likely to
break: the two constructors, typed ids, one file per use case, writes through the unit of work in
an events project, tests next to the code, the Object Mothers. presentacion/AGENTS.md says what
is generated and must not be edited, the error contract, the health probes and the shape of a
handler.
The compiler does the reviewing
Section titled “The compiler does the reviewing”An agent that has used repositories in other frameworks will reach for guardar (save). In a
Puerto project with domain events, the repository has none, so that is a compile error:
async fn ejecutar(&self, params: ParamsPublicarProducto) -> Result<Producto, ErrorProducto> { tracing::info!(id = %params.id, "publicar_producto: inicio"); let mut producto = self .repositorio .buscar_por_id(params.id) .await? .ok_or(ErrorProducto::NoEncontrado)?; producto.actualizado_en = chrono::Utc::now(); self.repositorio.guardar(&producto).await?; Ok(producto)}error[E0599]: no method named `guardar` found for struct `Arc<(dyn RepositorioProducto + 'static)>` in the current scope --> contextos/producto/aplicacion/src/publicar_producto.rs:51:26 |51 | self.repositorio.guardar(&producto).await?; | ^^^^^^^ method not found in `Arc<(dyn RepositorioProducto + 'static)>`
For more information about this error, try `rustc --explain E0599`.error: could not compile `aplicacion_producto` (lib) due to 1 previous errorThat output is not written by hand: a script generates a project, writes that use case and runs
cargo check, after every Puerto release. The agent reads it, finds the uow_factory next to the
repository in the same struct, switches to the unit of work, and the event gets recorded. Nobody
had to catch it in review. The same goes for mixing up two entities’ ids, an error variant without
an HTTP status, a consumer listening to an event that no longer exists, or a frontend type that
disagrees with the API. The architecture
lists them.
Generators instead of wiring
Section titled “Generators instead of wiring”The code an agent is most likely to get subtly wrong is the code that connects things:
dependency injection, module declarations, route tables, the frontend’s composition root. In a
Puerto project the agent does not write it. AGENTS.md tells it to run the generator:
puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!puerto generar caso-de-uso Producto cambiar_precio_productopuerto generar bootstrappuerto validarFor bigger features, the layer-by-layer generators keep the agent’s context to one crate at a time: domain first, tested, then the next.
Where a person still reads the diff
Section titled “Where a person still reads the diff”The generated AGENTS.md sorts changes by how forgiving the system is when they are wrong (it
calls the tiers Nivel 1 and Nivel 2):
- Tier 1: fails silently, slowly or expensively. A green suite is not enough; a person reads the whole diff before it is committed. SQL migrations, money and other arithmetic the business relies on, authentication and authorization, uniqueness and deduplication, data that crosses a tenant or customer boundary.
- Tier 2: fails loudly and reversibly. The checks are enough. DTO and domain mapping, adapters with real integration tests, read-only queries, docs.
A change that touches both is Tier 1. And the agent makes one commit per piece, green, so the history shows what it did in steps a person can review.
Upgrades are prompts too
Section titled “Upgrades are prompts too”When a release changes generated code, its migration guide in the changelog includes a paragraph written to be handed to a coding agent as is. See Upgrading.