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.

I remember when an engineer friend of mine told me:

The pace of change is just unsustainable. Every week we are supposed to change the way we work.

But this was circa 2018, and he was talking about JS frameworks. Feel old yet? These were, apparently, the good old times!

Jokes aside, AI feels different from a new JS framework, and many engineers I talk to are struggling with it in a deeper way.

When our work is challenged, our identity is challenged, too. This is especially true for knowledge workers, and for engineers in particular: we find the output of our work to be an act of creation, and so we take pride in it. It’s easier for us to identify with what we do than it is for people who do less creative jobs, which means that changing how we work has very direct psychological consequences.

I know this because of my own weird journey. I studied CS, started a PhD, dropped out to start a startup, sold it, became director of a larger company, and today I run Refactoring and Tolaria: respectively a newsletter and an open-source app.

This means at different points in time I have been a researcher, a founder, a manager, a content creator, and an open-source maintainer. Many of which at the same time!

I don’t think I am exactly world-class at any of these, but I feel fortunate to having done many different things, and having looked at tech from different angles. But this also means along the way I had my own sense of identity challenged many times, and had to adjust. Every single time.

Sometimes change felt easier, other times harder, but it eventually became a familiar feeling. That’s probably today why I am not bothered too much by AI, but I understand why many people are.

So, today I want to talk about how you can think about all of this in order to become more resilient, both psychologically, and – practically speaking! – on the job market. I won’t make big predictions, because I don’t feel I am particularly good at those, and also because no one really knows what is going to happen anyway. Instead, I’ll share a few principles and mental models that work for me and I believe will stay true for a long time.

This is pretty much what Ray Dalio does in Principles: if you do ambitious things, you will go through struggles and fail at some of them, but if you pay attention, you can turn what you learn into principles that work for you. Dalio also says that there are no principles that work for everyone: you should find your own! What follows are some of my principles, not necessarily yours.

This is also a written version of the talk I am giving today at code.talks in Hamburg, and you can find the slides here.

Here is the agenda for today:

• 🥣 Be a mediocre soup — also how to walk on ice, and put dots on maps.

• 👔 Work as a manager — own the outcome, not necessarily the building.

• 🔀 Product or platform — the two directions you can broaden your role in.

• 🚌 How to make it happen — drive the change, and be slightly too ambitious.

• 📚 Resources — articles to dive deeper on each of these.

Let’s dive in!

🥣 Be a mediocre soup

One of my favorite ideas about personal identity comes from Scott Adams, the creator of Dilbert, who said about himself:

It’s not his skills that are unique, but rather their combination. That gives him a good answer to the question: why me? Why should I be the one doing Dilbert?

I believe it’s important, at work, to be in a position where you provide a unique, or rare, way of contributing. I also believe that, especially today, it is easier to do that by combining different things you know, as opposed to becoming 99-percentile at one specific thing.

So, quoting Scott, the first principle could be: be one big mediocre soup. But I’d rather turn it into something more actionable, which is: find a broader version of yourself.

Read more

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

📊 AI sped up coding, but not reviews

This week’s newsletter is brought to you by our friends at DX!

AI tools sped up code authoring. Review and release systems haven’t kept pace.

DX’s newest AI Impact Report, based on data from 500+ engineering organizations, shows developers opening far more pull requests each week, each more than twice the size it used to be. As a result, PRs wait more than twice as long for a first review.

Download the full report to see where delivery friction is moving and where leaders should focus next to get the most out of their AI tools 👇

Download the full report

🚚 Treat process changes like migrations

At LDX3 in New York, Will Larson opened with a keynote about the delivery journey of his team at Imprint: from manual gates everywhere, to CI/CD, to agentic workflows.

What I liked most was that he framed each of these steps as a migration.

We know a lot about migrating code, and I believe most of the same logic applies to processes and workflows. Here is how Will approached it:

1. Understand people’s problems — there is a reason why people do things the current way, even when it looks flawed, and to build something better you need to understand those problems deeply.

2. Get buy-in — even with clear top-down direction, the implementation should be collaborative. When Will wanted to move from Jira to Linear, he started by involving the biggest Jira fans, because if he could address their concerns, the rest of the team would be easier to migrate.

3. Draw hard lines — inclusion matters, but once a direction is taken, resources need to support it. Will made Claude Code the recommended coding agent: people can still use something else, but they won’t get support from the platform team.

4. Sweat the details — every migration has a long tail of things to fix and edges to smooth, so keep working on it even when it seems that most of the work is done.

I wrote a recap of my favorite talks from LDX3 and ProductLab, including Will’s 👇

🧰 Treat skills like code

In August I talked with Charlie Guo, developer experience engineer at OpenAI, about how teams are building with agents today.

We spent a lot of time talking about the move from single-player to multi-player: how do you take the productivity gains of a few AI power users and spread them across the team?

Charlie’s answer starts from skills. He organizes them in three tiers:

• 🧑‍💻 Personal skills — live in your local folder, and are useful only to you.

• 📂 Project skills — baked into the repo, and shared with everyone working on that project.

• 🏢 Organization skills — hosted in internal repositories blessed by IT and security, that anyone in the company can browse and clone.

Skills follow the same lifecycle as regular code: they are version-controlled, discoverable, they have owners, and an update process.

But tooling is not enough. Charlie knows people who don’t share their AI tricks because they don’t want their boss to think they are cutting corners, or because they are stack-ranked on AI proficiency and want to keep their edge. So if you lead a team, you should start from the culture side, and make sure that sharing a good workflow gets rewarded and celebrated.

You can find the full conversation with Charlie here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Redesigning Source Control at Anthropic

14 min • by Anthropic

Anthropic went from about 2,500 merged changes per day in May to over 30,000 in September, and git couldn’t keep up. So they built Scion, a custom source control system designed around always-online agents, and moved the whole monorepo off git in five months.

They argue that other companies will hit the same problems soon, and I believe it.

🥈 Hunger Beats Tenure: Advice for Junior Engineers

5 min • by Felix Rieseberg

Felix is a hiring manager at Anthropic, and this month he stopped doing coding interviews, because Claude is better than candidates at them anyway.

He also argues that AI is good news for junior engineers: you can pick a business goal, build one bold idea over a weekend, and skip a lot of the usual red taping.

🥉 The Counting House

32 min • by Steve Yegge

Steve explores a pattern to address huge volumes of repetitive work: cheap models on very tight rails, one case type at a time, scored against the humans doing the same job. It’s the exact opposite of his own wide-open software factory. Long read, but worth it.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

I wish you a great week.

Sincerely 👋
Luca

Today’s episode is brought to you by: TRM Labs

Criminals are scaling with AI. Build the technology that helps crimefighters fight back. TRM is hiring, go to https://www.trmlabs.com/careers

Today’s guest is Benedikt Stemmildt, founder of hackers&wizards and co-chair of the CodeTalks conference. With more than 15 years in software, Benedikt now spends most of his time helping companies and product teams adopt agentic engineering, from training to full transformation.

We talked about why product and engineering roles are merging, why engineers resist AI the most, where the time you save with agents should actually go, and why Benedikt is not a fan of spec-driven development.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute, handcrafted takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 🤝 Product and engineering converge

2. 🧱 Why engineers resist the most

3. 🧹 Where your AI time should go

4. 🏭 Factories, not spec-driven waterfall

5. 🔍 Reviews, agents, and the road ahead

⠀Let’s dive in 👇

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.

We recently introduced monthly themes in the Refactoring Community, as a way to work all together on one topic at a time, and to get deeper and more interesting insights.

In October we discussed Management in the Age of AI: we had a big community thread, an AI Club edition, a Mastermind, and last week we asked everyone a simple question:

In two years, will your company need more managers or fewer?

Outside the community, the answer many CEOs are giving is fewer:

• Jack Dorsey wrote that “there is no need for a permanent middle management layer“ at Block.

• Brian Armstrong announced “no pure managers“ at Coinbase – every leader must also be an active individual contributor.

Also, it seems that most conversations about AI are about software factories, bottlenecks, code reviews, and all the IC stuff. Very few are about what happens to the people who manage those ICs.

So, today we look at what AI is really changing in the manager job, using a month of community conversations plus a ton of research and recent stories. Here is the agenda:

• 🎯 What a manager is for — four areas that haven’t moved.

• 🧹 What AI takes off your plate — glue work, status, and some building.

• ⚔️ The AI giveth and the AI taketh — more review, slop, and the AI transition itself.

• 🧭 How to set the quality bar — slop as feedback, measuring what matters, reviewing the harness.

• 🛠️ What to do with the space that’s left — a small model for using the time AI frees up.

• 📚 Resources — 10+ articles and stories to help you dive deeper.

Let’s dive in!

🎯 What a manager is for

To see what AI changes, we have to start from what the job is for, and that part to me hasn’t moved a lot. Andy Grove wrote in High Output Management that:

I believe that’s still pretty much it.

On top of this, everything a manager does to raise that output falls more or less into four areas: Product, Tech, Process, and Team.

These are the same four pillars I used back in 2024 to describe what an EM does, taking a page from Pat Kua’s EM archetypes, and I believe they still hold. Each of them answers a different question about the team’s output: what we build, how we build it, how the work flows, and who does it:

1) Product 🧭

Shape what the team builds and why, together with PMs and stakeholders, and keep the technical direction aligned with what the business needs.

2) Tech 🔨

Make sure the thing is built well: design, quality, reliability, and the technical risk that comes with them. This is where technical skills still matter for managers, because it is hard to judge what good looks like if you have never built the thing yourself.

3) Process 🚚

Make sure the work gets done in a reasonable time, without too much friction: planning, scoping, coordination, moving information around, and removing obstacles.

4) Team 🪴

Enable trust, alignment, and growth across people and teams, from hiring to careers. This is the human core of the job, and probably the part that has changed the least.

No manager covers all four equally, of course: how you split your time depends on the company, its stage, and especially on where your team is strong already. Nevertheless, AI touches all four of these, both in good and bad ways.

Let’s start with what it takes away.

🧹 What AI takes off your plate

The first obvious area where AI is helping managers is glue work, like moving information between tools, writing up meeting notes, and in general, processing information coming from disparate sources.

Anyone who has worked as a manager for a long time knows this is 1) incredibly time-consuming, and yet 2) absolutely foundational to the success of your job.

Fetching status is an easy example:

Read more

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

🛡️ Centralize VPC traffic inspection on AWS

This week’s newsletter is brought to you by our friends at Palo Alto Networks!

Most VPC security stops at the perimeter, so traffic moving laterally between VPCs can be left uninspected.

With this solution template, you get a pre-configured Palo Alto Networks VM-Series environment with an AWS Gateway Load Balancer across four VPCs, so you can try:

• Three traffic flows, one inspection point — route outbound, east-west, and inbound traffic through VM-Series via Transit Gateway.

• Live threat simulation — a real-world exploit hits your demo app, and you switch from alert to active blocking.

• App-ID in action — identify SSH on a non-standard port and enforce rules by application, not topology.

Explore the full architecture, step-by-step walkthroughs, and a live threat simulation, all for free!👇

Get the free solution template

🛝 Governance can make you faster

Many teams feel conflicted about putting real AI governance in place, because it looks like a brake at a moment where everybody expects you to accelerate.

I have a contrarian take: I believe good governance can be an accelerant.

In 2006, Peter Summerlin ran a simple study about kids in playgrounds. Teachers took kids to a playground with no fence, then to a comparable one with a defined border. Without the fence, the children stayed huddled around their teacher, afraid of leaving her sight. With the fence, they felt free to explore within the boundaries. So in playgrounds with fences, kids used more space.

People work the same way. Once they know where the fences are, they feel empowered to do more within them. But that’s only true if governance is good.

We already see this in coding. We talk about guardrails for AI coding all the time, and having strict guardrails is exactly what allows me to be more liberal with the tasks I give to my agents, and with what they can ship.

Data also seems to point the same way. A late-2025 Google Cloud / CSA study looked at agentic AI adoption by governance maturity:

• Full governance → 46% adoption

• Partial governance → 25% adoption

• Still in development → 12% adoption

Correlation is not causation, but it makes it hard to look at governance as just a tax.

I wrote a full guide about how to get started with AI governance, including what you should govern and how rules graduate from common sense to software 👇

Refactoring

Getting started with AI governance 🔒

Hey there, Luca here…

Read more

2 months ago · 30 likes · Luca Rossi

🚲 Put gears, not modes

In July I talked with Geoffrey Litt, design engineer at Notion, about malleable software, and he shared one of his favorite product design parables.

Imagine a bicycle whose gears are labeled not with numbers, but with modes like “gravel gear” and “uphill gear”. It sounds user-friendly, but it’s actually terrible. What do you do when you’re going uphill on gravel?

When you hide the underlying model behind labels, you take away the mental model people need to develop to handle new situations. And humans are smart! They can learn numbered gears, and then combine that knowledge creatively.

What malleable software means is having a smaller set of primitive components that can be reassembled to make anything, and doing a really good job introducing and teaching those components to everyone using the software, just like bicycle gears.

Notion is a good example of this. Every paragraph, heading, and image is a self-contained block you can drag, nest, and sync across pages. It’s a small learning cost upfront that keeps paying back over time, and now it pays back with agents too: they reuse the same primitives, so Notion agent instructions are just Notion pages.

You can find the full conversation with Geoffrey here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 On the Death of Amazon’s Writing Culture

7 min • by Steve Huynh

Steve spent almost twenty years at Amazon, and he argues that its famous writing culture didn’t survive AI.

Bezos used to say you can’t write a six-page memo without clear thinking, and that is simply not true anymore, so a doc is no longer proof that someone has thought about the problem. Food for thought.

🥈 Someone Behind the Software

3 min • by Karri Saarinen

Karri argues that good products carry something of the people who make them, and that many products today feel messy because adding new capabilities is much easier than rethinking the existing ones. This is a great take, that I also needed to hear for Tolaria.

🥉 How to Be More Ambitious: A Tutorial for Humans With Models

9 min • by Felix Rieseberg

Felix works on Claude, and wrote a practical guide to using AI for more than doing the same work faster. He splits ambition into altitude, depth, and range. For example he went from asking Claude to fix single crashes to asking it to keep the apps crash-free, which first meant giving it crash reports and machines to reproduce bugs on. Lots of good prompts to steal, too!

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

I wish you a great week.

Sincerely 👋
Luca

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

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

🚀 Build event-driven apps without the overhead

This week’s newsletter is brought to you by our friends at AWS and Confluent!

Deliver real-time customer experiences without managing streaming infra! Confluent Cloud is a fully managed Apache Kafka-based solution for event streaming, available directly from your AWS account.

See how Confluent Cloud integrates with Amazon S3, Redshift, Lambda, and Bedrock to:

• Accelerate development — build real-time data pipelines connected across your AWS tools

• Simplify operations — offload event streaming management to Confluent Cloud

• Scale in real-time — power event-driven and generative AI apps within your AWS environment

Get technical details to start building, from step-by-step tutorials and Infrastructure-as-Code templates to a free trial 👇

Explore Confluent Cloud on AWS →

🏃‍♂️ Make room for hard things

In Mental Marathoners, I wrote that a possible consequence of intelligence getting cheap, is that the edge moves to people who still want to stretch their own thinking.

What I don’t buy is that this hunger is just a trait — that you either have it or you don’t. I prefer to ask myself what makes me hungry in the first place.

There is a data point about runners that stuck with me. Regular runners (4+ hours a week) are unusually affluent and educated, even though running itself is cheap. This means the filter is not the cost of the hobby. To me, this looks more like Maslow: once basic needs are covered (i.e. you are affluent and educated), you free up mental space for harder challenges (i.e. running).

We become hungrier when the rest of our life is simple enough that a hard problem has room to be attacked.

So I think of energy like a jar. If you fill it with sand (chores, fake urgencies, a hundred open tabs), the rocks never go in. The stretch work is a rock, and in my experience, you should spend at least half your time on that.

I wrote more about mental marathoners and how to stay on the right track here 👇

Refactoring

Mental marathoners 🏃‍♂️

A couple of weeks ago, I read The People Who Will Thrive in the AI Age, by David Brooks…

Read more

2 months ago · 45 likes · Luca Rossi

📖 Use stories to deliver hard feedback

Earlier this year I talked with Michael Lopp (Rands) about the power of stories at work, and one part I keep coming back to is how he delivers hard feedback.

He told the story of a high-performing director who had only ever gotten top marks, then suddenly got a “C” after a promotion, and got furious. Instead of saying “pull it together,” Rands walked him through a personal story of going through the same experience years earlier.

This didn’t fix things overnight – it took weeks and months of continued support – but the story created space for the person to process the feedback on their own terms, instead of locking into defense.

Their job is to choose to decide whether they want to learn or not. It’s really important. If they don’t hear the story, if they don’t hear the lesson, they’re not going to do anything.

When coaching or managing people, we should assume they are capable and resourceful. In this context, stories can give just enough input to unblock someone, without spoon-feeding the answer. They get to own the conclusion, and that ownership is often what makes them actually act on it.

You can find the full conversation with Michael here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 If Your Team Is Happy, Are You Doing a Good Job?

9 min • by Charity Majors

Charity goes back to the ZIRP-era belief that if your team is happy, you are doing a good job, and explains how psychological safety drifted from being about learning and performance to being about never feeling bad at work.

I agree with her that frustrating people and telling them no is part of a manager’s job, because growth is uncomfortable. Great read, and part of a longer conversation with Cat Hicks that is worth catching up.

🥈 Software’s Centaur Age May Last Decades

5 min • by Sean Goedecke

Sean argues we are living in the centaur age of software, where engineers paired with AI beat both unassisted engineers and unsupervised agents, and that this phase may last decades, like it did in chess.

I don’t know if he is right about the timeline (nobody really does), but I like his advice a lot: don’t jump ship early, and spend your energy figuring out what value humans still add.

🥉 How Do AI Coding Assistants Change the Shape of Eng Work?

4 min • by Lizzie Matusov

Lizzie covers a six-month study on how AI assistants reshape engineers’ days, and the results are mixed: perceived productivity held at 84%, but the share of engineers reporting a worse developer experience nearly doubled, from 14% to 27%.

Time moved from writing code to directing and checking AI output, and focus took the hardest hit. I liked the practical advice at the end, especially batching AI review into set blocks and keeping design work and hard debugging on separate, protected time.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

I wish you a great week.

Sincerely 👋
Luca

Today’s episode is brought to you by: Notion

Learn more about Notion’s Developer Platform today at https://ntn.so/refactoring

Today's guest is Francisco Trindade, VP of Engineering, founder of two companies, and author of “Leading Effective Software Teams”, which I just read and loved.
So in this chat, you will learn how to think about your team as a system, how to optimize flow in the developer process, and why you should absolutely hire junior engineers.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute, handcrafted takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

Agenda:

1. 📘 Why a book about teams as systems

2. 🧠 Systems thinking in day-to-day management

3. 🌊 Optimizing flow and measuring what matters

4. 🎯 Autonomy and shaping work for people

5. 🌱 Why junior engineers still matter

⠀Let’s dive in 👇

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.

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

Hey, Luca here! Welcome to a new edition of the 💡 Monday Ideas 💡 — ideas and readings to start the week on the right foot.

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

Hyperscale Remediation: Autonomously Secure Your Software Estate

This week’s newsletter is brought to you by our friends at Blitzy!

Security teams don’t need another list of alerts. They need to know which vulnerabilities are reachable, exposed, and safe to fix. Blitzy understands your entire software estate and, through Proactive Insights, surfaces known and previously undiscovered vulnerabilities in the enterprise codebase and remediates them autonomously. It traces each finding through execution paths, identifies dependencies, and validates remediation. Blitzy then turns prioritized risks into batches of tested pull requests for engineers to review.

The result: less alert noise, faster remediation, and confidence that each fix is safe. Find risk in context and remediate it securely at enterprise scale.

Try on your codebase today

📚 Knowledge capture compounds engineering quality

In April, Rob Zuber and I wrapped up our software factory series with an article on compounding. We asked: how do teams actually get better over time, instead of just shipping more?

I believe knowledge capture is one of the few things in engineering that truly compounds.

Teams usually capture too little of it. They especially lose decisions, forgetting why systems work the way they do.

There is basically no excuse today for not getting this right, because capturing and processing information is much cheaper than before. Meeting notes, ADRs, product decisions, can all be captured, summarized, updated, and reused by agents.

So docs become an asset that improves the development loop, instead of a tax. And the more context the team captures, the more coherent decisions the AI can make on the next project.

This is especially important for building the right thing, as opposed to simply the next thing. A codebase becomes easier to steer when future work can see past decisions.

Read the full article here 👇

Refactoring

The Compounding Software Factory 📈

Hey there, Luca here…

Read more

6 months ago · 61 likes · 2 comments · Luca Rossi

🤝 Good engineering is an exercise in human relationships

Two years ago I had Kent Beck on the podcast, and we talked about Extreme Programming and TDD. I rewatched that interview recently to figure out what has changed (and what has not) since then, and a part that stuck with me is when he said good engineering is an exercise in human relationships.

This is easy to miss because you may just treat XP as a bag of techniques: short cycles, tests, pairing, reviews, and so on. But all of these only work if people communicate and give each other feedback.

This ties in with Kent’s idea that Agile goes largely against traditional power structures. Waterfall represents a fatal attraction for many teams because it replaces grassroots communication with a plan that gets transmitted down through hierarchy.

If the human relationships are missing, you can install the practices and still not have the actual engineering.

You can find the full conversation with Kent here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 The Kids Are Alright

6 min • by Francisco Trindade

Francisco takes on the question of whether we should still hire junior engineers, and his answer is a strong yes. If the job of a senior becomes leading a project by orchestrating agents, the job of a junior will be to lead simpler projects in the same way. And if juniors have nothing meaningful to do on your team, that probably says more about your process than about them. I loved this one.

🥈 Software Factories Are a Local Maximum

3 min • by Aviv Ben-Yosef

Aviv makes a great point: agents can make us lose the healthy friction that made us think about why we were building something. I have written a lot about software factories myself, and I 100% agree with him.

🥉 How to Write an Effective Software Design Doc

15 min • by Michael Lynch

Michael wrote design docs at Google and Microsoft, and this is his full playbook on when a doc is worth it, what belongs in it, and what doesn’t. I feel this is even more relevant today, since a good design doc is pretty much the context you want to give your agents (or have them help you write anyway).

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
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

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

🖥️ Coding agents need more than a fast loop

This week’s newsletter is brought to you by our friends at Blitzy!

Coding agents have sped up individual tasks, but they haven’t solved the coordination, validation, and handoffs that determine how quickly software ships, especially the enterprise one!

Tomorrow join Sid, CTO and co-founder of Blitzy, for a live session on what changes when a system can hold context across an entire codebase—not just a single file or function.

He’ll walk through a real project in Blitzy, covering reverse engineering, tech spec generation, the Agent Action Plan, code generation, and PR Review, including where human review gates the process. There will also be a Q&A at the end 👇

Save your seat!

🚀 Create high-agency engineers

Out of the various interviews / case studies we did last year, one of those that aged better is the one with Greg from Graphite.

I think it’s because we talked very little about tech, and more about values and culture. In particular, Graphite is obsessed with building a team where engineers have high agency.

What does a high-agency engineer look like? For Greg, it’s someone who owns problems end-to-end, which allows for:

• More productivity — less back-and-forth, less waiting, less “that’s not my job”.

• More fulfillment — people who have real impact stay engaged, grow faster, and stick around longer.

High agency, though, it’s not (only) a personal trait — it needs to be enabled by your team environment. For Greg, at a team level, agency comes from three things:

1. Purpose — a clear vision of where you are going and why it matters.

2. Permission — freedom to go after big things, make decisions, and occasionally get things wrong.

3. Simplicity — cognitive load low enough that ownership feels like a superpower, not a burden.

To make this happen, for example, Graphite is extremely light on product management: a couple of PMs for 30+ engineers. Engineers need to fill the gaps: talk to stakeholders, prototype, dogfood, and push work forward without waiting to be unblocked.

To be honest, they also have an unfair advantage: they build a dev tool, so their engineers are their users. Which means product intuition comes for free.

But for everyone else, the principle holds: get engineers closer to customers. The difference is you have to invest more intentionally about it:

• Bring engineers to customers — sales calls, user interviews, support escalations. First-hand experience and empathy beats summaries.

• Make context accessible — record calls, share clips, pipe tickets into Slack.

• Dogfood relentlessly — even if the product is not “for” engineers, find ways to make them use it.

I wrote a full case study about how Graphite ships 👇

Refactoring

How Graphite Ships 🚢

It’s a weird time for engineering teams…

Read more

a year ago · 19 likes · Luca Rossi and Greg Foster

🧭 Growth trajectory >> AI fluency

Greg’s story made me think about my interview with Austen McDonald, former hiring committee chair at Meta, and author of Mastering Behavioral Interviews, where we discussed how AI is reshaping how engineers get assessed.

Austen recommends evaluating AI skills in both technical and behavioral rounds, but the questions should be different. In behavioral interviews, stories are king. So you may ask something like “Tell me about a time you used AI and it didn’t work out.”, instead of abstract prompts like “How do you think about AI?”

But the strongest predictor is not current AI usage at all. It is growth signal: is this person staying on top of industry trends, running side projects, adapting when the ground moves? This has always been important, but now more than ever.

“The most important thing about this person is not how they use AI right now, but how they are going to be adapting to using AI as the landscape changes.”

Austen particularly focuses on ownership. As AI handles more of the stack, “full stack” expands toward more areas of the business: customers, go-to-market. Does the candidate reach for more end-to-end ownership? Are they willing to do so?

You can find the full conversation with Austen here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 If We Do Not Stop to Help Each Other, What Do We Become?

3 min • by Jeff Atwood

Jeff shares a great message from a developer who once got through a dangerous deployment because strangers on Stack Overflow chose to help him. An LLM could have provided the same (or a better?!) answer, but not the feeling that somebody cared. We need that reminder!

🥈 Dishwasher Mode for AI Tasks

1 min • by Clemens Adolphs

A dishwasher is slower than washing plates by hand, but we don’t care, because it still frees up our time. Clemens uses the same frame for AI: give it small, annoying tasks off the critical path, then care more about reliable completion than raw speed. I liked this a lot.

🥉 The Sensible Defaults Playbook

2 min • by Thoughtworks

Thoughtworks shares its collection of good defaults. Their approach is to have defaults remove recurring friction, but without becoming dogma. Start with practices that usually work, adapt them to the context, and review them as the environment changes.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by: Notion

Learn more about Notion’s Developer Platform today at https://ntn.so/refactoring

Today's guest is Adam Tornhill, founder of CodeScene and author of Your Code as a Crime Scene.

With Adam, we talked about how his team refactored the whole Street Fighter 3 codebase, which is more than 300K lines of code, in just a few days and spending a few thousand dollars in tokens, and measured how that led to better and cheaper AI development of new features.

And then we discussed how the CodeScene team does agentic development, what the process looks like, what the bottlenecks are, and what are the crucial parts that Adam believes we still need to do as humans.

Show notes:

• The Street Fighter case study

• Controlling the uncertainty machine: do you still need to read the code?

• Making legacy code AI-ready

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute, handcrafted takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 🕹️ Refactoring Street Fighter with AI agents

2. 📖 The refactoring playbook

3. 🧪 Testing, docs, and the new fundamentals

4. 🤖 CodeScene’s agentic development process

5. 🔮 Bottlenecks and the future of the developer role

Let’s dive in 👇

1) 🕹️ Refactoring Street Fighter with AI agents

Adam’s team at CodeScene, in collaboration with researcher Marcus Borg, set out to explore large-scale refactoring using AI agents. They needed a code base that was non-trivial, legacy, and universally understandable, so they picked a decompiled version of Street Fighter 3, a 25-year-old game with 300,000 lines of C code.

When they first analyzed the code base with CodeScene’s own metrics, it scored a 5.4 on a 10-point scale, roughly the industry average for enterprise code and very far from what Adam calls “AI-optimal code” (9.5 or higher). The team had two goals: uplift the code health as much as possible, and preserve the existing behavior of the game.

“I’ve never ever seen anything close to this before. A rewrite at that scale would have been a 12-to-18-month project. And now that can be automated for a fraction of the cost at a fraction of the time.”

Street Fighter turned out to be a particularly good target because the game already had a clever test approach: computing the hash of each rendered frame and comparing them. This gave the agents a reliable way to verify that refactoring didn’t break anything.

The preparation phase took about two weeks (as a side project), with the team exploring different models and patterns. The actual uplift then took just a few days and cost roughly $4,000 in API tokens. They primarily used Claude Code with Opus, because while GPT models were competent at refactoring, they weren’t as good at documenting and extending the playbook.

2) 📖 The refactoring playbook

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

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

📚 Master production-grade orchestration, for free!

This week’s newsletter is brought to you by our friends at Kestra!

A few months ago we published an article about how to orchestrate AI workflows, together with the team at Kestra, an awesome open source project used by the teams at Apple, JPMorgan, and more.

Today I am happy to help them spread the word about the Kestra Academy, where you can find self-paced courses on infrastructure automation, AI workflows, and standardizing orchestration across your engineering org.

In the academy, you can learn how to govern complex workflows and start running production pipelines the same week.

You should check it out! 👇

Learn how to run orchestration

🏁 Faster coding vs faster delivery

Most AI coding tools optimize 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 is just a small part of how software gets shipped. There is an outer loop too: deciding what is worth doing, shaping and reviewing the solution, releasing it, and learning from production.

If you don’t improve both, the constraints move elsewhere:

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

So the goal should be end-to-end throughput, which requires a workflow that encompasses both the inner and the outer loop.

I wrote a full case study about how the guys at TRM are doing this 👇

🧪 Agents will game your tests

When I spoke with Anush Elangovan, VP of AI Software at AMD, he described a funnel where creativity is allowed to run wild at the top, but progressively more human judgment is needed as code moves toward production.

He also shared an entertaining story about building Spur, an AI-native job scheduler. The agents writing the code were so “smart” that they found a shortcut: instead of actually running unit tests on hardware, they simulated the hardware and reported success.

“The agents were so smart that they would simulate the hardware and pass the unit test and say ‘yes, success.’ We had to say no, no, no — you never simulate the hardware. You have to actually run the test on hardware before you can promote a PR.”

That forced the team to build a superset of the guardrails they previously had for humans. Test harnesses now need to account for adversarial agent behavior. The result, Anush said, is a quality system roughly 10x more comprehensive than what was needed when humans were the only contributors.

I have found this to be a useful posture: assume agents will optimize for passing the tests, not necessarily respecting their spirit, and design accordingly.

You can find the full conversation with Anush here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 The Manager’s Path in the Age of AI

13 min • by Camille Fournier

Camille asks what still belongs to managers when AI raises individual output and eats the small day-to-day interactions that build trust and rapport across an org. This is the written version of the talk I heard at LDX3. I loved 100% of it and it gave me a lot to think about.

🥈 Code Yellow, Code Red

11 min • by James Stanier

James walks through declaring a Code Yellow after months of instability eroded some customer trust. Running it well means clear communication, defined goals, and company-wide support to fix problems, without blame.

🥉 Trying the Software Factory Pattern

3 min • by Will Larson

Will is trying a “software factory” loop: agents audit the project’s goals and metrics, keep track of state on Linear, work on the non-blocked tasks, and re-check when the description goes stale. This was short and practical, and a good read.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Run a better engineering team

See you next week!
Luca

The Refactoring Community hosts a ton of great conversations in threads, but, most of all, every month we run two live sessions, hosted by our awesome Community Lead Melinda Seckington, and always joined by yours truly. These sessions are:

• Mastermind — leaders bring a real problem and we work on it.

• AI Club — people show what they learned about AI that month, including the parts that did not work.

This monthly recap makes sure the good stuff doesn’t stay confined to Zoom. So here is the agenda for today:

• 🧠 How to think about productivity now — what we discussed in the September Mastermind.

• 🪄 September AI Club — terminal personal OSes, picking the right models, and agents that live in the cloud.

• 📅 What’s next — AI Club on 2 Oct, Mastermind on 19 Oct.

• 💬 How this works — and how to join.

Let’s dive in!

🧠 Redefining developer productivity

In this month’s Mastermind, we talked about what “good” looks like when most of the volume metrics (PRs, commits, lines of code) feel worse as proxies than they used to. Btw, have they ever been good? Probably not, but they are arguably worse now because of AI.

One of the biggest points of discussion was the tension between:

• Investing in automation — making the “harness” and overall pipeline better, versus

• Just shipping things — with familiar human-in-the-loop tools, especially under a short deadline.

Why is there a tension? Because with engineers increasingly acting like engineering managers of agents, there is often higher leverage in using their time to improve the system, rather than closing the ticket in front of them. But it’s still tricky to balance the two

Personally, I have found that, before digging into a task, it’s worth asking yourself whether this is a system problem, worth fixing for posterity once and for all, or just an immediate, one-off ask.

My rule of thumb is: as soon as you find yourself doing something twice, make sure you don’t do it three times.

We also talked about what to measure instead. Some people pointed at the team actually delivering on their cycle (or Sprint) goal, while others discussed the amount of features shipped, or cycle time. I think a very good leading signal is simply to directly ask engineers how they feel about work, and where they felt they were wasting time that week. Good conversations always deliver an incredible amount of signal.

There is also a ton of work that is hard to measure, aka invisible work. Things like mentoring, “insurance” maintenance, and the informal chats that keep teams moving do not show up well under hard metrics, and they get squeezed when people optimize for numbers. It’s also unclear how to score that work cleanly. No one had an answer here!

As always, you will find the full writeup in the Mastermind space (if you are in the community).

🪄 September AI Club

In this month’s AI Club, four people shared their AI wins for five minutes each, then we did the quickfire round again. Melinda wrote it up properly here. I liked a few threads in particular:

• AI as an accountability partner — Kishan has built something like a personal OS that mostly runs from the terminal: daily check-ins that read journals and plans, a weekly retro on what energized / drained him, and a folder structure so ideas (notes, photos, voice memos) get filed without conscious sorting. He also shifts models by task (heavier for planning, lighter for execution) and periodically audits the core memory file itself, because instructions written in one place do not always get pulled into the right context.

• The same prompt, very different outputs — Julie ran the same reflection prompt across a chat interface and a coding CLI on the newest model family. The chat version came back quite readable, while CLI version needed a lot of correction. Several people in the room had noticed the same split: this generation of models can be stronger at one-shot coding and weaker at other things, like… clear writing! So, do not assume “newer” means better across the board.

• Moving the operation to the cloud — I shared my own migration of agents off the Mac Mini onto cloud machines (after a power outage and too many agents fighting over one box). Coding stays local on a kanban, while everything upstream moved. I wrote the longer version in My agents are moving to the cloud.

• Working solo on something that cannot fail — Andrea is deep in a high-stakes embedded / security project, mostly alone after the rest of the team went on leave. He walked us through how he set up two tiers of docs: customer-facing ones, reviewed manually line by line, and internal brainstorming ones, mostly for AI consumption and not reviewed directly. Autonomy helps a lot, but every now and then it does funny things, like fabricating a citation that doesn’t exist, so he keeps the high-stakes parts of the ops on a tight leash.

All in all, a very practical session. Less about shiny demos, more about how people actually run their week with these tools.

📅 What’s next

Both the Mastermind and the AI Club, like all community activities, are for paid members of Refactoring. Here are the next editions 👇 RSVP on the event page to help us size the room:

• AI Club • Fri 2 Oct, 14:00 CEST — five-minute shares, questions, and the one-sentence fireside round at the end.

• Mastermind • Mon 19 Oct, 18:00 CEST — third Monday of the month, as usual!

Bring your questions! These sessions work because of the members, not because someone gives a talk.

💬 How this works

The Refactoring Community is a private space for paid subscribers of Refactoring: it hosts async threads, Q&A, and monthly live rooms like these.

It is home to more than 1500 engineers and managers, and it’s my favorite place on the internet!

To join it, subscribe to the full version of Refactoring!

Join the full Refactoring 🙌

That’s it for today! See you on the next events!

I wish you a great weekend 👋
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 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

I also publish an original essay every Wednesday. Here is the one from last week in case you missed it:

🔨 Autonomous Software Dev for the Enterprise

This week’s newsletter is brought to you by our friends at Blitzy!

Blitzy is built for large, complex software projects that other coding agents cannot handle: large-scale refactors, scaled vulnerability remediation, and undocumented legacy systems.

Blitzy’s Sandbox lets engineers evaluate Bitzy on their own software estate, at their own pace. Eligible organizations can connect real applications, reverse-engineer up to 1 million lines of code, generate up to 25,000 lines of E2E tested code, and surface prioritized security vulnerabilities across their software estate.

Try Blitzy on your codebase

🌱 Grow juniors with guardrails and judgment

One of the most important qualities of junior engineers is that they can turn into senior engineers. But that does not happen automatically.

There is a dream scenario where juniors grow, become senior, and help rotate headcount when seniors leave. But there is also a nightmarish one where juniors are thrown in the trenches, abuse AI in ways they do not understand, nobody checks on them, and the product eventually goes to shit.

When the growth cycle breaks, it is usually because juniors do not have a tight enough feedback loop: 1) one that keeps the work high quality, and 2) one that helps them learn from doing it.

To me, the loop looks two-fold:

• Invest in an amazing harness — create guardrails, rules, and gates, and encode everything that can ensure quality automatically. This helps everyone: seniors, AI, and juniors who can learn from the same rules.

• Pair juniors with seniors — let young folks experiment and move fast, but keep seniors close enough to provide judgment and supply systems thinking.

There is no way around the fact that AI makes the junior path harder in some ways, because more judgment is needed earlier. But that is also why freezing junior hiring is such a fragile bet: you optimize for today’s output, at the expense of starving the pipeline that should produce tomorrow’s seniors.

I wrote more about this in the full piece 👇

📱 Most AI products are still “m.google.com”

When I spoke with Charlie Guo, developer experience engineer at OpenAI, we walked through three eras of AI-assisted development.

First came models that could autocomplete snippets, which became tools like GitHub Copilot. Then came AI-native IDEs like Cursor, where the model sat inside the editor. Now we are entering a third phase: standalone apps that orchestrate agents, and move beyond the text editor entirely.

Charlie believes most products are still stuck in the middle of that transition:

The m.google.com of AI was (or is): take this product and cram a chat box on the sidebar, and then chat with it on the side while you’re doing stuff in the app.

That’s similar to when the iPhone arrived: companies took desktop websites and mostly squeezed them into a vertical layout. It took nearly a decade to invent native mobile products: Uber, DoorDash, things that could not really exist on a desktop.

We are in that same messy middle with AI. A chat sidebar is not necessarily bad, but it’s just an easy retrofit. Native agent experiences are still being invented.

You can find the full conversation with Charlie here 👇

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 What psychological costs does AI adoption create for engineers?

4 min • by Lizzie Matusov

Lizzie covers a case study from a large Danish software company, one year into an org-wide AI rollout. Regular engineers feel “accountability anxiety” and “craft identity disruption” as tools take over work, while architects (more augmented than replaced) barely show the same costs. Interesting research, worth looking into.

🥈 De-Brainrot Vacations

4 min • by Daniel V.

This piece by Daniel really resonated with me. He noticed that after years of engineering, plus AI and phone dopamine, his thinking got slower and lazier. So he used a countryside vacation to reset his brain by reading hard books and doing math and physics as a hobby. This is peak mental marathoners!

🥉 The Internet Is Kind of a Predatory Cesspit Now

8 min • by Stephen Diehl

Stephen argues that, over the years, “predation” moved from the periphery of the internet to its very core, and that a lot of ordinary people have been (often unwillingly) conscripted into it. I have less of a bleak view about this, but I see where Stephen is coming from and I don’t necessarily disagree. Worth reading!

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by: Notion

Learn more about Notion’s Developer Platform today at https://ntn.so/refactoring

Today's guest is Rahul Raina, co-founder of TRM Labs, which is a YC-backed company that works on solutions and products for security, fighting criminal networks, AI attackers, and more.

With Rahul, we had a great chat that covered a lot of ground, starting with the tough reality of cyber defense today, and why attackers by default always have the upper hand when AI and technology improves. And then we moved to a deep dive into how the TRM team works and how they rebuild their whole product development workflow for AI, including reshuffling all the technical roles, compressing the developer process steps, and creating dedicated artifacts for human reviews.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute, handcrafted takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 🛡️ The asymmetry of cyber defense

2. 🔄 Inner loop vs. outer loop

3. 🏗️ Redesigning the shipping framework

4. 🧪 Building a culture of experimentation

5. 🔍 Human review in an AI-driven workflow

⠀Let’s dive in 👇

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