← Back to Blog

Ten repositories, several agents and no scares: how we work with Claude Code

Gorka Mendez
Gorka Mendez15 min read
engineering

BlaBlaNote is a small team with ten repositories: the app, the events platform, the matchmaking engine, the website, the community, the browser extension, the docs, the end-to-end tests, legal compliance and one more that deploys nothing. All the code is written by Claude Code, often with several sessions at once and sometimes with two in the same repository. And we ship to production several times a day.

With a team like that, the hard part is making sure nothing breaks while all that code gets written.

An agent never gets tired, but it starts every session with no memory of what happened last week. A person does remember, for a few weeks. That’s why the rule that organises everything is easy to say and a lot harder to keep: no important rule can depend on someone remembering it.

This post explains how we do it. There are three pieces: a repository that holds the rules, hooks that enforce them and a loop that turns every mistake into a new check.

The repository that deploys nothing

The tenth repository is called planning. It has no product code. It holds the working protocol every session reads, the plans for each open front, the hooks, and the logs of incidents and findings.

It lives on its own for a practical reason. If the protocol lived inside the app, every branch would have its own copy and each copy would drift its own way. Kept apart, it survives any branch and any working copy, and every session starts from it with the product repositories alongside.

Plans carry their status at the top. Every plan opens with a Status: line, and an index groups them by front and says which one leads each. A single command prints the status of all of them, so before calling something pending or done you can check in seconds. A new plan without its status line or its index entry triggers an automatic warning.

The rules repository, with the protocol, the plans, the hooks and the incidents, next to the nine product repositories. Below, a command that lists each plan’s status line: delivered, in progress or replaced.

The protocol has a budget. It’s capped at 30,000 bytes, and going over triggers a warning. It looks like a detail and it’s the most important thing in the whole repository. Every Claude Code session loads the entire protocol into its context, and a protocol that grows without limit ends up like any long manual: nobody really reads it. The pruning rule is this: any warning that already has a machine behind it shrinks to one line that says what happens and who watches it. The full story (date, symptom, cause, fixes) goes to an incidents file that no session loads.

One task, start to finish

Animation of three tasks moving through eight stations: session, worktree, test, closure, e2e, CI, merge and production. One task formats its code on edit; another tries a direct push to main and the guard blocks it; another runs the e2e suite because it crosses from one repository to another and then goes red in CI; a fourth scene shows an attempt to write to production being blocked, and the last task clashes at merge with another one in the same repository, rebases and gets in.

This is how a task travels to production.

1. Start with everything up to date. When the session starts, a hook pulls the changes for all ten repositories and compares each one with its remote and with what it has installed. Reading old code throws no error: not when you read it, not when you look at its history. The hook also checks every working copy and warns about what would fail without a word, like a config pointing at another copy’s environment or assets that were never built. Those failures end in green tests that test nothing, or in emails sent to the wrong place.

The output of the startup hook: all ten repositories up to date and three warnings about copies with failures that would throw no error, each with its consequence, plus the list of finding categories still waiting to be automated.

2. Every task in its own copy. We never work in the main checkout, because other sessions are running in parallel. Each task creates its own working copy (a git worktree) with its branch, its ports and its own database. A script hands out the ports and nobody types them by hand. Two sessions on the same database would wipe each other’s test data, and they’d do it silently.

The main checkout, where nobody works, and three copies in parallel, each with its branch, its ports and its own database.

3. The failing test comes first. In the backend and in the interface alike. A bug always starts with a test that reproduces it and fails before anything is touched. Then comes the minimum code to turn it green.

4. Each repository’s mandatory closure. Every repository has its closure checklist, and it’s not optional or dependent on the size of the change. In the app it’s eight fixed steps: formatting, static analysis, the change’s tests, simplifying, review, the full suite, checking that what another repository claims about the app still holds, and updating the docs. Plus two more that depend on what the task touches: if a screen changes, it gets captured on mobile and desktop and looked at; if a prompt changes, its evaluation runs against the real model. In the events platform it’s eleven, including the frontend lint, its unit tests, mutation testing and a browser test when the change has an interface.

The two closure checklists side by side: the app’s, with eight fixed steps and two that depend on the change, and the events platform’s, with eleven.

The review is done by another agent, without the context of whoever wrote the code. It’s a subagent that gets a package with the diff, the repository’s rules and the test results, and returns findings with their severity. The session that wrote the code never reviews it, because whoever writes can’t see their own blind spots. And CI doesn’t repeat the review: what the reviewer misses, nobody sees.

The author session hands a package with the diff, the rules, mutation on the diff and the finding types to a reviewer with no context, which returns high, medium and low severity findings.

5. Cross-repository tests, only when needed. Each repository tests its own part with a double of the other side. That means two repositories can both pass green with the contract between them broken. That’s what the end-to-end testing repository is for, with a table of seams: if you touch the message the events platform sends to the app, this flow breaks and this test runs. If the change lands on a seam, the task updates that test and runs it, or says explicitly that it couldn’t run it. If it lands on none, it’s skipped.

Events sends a field called start and the app expects one called date. Each side’s tests pass with a double of the other; the end-to-end suite brings both up and catches that the event arrives with no date. Below, a table that decides when it runs.

6. The PR. It opens as a draft, runs the tests split into four batches in parallel and, once green, moves to ready. Red doesn’t get merged, and “it passed locally” doesn’t count as a reason.

7. The merge. This is where our most worked-on guard lives, and it gets its own section below.

8. Production. Merging is publishing: the merge to main deploys on its own. A task counts as closed once it’s in main, deployed green, and a script has cleaned up the working copy, its database and its branches.

Hooks: rules that enforce themselves

Claude Code lets you configure hooks: scripts that run at fixed moments (when a session starts, after every edit, before every terminal command) and can block what’s about to happen. For us they’re the difference between a written rule and a rule that gets followed.

We have four:

  • On startup, the one that brings the repositories up to date and warns about silent failures.
  • After every edit, the one that formats the code and runs the lint. If the edit touches one of the guards, it also runs the guards’ test.
  • Before every terminal command, a guard that blocks direct pushes to main in the product repositories, any way of destroying the development database outside a working copy, and commands that would sweep away unsaved work. That last one only blocks if there really is something to lose.
  • Before every terminal command, another guard that keeps production read-only. Only aggregates come out of it (how many, since when) and never fields with personal data.

The four hooks on a session timeline: on startup, after every edit and two before every command. Below, a terminal where the guard blocks a direct push to main and a merge with overlapping changes.

You can change production data, but only one way: with a command that by default only reports what it would do and only acts with an explicit flag, it arrives in a PR, gets reviewed and gets deployed. It takes a few hours longer, but it leaves a trail in git and can be reverted. A console open against production only exists in the history of a conversation.

What comes out of production and what doesn’t: yes to record counts, dates, statuses and IDs; no to names, emails, whole rows or writes. And the path to change data: a command that reports by default, PR, review, deploy and flag.

The guards follow a few principles we learned by getting things wrong:

Always an allowlist. A guard that lists what’s dangerous protects you from yesterday’s mistake. One that lists what’s allowed also protects you from tomorrow’s. We apply the same idea inside the code, for example in the check that decides whether a command may delete data:

A table with five environment values: production, empty, misspelled, an environment created later, and local. The blocklist only stops on production and destroys in the three odd cases; the allowlist stops on all of them except local.

The blocklist lets it through, and destroys, if the environment variable comes empty, misspelled or with the name of an environment created later. The allowlist treats anything it doesn’t recognise as production.

If it can’t check, it blocks. If a guard is missing a tool, has no network, or the machine is so loaded it can’t check in time, it doesn’t let things through. It blocks and says why.

An annoying guard ends up switched off. A false positive costs more than it seems: the third time a guard blocks something harmless, someone looks for a way to turn it off. That’s why the guards’ test starts with the false positives.

Guards have tests too. Right now there are 326 cases, each with its input and expected result. On top of that, every guard has a mutation: a deliberately broken version the test has to catch. If a mutation survives, a case is missing.

Every hook has to earn its place. We only automate a failure when it meets two conditions: it’s silent (no error, or the error talks about something else) and a machine can detect it. That’s why there’s no hook that runs the whole suite on every edit, and none that checks the closure at the end of every session. The first would cost minutes on every change. The second would have so many false positives we’d switch it off within a week.

Green expires

The merge guard deserves its own section, because it solves the problem most specific to working with several agents at once.

A green PR is green relative to the main that existed when its tests ran. If another task merges underneath in the meantime, that green no longer counts, and GitHub doesn’t rerun the tests on its own. With several sessions in parallel, this happens every day.

So before every merge, the guard decides. It checks that the PR is green and that what’s about to be merged is exactly what was tested. Then it looks at whether main has moved. If what came in and what you want to merge touch different files, it lets you through. If they overlap, or if either one changes something that alters the test environment (dependencies, configuration, database migrations, routes), it blocks. Then it’s rebase, run CI again and try again.

Two cases: with different files the gate lets you merge; with shared files it blocks and forces a rebase and another CI run. And it always blocks if either touches dependencies, configuration, migrations or routes.

That’s the case in the animation: two tasks in the same repository, the first gets in, and the second finds the gate closed until it catches up.

Every CI minute counts

GitHub Actions minutes cost money, and with several sessions pushing at once they go fast. We once ran out halfway through the month. Since then, every piece of CI has to justify what it costs, just like the guards.

The PR starts as a draft and doesn’t move to ready until we’re sure. Tests run in draft, but nothing deploys. Before, every push deployed to the test environment: about 8 minutes per deploy, and almost two wasted deploys per PR, because the next push made them stale. Now the PR only moves to ready once the closure is done and the draft’s tests are green. That’s when, and only when, it deploys.

A tree that already passed isn’t tested again. When moving to ready, GitHub used to rerun the whole suite on the same commit the draft had just approved. And again on merge, on a new commit with exactly the same content. Now the first CI step looks at the exact content it’s about to test, whatever the branch or commit, and asks whether it already passed every test. If the answer is yes, the suite is skipped, and that’s about 24 minutes of runner each time. If main has changed underneath, the tree is different and the tests run, as they should.

A table with four moments: the draft push runs the four batches without deploying; on ready and on merge the tree is already tested, tests are skipped, about 24 minutes are saved, and it deploys to test and to production; if main moved, the tree is different and the tests run. Below, before and now: one deploy per push versus a single one on ready.

We don’t use GitHub’s merge queue. It would solve the race between PRs that touch the same thing, but it reruns CI for every PR that enters the queue. And the usual alternative, requiring the branch to be up to date with main, forces a rebase and a full suite every time main moves, even if what came in has nothing to do with it. The gate we described above does the same job asking only for what’s needed: if the changes don’t overlap, the green holds; if they do, another round.

Mutation, only on what changes. Mutation tests plant small bugs on purpose and check whether the tests notice. In the app we used to mutate every file a change touched, almost ten minutes per task. Now each task mutates only what its change adds: it removes each new condition, one by one, and checks that some test fails. It takes seconds. We also switched off the weekly measurement of the whole codebase: it cost thousands of CI minutes a month and rarely made it to the end. In the events platform, where mutating the touched files takes under a minute, that pass stays in the closure too.

And whatever can break, better break it locally. Every red push is another full pipeline. That’s also why the mandatory closure exists: what it finds locally doesn’t spend a single CI minute.

The loop that learns

Everything above prevents the mistakes we already know about. But the ones that hurt most are the new ones, and for those there’s a loop with two inputs.

Review findings. Every finding from the closure reviewer goes into a log with a category: “test that doesn’t test what it says”, “failure that passes silently”, “translation that changes the meaning”. The rule is that a category that shows up in two PRs and still has no automatic check gets turned into one that same week. That check has to catch the category in any diff; repeating the test for the case that exposed it falls short.

We have to be honest about the numbers. We’ve logged 119 PRs, 49 distinct categories, and only 4 have been turned into an automatic check so far. Writing a check that sees a whole category without false positives is hard, and a bad check is worse than none. What is automated is the reminder: every session starts with the list of pending categories in front of it.

An excerpt from the log with three categories: one already automatic, one seen in two PRs that’s due for conversion this week, and one seen only once. Below, a bar: 4 of 49 categories converted.

Incidents. Even with all this, things still break. Almost always for one of these reasons:

  • What throws no error. A config pointing at the wrong environment, a test that passes without testing anything, or a value computed from a source that no longer exists. All green, and all wrong.
  • Two correct changes that aren’t correct together. Each PR passes its tests on its own and the problem only shows up when they live side by side in main.
  • What only happens in one environment. Local tests and CI use different databases, and what one tolerates, the other rejects. Or a variable nobody pinned that has a different value on your machine.
  • Commands whose dangerous half is the one that asks for nothing. A command that deletes when you run it with no arguments is a trap waiting for someone in a hurry. That’s why every command that deletes, truncates or overwrites data reports by default and only acts with an explicit flag.

A terminal: with no arguments, the command reports it would delete 312 files and deletes nothing; with the flag, it deletes them and leaves the list in the log.

Every incident is logged with its date, its symptom, its cause and the fixes taken. If a machine can detect it, it becomes a guard with its test cases and its mutation, and the protocol keeps a single line. If not, the warning stays written down and explains why there’s no machine behind it.

An incident’s path: the log, the question of whether a machine can detect it, and the two ways out: a new guard with its test cases and its mutation, or a written warning with its reason.

Is this a software factory?

Everyone is talking about software factories now: agents that take an idea in one end and deliver finished software out the other. The question is inevitable, and the short answer is only partly.

Some things really are factory-like. There’s a line with fixed stations, and each repository has its own. The guards do what mistake-proofing systems do in a plant: they make the failure impossible. The line stops itself when something goes wrong, with a red CI or a merge that clashes with another. And there’s continuous improvement, because every repeated mistake has to end up as a check.

But others aren’t. What gets built, when a task starts and whether it’s well framed are still our call. There’s no queue that processes itself from backlog to production. And continuous improvement is lagging behind, as those 4 of 49 show.

So we’d rather give what we’ve built another name: the quality control of a software factory. The agents produce and the line decides what gets through.

What we take away

  • Context is a budget. A protocol nobody reads protects nothing. One line with a machine behind it beats a well-written paragraph.
  • Whoever writes doesn’t review. A reviewer with no context finds what the author can no longer see, whether that’s a person or an agent.
  • Machines before memory. Everything that can be checked checks itself, and everything that can’t gets written down with its reason.
  • Not everything deserves a machine. A check that costs minutes on every change, or that annoys more than it protects, ends up switched off. Every piece has to pay for itself in the time it saves.

Working like this gives us peace of mind. Most of what could go wrong is stopped before it reaches production, and what does get there leaves something learned for next time.

If you also work with agents and want to compare notes, write to us. We love talking about this.

Gorka

Gorka Mendez

Gorka Mendez

Co-founder
30 days free

Ready to transform your conversations?

Join professionals who capture, organize, and act on their conversations with AI-powered intelligence.

30 days free
No credit card required
Cancel anytime