Once a month, I share how the project is going: an overall recap, the latest updates, and what I learned along the way. Everything comes from real experiments, including the parts that didn’t go as planned!

This is a big edition: I am introducing our brand new iOS app and massive updates to the coding workflow!

If you missed the previous episodes, last month we talked about moving agents from local machines to the cloud, and earlier chapters covered how I run the Tolaria project and guides, gates and guards.

Here is the agenda for today:

• 🐢 Why releases have been slower — a personal note, before the news.

• 📱 Introducing Tolaria for iOS — with Android coming soon!

• ☁️ Cloud dev environments — plus Verity, and how agents access tools.

• 🤖 Growing the bot family — the assistants that help me run everything.

• 🔭 What’s next — Tolaria on the web, and inside your agents.

Let’s dive in!

🐢 Why releases have been slower

I want to start with a small apology, as you may have noticed that Tolaria releases have been slower these last couple of months.

The truth is, after the big rush of the first months, I took some time off. This gave me some space to look at how I was working from a distance, and reflect.

I believe my #1 mistake has been to allow my attention to spread too thin across a deluge of small things every day instead of fewer, bigger bets that would truly make a difference. This is understandable because Tolaria has a massive surface for bugs and small tweaks, as it: 1) runs on multiple OSes, 2) works with multiple AI agent hosts, 3) works with the file system, the CLI, git, and 4) just does a lot of things! So I can literally fill up all of my time just working on the small improvements that people report on every day.

This felt productive, but over time I also got stressed and less motivated by that kind of work. So I took a step back, got back to the drawing board, and this is what I want to do now:

• Invest most of my time in the big bets — define the few clear areas that need most of my human taste and strategy input. For me right now, these are mobile, a web version of Tolaria, and how Tolaria works with agents (more on all of these later!)

• Create a good workflow for the small daily improvements — good product experience is made of a thousand small things, so the little daily tweaks count. But it’s important that I keep improving my workflow so that these get done without draining my energy, and the product keeps improving, instead of degrading.

All in all, I am figuring this out as we go, so thanks for sticking with me.

Anyway, the good news is that, from now on, things are going to get much faster. Over these months, I pretty much rebuilt how I work: the new setup lets me do much more in parallel, and scales much better than before. You can see the first results in the updates below, starting with the biggest bet of all, which is ready for you to try 👇

📱 Introducing Tolaria for iOS

The big news of the month is: Tolaria now runs on iPad and iPhone. 🎉

Mobile has always been, far and away, the #1 requested feature on our product board. If you run an iOS device, now it’s here for you to try.

But also let me be honest. The apps are still in a rough state: some parts are ugly, some are bugged, and some probably won’t work at all. But the core of what makes Tolaria useful is already there, and works on both iPad and iPhone. Like, for example:

• The visual Markdown editor, with slash commands, properties, and source mode.

• Real Git push and pull with auto-commit, and two-way sync with an iCloud or Files folder.

• The command palette, plus iOS gestures and rotation.

• 19 languages, like the desktop app.

Some of the rough edges include: git sync being limited to repos you clone from GitHub (with Github sign-in), large vaults are kinda slow to clone, and the app just crashing sometimes. Also, no AI yet, but coming soon.

The iOS app is available today on TestFlight. And since Tolaria is open source, you can also check out the source code and compile it yourself!

Download from TestFlight

Also, I also created a brand new Discord server to talk about all things Tolaria. I will also use it to post changelogs and announcements, and I will engage personally with the community. You can join below:

Join Tolaria's Discord

Finally, a couple of FAQs:

What about Android?

Because the app is built in React Native, Android is coming soon. I just haven’t had much time to test it yet, and I’d rather ship it when I’m confident it works well. But of course, you are welcome to try it from the source, and submit PRs to make it better.

Why React Native?

You might have seen that Shopify recently announced it’s moving its mobile apps from React Native back to native Swift and Kotlin. They had gone all-in on React Native in 2020, and they explain that coding agents have made building each feature much cheaper, so native is now viable and keeps them closer to platform capabilities.

So could I have gone native? Maybe yes, but what really moved the needle for me were over-the-air (OTA) updates. With OTA, I can push fixes and improvements straight to users, without waiting on reviews each time. Now that agents can ship very fast, that felt table-stakes to me. And yes, there is also some code we can share between the desktop and mobile versions, but it’s not a lot anyway, so it was not a primary factor in the decision.

Let me know your thoughts, and on to the next updates 👇

☁️ Cloud dev environments

Last month I wrote about my agents moving from local machines to the cloud. This month, the whole development environment followed.

1) Three coding agents, two of which in the cloud

Before, my coding agent ran on my Mac Mini with Codex, doing one thing at a time. Simple as that! In September, it had become already obvious that this was extremely inefficient:

• Doing one thing at a time was no longer enough, given the various work threads: desktop, web, and mobile.

• Mobile access was cumbersome, and so was access for other agents (e.g. Grok Bot)

• Long-tail reliability issues were real: I got a brief power outage while a was away, stalling work days; macOS sometimes really wants to restart; Starlink goes down, etc.

So, since early October, I have moved most of the work to two Linux machines on Hetzner: one of them runs Codex, and the other runs Claude Code. I also still use the Mac mini for the iOS mobile work and builds.

Having both an OpenAI and Anthropic stack is useful for many reasons, like being able to immediately test new models, and use tools that are specific to one of the two stacks, like Verity, which I use with CC.

This setup also completely untethered coding from my machines, and I can now drive work from my “PM” Grok Bot agent, who in turn SSH into the coding machines.

2) Welcome Linear

I also moved from Todoist to Linear for tracking work.

All the work the agents pick up now lives in Linear, which provides cleaner (and deeper) abstractions for product dev work, and also better agent integrations.

This is still early, so I don’t have a lot to say about it, but the integration has been seamless so far, and I am learning how to use it best.

3) 4x faster CI with CircleCI

On the CI side, we moved from GitHub Actions to CircleCI, and the main pipeline went from about 15–16 minutes to ~4, which is roughly 4× faster!

Locally, every push still goes through the same Husky gates, performed on the CircleCI sidecar chunks, largely in parallel: CodeScene (10/10), Codacy (zero new findings), unit tests, and Playwright smoke tests.

4) Using Verity

I started using Verity, a new product from the team at Codacy, on my Claude Code machine.

When the coding agent completes a task, Verity checks the change for quality, security and whether it matches the product’s tech strategy, using AI review, static analysis and formal proofs in Lean. It either passes the change, or blocks and hands the fix to the agent.

With respect to other tools, what sets it apart is the knowledge base concept. Every important decision gets recorded alongside my ADRs and docs, so future sessions learn from past ones and don’t repeat the same mistakes.

It has already blocked several changes, for legit reasons. I like it so far, and I like the dashboard it includes, where you can check runs, usage, the knowledge base itself, and more. Free during beta, with v1 launching in the coming weeks.

5) Centralized access to tools

With more agents doing more work (including Grok Bot, see more below), the way we used to handle credentials got really messy, with tokens scattered across machines, configs and bot settings.

I first moved agent access to tools into 1Password, but it didn’t work super well so I developed a small custom vault service. Every agent has its own identity, looks up the logins it needs, and can create new ones. It’s a small thing on paper, but it made the whole setup feel a lot more manageable.

It’s also way easier now to spin up new agents on any agent host, as I can simply give it access to the vault.

🤖 Growing our Grok Bot family

Behind all of this, there’s a growing family of assistants.

In September I ported my non-coding agents to Grok Bot, and this month we expanded on it, spawning more of them for dedicated areas, and it has all been working very well.

I don’t think it’s worth going into detail about what each bot does, but here are general lessons we have learned in the process:

• Make spawning new agents as easy as possible. We developed the vault for credentials, and a small custom tool to automatically connect new bots to Slack. Unsurprisingly, the less friction there is in delegating and scaling work, the more work you will delegate and scale!

• Shared team bots + personal assistants work great. Everyone on our team has a personal bot that acts as chief of staff, plus we have shared bots for the areas where we collaborate. This seems like a good pattern that is working well for us.

• Mobile access matters a lot. If I had to pick just one reason why Grok Bot is winning for us, it would be mobile. Whatever agent host you use, make sure you create a good mobile experience (notifications, sync, voice notes, calls). Working with agents is more and more about doing many small things at random times, rather than sitting at your computer for long stretches, so mobile is an incredible enabler.

So far I’m very happy with Grok Bot itself. A big reason is also that it now runs models other than Grok under the hood, like Opus 5.5, and the difference in quality shows.

🔭 What’s next

Beyond mobile, two big things are coming next: Tolaria on the web, and inside your agents.

1) Tolaria on the web

Many teams have asked for a simpler, managed version of Tolaria. This doesn’t mean changing how the desktop app works: it stays fully offline-first, vaults are still cloned locally as Git repos, and so on.

What can change is the hosting.

Today, to share a vault with your team, you need GitHub or another Git host. That works, but it gets messy when it comes to managing permissions and onboarding people. A GitHub repo also has a pretty much all-or-nothing permission model: someone either has access to the whole thing, or they don’t. For code that’s fine, but for docs it’s limiting, especially once external contributors are involved.

So the question for me becomes: can we retain the core principles of Tolaria, while also bringing it closer to how Google Docs works, where you can share specific documents with colleagues and partners?

A web version of Tolaria, that also hosts your file, is the natural place for that. Like the rest of Tolaria, it will be open-source and self-hostable. But we’ll also offer a simple managed option you can pay for, priced very cheaply.

Work is already underway!

2) Tolaria inside your agents

Last week I wrote about how to design a good MCP server, and the backdrop to that piece is that more and more work is obviously happening inside agent hosts.

I expect docs to follow the same path: more and more people will add to and edit their Tolaria vaults through agents, in their favorite agent environment, rather than inside Tolaria itself.

It’s already true for me, by the way! Tolaria is at the center of my workflow and the source of my knowledge base, yet, the more my agents get good at working on it, the less I use it directly.

So we want to build good plugins for all the major agent hosts (Grok Bot, Claude, ChatGPT, Codex). Also, not just tools for chatting with the agent, but also some UI and things you can do right inside the host. Today, Tolaria already ships a local MCP server with 12 tools, which register itself automatically. A few ideas we’re exploring for what comes next, none decided yet:

• Live, editable note cards rendered inside the agent chat.

• A hosted remote MCP, so ChatGPT and Claude can reach your vault (possible with the web version!)

We’re going to invest big here, because more and more work is shifting to those surfaces.

I’d love your help with this. If you use Tolaria through agents today, hit reply and tell me how. And if you try the mobile app, tell me what you think, rough edges included.

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

Every week I write an article to 170K+ engineers about how to make good software together. To get access to all our articles, resources, and our private community, subscribe to the full version.

More and more products these days show up inside agent hosts like ChatGPT, Claude, Grok Bot, as plugins that the model can use. In many cases, agents also act proactively and recommend plugins that fit their current job.

This means, as many predicted, that agents are becoming important distribution platforms, with many users discovering new products from inside them.

Such plugins, under the hood, are powered by MCP servers, which wrap and expose the tool's functionality.

On paper, these look easy to build. In practice, less so.

I bet everyone who has played with agents for a while has found themselves routinely battling with MCPs that are either broken, or incomplete, or don’t work as intended. I surely have, and I keep seeing embarrassing stories popping up on the internet about it.

Just last week, Figma got backlash for having hardcoded the list of allowed clients in their MCP server, effectively disabling popular tools like Pi and OpenCode. One of the creators of the MCP protocol himself chimed in to note that this is not how the protocol should work.

Why does this happen? I believe many teams just underestimate what it takes to create good MCP servers. They think about them as simple API wrappers, assign the task to an intern, and call it done.

Last year I wrote How to Design APIs for an AI World, because it was already clear that APIs needed to be adapted for when the caller was an agent rather than deterministic software. Fast forward to today, a lot has changed about how agents interact with software, so I am writing a sequel that 1) dives deeper, and 2) covers more of the product surface.

To do this well, I am also looping in Luigi Pederzani and the guys at Manufact, who I have known for a long time. They are the authors of the open-source framework mcp-use and have been working on MCPs from the very early days, so they are the most knowledgeable people I know about this space.

I will also be pulling real examples from products that are doing this right, like Notion, Block, Stripe, and Sentry, so you’ll leave this article with practical references that you can take inspiration from.

So here is the agenda:

• 🧩 Jobs instead of endpoints — deciding which tools should exist in the first place.

• 🧭 Designing for an agent caller — descriptions, improvisation, errors, and UI.

• 🔄 The production lifecycle — what is different from running a normal backend.

• ⚖️ Self-host vs managed — figuring out when each one makes sense.

• ✅ Checklist — what to do with your team next week.

Let’s dive in!

Disclaimer: I am thankful to Manufact for partnering on this and sharing how they see MCP design and production in the wild. I am a fan of what they build and you should check it out.

Learn more about Manufact

As always, I will only write my unbiased opinion on the practices and tools covered, Manufact included.

🧩 Jobs instead of endpoints

So, where do you start?

In my experience, the most common mistake is simply taking the endpoints you already have and turning each of them into a tool. REST (or GraphQL) APIs are usually built around resources and CRUD verbs, which work great for software that knows exactly what it wants, and can express it as atomic operations.

An agent, instead, is trying to complete a job on behalf of a user, like “file this bug with a reproduction and an assignee”, or “summarize the blockers of this sprint”.

If jobs depart too much from what single API endpoints do, the model spends tokens (and time) finding the right paths, chains five calls where one would do, and may still fail the workflow the user actually wanted.

Instead, it’s useful to work top-down, starting with the end in mind. List the handful of end-to-end workflows people actually ask agents to do with your product, and then design one tool, or a tight chain of tools, for each of them.

This also gives you a rule of thumb for granularity:

• Too fine-grained — and you pay for multi-hop agent loops (LLM seconds times N) on top of a confused tool choice.

• Too coarse — like one mega-tool with a kitchen-sink schema, and arguments get brittle, recovery gets hard, and auth gets messy.

A good default is tools that finish a job in one or two calls, batching related reads when you can and keeping multi-step flows for the domains that truly need them. When you do need them, make the intermediate state explicit in the responses, so the model can continue without guessing.

A useful example is Notion, because they shipped both versions.

In the Notion API, the content of a page is a tree of blocks (paragraphs, headings, to-dos and so on), and their first, open-source MCP server mapped each endpoint 1:1 to a tool, so agents had to work with blocks too. Blocks are a great abstraction for an API: they are granular and composable, and they give apps that render or sync Notion content precise control over every detail.

An agent, however, usually has a bigger job in mind, like writing up a meeting recap or adding a section to a plan, where the natural unit is the page. Notion’s own takeaway was that 1:1 mapping “created suboptimal experiences for AI agents.”

So, on their new hosted server, they eventually changed the abstraction. There is no tool to create, update or delete individual blocks anymore: pages go in and out as Notion-flavored Markdown, and one page-level call replaces a chain of block calls:

The work of turning Markdown into nested blocks, or finding the right block to change, moved inside the server.

Block tells a similar story in their MCP playbook: the first version of their internal Linear MCP had 30+ tools that mirrored the API, and a question like “what issues is bob@example.com working on” took four to six calls.

🧭 Designing for an agent caller

Once you know which tools should exist, the next question is how they should behave.

The thing to keep in mind here is that your caller is different in many ways from the software that typically hits your API. We covered this for APIs in general last year, and most of those ideas apply to MCP, with possibly even less forgiveness.

To me, here are the most important ideas to remember:

1) Descriptions are runtime

Developers read your API docs once and internalize the patterns, while agents re-read tool names and descriptions at every turn, inside a limited context window, and decide what to call based on that alone.

So, you should 1) name tools the way a user would phrase the request, and 2) use the description for the stuff that actually drives behavior: constraints, preconditions, and when not to use the tool. I would also put description edits through review and some testing, because changing a sentence there can change what the model does as much as changing code.

Sentry’s MCP server does this well, for example, in its search_errors tool:

The model learns what the tool is for, and what to use instead.

2) The caller improvises

Agents may invent argument shapes, call tools out of order, retry in odd ways and forget that setup has already happened, and the host will often retry on their behalf.

So the principles we discussed for AI-facing APIs are your defense here, which in practice means strict schemas where it matters, safe defaults, and idempotent writes on anything risky. For high-stakes actions, you can refuse with a clear message and offer a human-in-the-loop path when the domain needs it.

Stripe does this well for APIs: every POST accepts an Idempotency-Key, and a retry with the same key returns the first response instead of creating a second object. On MCP tools, you can do the same with an idempotency key argument, and declare how each tool behaves with the protocol’s tool annotations:

Clients can use these hints to decide when to ask for confirmation, as Block’s Goose does.

3) Errors should teach the next attempt

A key difference between agents and deterministic software is that the former can (and will try to) recover from errors by itself. So you should help with it.

This means a bare {“code”: 400} is fine for deterministic software, where a developer will eventually read the logs and fix the call, while an agent benefits from errors that are more descriptive and tell it what to do next, like the expected format, an example, or a different tool to use instead.

Block’s playbook shows a good one from Goose, for files over 400KB:

It says what went wrong, why, and what to try instead.

It also pays to log which errors agents hit most, because many of them will point to the tool's surface and hint at what you can improve. Half of your failures might be “invalid priority” because the schema says high and the server expects P1.

4) The job can come with its own UI

Lately, MCP servers can do more than expose tools.

With MCP Apps, a tool can point to an HTML resource that the host renders in a sandbox, so your product can show its own interface right inside the conversation.

This matters for jobs where the user wants to see and touch the result. In a design tool, for example, the user may open a project, select a screen, ask the AI to change it, and see the result in the same canvas. Doing that through text alone would mean describing objects back and forth, while here the app can tell the agent exactly what the user selected.

ChatGPT goes a step further with MCP Extensions, which turn an MCP server into a plugin with specific entry points: a launcher in the sidebar, a tab inside a conversation, and handlers that open files with a given extension in your own viewer. These are host-specific, and some of them (like file entry points) are desktop-only for now. Luigi wrote a good walkthrough of this.

🔄 The production lifecycle

The second intuition to update is about what happens after launch. Shipping an MCP server feels like shipping a small backend service, and in many ways it is, but keeping it healthy also involves work that a regular backend doesn’t have.

Differences mostly show up in three places:

1) Managing hosts

Your MCP will be called by ChatGPT, Claude, and a long tail of other clients, each with its own behavior and update cycle, and the same server can produce very different outcomes across them.

Manufact has an interesting testing write-up that walks through an issue-tracker example where Codex manages to work around server bugs and pass, while Claude fails the same suite because of sneaky defects in the tools. If you only test with your favorite client, it is easy to ship bugs like these without ever seeing them, so make golden prompts on a few real hosts part of normal product QA.

2) Updating the protocol

In about 18 months, MCP has changed a lot: from HTTP+SSE to Streamable HTTP, then tighter OAuth rules, and then the 2026-07-28 revision, which the maintainers describe as the largest since launch.

Just in recent changes, sessions and the initialize handshake are gone, every request is self-contained, and auth has been changed substantially.

Being MCP a client-server protocol, you need to incorporate changes ASAP, because even when your own server code doesn’t change, the one in the clients will!

3) Distributing to directories

Distribution through agents comes with its own process, too.

ChatGPT app review, the Claude Connectors directory, Cursor Marketplace, Muse and Grok custom connectors all want slightly different assets and reviewer access. Each platform has its own packaging, review, and update flow, so you should track the requirements for each destination, keep the endpoint stable, and test the experience after every change.

Put together, this is closer to keeping a mobile app healthy across OS versions and app stores than to maintaining an API behind an SDK you control. None of this is rocket science, but it’s a significant (and growing) surface to keep track of.

⚖️ Self-host or managed?

So, all that said, should you run all of this yourself? It depends on how much of the lifecycle above actually applies to you:

• Self-hosting — is fine when the MCP is internal (e.g. stdio), used by one team or IDE, the blast radius is low, you are okay owning SDK upgrades when the protocol changes, and you are not listed in marketplaces.

• Managed — a hosted platform pays off when you ship a remote MCP as part of your product across many directories (ChatGPT, Claude, Cursor, ...), you want cross-client test suites against real hosts and checks before each submission, and all of that work sits on your critical path without being what makes your product special.

As a quick plug, the second scenario is what the team at Manufact is building for. Their MCP cloud lets you connect a repo and deploy, test against clients, monitor usage, all with mcp-use as open-source framework underneath.

If you are already hosting your server elsewhere, they also run cross-client tests and publishing-readiness checks without moving the deployment. I love their approach and you can learn more about it here.

✅ Checklist for next week

If you have been thinking about developing (or improving?) your own MCP server, and want something concrete for the team to begin with, here is a quick checklist:

1. List the most important agent workflows — that should exist (say < 7), and delete the endpoint-dump tools that do not serve them.

2. Rewrite tool names and descriptions — as if they were prompts, and put description changes through review.

3. Add actionable errors — and idempotent writes to the risky tools.

4. Pick three hosts — and run a golden-prompt test of the full experience, UI and permissions included.

5. Assign an owner — for MCP health, with a re-check after every major MCP, Claude or ChatGPT release.

6. Decide self-host vs managed — for deploy, test, monitor and publish, and write down the reason.

💬 Join our community!

Hey, thank you for making it this far! If you liked this piece, consider subscribing to the full version of Refactoring. Paid members get exclusive access to our private community of 1500+ tech leaders, where every month we pick one theme and dig into it together.

In October the theme is management in the age of AI, and on Monday, October 19 we have our next live Mastermind on rethinking the manager's role.

Get access to the Community

And that’s it for today! I wish you a great week.

Sincerely
Luca

About four years ago I published Do you really need a Staging environment? — the first article of mine to really go viral. Front page of Hacker News, more than 2,000 likes on Linkedin, and hundreds of comments across social media.

Many of such comments were just... angry! In fact, even if the title was framed as a question, I argued that, in most cases, staging environments did more harm than good. And many people didn’t like that.

Fast forward to today a lot of things have changed. Teams ship more code, faster, and more often. Does this make staging (and/or equivalent intermediate envs) more or less valuable? I see you saying “it depends” — so it depends on what?

So today I want to revisit the original thesis, figure out what still holds, vs what needs to change.

Here is what we will cover:

• ⬅️ What I argued in 2022 — a short callback to refresh our memory.

• ✅ What still holds — parity, batching, and when shared staging still pays off.

• 🤖 What AI changes — more throughput, worse env lies, safety net in prod.

• 🛡️ Guardrails for dev — guides, gates, and guards upstream of merge.

• 🚢 Ephemeral preview envs — review on isolated, prod-shaped envs.

• 🔬 Observability and controls — recover fast when something slips.

• 🎯 Final checklist — what “good” looks like now, without the sermon.

Let’s dive in!

Disclaimer: I am thankful to Upsun for partnering on this piece and for pushing me to revisit this topic properly in 2026. I am a fan of what they build around Git-native environments, and you should check them out.

Learn more about Upsun

However, as always I will only write my honest opinion on the practices and tools covered, Upsun included.

⬅️ What I argued in 2022 (briefly)

The original piece tried to get clear about when a shared staging / pre-prod environment helps, vs when it mostly adds cost and delay.

The two problems I saw (and still see) the most often are:

1. Staging is often unreliable — because keeping it at parity with prod (i.e. data and infra) is hard and expensive. So most teams cut corners: a fraction of the database, different instance sizes, and just some of the services.

2. It makes releases many times slower — an extra release level means waiting for the env, batching several features “because we are releasing anyway,” deploys that become morning-only (or only “at the start of the week”), and the classic “whose change broke staging?” moments.

The way out already existed in 2022: small diffs, strong automated tests, feature flags, canary / progressive delivery, and real investment in observability in production. This way problems in prod are smaller, and you are fast at catching them anyway, even without staging.

On top of this, bonus points if you setup two of my favorite things:

• Preview links for QA — envs that spawn on the fly for features that need dedicated product review.

• Remote dev environments — that live in the cloud and can inherently be closer to prod than a developer laptop.

This is the gist of what I wrote back then — if you want the longer version (including when staging still earns its keep), here is the original:

✅ What still holds

Read more

Every week I write an article to 170K+ engineers about how to make good software together. To get access to all our articles, resources, and our private community, subscribe to the full version.

Lately, I have become more and more interested in how teams are using AI inside real production workflows.

Sure, your Claude skills are cool, and so is your AGENTS.md, but I want to see how this tech graduates into stuff we run on our servers, reliably, all the time, and creating value.

This is also not the first time I have written about this:

• In May, I published How to Orchestrate AI Workflows, which is a primer for moving from AI loops to more structured orchestration.

• Earlier this month I published Getting Started with AI Governance, to talk about security, control, and how “if you want the car to go fast, you need brakes!”

So today I want to go deeper into what it means to create good AI workflows at scale, based on conversations I had with the people who are doing this for real. I took a lot from my recent chat with Jan, from friends I met during recent travels, and especially from Ludovic and the guys at Kestra, that I am looping in again after the huge success of the first piece we wrote together!

Here is the agenda:

• 👁️ Observability — what to watch on agentic runs, plus a practical checklist.

• 🛡️ Boundaries — how keep sensitive data where it lives, and separating workers from orchestration.

• 🧑‍✈️ Human in the loop — when to put a gate, and how to resume without replaying an hour of work.

• 🔌 How to get started — prefer governed flows as tools for the agents you already trust.

• 📚 Resources — a few places to go deeper on the practices above.

Let’s dive in!

Disclaimer: I am thankful to Kestra for partnering on this and providing ideas and insights about the orchestration industry. I am a fan of what they build and you should check it out.

Learn more about Kestra

However, as always, I will only write my honest opinion on the practices and tools covered, Kestra included.

👁️ Observability

A surprisingly high number of the teams I spoke with built some AI observability tools in-house.

To me this feels like when, around 2022, I ran the first surveys about what tools teams used to measure engineering metrics, and about ~50% of respondents had patched something together themselves, e.g. pulling numbers from Github and putting them on Grafana.

Likewise, today many teams are logging basic info themselves. For every run, this is typically token spend and the final answer of the agent. This is good! You get your hands dirty, learn what you really need, and wrap your head around the idea of measuring this stuff.

However, just like with engineering metrics, these setups fail as soon as you need to drill down into specific steps of the agent runs. Which, as long as your runs are short, might not be a big deal, but as soon as you have a long (and expensive!) recurring job failing halfway through, you may want more control over what happened and why.

In my experience, good observability for such workflows means you can reliably get the following information, ideally from the same system:

1. Intermediate step outputs — not only the final blob. Each meaningful step should leave something inspectable: a fetched record, a classification, a draft that was about to be sent.

2. Tokens and cost per run — these are the basics everyone measures, and for good reason. This should be ideally broken down per step / model / tool.

3. Tool and MCP calls — which servers, which tools, with what inputs and outputs.

4. Who or what triggered the run — a human (manual trigger), a schedule, a webhook, or another agent session. Origin and session tags matter when you audit later.

5. State at failure — which step failed, what was already committed, what is safe to retry.

If these still feel a bit abstract, here are a few questions you can ask yourself (or your team!) about your setup:

Read more

Every week I write an article to 170K+ engineers about how to make good software together. To get access to all our articles, resources, and our private community, subscribe to the full version below:

Run better engineering teams

I am back from two weeks of travel, during which I took some time off but also attended two great conferences: LDX3 in New York, and ProductLab in Berlin.

Conferences, for me, are a great way to say hi to friends and to check the pulse on the trends and sentiment in tech. This time made no exception: I learned a lot by attending talks and workshops, and simply by talking with people.

So this week’s edition covers my personal highlights from such talks and conversations.

Here is the agenda for today:

• 🚚 Doing migrations right — Will Larson on Imprint’s delivery journey, framed as a set of migrations.

• 🗣️ Guiding people through change — Meg Adams’ diagnostic tools for having hard conversations.

• 🧭 The Manager’s Path in the Age of AI — Camille Fournier on what still belongs to managers in 2026.

• 📊 DX quarterly numbers — Justin Reock’s latest AI impact data, plus how I think about these metrics.

• 🎙️ How n8n is embracing AI — highlights from my conversation with Jan Oberhauser, founder of n8n, in Berlin.

Let’s dive in!

1) 🚚 Doing migrations right

LDX3 opened with a great keynote by Will Larson, who described the delivery journey of his team at Imprint: from manual gates everywhere, to CI/CD, to agentic workflows.

Will’s talk was extremely practical (we need more stories like this), and framed these steps as migrations. We know a lot about migrating code, and most of the same logic can be applied to processes and workflows.

Here are the parts of Will’s approach that stuck with me:

• Understanding people’s problems — there’s a reason why people do things the current way, even if it looks flawed. To build something better, you need to understand current problems deeply, which is hard!

• Getting buy-in — Will stressed how, even if there was clear top-down input about the direction, the implementation was a collaborative effort where people were involved at all stages. At some point, Will wanted to migrate from Jira to Linear, and started by involving the people who were the biggest Jira fans. He knew that if he could address their concerns, the rest of the team would be easier to migrate to.

• Draw hard lines — inclusion and collaboration matters, but once a direction is taken, resources need to go to supporting that direction. In picking AI coding agents, Will settled on making Claude Code the recommended coding tool: people who wanted to use something else could do it, but would not receive support from the platform team.

• Sweat the details — with any migration there is always a long tail of stuff to be fixed and edges to be smoothed until things truly work for everyone. Keep working on it even when it seems that “most of the work is done”.

2) 🗣️ Guiding people through change

During LDX3, I attended a workshop by my friend Meg Adams, who I also interviewed last year, about having good conversations with people and guiding them through change.

Read more

Lately I have been talking with both software engineers and security people about this moment in AI rollout, and it’s interesting how they feel it from opposite ends.

At first glance, there seems to be a real tradeoff between making AI useful, and keeping it safe:

• On one side, the best stories about AI impact always involve connecting it to pretty much everything you got: tickets, docs, CRM, Slack, telemetry, and more.

• On the other side, this creates a big surface for threat that even the latest models are extremely vulnerable to.

As of today, most agent setups I see are still completely ungoverned. What can this agent touch (MCP servers, browser, data, ...)? Who connected it? What customer data can actually leave the building?

Many teams are conflicted about putting real governance in place because that’s perceived as a brake, in a moment in time where you are expected to accelerate instead.

I have a contrarian take on this, that I want to discuss today.

In 2006, Peter Summerlin, a professor in Landscape Architecture in Mississippi, ran a simple study about kids’ behavior in playgrounds:

A simple study was conducted to discover the effects of a fence around a playground and the consequent impact it would have on preschool children. Teachers were to take their children to a local playground in which there was no fence during their normal recess hour. The kids were to play as normal. The same group was to be taken to a comparable playground in which there was a defined border designated by a fence.

In the first scenario, the children remained huddled around their teacher, fearful of leaving out of her sight. The later scenario exhibited drastically different results, with the children feeling free to explore within the given boundaries.

So, in playgrounds with fences, kids actually used more space.

I believe good governance can be an accelerant. Like kids, once people know where fences are, people can be empowered to do more within them. But that’s only if governance is good, which is a big if!

Today I will try to explore what this looks like, in the context of AI. Here is what we will cover:

• 🛡️ Bounded freedom — why governance speeds AI rollout, instead of killing it.

• 🧱 What you should actually govern — people, agents, data, tools, and actions.

• 🔒 AI operates on a subset of human trust — the analogy between human and AI governance only goes so far.

Let’s dive in!

To explore this, today I am also bringing in Becky Brooks from MCP Manager. They work at the forefront of this topic, and have helped me a lot in making my mind up.

I am grateful to have them as a partner on this piece, and you should check out their MCP gateway, which companies use to manage how data and tools flow to and from AI.

Learn more about MCP Manager

In any case, I will only write my unbiased opinion about the practices and tools covered, MCP Manager included.

🛡️ Bounded freedom

A lot of ambitious teams that I know delay governance and compliance, with the idea of going AI-native first, and cleaning up later. In my experience, this order is backwards.

Without clarity, people react in two possible ways:

• They freeze — they are unsure about being punished for this or that, and they just go the safe route, doing with AI much less than they would be able to.

• They go underground — I was on a train once, and a guy in the seat in front of me was using his company laptop with one hand, and ChatGPT on his personal phone with the other hand, copy-pasting stuff between the two. You don’t want that to happen, obviously.

There is a study by Google Cloud from late 2025 that confirms this. Teams with clear governance in place get much farther, and faster, on agentic adoption than those without:

• Teams with full governance → 46% adoption

• Teams with partial governance → 25% adoption

• Teams with “still in development” governance → 12% adoption

Of course, correlation is not causation, but it still makes it hard to look at governance as only a tax.

And when you think about it, that’s already what happens in specific domains, like coding. We talk about guardrails for AI coding all the time, and I even published my own approach with guides, gates, and guards, which is, admittedly, quite strict.

Having strict guardrails is what allows me to be more liberal with the tasks I give to my agents, and what they can ship.

So if good governance is guardrails for data, tools, and people, what does this look like? Let’s try to figure out.

🧱 What you should actually govern

Working from first principles, what is it that you should actually govern? To me, it looks like four things:

1. People — who may use which AI client or gateway (by role, team, seniority). E.g. engineers get the coding setup, interns do not get production CRM tools, etc.

2. Agents / clients — which AI surfaces are approved at all. Company Claude yes, personal ChatGPT no, and so on.

3. Data & tools — what the agent can see (and call). Drive folders, Slack channels, Jira projects, databases, CRM, MCP servers.

4. Actions — what it may do once it is connected. Read, write, delete, open a PR, message a customer.

It’s interesting to note that this looks exactly like the same line of reasoning we should apply to people, even without AI. And I would argue that we should start with governance for people first, and address AI later, because the opposite is impossible.

Read more

Every week I write an article to 170K+ engineers about how to make good software together. To get access to all our articles, resources, and our private community, subscribe to the full version below:

Run better engineering teams

Hey there! Welcome to a new edition of my monthly updates on my AI coding workflow.

Once a month I publish an article about how I develop Tolaria, including an overall recap plus the latest updates, and some useful resources. I only ship these when there is something real to say, so you will not get the same post every month just with a different date on top!

I consider part of my work (combined between Tolaria & Refactoring) to always try the latest and greatest, so you will only get thoughts that come from real usage and experiments.

So here is the agenda for today:

• 🔄 Workflow recap — for those who missed the previous episodes.

• 💧 Tolaria updates — product updates from this month, and what’s coming next.

• ☁️ Agents move to the cloud — a general trend plus my personal experience of gradually moving away from my Mac Mini (and my laptop).

• 🤖 Moving to Grok Bot — from a single local orchestrator agent to a panel of five, hosted in the cloud.

• ➡️ What’s next — what I am excited to improve for next time.

Let’s dive in!

🔄 Workflow recap

For those who missed the previous episodes, here are some pointers:

• Product management — how I do traffic control between issues, PRs, and product requests, and orchestrate the overall product backlog.

• AI Coding — my own approach to scaling coding with agents, via guides, gates, and guards. Mostly remained unchanged from last month.

• Tools I use — deeper dive into how I use the tools from the alliance, and others too.

• Summer AI Coding Updates — last month’s edition (forking our editor, custom performance gates, and notes about the latest GPT models).

Also, this series (and the whole development of Tolaria) is made possible by the great tools I use everyday, that also sponsor the project, which are:

1) CodeScene 🔬

It guarantees great code health across the codebase. My coding agent uses their CodeHealth MCP as a guardrail, enforcing 10/10 health. I have been using it from day one of Tolaria — very recommended!

2) Codacy / Verity 🔒

It’s quality & security as gates: an all-in-one PR reviewer. Codacy also launched Verity (beta), which helps Claude Code fix quality, security and intent issues on every run, and builds a knowledge base of decisions to make every session smarter than the last. That’s basically what I have been doing manually with ADRs, so I am excited to see where this is going!

3) Unblocked 📑

I use Unblocked as context engine, both for my coding agent to use, and for me to ask questions to. I am also testing their latest Unblocked Code coding agent as a straightforward way to get small tweaks done.

4) CircleCI 🔧

I use CircleCI to run local validation remotely, via their chunk sidecars, and I am also migrating the whole remote CI to it. I love their focus on speed and reliability, which is important to me in order for validation not to become too big of a bottleneck for the coding agents.

Now on to the new stuff, but first... product updates. Because my workflow is only as good as what I ship with it 👇

💧 Tolaria updates

This month for Tolaria is lighter on new features and heavier on two bets that I am still working on. These are the mobile apps and a hosted version of Tolaria. These are also two of the things people are asking the most for (mobile is #1 far and away), so I’ll give some updates.

1) Mobile

By now I have a working iPad prototype already, with the UI rebuilt in React Native. It’s a universal app, so it also works on Android tablets (at least in the simulator, because I don’t have one to try it on).

I started with the tablet first for two reasons: 1) the UI is easier to map almost 1:1, and 2) selfishly, I do a lot of work from my iPad so I need an iPad version of Tolaria.

What’s still missing/unfinished are mainly the Git and AI integrations, with Git being particularly tricky (will elaborate on it over the next few weeks!)

Once the tablet version is ready, though, the smartphone version is quite straightforward. The UI will be simplified a bit, but technically speaking it’s not a big deal.

2) Hosted Tolaria (exploration)

I am also thinking about releasing a web version of Tolaria, that is self-hostable but also available with a managed option, so the vault is reachable without the need for a local native app.

This would be good for many reasons:

1. Makes sharing files easier, opening up to web sharing a-la Google Docs

2. Obviously makes vaults accessible from anywhere (also reducing the need for mobile native apps)

3. Could turn into a side business model for Tolaria, with the managed version being a paid option.

About the third point: Tolaria is run and developed as a sidekick to our Refactoring business, and we also have good sponsors (thank you ❤️) so I am under zero pressure to profit further from it, but a hosted version 1) could be genuinely useful for some people (they asked for it) and 2) of course it would cost money to run, so it should be paid.

This is still in exploration stage, so I am happy to hear your thoughts and ideas about it!

☁️ Agents move to the cloud

By now, I think we have all seen the half-open laptop meme. As you can see in my previous posts, for a long time, I have run all my product development on my machines, and in particular:

• Orchestration via OpenClaw first, and Hermes later.

• Coding via Codex instances on my Mac Mini, and occasionally on my Macbook.

I believe that as 1) we understand better what agents need, and 2) agents themselves become more capable and can use computers more broadly, we are necessarily going to move away from local environments and increasingly ship these in cloud VMs, at least for agents doing actual work.

In a way, this is the same thing that happened with regular applications. We are not hosting websites and apps in our basement anymore (at least not the majority of us?!) — we are using the cloud for that. Cattle vs pets, and all that jazz.

I believe the same will happen with AI agents, because the benefits are just overwhelming. I don’t think local agents will disappear, because it will always be good to run a good agent on the computer you actually use, but when it comes to deploying many of these boys, there’s no way we’ll be doing these on our machines. So most of the agentic work will turn to the cloud.

For me, this migration had already started slowly, with experiments here and there, but got a decisive acceleration when I tried Grok Bot this month.

Grok Bot has been a revelation because of how well-made, convenient, and useful it is, and I migrated all my agent work (except coding) to it.

If you are unfamiliar with it, Grok Bot is an agent environment built by the team at Cursor, where you can spin new agents that are automatically hosted in the cloud, on Linux VMs. On their machines, the agents can do anything they want: install stuff, use tools, use their browser, and so on. Mind you, this is nothing inherent new or that you couldn’t setup yourself, but it’s just 100x more convenient than setting things up manually with SSH, Tailscale, Termius, containers, and so on.

So, once you try it, it’s pretty obvious all agent environments should work this way — and I bet they will. Because having agents hosted in the cloud makes them replicable, disposable, makes it easy to run many of them concurrently, gives you good mobile access out of the box, and a loong tail of quality of life improvements.

So here is how Grok Bot changed my agents setup:

🍻 From Brian to... Brian & Friends

If you followed the previous episodes, you know that I have been running just one main agent, as a second version of myself, for all the orchestration work that is not coding. It’s called Brian, and it’s my “Chief of Staff”.

Over time, Brian clearly started doing too many things, taking care of: product work for Tolaria, all kinds of work for Refactoring, and various scheduling and traffic control for my own life.

Grok Bot allowed me to easily spin off Brian’s work into multiple agents, so that now I have five of them:

1) Brian

Stays as Chief of Staff.

He is the default agent I reach out to for anything misc, and is on top of everything that happens that I need to be aware of.

Every morning he sends me a brief about what I need to take care of during the day, writes me a recap at the end of the day, and occasionally sends stuff my way during the day when something urgent needs my attention.

Now, however, he is also being helped by his friends 👇

2) Karn

Runs product management for Tolaria.

It has access to all the product signal that comes from PostHog, Sentry, Github, Canny, emails I receive about Tolaria, and people talking about it on social media. Like Brian before it, it does traffic control, triages and dedupes items, specs them, and puts them on the coding kanban board.

He also sends me a brief every day with the key decisions I need to make about Tolaria, including tasks I need to review 👇

3) Edith

Is my Editor-in-Chief.

While I insist on writing all actual articles by hand, Edith intervenes at the beginning and at the end of the process, by doing:

• Research — for any new article, it pulls related ideas from past articles I wrote, interesting new articles I should read, podcast interviews, and more. It is phenomenally helpful in compressing and improving the research work.

• Feedback — after I write a full draft, it gives feedback on everything from basic grammar to inconsistencies in the structure, contradictions, and so on. It is good at challenging what I write so I can reflect more on it.

It is also “in charge” of the newsletter publishing calendar, so it makes sure the various drafts are ready at the right time, podcast interviews are lined up, articles done in collaboration with others are shared in advance, and so on.

4) Sponsy

Helps with Sponsorships.

At Refactoring, sponsorships are led by Matteo, my closest collaborator, and they involve a ton of operations. Sponsorships deals have a whole lifecycle, like standard sales deals, plus they spawn tasks that are specific to the newsletter work, like:

• Collecting the copy to include in the newsletter

• Sending previews

• Reporting numbers after ~1 week

• and more!

Sponsy helps a lot with mapping the status of the various deals, what needs to happen every day.

5) Grow

Grow is the newest addition to the bot stack (or should I say team?!). It tracks a bunch of metrics for the newsletter health (open rate, growth, click rate, ...) and helps with operations related to the paid ads campaigns we run.

In particular, it does a lot of work that would otherwise be manual: for example, importing new subscribers from campaigns into Substack, and assigning the correct tags to them so we can create email sequences.

It also sends daily reports about how campaigns are going, like:

Closed week: 163 Substack Meta regs (vs 203 prior, −40 / −20%). Received-mail unique 7d open 40.0% (60/150) vs 44.8% prior (−4.8pp). Morning was 36.1%; afternoon refresh after more people received mail (raw 60/163; 13 not received yet). Paid converts: 2 (vs 3 prior).

🔭 What’s next

This setup is about one month old and is by no means perfect, but it just shows how much promise there is in creating fleets of small-scoped agents to scale work.

To make this viable, though, it needs to be easy to create and steer these guys, which I think is what Grok Bot is uniquely succeeding at.

When agents are successful at 1) doing their thing, plus 2) reporting to you, you can legitimately do most of your work in a chat environment, or with voice notes, without using the tools yourself. Which is basically what you see in the GPT 6 Astra launch video.

I think this is a good direction to point ourselves at, as a proxy for good delegation. So, good questions you may ask yourself are:

• “How can I use my computer less?“

• “How can I do more work from my phone, just sending voice instructions?”

In a way, it’s like when you see pictures of the desk of the President of United States, and there is no computer. How does the guy (ok, the previous guys) get things done? He just talks to people. People come and tell him what needs to happen, what decisions he needs to make, who he needs to speak with, and he does. He doesn’t need tools.

This might be an extreme, but I think you see my point.

📌 Bottom line

And that’s it for today! Here are the main takeaways:

• ☁️ Most agent work goes to the cloud — local agents won’t disappear on the computer you actually use, but deploying the bulk of them on your Mac Mini (or laptop) stops making sense. Same arc as applications in the cloud.

• 🤖 Grok Bot made the jump easy — cloud Linux VMs, install what you need, with browser included. I moved all non-coding agent work there because it is just much more convenient than the SSH / Tailscale / Termius stack.

• 🍻 Team of small agents > One mega agent — work feels better now that I have a small fleet of focused agents instead of Brian doing all of the work.

• 🔭 Aim at less computer, more chat — when agents do the work and report back, more of your day can live in chat or voice notes. So a proxy for good delegation becomes: how can I use my computer less?

I wish you a great week!

Sincerely 👋
Luca

I loved it, celebrated it as the best piece I read that week, and since then I have kept thinking about various ideas that built up on it, and that I want to share today1.

First of all, let’s start with the title: what does thrive mean?

Each of us has (or should find) their own version of success, but a broad one that I particularly like is: becoming better versions of ourselves. I like it because a lot of the good things in life are downstream from growing as a person. You become better, and better things eventually come to you. That’s true in work, relationships, health, and pretty much anywhere.

Of course, that’s not the only way good things can come to you. Many come by chance, or luck if you may, but if you want to find an angle that is actually under your control, you can hardly go wrong by trying to upgrade yourself over and over.

And here is the problem with AI: I don’t feel that as a tool, by default, it helps with that. Pretty much the opposite. If you blindly use AI to the best of its capabilities, chances are you gradually get worse at several things.

So, when I think about my usage of AI, that’s the angle I try to use. How can I make it so that 1) AI helps me at producing more and better work, while 2) making me better as a professional (and a human being)?

We’ll be exploring this today:

• ⚖️ What AI takes from us — for everything tech gives, something else you now have to nurture.

• 🏃‍♂️ Mental marathoners — when intelligence is cheap, stretching yourself becomes your edge.

• 🧱 What makes us marathoners — instead of riding as passengers.

• 🧭 How do you know you are on the right track — better work, learning, taste, energy.

Let’s dive in!

⚖️ What AI takes from us

The fact that AI makes us worse at some things may seem counterintuitive, especially coming from a work tool, but it’s not really surprising if we look at the broader trajectory of technology.

In fact, progress is not strictly linear and incremental. For everything that tech has given us, there are also things we now need to intentionally safeguard and nurture, more than we used to in the past, in order not to lose them:

• An obvious one is physical health — regular, commercial gyms were not a thing until the 70s, when our lives gradually became more sedentary and all of a sudden fitness became something you had to be intentional about.

• Another one is attention span and our ability to focus — today, we kinda all agree they are under attack, but we hardly ever thought about them before the social media era.

So what is AI going to take from us?

This is a tough question, because AI is likely the broadest tech improvement we have seen in our lifetimes. By simplifying it a bit, it delivers two main things: intelligence and knowledge.

Knowledge is, obviously, about knowing things, while intelligence in this context is the ability to reason on a problem and apply logic to come up with a solution. Most work (and life) tasks require some combination of knowledge and intelligence to be done.

Now, we may nitpick about the definition of AGI, but, as of today already, we have to admit AI does a better job than people for probably >90% of such tasks. That’s the reality, folks. And that’s because, even in those rare cases where an expert still has an edge (better knowledge), or you can reason through a problem better than a frontier model (better intelligence), AI still most often wins because of how cheaper and faster it does the thing. Even when the work done by AI is just, say, 80% as good as a human expert, it may still win because it’s 80% faster and cheaper, and that’s a desirable tradeoff.

Should we be excited about this, because of the opportunities it brings, or scared, because we feel increasingly disposable? It depends.

Personally, I believe this is fine as long as we use AI in a way that puts us, as individuals, on a trajectory of personal growth, instead of regression.

Is this even possible? I believe so. Chess and Go are great examples of this: AI surpassed humans long ago, but it also allowed humans to get immensely better by watching AI play, and now both games are more popular than ever.

But what does it take to get there? Let’s talk about volition and... marathons 👇

🏃‍♂️ Mental marathoners

In his article, David says that when intelligence is plentiful, volition becomes valuable. In this case, it’s volition to stretch your own abilities and become a better version of yourself. David calls the people who are willing to go through this: mental marathoners.

I like the marathon picture for this, because marathons do not fit a practical purpose, outside that of stretching what you can achieve as a human. When it comes to health, you can (and it’s probably easier to) get in great shape without extreme 40km runs, and of course, when it comes to pure utility, a car covers that distance just fine.

So, just like marathoners run because they feel the need to run and challenge themselves, mental marathoners are supposedly those who feel a need for cognition, and are going to use AI to get better and sharper, as opposed to being passive passengers of this tech.

Now, where David and I disagree is in framing such a need as an innate trait — you either have this hunger or you don’t. I don’t think this is the case, and in general I don’t find this to be a productive way of looking at things. The productive way, instead, is by asking: what can we do to become hungrier for cognition? Or why don’t we feel like it right now?

In other words, assuming we are not either born hungry or not, what can we do to become hungrier? This is an interesting question because it is relevant at all levels:

Read more

Every week I write an article to 170K+ engineers about how make good software together, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Recently I have started researching and publishing more case studies about how real companies are doing product development with AI. That’s because I feel that many people are like: “enough with the thought leadership!” — and that includes me!

This time I am doing a deep dive into the AI workflows of the team at Unblocked, which I have known for a long time. I sat down with Dennis and Brandon, who walked me through some of their most interesting processes.

The team at Unblocked is especially relevant because they got skin in the game. They ship a product that turns the team’s code, docs, tickets, and conversations, into actionable context for agents. So they dogfood all of this every day. That’s a strong incentive to work as close as possible to the frontier, rather than doing things “as we have always done” (cit.)

I also love that a lot of what they do is public: they maintain an open-source cookbook with several recipes (skills), which you can fork and copy.

So here is the agenda for today:

• 🎚️ Dynamic autonomy — scoring runs for risk and confidence, and behaving accordingly.

• 🧪 Case study #1: vibe check — one skill, two triggers, three exits.

• 🚨 Case study #2: AI-assisted incidents — humans drive, cleanup can go further

• 📘 Creating a cookbook around it — interactive vs headless, and how the score moves

• 📊 Delivery numbers — what the metrics say so far.

Let’s dive in!

Disclaimer: I am a fan of what Unblocked is building and I am grateful to have it as a partner on this piece. You should check it out!

Learn more about Unblocked

However, I will only write my unbiased opinion about the practices and tools covered, Unblocked included.

🎚️ Dynamic autonomy

One of the most popular ideas about AI workflows is the so-called autonomy slider — that is, for any given process you should design how much leeway to give to the AI, vs how much humans should intervene (and when, and where).

Autonomy is, of course, a spectrum. If perfect autonomy looks like a loop, we talk about humans-in-the-loop to express that some parts are designed for humans to interrupt the AI and do things.

One of the most interesting ideas I got from Dennis and Brandon is about making this autonomy slider dynamic: a lot of their workflows are designed to have runs scored for risk and confidence. Such a score guides how much autonomy the agent gets at that time, and where a human has to step in.

This is a flexible concept that can be applied to many different workflows: shipping code, processing bug reports, intercepting incidents, and more.

In fact, most of these include extremely diverse situations, so it’s tricky to hard-code human gates into the workflows themselves. You constantly risk having either:

• Safe work unnecessarily waiting in queue, or

• Risky work getting through when it should have been stopped and inspected first.

To make an example, let’s say a bug report spawns from a customer success chat, or from Datadog telemetry. The AI evaluates two questions:

• How confident is the AI about this job being real, and being able to do it?

• How risky is this change?

This leads to a score that drives the next action:

• 🔴 High risk, low confidence — just write a ticket and hand it to a human.

• 🟡 In the middle, roughly 50 to 70% — Slack a person who can answer more questions about the work itself, with the context already attached.

• 🟢 Low risk, high confidence — write the code directly and open a PR.

The same idea is used on PRs. A change that is evaluated as low-risk can go through without a human review, while a high-risk one puts a human reviewer in the loop.

So, let’s get more into the details of this.

🧪 Case study #1: vibe check

The first process Brandon walked me through was something they call vibe check.

Read more

It goes like this: since AI can approximate well what a junior engineer is able to produce, there is no point in hiring anyone who is not senior. In fact, senior engineers are the only ones capable of steering these tools.

From what I can see, this story is real, in the sense that many people believe it. I know many companies who have frozen junior hiring, and others who are explicitly steering towards small, senior-heavy teams.

I believe this is a mistake. And I don’t mean it from an ethical angle (the poor junior engineers!) — I mean from a practical, business one.

It’s also a mistake I have seen being done many times, well before AI, pretty much based on the same arguments. If anything, AI supercharged some of the same fallacies that have been around for decades.

Also, I am not alone in this. If you have been following Refactoring, you know the junior engineers topic is a recurring one both in the newsletter and in podcast interviews. Over time, I discussed it with Chris Lattner, Charity Majors, Meri Williams, and more.

So today I will put everything together and make the definitive case for hiring junior engineers on your team in 2026! Here is the agenda:

1. 🏋️‍♂️ Juniors are required to do more now — let’s acknowledge where this is all coming from.

2. ⚖️ Junior vs senior engineers — the difference is messier than you think

3. 🔭 First vs second-order effects — thinking of your team as a system when it comes to process, hiring, and growth.

4. 🌱 How to make it work — because juniors just don’t turn into seniors automatically.

Let’s dive in!

🏋️‍♂️ Juniors are indeed required to do more now

Let’s start by acknowledging the obvious: all engineers, not just junior ones, are required to do more now.

More of what? For junior engineers, the job looks qualitatively very different, and requires a lot of things from them *earlier* in their careers than it used to.

Think of:

• Code reviews — because of AI, junior engineers need now to review code from the get-go. Which in turn requires more... 👇

• Critical thinking — engineers need to constantly question the why and how provided by AI.

• Systems thinking — people are given bigger pieces of work from the start, which requires them to employ non-obvious design chops.

This is what many people see and makes them say: “yeah, junior engineers are screwed”.

I don’t think that’s the case, because there’s more to junior engineers than coding 👇

⚖️ Junior vs senior engineers

Anyone who has worked for some time in teams with mixed levels of expertise knows that the frontier, or boundaries, between a junior and a senior engineer is not clear-cut. It’s jagged.

Engineers do not grow linearly, simply becoming more capable over time. As humans, we also lose things over time. In my experience, there are things at which senior engineers are, on average, worse than junior engineers.

Many senior engineers are, vs junior engineers:

• More resistant to change

• More biased towards doing things the “old way” (tech choices, processes, you name it)

• Less energetic and hard-working

• Less willing to do the boring but necessary work that exists in all teams

Conversely, junior engineers may lack part of what is needed to steer AI towards quality and safety, but are often better at using it as a whole. They have no bias and adapt faster because, simply put, they have less to unlearn.

They have an easier time keeping their intuition up to date about how to use agents, orchestrate them, and create autonomous loops. Are these loops designed for quality and sustainability? Probably not! But, on the contrary, I know many 15-years-of-exp developers who simply refuse to build loops at all, because they want to retain control over every single LOC, which is wrong just as well.

That’s all to say that the comparison between juniors and seniors is complicated, and is wildly dependent on individuals.

Furthermore, so far we have only talked about production — the things that engineers actually make. But that’s only the immediate, first-order output of your team.

Team success is also driven by processes, cost, hiring & retention, individuals’ growth, and all kinds of system-level factors that are often neglected in this conversation.

What is your team going to look like one year from now? What about two years? How does that change based on the level of seniority mix you design your team for? I know companies that are more or less intentionally refusing to plan for longer than a quarter, because of AI uncertainty and all. But I don’t think that can be an excuse. As Eisenhower said: “Plans are useless, but planning is indispensable”.

So let’s try to loop all of this in 👇

🔀 Second-order effects of mixing seniority

Out of the various parts of your team life that are “not coding”, there are three that are particularly relevant when it comes to seniority levels, and it’s process, hiring, and growth.

1) Process

In my experience, the teams that are best at designing and enforcing good dev process are those with a healthy mix of seniority. In fact, both extremes are often bad:

• Junior-heavy teams — often would love good process, but don’t know what it looks like.

• Senior-heavy teams — know what good process looks like, but they can bridge gaps with individual experience and knowledge, so have less incentive to make things explicit and robust.

Mixed, diverse teams have both the senior folks who can design process, and the junior ones to benefit.

Needless to say, process, guardrails, devex, and all that jazz today is 10x more important than in the past, because that’s also how you scale AI work (the “harness”!).

2) Hiring

Senior engineers are hard to find and hire: you are competing for a limited pool of talent, and the pipeline is long and expensive. No way around it.

Conversely, junior engineers come from predictable, controllable hiring channels, like universities, bootcamps, and the likes. They are both cheaper and faster to hire.

3) Growth

Junior engineers can grow into the specific mix of duties and skills that your company needs, often compensating for the lack of experience with this special fit that is hard to replicate by hiring a senior. Even worse, a senior engineer who is already invested in a set of technologies and practices may have little interest in steering towards how your team does things.

Junior engineers are also easier to keep engaged, growing, and happy for a long time, simply because the bar for work that makes them grow is lower than for a senior. In any company there is a ceiling to what an engineer can learn, and senior folks just leave when they stop growing. In a healthy mixed team, senior departures are compensated by juniors who have risen through the ranks, and eventually replaced the former.

🌱 How to Make It Work

So, as Martin Fowler put it on the podcast, one of the most important qualities of junior engineers is to eventually turn into senior engineers. That said, this doesn’t happen automatically.

While there exists, indeed, a dream scenario in which junior engineers grow, become senior, and *rotate* your headcount to compensate other senior departures, in circle-of-life fashion, there is also a nightmarish scenario in which juniors are thrown in the trenches, abuse AI in ways they don’t understand, nobody checks on them, and the product and tech eventually goes to shit.

When this cycle breaks, it’s because junior engineers don’t have enough feedback loop to 1) ensure their work is high quality, and 2) learn and grow from doing it.

The way to create this feedback loop, to me, looks like two-fold:

• Invest in an amazing harness — create guardrails, rules, gates, and encode everything that can ensure quality automatically. This benefits just about everyone: senior engineers, AI, and junior engineers who can learn from those same rules.

• Pair juniors with seniors — let young folks experiment and work fast, but pair them with seniors to provide judgment and systems thinking. It’s still early days for this and everyone needs to find their own formula, but e.g. I loved Rick Clegg’s talk about what they do at Wise about it.

📚 Resources

I got plenty of resources about this if you want to deep-dive more:

• Scaling Juniors in the AI Era — the aforementioned talk by Rick Clegg from Wise about using automate guardrails to let junior engineers ship faster with AI.

• You Don’t Hire Juniors to Do Menial Chores — great piece by Frederick Van Brabant about how juniors help innovation: they bring fresh takes to many things, and stress-test your assumptions because they have not yet learned all your bad habits.

• Diversity, AI, and Junior Engineers — my interview with the awesome Meri Williams, where we talked a lot about growing engineers.

• In Praise of Normal Engineers — the incredible article that Charity Majors wrote for Refactoring, where she argues we should hire the “right” people instead of the “best” ones, and invest in 10x teams, instead of 10x engineers.

📌 Bottom line

And that’s it for today! Here are the main takeaways:

• ⚖️ The junior vs senior frontier is jagged, not linear — engineers don’t simply get better at everything over time. Seniors gain experience but often become more resistant to change and harder to keep engaged, while juniors adapt faster, have less to unlearn, and are often better at embracing AI workflows.

• 🔄 Mixed-seniority teams build the best processes — senior-heavy teams have less incentive to make knowledge explicit and systematic, while junior-heavy teams don’t know what good looks like. You need both. Also, robust, explicit process is exactly what scales AI work.

• 💰 Junior hiring is cheaper, faster, and more sustainable — instead of competing for a scarce pool of senior talent, you can hire juniors from predictable channels and grow them into the specific shape your company needs, creating a circle-of-life rotation that compensates senior departures.

• 🛡️ Invest in the harness, not just the horse — the way to make junior engineers thrive is to build amazing guardrails (automated quality gates, rules, standards) and pair them with seniors who provide judgment and systems thinking.

• 🔮 Refusing to hire juniors is a bet against your own future — if you only hire senior engineers today, you are optimizing for short-term output while starving the pipeline that will sustain your team for years to come.

See you next week!

Sincerely 👋
Luca

Once a month I publish an article about how I develop Tolaria, including an overall recap plus the latest updates, and some useful resources.

I consider part of my work (combined between Tolaria & Refactoring) to always try the latest and greatest, and work at the frontier of what’s possible, so you will only get thoughts that come from real usage and experiments.

Also, this is the first month since we launched the Tolaria Alliance, which has been a huge success so far! This is what allows Tolaria to stay free and open source, and this series (and the whole development of Tolaria) is made possible by the great tools I use everyday, which are:

• CodeScene — to guarantee great code health across the codebase.

• Codacy — to guarantee code quality and security.

• Unblocked — to help agents (and myself) fetch information across the codebase, ADRs, Github issues, and commit history.

• CircleCI — to allow fast and scalable local validation, and remote CI (migrated this month!)

That said, here is the agenda for today:

• 🔄 Workflow recap — for those who missed the previous episodes.

• 💧 Tolaria updates — what happened on the product side.

• 🔀 Forking open source — and the future of it

• 🚏 Creating custom gates — to give agents stricter constraints.

• 🤖 On using GPT 5.6 — and the latest models

Let’s dive in!

🔄 Workflow recap

First of all, if you missed the previous editions, here are some pointers:

• Product management — how I do traffic control between issues, PRs, and product requests, and orchestrate the overall product backlog.

• AI Coding — my own approach to scaling coding with agents, via guides, gates, and guards. Mostly remained unchanged from last month.

• Tools I use — a deeper dive into how I use the tools from the alliance, and others, too.

• ADRs, and more — in the initial workflow article I discussed how I do docs, which has scaled nicely so far.

Now on to the new stuff, but first... product updates. Because what is my workflow worth if you don’t see what I shipped with it?!

💧 Tolaria updates

This month Tolaria has followed a bit of a barbell strategy, where the two extremes are:

• 🔨 Basics — hardening performance and quality of life features for the editor, which remains the most crucial experience to nail.

• 🌚 Moonshots — trying (possibly overly) ambitious ideas, and see what sticks.

I will talk more in detail later about performance, because I have thought a lot not only on what to do about it, but also how to create a mini workflow so that it doesn’t degrade over time.

1) Basics 🔨

Basics include small features like block selection and navigation (a-la Notion), and the ability to collapse any heading and list item (a-la Bear). I constantly “borrow” features from other editors and note apps I love, but at least I credit them 😄

Of course, you will also find a long tail of more improvements, like being able to open vaults in separate windows, more MCP tools, more granular controls for AI agents, and just a lot of stuff!

2) Moonshots 🌚

Talking of moonshots, you can now create HTML blocks inside Tolaria.

This wouldn’t be that ambitious, if not for the fact that you can also reference properties from any note inside the HTML, and use a simple set of formulas to render lists, format values, and more.

This builds on the same system that allows spreadsheets to reference note properties, which was working well, so I said why not?! It plants the seeds for making Tolaria a platform where you can build mini apps that take information in real time from your notes.

It’s very cool if you ask me, and I am eager to see what you will build with it!

As I anticipated, though, what I am the proudest of is our performance work, which deserves a separate chapter 👇

⚡ Performance & forking open source

Read more

When I write about AI coding, you can typically find three types of articles:

1. Commentary on recent research — as we did several times recently.

2. My own experiments — these days, mostly about building Tolaria.

3. Case studies — about how other teams work.

The third type is the hardest to write. There are very few companies that accept to put themselves out there and talk about practices, not just tools or tokens. That is why I was happy when I met Rahul and the team at TRM Labs, and they agreed to share how they are redesigning their product development workflow.

For context, over the last few months, I have argued that AI is changing the cost structure of development. So, since coding is now cheaper, we need to find a way to make everything else cheaper too.

TRM reached the same conclusion and did something interesting: they rebuilt their shipping workflow and encoded it into a custom internal harness called Cortex, which they are now open-sourcing.

Today we’ll explore how they have been thinking about it. So here is the agenda:

• 🏁 Inner loop vs outer loop — a useful mental model to translate faster coding into actual faster delivery.

• 🔀 From handoffs to outcomes — how TRM redesigned its product workflow around the work rather than the roles.

• 🧰 Cortex as a harness — how reviewable artifacts, deterministic gates, and repository context make the workflow reliable.

• 🧪 Starting small — how TRM moved from a greenfield experiment to a regulated production system.

• ✅ Healthy code and healthy people — why increasing automation doesn’t mean removing human judgment.

Let’s dive in!

I want to thank Rahul and the team at TRM Labs for partnering on this piece. You can learn more about their work below:

Learn more about TRM Labs

🏁 Inner loop vs Outer loop

Most AI coding tools optimize what we call the inner loop: you describe a feature, watch the agent write the code, and get something working a few minutes later. This is where AI has delivered the most visible improvements, but it’s just a small part of how software gets shipped.

Other than the inner loop, there is an outer loop, that covers the broader cycle: deciding what is worth doing, shaping and reviewing the solution, releasing it, and learning from production.

As of today, it’s been obvious how AI can help with the inner loop, but much less so with the outer loop. And if you don’t do both, constraints move to other parts of the workflow, like:

• 🔍 Reviews — agents create more PRs than people can reasonably inspect.

• 📋 Shaping product — the team can build faster than it can decide what good work looks like.

• 🎯 Customer signal — shipping the wrong thing faster is still waste.

At a small scale, this is the same acceleration whiplash I have experienced with Tolaria. Starting work is cheap, but my ability to review it, decide what is good enough, and create the next piece of work does not scale at the same rate.

To fix this, the TRM team stopped treating engineering speed as the goal and started looking at end-to-end throughput instead 👇

🔀 From handoffs to outcomes

Like most companies, TRM had a product shipping framework. This can be more or less formalized, but chances are your team has a shared language for how an idea moves from customer feedback to production.

At TRM, such a framework had nine stages and was mostly organized around roles. A Product Owner prepared the spec, a Technical Product Manager helped translate it; a Technical Anchor owned the implementation, and various artifacts moved from one person to another.

The process was designed around the assumption that every artifact had to be created by one specialist and handed to the next.

AI weakens that assumption. For example:

• A PM can now explore technical feasibility and create a working prototype.

• Or, on the other end, an engineer can investigate the customer context and draft a product spec.

Does this mean the intermediate artifacts disappear? I don’t think so. If anything, specs, plans, or decision records can become even more important when agents do the implementation, to trace execution and record history. But it’s likely that individual artifacts no longer need to belong *exclusively* to an individual role.

So, TRM rebuilt the framework around six outcomes, organized into three groups:

1. 🔭 Sense and Decide — collect signals, understand the problem, and decide whether it is worth solving.

2. ✏️ Shape and Make — turn the problem into a reviewable direction, then build it.

3. 📣 Communicate and Learn — release the change, observe its impact, and feed what was learned into the next cycle.

These are broad areas that change the job of the people involved:

• 🎯 PMs and EMs expand their scope — they can test feasibility and prototype ideas without waiting for engineering capacity.

• 🧑‍💻 Engineers get closer to the problem — they can retrieve customer signal, shape solutions, and work across more of the stack.

• 🎨 Specialists turn judgment into platforms — designers, security engineers, and other experts create rules and constraints that make good decisions easier for everyone else.

I really care about the last point, and I think it’s how specialist work is evolving today. Deep specialists are more and more an overkill for regular production tasks — they have a bigger impact when they bottle their taste into design systems, components, security policies, workflows, and platform in general.

So TRM laid down the process and then created a harness around it 👇

Read more

One of the things I like the most about the DX team is that they run an incredible amount of research. They run surveys all year round, and keep a pulse of where the industry is going around several topics — especially AI and developer experience.

They recently released the Q2 2026 AI impact report, the latest in a quarterly series tracking how AI is reshaping engineering teams. I regularly check out these reports, and one thing I noticed is how they gradually moved from discussing adoption to discussing impact.

The feeling is that AI is everywhere now, and the main challenge for engineering leaders is not to spearhead adoption anymore, but rather justify the exponentially-increasing AI budgets, by demonstrating what AI is actually delivering.

I got preview access to the report, and today we will comment on a few key highlights.

So here is the agenda:

• 📊 Speed is real but uneven — what 500+ teams reveal about where AI gains concentrate, and who’s being left behind.

• 🧱 Orgs are not multiplying AI output — developer experience is declining even as velocity climbs.

• 🔬 Code is easier to change but harder to trust — a surprising divergence between maintainability and confidence.

• 🚶‍♂️‍➡️ Spend is outrunning returns — AI budgets are up 28x, but innovation ratio is flat.

• 🧭 What this means for engineering leaders — how to shift from tool adoption to system optimization.

Let’s dive in!

I want to thank Justin and the DX team for partnering on this! I am a big fan of their work and you should check out the full report here.

Download the full report

📊 Speed is real but uneven

Across the 500+ respondents, over 50% of the code is now generated by AI. This metric has accelerated rapidly, increasing from 34% in Q1 2026.

Median weekly throughput rose 37% over four quarters (1.42 to 1.94 PRs/eng/week), and deployment frequency is up double digits across most segments. However, gains are concentrated among small organizations (less than 100 engineers) and tech-sector teams, pulling away from larger and traditional-industry teams, and the gap is widening.

This echoes what we have seen in other reports recently, from the Acceleration Whiplash, to the State of Software Delivery earlier this year.

The speed at which the tools keep improving makes gains compound for teams who invest into AI workflows, so the distribution of team productivity becomes a steeper and steeper power law, with the top percentiles pulling away from the pack.

🧱 Orgs are not multiplying AI output

DX measures developer experience with a proprietary index called DXI (we talked about it with Abi Noda), which, over the last four quarters, has dropped on average from 67 to 65.

Again this is not an even drop: AI is improving some aspects of the devex (docs quality, code maintainability, onboarding speed) while making others worse: larger PRs, slower reviews, less incremental delivery. In aggregate, the net effect is negative.

Median PR sizes have nearly doubled during the same period — and of course increases in PR size are an early proxy for technical debt, bugs, review friction, and all kinds of nasty stuff.

So, velocity metrics alone will tell you things are improving, but devex metrics will tell you that the system (and developers) are strained, and we are far from a sustainable, positive flywheel.

My personal feeling about this is that so far we have mostly tried to slap AI onto the existing steps of the dev process, while running them the same way we always have. This might bring incremental gains, and even work well for some of the steps, but it completely breaks others, like code reviews.

It’s obviously foolish to think that AI can make developers write code 3x faster (as it already does), while assuming we’ll need to keep reviewing every single LOC manually.

Read more

That’s because I write a lot about my AI workflows with Tolaria, but many people (rightfully) tell me that things are more complex on a real team.

So I invited the team at Augment to share how they transformed their own engineering org, redesigning their main dev workflows. It’s free for everyone and you can RSVP below!

Learn more and RSVP!

Hi there! A lot of people these days ask me what AI models I use for coding, which I usually explain in my monthly recaps.

Some people also ask me “why” I use one model vs another, and that’s a way more complicated question to answer. AI models are hard to evaluate, because there are several factors to consider, and because, despite what public benchmarks say, each team situation is unique.

So today let’s try to think from first principles about how you should choose what LLM to use for coding, factoring everything in. Also let’s try to find some durable angles, so that you can create a mental model for yourself that stays valid for more than a couple of weeks.

Here is the agenda for today:

• 🔺 Accuracy / Speed / Cost — the three dimensions of model selection. But they are messier than you might think.

• 📊 Public benchmarks are not enough — you can’t trust leaderboards, and how your codebase discipline sets your floor.

• 🧪 How to evaluate AI models — a maturity path from “just don’t” to building your own eval.

• 🔀 Model routing — not all tasks are equally hard, so stop paying frontier prices for all of them.

• 🏠 Self-hosting: almost never — cloud-hosted cheap models beat your own hardware, every time.

Let’s dive in

🔺 Model Selection 101

With some degree of simplification, today you have three macro choices:

1. Top frontier models — e.g. Fable 5 or GPT 5.6

2. Large open weights models, hosted in the cloud — e.g. GLM 5.2 on OpenRouter

3. Smaller open weights models, self-hosted — e.g. see DeepSeek 4 Flash via DwarfStar by Antirez

These choices are actually more nuanced than this, because e.g. within frontier models, you may tweak the level of reasoning, or intentionally pick a smaller model that is cheaper and faster, because you feel it is a better fit for your task.

In fact, when judging models, there are three dimensions to consider:

• 🔬 Accuracy — % of times the AI gets the thing right

• ⚡ Speed — tokens per second

• 💸 Cost — cost per 1M tokens (multiplied by tokens required)

To make things even messier, these dimensions are not orthogonal. For example:

• A model with higher accuracy may translate into fewer round trips, which may translate into fewer tokens being used.

• With many models you can reduce the amount of reasoning to improve speed while reducing accuracy.

So, in most cases, performance is tricky to evaluate. Top frontier models guarantee max accuracy, but do you really need it?

Most people have anecdotal experience of small tasks for which fast + cheap models delivered the same level of accuracy. But how do you recognize them?

Also, it’s trickier than that, because even for bigger tasks you might find that a faster model, while less accurate, iterates faster over mistakes, leading to a lower cost overall. That’s what Jamie Turner, founder at Convex, was already saying last year:

We optimize for fast feedback loops over perfect output. It’s better to get 80% correct code in 2 seconds than 95% correct code in 2 minutes.

Jamie made the case for optimizing for a quick feedback loop, so that developers don’t lose their train of thoughts while waiting for slow responses, even at the expense of a few more errors.

This is even more compelling when you factor in that with the current crop of LLMs, accuracy and cost are not in a linear relationship: a model that is 80% as accurate as the top frontier one might cost 1/10th of it.

Two good examples are GLM 5.2 and Grok 4.5. They both score pretty close to the top OpenAI and Anthropic models, while costing a small fraction of them.

Looking at these numbers is a good way to start some kind of quantitative reasoning around models, but I don’t think it’s enough 👇

📊 Public benchmarks are not enough

I have grown skeptical of public benchmarks, for two reasons:

Read more

Every week I write an article to 170K+ engineers about how make good software together, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Subscribe now

I happen to know many startups who develop B2B products for large companies. I worked in one, invested in another one, and have friends who work in others.

An evergreen problem about these products is organizing work in a way that successfully takes into account:

1. Roadmap / long-term product strategy

2. Impromptu requests from key customers

This is tricky from all points of view: business, tech, and team organization. I have thoughts about this, so let’s start from first principles. Really the very basics.

We build tech to solve problems to customers, that pay us in return for it. At any given time we can have many of such customers. Based on this, the type the work we can do to solve such problems lays on a spectrum from bespoke to one-size-fits-all:

• 100% bespoke — is consultancy work. You just solve the problem, IP is of the client, zero reuse.

• 100% one-size-fits-all — is product work. You develop features that can be used by all (or many of) the customers of your product.

These types of work are very different but, fortunately, in most real-life situations it’s obvious where your work should land on the spectrum.

First of all, a lot of the ambiguity is cleared up upfront, by deciding the type of business you want to build. Knowing that you want to build an agency vs a B2B SaaS takes a lot of cards off the table:

• If you run an agency, the problems you solve change all the time, and there is most often not a clear path to building reusable pieces.

• Conversely, if you ran a B2B SaaS with e.g. thousands of customers, any of these customers might want something custom, but it’s obvious that it’s not worth to build it just for them.

About the latter, though, what if these customers are not thousands, but hundreds — or maybe just tens — and each of them is very valuable to you?

That’s where things get messy. Welcome to enterprise B2B SaaS.

So here is the agenda for today:

• ⚖️ Customer work vs product work — why enterprise B2B creates a unique tension between different types of work, and how you should think about them.

• ⁉️ Is it worth to do bespoke customer work? — the right questions to ask yourself before committing to custom work for a single customer.

• 🎽 How to design team structure — use dedicated roles like solution engineers of FDEs to shield your roadmap from customer requests.

• 📏 How to design tech strategy — empower solution engineers with great platform, so they move fast and build things close to product shape.

• 🔀 How to converge — treat customer work as validated product input, and create avenues to merge it back over time.

Let’s dive in!

⚖️ Customer work vs product work

If a customer of yours is paying you $100K for a yearly contract, instead of e.g. $2K, and you have, say, only 12 of those customers, all of a sudden their requests, however absurd, look... different.

This customer has leverage — and you have probably spent a lot to acquire them, so it can make complete business sense to do something specific to make them (and only them) happy.

We said this is a spectrum, but for the sake of simplicity let’s call this type of work “customer work“, as opposed to more general “product work“, which is done in the service of everyone.

The problem with customer work vs product work is that they have completely different shapes, when it comes to fundamental factors like:

• When and how such work spawns

• How urgent it is

• How big it is

• How it fits your overall strategy

One of the goals of your standard product workflow is to control for these factors, in order to normalize them. So items you plan for are: comparable in size, planned in timely fashion, all fit your strategy, and so on.

Customer work spawns, by definition, from external forces, which makes all of the above out of your control. It also doesn’t land with the same level of discipline that you might put into your product process, so it’s work that is often: urgent, big, and unrelated to your plans.

This leads to questions:

• When is it worth to do these things?

• How should I design my company accordingly? Speaking of team, tech, and process?

Let’s start with the first one.

Read more

By now, developing Tolaria is a big chunk of my working time (about 40%, to be precise). I like this balance and I am happy I can regularly write articles about AI coding coming from my own experience, as opposed to pure research.

I also don’t want to end up writing only about that, and so far I have kept a schedule of about once a month. This feels like is a good cadence: it’s feel overwhelming for readers, and gives me time to produce actual updates to the workflow, as opposed to posting always the same things.

So, today I am covering a few workflow updates, but most of all I am introducing a new set of partnerships I am very proud of.

So let’s dive in!

💧 The State of Tolaria

First of all you may wonder: how is Tolaria doing? Pretty well, if you ask me.

From a growth perspective, it has now almost 18K stars on Github, 100K+ downloads, and thousands of daily active users.

From a product perspective, this month we delivered a ton of updates, including some massive ones, like the support for native spreadsheets.

You can now create and edit spreadsheets inside Tolaria with Excel-compatible formulas in a completely open and portable format, which is basically CSV with a frontmatter on top.

We also improved a lot of the editor experience, adding collapsible headings, block navigation, better spacing and typography, all while making everything faster than ever. If you haven’t tried it in a while, you definitely should!

I really enjoy developing (and using!) Tolaria, so the question recently has rather become: how do I make this work sustainable, while keeping everything free and open?

Enter our tech alliance!

🦸‍♂️ Creating our own Tech Alliance

The tools I use to develop Tolaria are no secret — you can figure out most of them by looking at the repo, the AGENTS file, hooks, and my own articles.

So, over the last month I reached out to the ones I use the most to figure out if we could work together to make the development of Tolaria more sustainable on my end via open source sponsorships, in return for me spreading the word about how I use such tools, and providing good feedback on how to improve them.

The result is an alliance that as of today includes four tools: CodeScene, CircleCI, Codacy, and Unblocked.

These partnerships allow Tolaria to stay free and open forever, and even give us the opportunity to accelerate by hiring a great product engineer (if you think you are a great fit, please reach out and say hi!).

So today I will tell you more about my workflow, which includes these tools — but first an ethical statement: I will only ally (and stay allied) with tools I personally use and believe are the best way to do what they do. As you will see these are non overlapping: each has its own job, so they really make for my tech stack. Over time we will also expand on this and create exclusive deals for Refactoring subscribers!

Before we talk about the tools, it’s worth refreshing how I think about controls for code written by AI. I have written about it in this recent piece 👇

In a nutshell, I steer AI output in three main ways:

• ↪️ Guides — instructions in the AGENTS file and skills. Not 100% reliable: the AI may or may not follow them.

• 🔄 Gates — deterministic checks that don’t let bad code move forward if some conditions are not met.

• ↩️ Guards — fallback procedures that typically run once a day to fix what goes through the cracks.

Out of these, the most important part is the gates, because they have the (deterministic) power to stop bad code, so the more I can express this way, the better. Most of the tools below are integrated this way.

So let’s go 👇

🩺 Code Health — with CodeScene

CodeScene probably needs no introduction because I have written about it many times here. I am a big fan of Adam Tornhill‘s work, which to me is about two big things:

• A proprietary algorithm to calculate code health, that considers 20+ factors.

• The “hotspot” approach, which looks at git history and suggests refactoring targets prioritizing files that are changed the most often.

I integrate CodeScene as a hard gate in local hooks: new code can’t be committed if it’s not a 10/10. For modifying old code, the AI needs to follow the boy scout rule: leave the code better than it found it. So it measures the code health before touching the file, and after, and the score needs to be the same or higher.

After any commit that improves the overall codebase health, the AI also increases the thresholds, to create a positive flywheel.

After four months working like this, now the code has perfect health, and the current threshold is literally 10/10!

🔒 Security and Quality — with Codacy

Codacy works on code quality too, but from a different angle: rather than scoring files, it surfaces individual issues.

Issues come with severity levels and belong to various categories, like security, performance, compatibility, code being error prone, and more.

Codacy has an MCP that I use to steer my Codex locally, and to implement an actual blocking gate before it pushes any code. All new code has to be issue-free, and when touching old code, the AI also needs to fix existing problems, other than making the business changes.

I am also working with the Codacy team on their new product Verity (you can join the beta for free here), that aims to steer agents’ work by creating a knowledge base of past decisions.

This is interesting to me because I do that with ADRs, and would love to create more reliable controls against code that violates them. Verity is promising about that, and should also track token efficiency and a bunch of process metrics that I am interested in improving over time.

✅ Validation — with CircleCI

A few months ago I made a change in how I run our test suite, creating local hooks with Husky so that AI agents can immediately see if controls fail, instead of waiting for the remote CI.

This was very effective at improving the agents’ work, at the expense of completely hogging my machine every time. Some parts of the test suite are particularly heavy (e.g. playwright), and running them in local means the whole thing takes time — about 15 mins — and parallelizing things is out of question, because resources are not enough. It’s tricky to run even just 2 worktrees at the same time: things sometimes literally crash.

I talked with Rob Zuber from CircleCI about this, and they implemented a great solution: local hooks that are run remotely, in what they call Chunk Sidecars.

Sidecars are preconfigured environments that run alongside your local workflow, and validate changes as they happen.

This allows to 1) free up your machine resources, and 2) make things faster by introducing real concurrency.

This way I have been able to reduce the suite run time from 15 to 4 mins, while also being able to spawn more worktrees safely. A massive win!

📖 Fetching knowledge — with Unblocked

Unblocked is a context engine: it takes information from several sources (e.g. Github, Notion, Slack, Datadog, ...) so you can ask questions about it.

I have known Dennis, Claire, and the team at Unblocked for a long time, but didn’t think of using it for Tolaria until just recently, because I thought that Unblocked would shine when you have many information sources, and we legitimately don’t have many.

I was wrong.

I plugged it about one month ago, connecting it to Github and Sentry. Sentry is useful to triangulate issues, but the Github connection would basically be worth by itself, because it indexes the code, the ADRs, and all the history of changes.

I have been asking questions about how we do this and that and checking side by side with Codex (which instead just greps and fetches things on the go) and the difference in speed and accuracy is just obvious.

Even more importantly, Codex itself uses Unblocked via the MCP to understand past decisions and fetch relevant ADRs.

Big props to the Unblocked guys because this was an easy win and largely plug-and-play!

🔭 What’s next

Now that Tolaria has sustainable funding, I am going to invest even more on it. Again, I am exploring hiring a strong product engineer, so if you think you can be a good fit, feel free to reach out and say hi!

As for future work, the most important thing ahead is the mobile version.

I already have a working prototype for iPad, but there are still a lot of rough edges. Also, the iPad version is the easy part: for smartphones we need to completely reinvent the UI — I have been working on it 💪

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

To figure out what’s really happening in software engineering, I usually do three things:

1. I try things myself — recently by working on Tolaria.

2. I speak with people who know better — on the podcast and in the community.

3. I go through relevant research — to go big picture and get a grasp of the state of the industry.

Good research is hard to find, but a few weeks ago I was sent a copy of this report by the guys at Faros (thank you for that 🙏), which was very interesting for two reasons:

• Quantitatively — it’s one of the largest reports I have ever seen about AI coding: it surveyed 22K+ developers across 4K+ teams.

• Qualitatively — it’s very thorough. It doesn’t stop at measuring activity, but tries to understand the downstream impact of AI on all the stages of the SDLC.

It also paints an interesting trajectory when compared with other similar works from the past months, like the State of Software Delivery, which we covered just recently, and DORA’s State of AI Assisted Development from the end of last year.

So today I will report and comment on the main findings, trying to interpret them and connect the dots with the other things I have been observing lately.

Here is the agenda, with my main takeaways:

1. 🏁 Finishing work is hard — starting is now easy, and shipping is hard.

2. 🔍 Reviews are utterly broken — it’s now obvious that we need to do something about them.

3. 🔥 Poor quality is reaching prod (anyway) — production is suffering, big time.

4. 🪴 The way forward — some words of hope to close this on a high note!

Let’s dive in!

I want to thank the guys at Faros for giving me preview access to these results and partnering on this. If you want to download the full report, you can find it below 👇

Check out the full report

🏁 Finishing work is hard

Before we get to the first idea, there is an important preamble to be made.

We have said many times that AI is an amplifier, and that the *average* numbers of these reports don’t say a lot because they mix up the good teams that are getting a lot out of AI, with the average/bad ones that are not getting anything, or sometimes even negative results.

Now, Faros literally opens the report by saying that no — this is not the case anymore:

Across every downstream stage, the signal is the same: volume is up, quality is down, and the gap between the two is widening as adoption deepens. High-performing teams are experiencing the same downstream degradation as the median and average ones.

Words of hope! But what does it mean that volume is up and quality is down?

If we look at software dev as a pipeline, this means three things:

1. More work gets started, but

2. The amount of work that gets shipped is pretty much the same, and

3. The quality of such work is noticeably lower

Let’s go through all of this, starting with the most important point to me: starting work is now easier, but finishing it is harder than ever.

In particular, developers do more work indeed, by virtue of working on more things at the same time:

• +67% PRs touched / day

• +18% separate tasks

• +33% tasks completed, as measured by opening a final PR about them.

The problem is that such work doesn’t get to production just as fast. In fact, teams are noticeably slower at the last mile — shipping:

• +26% in-progress tasks stalled for 7+ days

• +14% work restarts per developer (tasks returning in progress after moving to another stage)

• -12% deployments per week

Qualitatively this is the same trend that both the State of Software Delivery and the latest DORA report found, but quantitatively worse. In fact, the numbers about coding activity and those about deployment frequency are respectively better and worse than previous reports, pointing at even more polarization.

One of the most visible results of this trend is lead time skyrocketing to a +480%, fueled by an avg +80% waiting time between each of the pipeline steps.

This is not surprising if we remember that:

So if WIP grows and throughput stays the same, lead time is bound to grow. But why does the throughput stay the same? Where’s the bottleneck?

Enter the elephant in the room: code reviews 👇

🔍 Reviews are completely broken

Read more

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Last week, Claude Code’s Boris Cherny got trending on X for saying this at the annual Anthropic conference:

I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops. And this is transition we’re going to see for the rest of the year

So, “my job is to write loops.”

Peter Steinberger (creator of OpenClaw) and several others picked up on it and agreed 👇

But before you roll your eyes and think here it goes another fad, new buzzwords, loop engineering, and so on, I’ll go out and say that I like this direction.

Loop engineering looks strictly better than prompt engineering because it forces you into systems thinking, as opposed to just focusing on what’s needed to deliver the current task. A loop is supposed to run indefinitely, so the focus shifts to reliability, sustainability, and how to make sure things stay good — vs diverge and go to shit.

But how do you ensure that?

I wrote about this several times lately, including last week, where I covered how I steer AI work with the 3Gs: guides, gates, and guards. These are not super new concepts: they build on what other smart people are doing, and they are my attempt to contribute to this global conversation.

But a problem I find in this conversation (which I am guilty of) is that it largely focuses on the tech side of things, while treating other disciplines as second-class citizens.

Namely, product.

When you hear people saying that software dev is now a factory, and the bottleneck is your product taste, review, validation, etc, what they are implying is that they have no idea about how to scale those things. In the AI race, product is behind engineering — big time!

The last time we discussed this on Refactoring has been when we published The State of Product Development, where we saw that only 9% of teams used AI to help product with specs (yay), vs 90%+ for coding. Since then I released Tolaria, started doing a lot of product dev myself, and tried a lot of different solutions and workflows to scale myself properly, both in tech and product.

So today I want to focus on product, taking pages from what works for coding, and exploring how we can make the same progress there.

To discuss this, I am also bringing in again Doug Peete from Atono, who has a privileged vantage point by working with thousands of product teams, and is working actively to fix this. We also talked a lot about AI & product in our recent podcast interview.

So here is the agenda:

• ⚔️ Product is harder than coding — an uncomfortable take we need to come to terms with.

• 📋 Towards Product ADRs — building on a successful tech practice.

• 📖 Glossary — a possible missing abstraction in how we develop product.

• 🔄 Product process — how to put everything together and work better with AI.

Let’s dive in!

Disclaimer: I am a fan of what Atono is building and I am grateful to have it as a partner on this piece. You should check it out!

Learn more about Atono

However, I will only write my unbiased opinion about the practices and tools covered, Atono included.

⚔️ Why product is harder than coding

Product is harder than coding, at least conceptually. I know this take will get many engineers angry, but think about it. For a product choice to be good, there is a lot to be taken into account:

• 🔭 Strategy — do customers want this? Do the right customers want this? How is this discoverable? Is this making things unnecessarily complex? How does it fit our business strategy?

• 🔬 Tactics — where do we put this? what’s the right UX? does it need a shortcut? should this live in the right-click menu? ...

A lot of these choices depend on aspects that we are not good at codifying into hard rules. It’s what we call judgment and taste.

Software engineering, on the other hand, is structurally easier, for two reasons:

• It’s downstream of product direction, so it has a narrower design space.

• Its deterministic nature allows it to be tested for correctness and non-functional qualities (performance, cohesion/coupling, complexity) in a more reliable way than product.

As a result, gates for coding agents are effective at enforcing good code, even when they have relatively little context about product. Static analysis, TDD, code health tooling, are all devices that help AI agents write good enough code—granted, not the code that the most talented engineer on earth would write—but still passable for many situations.

So how do we make product a bit more like coding? To answer this question, I will take a page from the least deterministic part of my coding harness: ADRs.

🏗️ ADRs

As I have written many times, I instruct the AI to create ADRs to store meaningful tech decisions. Each ADR has to include why that decision was made, what options were considered (and eventually discarded), and take care of superseding old ADRs about the same thing.

ADRs have been, so far, surprisingly successful. As I am writing this, Tolaria has 137 ADRs, and I see the AI using them all the time. It refers to them in specs, makes decisions that stay true to what exists, and reliably supersedes what’s not relevant anymore.

So, as of today, for most features I am comfortable not giving a lot of (tech) design input, because I know AI will pick it up from past decisions. I still review new ADRs, but they are 95% good — I do it more for my personal curiosity than because it’s a good use of my time.

The ADR workflow is, interestingly, completely non-deterministic. It’s a way to inject good judgment into the AI not by creating rules, but by repeatedly showing how we have done things in the past.

This is why I am hopeful about doing something similar to product 👇

📋 Towards Product ADRs

If ADRs are for tech work, what’s the equivalent for product? Mimicking ADRs, a Product Decision Record might record:

• 👁️ Intent — what the user needs to accomplish.

• 🎨 Design — how we decided to do it.

• ⚖️ Tradeoffs — alternatives that have been discarded and why.

If we roughly agree on this, the next question would be: what does actually deserve a PDR? To me, it’s any product decision we want to remember in case we meet a similar problem in the future. Anything genuinely new that we changed/added to the product, as opposed to reusing a proven pattern that we already understand well.

E.g. In Tolaria, I wouldn’t want to write a PDR to remember that we added “copy file link” as a right-click action to the current note — because there isn’t any novelty or interesting decision being made there.

Do PDRs map squarely to well-known product artifacts, like PRDs, Epics, or Stories? I don’t know about that either. Those other devices primarily exist to communicate what needs to be done. It’s great when they include more about the why, but it’s not clear to me whether e.g. a full PRD or user story should be stored as-is and work well as a PDR. Maybe!

The other reason why I tend to believe PDRs deserve a life on their own is that relevant decisions are largely independent of the size of the work. There might be a large Epic (e.g. integrating a new AI agent assistant into Tolaria) that doesn’t bring meaningful new product direction, and a small story that instead introduces new a interesting pattern.

Doug is experimenting with PDRs at Atono, calling them design decisions and attaching them directly to the stories they relate to — not as a separate doc for now. This doesn’t resolve the question of where a PDR lives when the decision is bigger than any single story, but looks good on the smaller end of the spectrum: when the decision is scoped to one piece of work, attaching it directly might hold up well in practice.

So, in general, even if there is a lot that we don’t know about their shape, we can agree that it’s valuable to record product decisions, in a similar way to what we do with architecture ones. And if we do, we should also agree that this is not enough 👇

📖 Product Glossary

Other than ADRs, I maintain other tech docs in the Tolaria repo, which are called ARCHITECTURE.md and ABSTRACTIONS.md. Without getting into too much detail, these are recap docs, that summarize the current state of our tech.

These are necessary, like views in a database, to avoid the AI to navigate eventually hundreds of ADRs (between those active and superseded) every time, just to reconstruct what exists. The recap docs give the AI the 10,000ft view, while individual ADRs are used to zoom into specific aspects.

What should this look like for product? Doug believes the right concept here is that of a Glossary.

The Glossary should list your main product abstractions: why they exist, what they are for, and how they are used. It maps your domain language, which in turn is shaped by your product surface.

An example from Tolaria may include concepts like:

• The Sidebar — which gives users ways to filter notes in their workspace

• The Note List — to make users navigate the current selection of notes

• The Breadcrumb Bar — to display the most important actions a user can do over the current note.

But also concepts that don’t map 1:1 to single interface elements, like the Git integration, or the Note organization workflow (capture / organize / archive).

It’s obvious these are not PDR candidates: they are long-lived abstractions that morph over time, and need a description that evolves with them. So, if anything, they are derived from a sum of product decisions.

Doug believes a shared glossary is the cornerstone that enables good AI-assisted stories and PRDs — because now the AI can ground them in your vocabulary, your past choices, and what exists. And he has data to back this up.

By talking with some of the teams we surveyed, which report abysmal low AI adoption for product specs (9%), it turns out a major cause is the amount of rework needed by generic AI specs. Making them good is just too much work, so most PMs keep writing specs manually. Doug and Atono have been testing glossary-backed AI stories internally and with customers, and they are seeing rework dropping from 60% to 20%.

(worth noting that 60% rework, as a baseline, is a ton. What if coding agents got things wrong 6 times out of 10? We would probably give up on them, which is what many PMs do with AI right now)

So the overall goal is to build foundational product knowledge: a map of what things mean in this specific product, which is not the same thing as a list of features.

So let’s say we have all of this in place, what does a new product process look like?

🔄 Product process

Any product work starts with capturing some intent — what the user needs to accomplish, how it maps to the product strategy, how we know this is successful, and so on.

This is 100% human (for now!) and is more about the why than the what.

Our input on the what can progressively shrink the more we help the AI figure out good (draft?) specs that respect the current product surface (glossary + PDRs).

Then, based on the feature, the maturity level of your process, and how greedy vs safe you want it to be, you may either:

• Have the AI do a first pass, so that your judgement is informed by an actual prototype, or

• Stop and tweak the draft spec before the AI goes forward.

Then you review and iterate on implementation as long as needed, and finally ship, possibly including new PDRs and Glossary updates.

Over the next weeks I will try to incorporate some of this into the Tolaria workflow, possibly retrofitting some PDRs and glossary concepts from the past. Will let you know how it works!

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Refactoring is read every week by 170,000+ engineers and managers from all over the world!

Hey! When I launched Tolaria I promised I would publish ~monthly updates to my AI coding workflow. The last one was in April, so I am late!

In May I also published how I run Tolaria as a project, but this was more about general orchestration, so I wanted to post an update that is more specific to coding.

I will start by saying that things are going... well.

Tolaria by now has a few thousands daily users, most whom are engineers. These are quite eager to report bugs, submit PRs, and suggest improvements on social media, Github discussions, email, and more — so keeping up with everything is quite a lot of work.

Still, I am happy with where we stand. As I write these, we got:

• 6 open issues — vs 417 closed.

• 14 open PRs — vs 306 closed.

• 1 day — average bug fix time.

• 99.1% crash-free rate — as measured by Sentry.

• ~28 commits / day — on average.

• 2 hours a day — I work on Tolaria, give or take.

I released Tolaria on April 22nd, so all of this happened in little more than a month, which is crazy when you think about it. From the day of the release, I added about ~1000 commits, and the codebase has grown a bit, but not massively: right now it’s 150K LOC, plus ~100K LOC of tests.

Most importantly, I don’t feel my velocity has decreased.

If anything, I am probably producing more output per unit of input than two months ago, so the effectiveness feels higher. Code quality also is higher, we are not drowning in regressions, and the rate at which bugs are reported feels stable.

So today I will cover the tweaks I made to my AI coding over the last ~2 months. To catch up with the full process, you can also go back to the previous articles here:

Here is the agenda for today:

1. 🚥 Guides, Gates, and Guards — my mental model for the various types of AI instructions. The core of the article.

2. 🤖 From Claude to Codex — I moved to Codex and (for now) I am not going back.

3. 💸 How much I am spending — monthly cost is now down >90%

4. 🔭 What’s next / missing — what I am trying to improve right now

Let’s dive in!

🚥 Guides, Gates and Guards

When it comes to the dev process, I think about the types of inputs that I can give to AI in three steps:

1. ↪️ Guides — rules and explainers of how to do things.

2. 🔄 Gates — deterministic checks that block bad things and force the AI to steer its output.

3. ↩️ Guards — fallback procedures to improve what falls through the cracks.

These steps are also somewhat sequential:

• Guides are the basic context that the AI uses to start the work

• Gates get into play to steer the work while it’s in progress

• Guards are the last line of defense against enshittification.

Let’s look at all of them:

1) Guides ↪️

We can as well call them rules, but then we’d lose the 3G’s memorability!

These days you write guides for AI agents in two main ways:

• AGENTS.md / CLAUDE.md — the core instructions that the agent always loads.

• Skills — specific instructions to do particular tasks. A skill gets used only when the task requires it.

It’s worth noting that the boundaries between the two surfaces are not very clear. It’s often dubious whether you should create a separate skill or just slam everything into the AGENTS.md, and even benchmarks are inconclusive about the effectiveness of the various strategies.

I believe that’s because, at their core, they are the same thing: instructions to the agent.

My dev process is simple enough that I can afford to keep everything into the AGENTS.md, and not use any specific skill. I have tried a few and never felt things got noticeably better, so I opted for keeping things simple.

You can inspect the actual file — it’s not perfect, mind you, but gives you a more precise idea.

In my AGENTS.md, the most important instructions are about:

• TDD — the agents has to write tests first and do the classic red → green → refactor.

• Boy scout rule — leave the code in a better shape than you found it. It should also measure the before/after quantitatively with CodeScene and Codacy.

• UI — always use shadcn/ui components when possible, and inspect our design language before implementing new UI (we got basic tokens for colors, typography, spacing, etc).

• Localization — extract and translate all the new strings in the supported languages. I use the Lara CLI for this.

Read more

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Refactoring is read every week by 170,000+ engineers and managers from all over the world!

Two weeks ago we came together in the Refactoring Community for our very first monthly AI Club session!

More than 30 people joined, and 5 volunteered to share recent learnings about using AI at work. Then everyone got the opportunity to ask questions and build on their ideas.

In this edition I will post a recap of the awesome ideas that were shared!

1. 🚜 The “combine harvester” pattern for long AI tasks

2. 🌙 Overnight procedures that catch what rules can’t enforce

3. 📓 A daily rhythm for noticing what we’re learning

4. 🎫 Using AI to make sense of messy stakeholder tickets

5. 🔀 Staged automation of a complex upstream merge

Let’s dive in!

The AI Club is run monthly and facilitated by professional coaches. It is exclusive for paid members of Refactoring, who get access to our private community.

Get the full version of Refactoring to join the next AI Club, on Jun 5th!

Subscribe now

1) 🚜 The combine harvester pattern for long AI tasks

Matej Vitasek, CTO, shared how he has been successful at having agents run through long, multi-hour tasks, by having them maintain their state in a markdown file that gets updated as the task goes on.

The markdown file holds:

• The instructions

• The progress so far

• What should happen next

As the task evolves, the file evolves too. You can also make the agent stop after a batch of work, reflect on what could have been done better, and update the process before continuing.

The benefit, as Matej described it, is that the work doesn’t have to happen in one sitting.

Anyone can pick the task back up at a later time and the agent can resume from the markdown file rather than starting over or losing context. For tasks that are too big to fit in a single session — or that you want to step away from and come back to — the markdown becomes a simple working memory.

It’s a small, low-tech pattern, but it works and it’s portable across multiple models and agents.

2) 🌙 Overnight procedures to catch what rules can’t enforce

I personally shared something that is working well for me and I don’t see talked about often: running daily, often overnight, procedures that look back at what happened during the day and try to catch judgment-based things that wouldn’t have been picked up by rules in the moment.

I call these guards.

My starting point is—I believe—the same as everyone: I write rules in the AGENTS.md / CLAUDE.md file, and try to enforce some things via CI and hooks: test coverage, static analysis, code health, and so on.

But there are things that are hard to gate:

• Did this change need an architecture decision record?

• Has an opportunity to refactor been missed?

• Is performance drifting over time?

These are judgment calls, and agents will sometimes ignore rules about them, or simply make mistakes.

So I have set up various procedures that run once a day, each focused on a specific concern. Like, in the cases above:

Read more