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

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

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

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

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

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

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

• 6 open issues — vs 417 closed.

• 14 open PRs — vs 306 closed.

• 1 day — average bug fix time.

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

• ~28 commits / day — on average.

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

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

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

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

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

Here is the agenda for today:

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

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

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

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

Let’s dive in!

🚥 Guides, Gates and Guards

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

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

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

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

These steps are also somewhat sequential:

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

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

• Guards are the last line of defense against enshittification.

Let’s look at all of them:

1) Guides ↪️

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

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

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

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

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

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

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

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

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

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

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

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

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

Read more

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

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

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

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

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

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

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

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

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

5. 🔀 Staged automation of a complex upstream merge

Let’s dive in!

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

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

Subscribe now

1) 🚜 The combine harvester pattern for long AI tasks

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

The markdown file holds:

• The instructions

• The progress so far

• What should happen next

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

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

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

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

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

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

I call these guards.

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

But there are things that are hard to gate:

• Did this change need an architecture decision record?

• Has an opportunity to refactor been missed?

• Is performance drifting over time?

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

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

Read more

During these chats, the most recurring questions I receive are not about the tool itself, but about how to organize information.

People understand the tool: types, relationships, views, etc — but are not sure about what types to create, how to connect them together, and what the regular maintenance of all of this looks like.

To help with this, today I am introducing Portent — an open spec for organizing knowledge bases, for work and life.

Portent provides strong defaults for the three key aspects of a knowledge base:

• Structures — how information is organized into different buckets, whether it’s types, folders, or else.

• Relationships — how such structures are connected and related to one another.

• Lifecycle — how information flows and is operated.

Portent was built with a few goals in mind:

• Convention over configuration — Portent is like the Rails of knowledge bases. Gives you sane defaults, but keeps you free to extend / change whatever you like.

• Usable with any tool — while Portent concepts are first-class citizens in Tolaria, they can be easily implemented in any knowledge mgmt tool.

• Combine life and work — create knowledge bases that blend personal and work data, over the same underlying type system.

• Flexible and extensible — Portent is easy to change and extend, and does not corner users into rigid schemas.

So let’s dive into this. Here is the agenda:

• 📖 Backstory — or why you should trust me on this

• 🍱 Types — the eight main types

• 🔀 Relationships — for knowledge, think graph instead of relational

• 🔄 Lifecycle — capture → organize → archive

• 🔌 Extending Portent — how to add more things, and what you may add.

• 🔨 Tolaria implementation — how to do this in Tolaria. Spoiler: there is a template.

Quick heads up! On June 2nd and 3rd I will be at LDX3 in London, where I will interview the one and only Rands, live on stage.

I love LeadDev conferences and I go every year. If you are thinking of coming, you can use the code LUCA15 to get 15% off the tickets! No affiliation — I don’t get any money from this.

Hope to see many friends there and say hi!

📹 Walkthrough

If you prefer watching instead of reading, here is my walkthrough of the Portent template 👇

📖 Backstory

Portent is the result of many years of work, and, just like with Tolaria, it feels that a lot of what I have done in my life has led to this:

• 2011: PhD — in 2011 I started a PhD to study non-relational databases and how their data models could be mapped one onto another. That started my obsession with organizing information. I later dropped out of my PhD to start a startup 👇

• 2017: Startup — we had one of the very first Notion workspaces in Italy, back in 2017. As CTO I created templates about how to organize work that were later adopted by many others, and personally coached several startups about how to organize work.

• 2020: Building a Second Brain — in 2020 I got in touch with the ideas from Tiago Forte, Sonke Ahrens, all the personal knowledge management literature, and started trying to take the best of it and applying to actual work knowledge.

• 2021: Refactoring — my creator work stressed these ideas to the limit and led to a substantial revision to allow 1) more productivity (write 3 newsletters / week), and 2) blend of personal and work data.

• 2025: AI & Tolaria — as I started working on Tolaria, I further revised how these concepts could be mapped cleanly into Types and Relationships, and optimized for AI collaboration.

So I am very opinionated about all of this, but I am also wary that this is a very personal topic, so any system should be:

• Small — only include what I am 100% sure it’s good, and not more.

• Flexible — to accommodate for personal tweaks and preferences.

The best analogy I can find is that Portent is like Rails for knowledge bases: turnkey if you want to, but infinitely customizable if you want to get your hands dirty.

🍱 Types

Portent recommends organizing data into eight main types:

1. Projects

2. Operations

3. Responsibilities

4. Tasks

5. Events

6. Notes

7. Topics

8. People

The name Portent itself is an acronym for the first seven types. Plus there’s people at the end, so it’s technically PORTENTP — but bear with me!

These types are grouped into two clean categories:

• PORT — the actionable types: Projects, Operations, Responsibilities, Tasks.

• ENT(P) — the non-actionable types: Events, Notes, Topics, People.

PORT organizes things to do, while ENTP organizes inert, non-actionable things.

🔥 PORT

PORT is by far the most important part of Portent. I believe the best way to organize a piece of information is downstream of asking: what should I do with it?

You are going to ask yourself this question all the time, so in order to give good answers, you need a good way to organize things to do. And when I say “things to do” it’s not necessarily work — it’s also personal life. The mental model is the same.

The most useful way I have found to categorize work is to do so along two axes:

• 📏 Size — whether work can be completed in one sitting or not.

• 🔄 Recurrence — whether work is one-and-done, or recurring.

Based on this, we can have four types of work:

Responsibilities

Responsibilities are recurring work that can’t be completed in one sitting.

They are good for modeling long-running areas for which you need to keep a standard.

Responsibilities don’t usually have fixed goals, because they are long-running — they rather have metrics or KPIs that tell you you are going in the right direction.

Examples: “stay in good shape”, or “ensure good product retention”.

Projects

Projects are one-and-done work that can’t be completed in one sitting. They have a beginning and an end, and a clear definition of done.

They can belong to a responsibility. E.g. if your “ensure good product retention” responsibility measures the NPS of your product, a quarter project might be about a beloved feature that people have been asking since forever, that is expected to improve that.

Or if you measure “stay in good shape” with your VO2 max, a quarter project might be to start playing Padel twice a week, and get your VO2 max from X to Y.

Operations

Operations are recurring work that can be completed in one sitting. They are procedures that are repeated always the same way, for which there is ideally a set of instructions.

Operations can belong to Responsibilities and Projects. E.g. in your “stay in good shape” responsibility, you might have an operation that describes your weight-lifting routine.

Or for a Project that is about a new product feature, you might have an Operation for the “Weekly Review” of how the development is going.

Operations are also, as of today, the biggest surface of collaboration with AI agents. Agents deliver a ton of value by owning procedures, that is, performing the same set of actions on a recurring basis.

Tasks

Tasks are one-and-done work that can be completed in one sitting. These are important to be defined this way and to be included in the general framework, but I actually do not encourage storing them in the knowledge base.

I am not completely against it either, but I generally believe tasks are better suited to being managed by a dedicated separate tool. For two reasons:

• Ephemeral — once a task is done, there is no big value in keeping it in the base. Any learning coming from the task should be stored in a separate note anyway.

• Specialized — tasks often require specialized interaction: due dates, status, kanban boards — all things that are better served by dedicated tools.

So yeah, it’s not bad to store tasks in a Portent base per se, but you are probably not going to get a lot out of it either.

🌱 ENTP

ENTP types are for information that doesn’t need action. Litmus test is: if it needs a status, it’s probably a PORT, otherwise, it’s an ENTP.

Let’s look at them one by one:

Topics

Topics are categories that have no expectations of action. They are simply topics of interest, that may or may not be useful in the future.

E.g. I like sim racing, and I often save links with gear or tutorials, but I have no projects or responsibilities about it, so it’s just a topic for me.

Or, at work, I may want to save useful resources about databases, but it’s not like I have a responsibility about that. Could just be useful in the future, so I create notes and set them as related to the databases topic.

Events

Events are things that happen. They are useful for mapping meetings, achievements, and calendar things.

People

People are pretty self-explanatory. You can attach people to pretty much any of the types above, and when done well, it’s like building a CRM.

Notes

Finally, Note is simply the default type. When you create a new item, it’s a Note first — and it stays so in absence of a better type for it.

Now, once you have the types in place, how do you connect them together?

🔀 Relationships

I believe the best way to model information relationships in a knowledge base is via a very small set of graph-style connections.

Portent encourages two in particular:

• Belongs to — strong relationship: owner, composition, usually in a one-to-many fashion.

• Related to — weak relationship: many-to-many, does not demand action.

Based on how you implement these, you can also compute the inverted versions, whose default names in Portent are:

• Belongs to → Has, or Children

• Related to → Referred By

The way you assign these relationships is up to you, but I have found that a good default mental model is:

• Use belongs to for relationships towards or between PORT items — e.g. an Operation belongs to a broader Responsibility, a meeting (Event) or a Note belongs to a Project.

• Use related to for relationships between ENTP items — e.g. an Event is related to a Person, a Note is related to a Topic, and so on.

An important upside of a relationships (and not only type) system, is that relationships stay the same across the whole knowledge base.

To understand why this matters, let’s look at alternative ways to model relationships, via the two most common ways: relational databases (tabular data), and folders (hierarchical data).

1) Relational DBs (tabular data)

In a relational model, like Postgres, or Notion databases, you need to define explicit relationships between each couple of tables you want to connect.

These relationships create a schema that is:

• Big — you end up recreating the same concepts across tables even if they semantically mean the same thing, and

• Rigid — enforced and hard to change once data is in place.

The upside is that data always stays strongly consistent and adherent to the schema.

2) Folders (hierarchical data)

With folders, every item (folder or note) can only belong to one folder. This massively limits the semantics that you can express via folder structures, which basically can only model strong, exclusive ownership relationships.

E.g. if you want meeting notes to sit in a “meeting notes” folder but also be included in the respective project folders, you can’t.

The upside of folders is that they make traversal extremely easy — as long as it’s done along the intended path.

3) Graph relationships

Portent’s take is that the upsides of relational and hierarchical models don’t matter nearly as much as in the past now that we have AI.

In fact:

1. Once most information can be organized by AI agents, consistency can be enforced easily even in the absence of a deterministic way to do it with software.

2. Folder traversal simply doesn’t matter in a world where agents can grep and fetch anything.

If we agree on this, simple default relationships work and scale better than anything else, because they create:

• Less semantic surface — easier to understand for both humans and AI, because it’s the same concepts everywhere.

• Cross-type meaning — easier to work across multiple types (e.g. find all “orphaned” notes == those that have no belongs_to and no related_to)

None of this is exactly new: graph DBs have been doing this since forever — I only argue this is the best way to build knowledge bases, especially now that we have AI.

Next, let’s talk of lifecycle 👇

🔄 Lifecycle

A common problem with knowledge bases is that it’s hard to keep them clean, understandable, and up to date. Portent encourages users to manage notes in three steps: Capture, Organize, and Archive.

These can be implemented as a status property for every note, and are meant to be enforced by your workflow somehow.

More on each:

1) Capture

The capture stage is only meant to make information available. Save that link for later, store those meetings notes, write down that thought in a random note.

Captured notes are not clean nor tidy: they are a mess, and intentionally so. The capture stage is optimized for speed: just capture everything, and then we’ll see.

2) Organize

Once a note is captured, you have to ask yourself two questions about it:

• What is this?

• What should I do with it?

The first question drives type selection, while the second drives what relationships to create for it.

If you can’t attach any Project, Responsibility, Operation, or Topic to a note, then it means you can probably trash it. It’s totally fine to capture things and then realize it was a mistake: capture things optimistically, and organize pessimistically.

I organize my captured notes once a week, and I implemented this workflow directly in Tolaria, where the default section is the “Inbox” (aka not organized) list of notes, and you can flag any note as “organized” with cmd+E.

3) Archive

An underrated part of what makes for a good knowledge base is separating current from obsolete information. The latter can still be useful — think past projects, old meeting notes, etc — but you don’t want them to show up in your regular usage.

You should have a clear way to mark notes as “archived”, so that humans and AI can ignore them by default.

🔌 Extending Portent

These are the basic concepts in Portent, but are not meant to be the only ones that live in your knowledge base.

Once you have understood the basics (organization based on actionability, simple relationships, capture vs organize, etc), it’s easy to extend them and add more concepts.

Common ones in my experience are:

• Calendar types — like years, quarters, and months. These are extremely clear concepts that will not pollute your base, and can be used to anchor and group things like projects, events, and more.

• Teams / areas — it’s useful sometimes to create larger groupings that represent domain or ownership areas, and attach PORT items to those.

• Note types — you may want to “split” the Note type into more ones: videos, resources, articles, etc. I am a fan of doing that with tag properties, instead of “root” Types, but you can do it either way.

• Specialized relationships — once you are sure about your model, it can be great to create a few specific relationships to disambiguate the use of the default ones.

And of course it’s useful to create types that map to the domain language of your use cases. E.g. I write a newsletter and I have types for the Essays I write, Evergreen notes, Podcast interviews, and more.

🔨 Tolaria implementation

Portent can be implemented in any note taking system, but has special support in Tolaria.

I created a Portent template vault here, that you can clone and use in Tolaria.

Tolaria is good for Portent because:

1) Lifecycle management

Capture → Organize → Archive is directly supported in Tolaria:

• The Inbox section shows all notes that haven’t been organized yet

• You can organize a note with cmd+E or the organize button in the editor bar

• You can archive a note with the archive button, and it will hide from the default sections.

2) Types & Relationships

Tolaria is natively organized into Types and Relationships, and it suggests default relationships that are exactly the Portent ones.

3) Multiple vaults

If you want to use the same type system (Portent) for both life and work, you can create separate vaults and mount them together inside Tolaria for you to see, while maintaining separate access control for e.g. your co-workers.

And that’s it for today! As always, let me know your thoughts on all of this!

I wish you a great week

Sincerely 👋
Luca

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

Refactoring is read every week by 170,000+ engineers and managers from all over the world 🙏🙇‍♂️

Hey there! Last week’s article about my workflows for Tolaria went incredibly well, and I got a ton of replies and questions via email.

One of the most recurring ones was: what’s next? How would you improve this?

Happy to answer. I have been building AI workflows for a while now, and, for the most part, I have done so in “100% AI mode” — that is, I tell an agent to do something recurringly, in natural language, and they do it.

These workflows are fast to ship and *mostly* work, but also have pretty obvious drawbacks, that I would love to discuss today.

I believe this is relevant because these days we are inundated by stories like: “n8n is dead!”, “it’s all agents calling agents!”, and so on, while reality is more complicated.

I also bounced a lot of ideas off with the team at Kestra, who runs an awesome open source platform for orchestrating workflows. Their help came at the perfect time, and we basically wrote this piece together.

So here is the agenda:

• 🧹 Cleaning up releases — starting from a real-world example.

• ⚖️ AI vs Orchestration — mapping pros and cons of how to run workflows.

• 🏗️ Agents as scaffolding — a useful mental model about going AI first, but gradually replacing it with code.

• 🗺️ Workflow engineering journey — a maturity model for developing your workflows.

Let’s dive in!

Disclaimer: I am thankful to Kestra for partnering on this piece 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 unbiased opinion on the practices and tools covered, Kestra included.

🧹 Cleaning up releases

To stay grounded and make you understand what I mean when I say workflows, let’s take a practical example. Whenever I create a new stable release for Tolaria, I have an automation to take care of the release’s aftermath.

This includes fetching all the bug fixes and feature requests that were shipped in the release, and update/close them in the respective channels, notifying the relevant users.

This is not rocket science by any means, but it involves a number of steps:

1. Fetch Github commits shipped with release

2. Match commits to the associated tasks on Todoist

3. For each task, retrieve the original entry either on Github Issues, or the Canny product board

4. For each Github issue, leave a comment saying this is fixed in the latest release, and close the issue

5. For each Canny item, leave a comment explaining how this was implemented in the latest release, and close the item

6. Finally, create short descriptive release notes to be attached to the release page.

The first version of this was entirely run by AI. No scripts — just a few high-level skills about how to access Github Issues, Canny, and Todoist — and natural language instructions about what needed to happen.

This mostly works. Sure, it is slow and expensive, but that’s forgivable given that I need to run it at most once per day. The problems come when it doesn’t work for any reason.

Say Github issues are not available at that specific time (ofc fantasy example given Github’s immaculate availability lately), or the run times out, or your favorite AI provider rate limits you in that very moment.

At that point the workflow fails, and it typically does so in the worst possible way: 1) silently, 2) leaving things in a dirty state, and 3) without any retry or recovery.

Of course you may build all of these into the procedure somehow, but if you find yourself manually plumbing standard ideas about how we have been running workflows since... forever, you should probably stop and ask yourself if there is a better way.

So let’s take a step back and think through this from first principles.

⚖️ Pure AI vs Orchestration

The tradeoffs between pure AI workflows (e.g. cron jobs on OpenClaw) and orchestration platforms a-la Kestra, resemble a lot those between AI and deterministic software.

AI is incredibly smart, but also incredibly expensive and slow. A lot of work just doesn’t need those smarts. Routing, retries, conditionals, scheduling — there is just a lot of plumbing that can be done in a purely deterministic way, saving time & money.

Also, traditional orchestration doesn’t only win on time and money: it is often a better choice full stop when you account for:

• Observability — you can’t debug pure LLM reasoning, as you can instead with workflow steps that are explicit and isolated. Also you get execution history, stats, and much more.

• Reliability — scheduling, resiliency, recovery from failures. This should be all built-in.

• Scalability — this is probably not a factor on its own, but more the result of all of the above combined. Being able to scale requires reliability, observability, low latency, and so on.

So where do we go from here?

🏗️ Agents as scaffolding

A few weeks ago, Will Larson published an awesome piece about using agents as scaffolding for recurring tasks, which means: a useful first pass to discover what the workflow should be.

Then, once the pattern is known, you should extract and harden as much as you can into deterministic code. So agentic steps are largely used as ‌prototyping tools, not permanent infrastructure.

This doesn’t mean eventually replacing all of the AI, but rather only using AI for the right things. With some degree of simplification:

• Orchestration wins at all-things-infra — observability, reliability, human-in-the-loop approvals, structured output validation, and so on.

• AI wins at the messy stuff — classification, summarization, judgment calls, and all the things you can’t write code for.

I love this take, and I think we can expand it into an actual maturity journey 👇

🗺️ Workflow engineering journey

Based on this, a natural progression may look like this:

1. Agent-first — everything in a loop, fast to prototype, but opaque to debug.

2. Isolate the deterministic parts — pull out the boring steps (fetch, validate, store, etc) into explicit code. Keep AI for judgment calls.

3. Structured orchestration — proper DAG / event-driven layer with retries, lineage, observability. AI becomes one task type among many.

4. AI-driven composability — LLMs generate or modify the workflow definitions themselves. The orchestration layer is stable enough to be a target for code generation.

I am particularly bullish about #4 because, when you think about it, it is a way to get the best of both worlds: you prompt the AI in natural language as you would for normal agentic workflows, but the AI actually turns that into structured, semi-deterministic work.

A quick plug to Kestra on this, which I am a big fan of. Because if you agree with these steps, a natural question becomes: what should an orchestration platform look like to enable AI to operate it? Kestra checks a lot of my boxes:

• Code-first — the AI should be able to write workflows in a declarative fashion, with code, because that’s what it’s best at (as opposed to e.g. GUIs).

• API/CLI first — trigger executions and manage workflows through API

• Open source — these days, considering the speed tech is moving at, I put a lot of value on the tools I use being open source, so we can evolve them faster as a community, in the open, and there is less lock-in.

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

Sincerely 👋
Luca

I did that to solve my own problems and to get my hands dirty with AI coding. In other words, I wanted to walk the talk, and then write about it here on Refactoring.

Little did I know this would feel more like speedrunning the talk.

Tolaria has now several thousand daily users, 10K stars on Github, and last week it was the 10th fastest growing repo… in the world, as measured by Star History.

To put things in context, there are only about ~5K repos in the world with more than 10K stars, out of ~30M.

This is of course, incredibly flattering and energizing, but I also joked with friends that I have been glued to my chair non-stop for these two weeks, because all this interest also posed very real operational problems.

Users, in fact, who are mostly engineers, contributed hard — and I am glad they did! As of today, Tolaria has received:

• 200+ issues on Github

• 150+ PRs

• 150+ feature requests on Canny

So I had to create workflows to help handle all of this: to ensure issues would be fixed fast and people would get feedback about ideas and contributions.

Fast forward to today, I am pretty happy with how it is going, and as I write this, we are down to:

• 15 open issues

• 11 PRs

• 81 feature requests

Today’s newsletter covers all these workflows and how I “survived” these two weeks, while only working part-time on Tolaria, and the rest of the time on Refactoring — in the meantime I also had to publish 4 newsletter editions and 2 podcast episodes.

So here is the agenda:

• 📥 Inputs — mapping and normalizing sources and channels.

• 🗃️ Backlog — turning everything into a single prioritized list from which agents can take work.

• 🔍 Validation — is it the one true bottleneck, as everyone is fond of saying these days?

• 🚀 Release — making work available to everyone and updating all the input sources.

• 📊 Analytics — tracing what happens in production.

Let’s dive in!

📥 Inputs

I have never maintained a sizable open source project before, so you’ll forgive me if some of what I am about to say will sound trivial to you.

At any given time, there are several types of inputs Tolaria receives, that can spawn work to be done:

1. Bug reports from users

2. Feature requests from users

3. PRs from contributors

4. Crash reports from telemetry (Sentry)

5. My own ideas (hello 👋)

These are all separate channels but, with some degree of simplification, they spawn two types of work: bugs and features.

More specifically:

• #1 and #4 spawn bugs

• #2 and #5 spawn features.

• #3 (PRs) can spawn either, but mostly features.

#1, #2, and #3 originally all lived in Github Issues, but bugs and feature requests have different needs and deserve to live in separate places. In fact:

• Bugs — only need to be replicated and squashed as soon as possible. I am a strong believer in a zero-bugs policy: catching bugs as soon as they are reported, and fixing them all ASAP. All in all, there is very little to decide about bugs.

• Feature requests — are another story. They benefit from being voted on (you want to see how many people want something), are generally bigger, so you may want to flag things as planned or in progress so users are notified, need to be specced, and, of course, you don’t want to build those that don’t match your vision. That’s a lot more to decide.

From a workflow standpoint, bugs are easy, features are not — which is why today we are down to only 15 open bugs out of 200, but still 80+ open feature requests out of 150.

The way I manage this is by keeping bugs on Github Issues, and feature requests on a separate product board on Canny.

To make people understand this, I created a rich “contribute” panel inside Tolaria where you are routed to different places based on how you want to help:

Still a lot of things go wrong all the time:

Read more

Today I am back with the third and last article in our Software Factory series, written together with my friend Rob Zuber, CTO at CircleCI.

Before this one we published:

1. The Era of the Software Factory

2. How to Grow your Software Factory

Why three articles? Because we like to work from first principles:

In the first article we established (with actual data) that teams that are getting far with AI are doing so thanks to good DX. The same teams that had good DX three years ago, are now winning the AI race: those at the 90th percentile are shipping >2x faster than before.

In the second article we said: ok, but once you have good DX, how do you create leverage with AI? And we laid out a plan in three steps:

1. 📋 Specs — start by writing good, detailed instructions about things to be done. E.g. “create a button that has the following specs […]”

2. 📚 Rules — turn specs into reusable rules for the AI to follow. This is when you can say to the AI: “create a button using our rules for creating buttons”.

3. 🧩 Modules — is the final stage, when AI can reuse code directly, instead of rules, and you can simply say: “create a primary button”

This seems good enough, so why a third article?

Because if you do all of the above right, your outcome will be: a solid dev process, in which AI produces good enough work to be shipped.

Now, while this seems like an ambitious target already, I still think we should aim higher.

To understand why this matters, we need to take a step back and reflect on engineering teams before AI. Here is the agenda for today:

• 📉 The default path is degradation — the uncomfortable reality of engineering teams so far.

• 🐛 What causes teams to degrade — talking about coding hygiene, capturing knowledge, and building the wrong things.

• 📈 How to get better instead of worse — how to invert the trend on each of these dimensions.

• 🎽 Empowering managers — this is peak manager territory. Let’s talk about what managers should really do today in the age of AI.

Let’s dive in!

As always, I want to thank Rob and the great CircleCI folks for partnering on this piece. I loved bouncing ideas off with them, and I am a fan of how they are trying to reinvent software validation for the AI era. You can learn more below 👇

Learn more about CircleCI

Disclaimer: in the article I only wrote my unbiased opinion about all practices and tools mentioned, CircleCI included

📉 The default path is degradation

Anyone who has worked in human software teams for years — teams that work on the same codebase over a long period of time, teams that grow, shrink, rotate, and do all the things that human teams do — knows that the default trajectory is not an improving one. It’s not even staying put.

Over time, the default is getting worse.

Codebases become a mess, large teams ship less than small teams (per engineer, but often as a whole), and products get shitty.

There are exceptions of course, but this is the reality of engineering for probably 90% of teams.

I think it’s exactly this bias, plus the fear of losing control over code, that makes us happy with AI just getting things right. Good enough. If we get moderately faster through this, and don’t degrade over time, that’s a victory already!

And that’s true, but what if we don’t stop there? What if the default becomes that things get better over time, instead of worse?

What if, for any change, instead of asking “is this good enough to ship?” we asked ourselves: “does this change make the next easier/safer/cheaper”?

In other words, a world in which, over time:

• The team gets faster — both individually and as a whole.

• AI gets more accurate — because tech and product get better understood.

• The codebase gets better — because of the aggregated understanding of the problem, the continuous refinement of the abstractions, and the collective time spent on making things right.

This has been discussed in recent times already, and often goes by the name of compound engineering — but it’s still unclear how to pull it off.

So today we are taking a stab at what real-world compound engineering might look like, based on the actual tools available, and our respective experience:

• Rob has the privileged vantage point of overseeing the workflows of tens of thousands of teams via CircleCI. CI is the crossroads through which most software activity has to go through, so it’s perfect to spot patterns, see what works, and what doesn’t.

• On my end, I have been building Tolaria for several months now (p.s. we got to 8K stars on Github!), have written 100K+ lines of code for it in over 2000 commits, and have developed strong opinions about the state of AI coding today.

🐛 What causes teams to degrade

I like to address problems by inversion, so to figure out how to make things get better, I like to start by reflecting on what makes them worse — and then avoid that!

We could spend weeks just debating this, but I’ll keep things simple and give you my top three candidates for what makes engineering teams (and products) degrade over time:

1) Coding hygiene

There is an obvious baseline of coding hygiene that helps keep things maintainable, like:

• 🔬 Good testing coverage — made of actual good tests (see Kent Beck’s desiderata)

• 🩺 Good code health — high cohesion, low cyclomatic complexity, small files, no bumpy roads, etc.

• 🧱 Good basic abstractions — that encapsulate domain language, instead of using language primitives all the time.

A key characteristic of coding hygiene is that it is largely domain agnostic. In fact, it can be easily evaluated by automatic tools that know nothing about your product.

It’s also, honestly, hard to maintain. Writing good tests is hard for a variety of reasons, they pose nasty tradeoffs and cause endless fights for time to market. Good code health is easier said than done, and even basic abstractions are often challenging.

So I empathize with teams that struggle with these — but nevertheless, these are the basics. What comes next is harder.

2) Capturing knowledge

If there is a single thing that compounds in life, it is knowledge. Knowledge is leverage, and teams are generally very bad at capturing and growing their collective knowledge.

First of all, they capture very little: no records of their decisions, no snapshots of what exists today (in whatever format), no vision/mission statements.

Also, most often no playbooks on how to do things: from designing features, to coding specific parts of the product, to operating systems in prod.

Again, I am not faulting anyone for this. Writing things down is hard, and keeping them updated is even harder.

3) Building the wrong thing

As a result of dubious knowledge + poor hygiene, we often end up building the wrong things.

And the more wrong things we build, the harder it becomes to steer a codebase, because of little residual design space (from bad abstractions), little confidence in changes (from little testing), and so on.

Again, these are all things that, by default, get worse with time. We know this from research. Large and old orgs, vs small and young ones, perform worse on all dimensions:

• Code health is worse.

• Institutional knowledge is less shared.

• Product moves slower.

So how do we not only stop the trend, but invert it? Let’s take on these one by one 👇

🔬 Improving code hygiene

As a result of AI writing the code, you can—and should—enforce it to write good code.

In my experience, you can do so by combining:

• Rules and skills — about what the agent should do (e.g. always write tests) and how it should do it (e.g. what makes for a good test?)

• Gates — agents often simply ignore rules, so you need gates that enforce these rules. Code health above X, test coverage above Y, and so on.

There are a ton of tools today that can automatically check for anything you can think of, and I am personally a fan of integrating them both in the CI (as usual), and as local hooks (e.g. with Husky), to shift things left and let AI find problems earlier. Rob believes this is where validation infra needs to go: creating environments fast enough, real enough, and context-aware enough for agents to validate against before code reaches shared infrastructure.

There is also hygiene work that comes from regular maintenance, after the code is in prod. This is classic KTLO, from updating dependencies, to fixing small bugs, investigating failures in logs, and more.

This is all work where today AI can give you an incredible hand. What used to be recurring grunt work for your team, can turn into recurring automations that lead to PR drafts. You can create some for:

• Proposing dependency updates

• Scanning for security vulnerabilities, from well-known online lists

• Fetch insights from Sentry and your instrumentation to auto-fix bugs before you are even aware of them

Personally, for Tolaria I have a hourly automation that:

• Scans Sentry logs and Github issues reported by users

• Investigates and tries to reproduce them

• When considered worth it, it creates tasks for the Codex/Claude queue

• Bug tasks (as opposed to features) are automatically taken in charge and a fix is drafted for me to review.

Is this perfect? No. Does it create duplicates, false positives, or simply interpret things wrong? Yes! But does it help reduce my cognitive load and effort on these? Absolutely!

📚 Capturing knowledge

AI is fantastic at summarizing, expanding, moving, and overall processing content — but only if you capture it first!

And today, frankly, you should capture just about everything, exactly because of how cheap it is to process and maintain such information.

So you should capture:

• Raw inputs — like meetings, brainstorming docs, things where you are diverging, not converging.

• Decisions — e.g. ADRs in tech, but also product insights, directions you decided to go, and all the whys that the AI can’t figure out by itself by simply looking at the what.

• What exists today — I call these recap docs, because I believe they should be built as summaries of smaller, atomic things. You can put together a big ARCHITECTURE.md doc as a combination of the ADRs, or the product version of it by combining PRDs and specs. This is 100% AI territory today: you provide human input about single features, but leave the plumbing around content orchestration to the AI.

All this stuff needs workflows to be created to capture data, process it, keep it in sync, and so on — but honestly, it’s all easy! We are engineers! And the leverage over time is incredible. So there is zero excuse not to do so.

🔨 Building the right thing

If you do the above right, the result will be building more right things, as opposed to wrong things:

• Things that build nicely on top of what already exists

• Things that are coherent with past decisions

• Things that work and do not degrade your codebase

Above all, things that actually improve your codebase — because they record more decisions, say no to the things that are wrong, and yes to those that are right.

And those no’s and yeses stay there to help make better decisions in the future.

Also, such compounding can and should happen in all of your environment, not just the codebase: build history, pipeline patterns, team context, baked in and available over time, so agents can validate more, debug better, assess if code runs, and, most of all, if they are building the right things.

🎽 Empowering managers

I want to close by spending a few words about managers, who are often neglected in this AI conversation.

“Managers are in trouble”, “AI is for builders”, “everyone is back to coding”, and so on.

Guys, all the stuff we discussed is peak manager work.

I have interviewed a lot of engineering managers on the podcast, and often asked them what’s the hardest part of their job. One of the common responses is: “the feedback loop is slow”.

Think about it. When you are an engineer, your feedback loop is: you write a feature, see that it works, if not you iterate, push it, possibly iterate on reviews, and it’s done. This is all extremely fast (even if it might not feel like so!).

Now compare it with the feedback loop of a manager who is trying to improve how sprint planning works. Or performance reviews. Or their team’s velocity. Any change you make to the process needs to be measured on a scale of several weeks, or months. And in many cases, what do you even measure?

Agent workflows are amazing for managers to operate because it’s like their normal work… on timelapse. Even if the agents are not that good, make mistakes, or trip over themselves, it doesn’t matter as long as they are fast and managers can course-correct quickly.

So if it is true that all engineers are becoming kinda like managers now, it’s also true that motivated managers can have some upper hand because, well, they are already managers!

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

Sincerely 👋
Luca

Check out Tolaria 💧

What is Tolaria?

Tolaria is a desktop app for Mac for managing markdown knowledge bases. In a way, it’s my own version of Karpathy’s LLM wiki.

I have a close circle of friends who have been using it over the past few weeks, and they use it to operate:

• Second brains and personal knowledge

• Company docs as context for AI

• OpenClaw / assistants memory and procedures

Personally, I use it to run my life and work.

I have a massive workspace of 10,000+ notes, which are the result of 6 years of Refactoring work + a ton of personal journaling and second braining.

Earlier this year I decided to migrate everything from Notion to markdown files for a variety of reasons (speed, control, better AI work), but I missed an app that allowed me to operate these files with a UX that fit my brain — so I built it!

So, this newsletter will explain a few things:

• 📹 Walkthroughs — how I use Tolaria for various stuff.

• 🌀 Tolaria + Refactoring — how Tolaria fits the broader Refactoring picture, and my life.

• ⭐ Tolaria Principles — things I believe in, on top of which Tolaria is built.

• 🔧 How Tolaria works — the main parts.

• 🔬 What you will find in the repo — interesting stuff you may look at.

Also, as I wrote before, I commit to keeping you posted about my AI coding workflow, and I will use Tolaria and its repo as a living artifact of how I create software with AI, trying to staying on the frontier of what’s possible, trying new things, and so on.

Tolaria will stay free forever, but if you want to stay posted with these explorations and support my work, consider subscribing to the paid version of Refactoring 👇

Subscribe now

p.s. we’ve recently launched our AI Club and will run the first edition next month. I’d love to see you there!

📹 Walkthroughs

Before you move further, you can find some Loom walkthroughs below — they are short and to the point:

• How I Organize My Own Tolaria Workspace

• My Inbox Workflow

• How I Save Web Resources into Tolaria

I recorded them because I think it’s way easier to see things in action than to read long explainers. So if you like what you see, you can continue reading below 👇

🌀 Tolaria + Refactoring

In this time of rapid change, deciding how I spend my time feels like a big deal. Tolaria is taking a lot of it, so it needs to be worth it, and I think it is.

With Refactoring I write about how to create good software — that’s how I literally make a living. Over the last few years I have done that largely by 1) doing research and 2) talking with the smartest people I knew.

With everything that’s happening with AI, this is not enough anymore.

Everyone needs hands-on work to understand what’s really happening, and form opinions that are not mediated by other people’s experience.

Also, in order to make for good evidence, such work needs to be ambitious. Side projects are nice, but can we build real, complex software with AI, without writing a single line of code? What about without reading it? Does it scale? Or do we drift into chaos?

So far, it scales.

Tolaria is not massive, but at this point it is not small either. By the numbers:

• 100K lines of code, in Rust + React.

• 1900+ commits

• 3000+ tests

• 70 ADRs

I have written more about how I work on it in this recent piece.

So, my commitment with Tolaria is the following:

• I will keep it free & open source forever.

• I will run my life and business on it.

• I will work 2+ hours / day on it to develop new things, fix problems, and make it useful for people other than myself.

• I will do as much of the work as possible with AI, trying to live in the future.

• I will keep you posted on Refactoring about this process.

In a nutshell, the goal is to work on the frontier and report back to you.

⭐ Principles

So, what is Tolaria about? When I speak with friends, jokingly I say that it’s like Notion, but offline, and for actual files. This is not 100% correct, but it’s a good starting point.

Tolaria is based on a simple belief: AI delivers the biggest benefits to those who are able to capture and organize context — whether it’s about their lives or work.

We often talk about “knowledge” management but it’s not only about knowledge: it’s about projects, goals, thoughts, relationships, and everything that happens in your lives. The more you can capture (and organize properly), the more AI can be useful to you.

Such material is, potentially, our most precious asset. We’ll want to keep it tidy, up to date, and most of all, under our control.

Keeping it under our control means not being locked into a specific tool or AI platform. It means being able to switch to different AIs by snapping your fingers, or using multiple ones together on the same collaboration surface.

You may want your Claude Code to do some autonomous research and write its findings, while your OpenClaw fetches your latest meeting notes and turns them into a doc, all while you write manually in your journal, or capture a valuable idea into an evergreen note.

This should all be possible and be backed by the same knowledge base.

Based on this, here is how I think such a knowledge base should work:

• Files — because of 1) portability, 2) offline work, and 3) how AI is massively good at working with them, files are an obvious choice for a knowledge base.

• Markdown — md has surfaced as the de-facto standard for documents in the AI era. And you can easily extend it with a YAML frontmatter to store structured properties

• Git — by using files, version control is an obvious fit. This is useful for 1) history, for 2) cloud sync, and for 3) tracking authorship of changes, especially in a world where humans and AI collaborate.

• Open source — if the goal is full & long-term portability, the app you use to operate your knowledge should stay under your control.

While the above items are the *core *principles, there are a few others I strongly believe in:

• Rich UX — there are a lot of markdown editors out there who are simply… editors. This just doesn’t cut it when you have a lot of notes and need to operate years of content. You need relationships, visual cues, navigation, colors, icons, stuff that tells you at a glance what a note is, where it lives, and so on.

• Keyboard-first — I am a developer at heart, so the more I can do via the keyboard, the better. In Tolaria there are shortcuts and commands for everything, and tab navigation works well, so you never need the mouse.

• Opinions — capturing and organizing knowledge is hard, so I will bring my point of view about it. When you do something every day, you need UX that is optimized for that, and you can only achieve that if your tool has opinions. Tolaria has many!

🔧 How Tolaria works

Tolaria is organized into a few main components:

1. Sidebar — for filtering notes in various ways

2. Note list — for displaying the list of notes that match the current selection in the sidebar

3. Editor — for editing the current note.

4. Status bar — for changing vault, check Git status, AI status, and handy stuff

Let’s look at each of these 👇

1) Sidebar

One of the core things you want to do when you have a lot of notes, is looking at just a subset of them at a time, based on various criteria.

Tolaria allows you to do so in many ways:

📥 Inbox

Notes that haven’t been organized yet.

This is inspired by Tiago Forte‘s concept of separating capture from organize. An “organized” note is a note that you know what you will do with. It may belong to a project, to a responsibility, a topic, or any concept related to how you organize work.

Review your inbox (e.g.) weekly to keep it from growing too large. You can disable the Inbox in Settings cmd+,) if you don’t like this workflow.

You can flag a note as organized by clicking on the “check” icon in the breadcrumbs bar, or with cmd+e.

🗃️ All Notes

As the name suggests, that’s the entire vault — every single note.

📦 Archive

A permanent home for notes you don’t want to delete but don’t want to see regularly. Archive aggressively to keep your vault clean. Archived notes still appear in search results, but not in sidebar sections.

🧩 Types

The main organizational device in Tolaria. Each note has a type, which by default is Note.

Each type can have its own icon and color, which you can change by right-clicking on it in the sidebar, or manually changing it in the properties or frontmatter of the type file.

Types are simply stored as markdown files, like Topic, or Project.

Click any type on the sidebar to see all notes of that type in the note list.

⭐ Favorites

Notes you’ve manually pinned to keep them top-of-mind. Great for active projects, journal entries, or reference notes you access frequently.

You can reorder them by dragging them in the sidebar.

Toggle a favorite note from the ⭐ button in the breadcrumbs bar, or with cmd+d .

🔍 Views

You can create custom views that filter notes by complex, nested criteria. The view editor fetches all available properties, plus allows for some tricks (like regexes and natural language dates)

Views are simple yaml files that get stored in the views folder. They can be edited easily and even created by the AI 👇

name: Active Projects
icon: 🚀
filters:
  all:
  - field: type
    op: equals
    value: Project
  - field: Status
    op: equals
    value: Active
  - any:
    - field: status
      op: equals
      value: active
    - field: date
      op: after
      value: in 1 week

📂 Folders

Tolaria stores notes in the root of the vault by default, but also scans your vault’s folder structure, which you can navigate at the bottom of the sidebar.

Folders are listed last because they are a secondary organization method—not the primary one.

🗑️ Trash

There is no trash bin, when you delete a note, it’s gone — but your git history is your safety net. You can always recover deleted notes from git if needed.

2) Note list

The note list shows the subset of notes selected by the current sidebar section. For example, clicking “Types → Project” shows all your Project notes.

⬇️ Sorting

You can sort the note list by any note property (they get dynamically loaded from the notes), plus file properties like modified and creation time.

Your choice will be remembered for that specific section.

💅 Display Properties

You can customize which properties appear as columns in the note list. This lets you see important metadata at a glance without opening individual notes.

For properties that are URLs or other notes, you can open them directly from the note list with cmd+click.

3) Editor

The editor is where you write and edit your notes. Tolaria supports two modes:

• WYSIWYG Mode — similar to Notion. Type naturally, use slash commands, and see the output directly formatted in the editor.

• Raw mode — shows the actual file characters. Access it with Cmd+/ or the code button in the breadcrumb bar. Useful when you need precise control over markdown syntax.

The note’s filename is always visible at the top of the editor. This keeps you aware of how the note will be named and linked.

A very important feature of the editor is the support for wikilinks. Type [[ to trigger autocomplete from your entire vault. This creates links to other notes, enabling the knowledge graph. Wikilinks also auto-update if the filename changes.

4) Git

Tolaria vault have first-class Git support and by default you retain fine control over it.

You can look at current changes and Git history from the status bar, create new commits and push them directly without ever leaving the app.

But if you don’t want to manage this manually, and want to use Git as a simple automatic sync layer, Tolaria also has an opt-in AutoGit mode in which it automatically creates commits and pushes changes after some time. It does so when the app gets idle, when you shift which app is in focus, and based on various heuristics.

5) Commands

One of Tolaria’s principles is being keyboard-first. Almost everything has shortcuts.

You can discover shortcuts from the mac menu and from tooltips on buttons.

A lot of actions also have a fall back or a quick way to do them via the command palette, which you can open with cmd+K

You can really do almost everything with it, including navigating to sections, creating new notes of a certain type, or perform routine actions.

You don’t even need to find the exact keywords — the palette is smart enough to match a lot of commands semantically:

🔬 What you will find in the repo

I will use this repo as a living artifact of how I do AI coding, for you to inspect at any time.

I have written exactly zero lines of code, out of the ~100K, and read very few of them. I am neither proud nor ashamed by it: it is what it is, and I would have never been able to build it otherwise.

Some interesting things that I haven’t seen too much elsewhere:

• The Architecture, Abstractions, and Getting Started docs — they have some overlap, but overall I feel they do a good job at capturing what the tech is about.

• The collection of ADRs — this is super useful, both for human review, and for AI to pick up on past decisions and what exists.

• The Vision doc — this is not super updated, but it is still useful to guide AI when we brainstorm new features.

Overall, this is a lot of context for the AI to inspect when you want it to do some “creative” task, like creating specs for new features, or making non-trivial tech choices, and dramatically increases the chances for it to get things right.

As of today I still review the ADRs and the changes to the main docs, but I find that AI gets these right >90% of the time.

➡️ Next Steps

If you download and install Tolaria, you will get the option of cloning a getting started vault that has examples and instructions. There is also a Feedback button in the status bar (bottom right) that gets you to Github issues, if you want to report anything.

Also feel free to reply to this email if you have any questions or just to let me know your thoughts! Please do! It’s been a ton of work and I absolutely want to know what you think about it 😄

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

Sincerely 👋
Luca

These are going to be monthly online gatherings where people can share wins and learnings from using AI, ask questions, and stay up to date about what works.

Join our AI Club 🪄

So today’s post is to explain 1) why I am starting it, and 2) how it works.

🎯 Why I am starting an AI Club

By now AI has taken over most of the online conversation about software engineering.

As I wrote last week, I think this is… largely correct. AI coding is so big and meaningful that figuring it out feels like the #1 priority for us as an industry. I don’t think we are misguided on this.

However, we are also in this very confusing stage where everyone is just trying things for themselves:

• Most teams have little-to-no shared practices / artifacts / ceremonies about AI.

• Opinions online are all over the place, and it’s hard to know who to trust.

• Most of us have very little time to try things out, and zero dedicated time at work to do so.

All of this against a backdrop of anxiety, layoffs, FOMO, and doomsday predictions.

Yay!

AI is also changing how I think about my responsibilities with Refactoring. It is changing the topics I cover, how I spend my time (I am back to coding, a lot), and the type of conversations I have with people.

So, Refactoring should help you run better engineering teams, and a big part of that now is about using AI well — together, as humans.

So I want to host good conversations about it, where people share what they are learning: the exciting wins, the humbling failures, and everything in between.

Sharing things with others not only makes us grow faster together — it’s also great to fight back against anxiety, impostor syndrome, and all the pressure that comes with the push for AI adoption.

So let’s use the Refactoring community as your extended team, where we compare notes and learn things together.

ℹ️ How it works

Here is the gist:

• Monthy 1-hour chat, hosted in the Refactoring Community.

• As with all-things-community, it’s for paid Refactoring members. We gate this to keep people committed and ensure high quality.

• Like our monthly mastermind, it’s facilitated by real engineering coaches, Joel and Melinda.

• I always join the call personally and share the things I have learned throughout the month

• Everyone who joins can share their own “aha” moments — a win, or just something that genuinely surprised them — ask questions, and get to know other community members

• Takeaways from the conversation are shared afterwards in the community in written form, for those who are not able to join.

• Finally, for paid Refactoring subscribers, in the newsletter I will also publish monthly AI updates that combine my own experiments with things that surfaced in community calls.

All in all it’s very simple. We’ll host the first one on May 8th, and we’ll always have them on the first Friday of the month, at rotating times to allow everyone to participate.

🔒 About the Refactoring subscription

Allow me a quick paragraph about the Refactoring subscription, which you might be considering joining.

It’s $15/month, or $150/year, to access the Refactoring community, all of our archive (300+ articles) carefully organized by topic, plus our weekly original long-forms about the latest and greatest engineering practices.

The community has bi-weekly events, professionally run, that alone would cost >$100 to join — each!

So if Refactoring helps you make just one better decision, thanks to something you read, or learned from someone in the community, chances are the subscription repaid itself for the full year.

I would love to have you onboard! 1500+ engineers have joined this already 👇

Join our AI Club 🪄

And that’s it for today!

Sincerely 👋
Luca

I received a lot of private comments, most of which can be organized into two categories:

• People wanting to learn more about the coding workflow itself.

• People wanting to learn more about the note-taking app I am building.

Both types of comments motivated me a lot, to the point where I decided to make all of this an official part of my Refactoring work, as follows:

• I am going to build this app for real, make it free and open source for everyone, and keep working on it as an ongoing effort.

• I am going to report my learnings about AI coding as part of the regular writing schedule, let’s say once a month or so.

I am convinced this is the right thing to do because, frankly, getting AI coding right is the #1 problem in software engineering today, and it’s not even close.

The economics of software are changing so much that there is no part of the process that is safe. Code reviews, QA, planning, staffing, traditional management — everything feels up for grabs and downstream of what happens with coding.

Also, while I love doing research and talking with others (e.g. on the podcast), opinions are so scattered across the board that I feel the strong need to try things myself, and do so in a serious, ongoing way.

So here is today’s agenda:

• 💧 Building Tolaria — a personal knowledge management app for the age of AI.

• 🦞 OpenClaw vs Claude Code — how I use them, and to do what.

• 🔧 Coding workflow — what changed vs one month ago, and what stayed the same.

• 📑 ADRs — the best recent addition to my coding.

• 🎨 Product workflow — how I create specs.

• 💸 How much I am spending — because I know y’all want to know that.

• 🤖 CLAUDE.md — bonus: my current Claude file, attached in full.

Let’s dive in!

💧 Building Tolaria

In the last article I said that what I was building didn’t matter much, well now it kinda does, because you are going to hear a lot more about it in the future.

Tolaria is a personal knowledge management app, extremely opinionated and tailored for my own personal use, but I hope it can be useful to others too.

It’s worth noting that this is not a particularly original idea. There exist plenty of tools in this space — Notion, Obsidian, Craft, Roam, and more — and most of them are very well made. Still, I know plenty of smart people who lately have been experimenting with weird setups.

Just last week, Karpathy wrote a viral tweet exactly about that.

Why such a renewed excitement around knowledge management? Because everyone who tries to work seriously with AI agents eventually understands that this is a core problem to solve: continuously supplying agents with reliable, up-to-date information about your life and work, and creating a good collaboration surface on these.

I suspect this still feels a bit abstract, so I’ll make a few examples from my own work:

• An agent should periodically fetch meeting summaries from tools like Fathom or Fireflies, create a note for the meeting with the summary and action items, and link the note to individual attendees (each of whom should have a page for themselves). If there are attendees who are new, the agent should create individual notes for each of them, enriching my personal CRM.

• An agent should receive voice notes from me and turn them into long-term notes and tasks, and connect them to the relevant existing pages.

• An agent should take every new article I write and split it into atomic evergreen ideas, connect them to similar ideas I have already saved in the past, and better organize my knowledge base so that it’s easier to write new articles in the future.

• An agent should suggest new article topics and podcast guests based on my recent readings and how these connect to things I have written in the past and interviews I already did.

In terms of intelligence required, most of these tasks are trivial. But they need a good collaboration surface 1) for agents to fetch the relevant info and 2) for me to work well with them.

Tolaria is my attempt to build this for myself first, and hopefully for some others too.

It will be completely free and open source, so that it also works as a visible artifact of my understanding of how to create products with AI, for other people to inspect.

At any given time, if you want to know e.g. what I write in my CLAUDE.md, or how I write docs, or what types of tests I write and which I don’t — you shouldn’t just trust my articles, you should be able to go to the repo and see for yourself.

This way, the ideas you read on Refactoring become the result of three things:

• 📚 Research — I read and collect experiences from others.

• 💬 Conversations — I go deeper by running community events and 1:1 podcast interviews.

• 🔧 Personal work — I do coding and product development myself to stress-test these beliefs.

All of these elements are meant to be public: you can get weekly digests of what I read, listen to the podcast conversations, join the community to chat with me (and others), and inspect the Tolaria codebase (soon!) to see how I write code.

Tolaria is not ready yet but it will be in a couple of weeks!

So where are we today? Here is an exec summary. Since I started working on it around mid Feb, here is what I got:

• 1526 commits — that is ~30 commits/day on average

• ~70K LOCs — about 45 lines / commit

• ~3000 tests — about 85% coverage

• 9.5/10 code health — as measured by CodeScene

• 40+ ADRs — to track our core tech choices, plus three summary docs for Architecture, Abstractions, and Getting Started.

That’s 2.5x the amount of code we had last month (we were at 20K LOCs), with better code health (9.5 vs 9.3), and better docs. I am still not writing any code, and I am still reading very little of it.

The product also got way better to the point where, by now, I have fully replaced my Notion workspace. It still feels surreal to say that out loud, after 6+ years of really intensive Notion usage, but here we are.

So let’s get into how I work on it, starting with coding 👇

🦞 OpenClaw vs Claude Code

In last month’s post I said that basically I acted as CEO, OpenClaw worked as a PM, and Claude Code worked as a team of designers + engineers.

Has any of this changed? Yes, and no. Roles are still kinda the same, but I am not using Claude Code strictly together with OpenClaw anymore, in the sense that the latter directs the former, but more in an async way. This change has been driven by three reasons:

• 💸 Cost — the initial workflow in which OpenClaw steered CC all the time was wildly inefficient in terms of token spend.

• 🎓 Capabilities — CC has caught up with a lot of OpenClaw stuff. Most of all, it has loops now.

• 👮‍♂️ Legal — most recently, Anthropic has explicitly banned this type of usage, but to be fair I had stopped it already.

So by now my OpenClaw and Claude Code work on separate things, in a completely asynchronous way:

• OpenClaw turns my inputs into product specs, checks on the general status of things, brainstorms new ideas, and in general does the work that benefits from broad context.

• Claude Code does all the technical work, including coding, writing ADRs and docs, and, crucially, QA, that was done by OpenClaw before.

OpenClaw doesn’t interact with Claude Code anymore, but it periodically checks that it doesn’t get stuck or crashes (which can happen for a variety of reasons). In that case, it restarts it.

🔧 Coding workflow

This article is largely meant to work as a delta vs my original AI coding article to highlight things that have changed, but it’s also worth noting the good stuff that has not changed.

The highest leverage parts of the AI coding workflow are still probably the CI gates on code health and test coverage. These gates exist in two places:

Read more

In that piece we argued that software engineering was undergoing a transformation from craftsmanship to factory work, with the gap between elite and average teams being more and more the result of good control systems and tight feedback loops, as opposed to individual brilliance.

Some will argue it has always been the case. Chasing 10x engineers has always felt like a dubious idea, with the healthy version being: let’s build a 10x team, instead.

Whether or not it felt true in the past, it certainly feels true now. The report showed that elite teams today — those that are getting the most out of AI — are exactly the ones who already had the best delivery infrastructure yesterday (i.e. 3 years ago). Today, these teams are both running their “factory” faster, and improving it faster. They are going faster than others, and accelerating faster, too.

So how do they do that? What does getting better look like? How do you even know it’s happening?

Let’s get practical and try to bridge this gap. Here is the agenda for today:

1. 🧮 DORA metrics are not enough — we need leading indicators of AI success

2. 📊 Specs, rules, and modules — a simple mental model for AI leverage in three steps

3. 🪴 Making things compound — how to make things happen on your team

Let’s dive in!

I am grateful to Rob and the CircleCI team for partnering again on this piece. You can learn more about CircleCI below.

Learn more about CircleCI

Disclaimer: even though CircleCI is a partner for this piece, I will only provide my unbiased opinion on all practices and tools we cover, CircleCI included

🧮 DORA metrics and LOCs are not enough

From the report above, we know there is a small group of teams leading the pack, with outrageous numbers like 2-3x throughput, and a large group of others that, on average, are getting nothing out of AI. Literally nothing. Zero. Nil.

And not because they are not trying! AI penetration with engineers is ~90% — basically everyone is using AI everyday for coding, but the median team is not getting any faster.

How do we know this? Because as of today, in 2026, we have a good understanding of how to measure the effectiveness of the software delivery process. For example, we can look at the DORA metrics. Whether or not you use AI in the dev process, we can track how long it takes for work to go through the pipeline, how many commits are made per day, what’s the success rate of these commits, and how fast you recover from mistakes.

These numbers give us a good idea of the health and effectiveness of the delivery process, and allow us to even venture into saying: “this team is doing better than this other team!”.

Sometimes they also allow us to say: this team is not doing any better than before — which is what CircleCI found on average in 2025:

• -6.8% commits in production

• -14% deployment success rate

DORA metrics are effective at measuring the impact of AI precisely because, counterintuitively, they ignore AI. They look at the output of the process, regardless of how the process is implemented.

This is both a blessing and a curse.

It’s a blessing because they stay close to where the value is, and it’s a curse because they are too high level to be directly actionable. Just like setting a goal of increasing business revenues by 10% doesn’t say much about what you need to do to get there, setting direct DORA metrics goals isn’t very useful, and can even backfire if you are not careful with it. E.g. it’s easy to increase the number of commits per day by splitting work into artificially small batches, and shipping just a few lines of code at a time just for the sake of pedaling faster.

So, DORA metrics are lagging indicators. They are good for assessing the production level of your factory, but they don’t tell you how to improve your stations. For that, we need leading indicators.

The most convincing leading indicator for the SDLC is developer experience. There is plenty of research today that shows that improving developer experience has outsized returns on the lagging indicators not only of the health of your engineering process, but of the business as a whole. This was already the core takeaway from Accelerate, exactly 10 years ago, and has only been confirmed ever since. About this, I particularly liked Frictionless recently, by some of the same authors of Accelerate.

Developer experience, though, doesn’t say much about how we are using AI.

What are the leading indicators of AI success?

Read more

In some cases, we even invented words we didn’t use before, like context, or, one of my favorite lately, intent. These words are abstractions—our bread and butter as engineers—and are born out of the necessity to discuss ideas, understand what’s going on, and improve how we work.

The intent concept is both important and, AFAIK, quite novel. These days you may hear it in sentences like “making sure PMs’ intent is captured into specs”, or “AI code should reflect the engineers’ intent”.

This angle frames software engineering as a translation act between something you want to achieve and what gets actually captured in artifacts like specs, UI design, up until code. If we continue this analogy, translation happens at every step, with different steps following different rules. Many engineering practices exist essentially to reduce the error rate of such translation.

So, seen through this lens, software development becomes an elaborated version of the telephone game. You win the game if the message is passed properly and ends up in… production.

That said, what the steps of the telephone game are (or should be), or what the best winning strategy is, frankly, it’s all up for discussion today. Should we write big specs beforehand? Should we keep human code reviews? Who should do this and that, and when, and how often?

Today I want to explore this, taking from what I have personally learned from my recent coding efforts, and ideas I bounced off with Amelia Wattenberger, who I interviewed last week on the podcast, and is joining me today on this piece.

So here is the agenda for today:

• 🔀 From intent to code — the journey of translating what you really want to do

• 🧱 Creating good platform — for each step of the journey, so AI doesn’t mess things up.

• 🛫 Staying at the right altitude — evolve your artifacts to match what you want to inspect

• 🔬 Using product to improve understanding — not just to implement it.

Let’s dive in!

Disclaimer: Amelia works at Augment Code and created Intent, a developer workspace with strong opinions about all of this. Augment is a long-time partner of Refactoring, I use it, I am a fan, and I am happy if you check it out.

Learn more about Intent

However, we are not here to promote Augment today, but rather compare notes about problems and try to predict where the puck is going. (The puck, Luca? In a telephone game? Yes)

🔀 From Intent to Code

Starting from something you want to achieve on the product you are building, then it’s a long way to encode that into, well, code.

Intermediate steps may vary based on your process, but you probably have some version of these:

1) Product intent

A high-level, one or two-sentence version of what you want to build. It may only live in your head.

Making an example from my own experiments (I am building an editor), let’s say I want to add split panes, like many editors have. In my head, that’s it. I don’t think about it a lot more.

2) Product specs

Product intent needs to be turned into a spec, like a PRD, which needs to stay faithful to my original intent, while deciding a lot more things.

How is this triggered? Is there a button? What does it look like? What about keyboard shortcuts? What happens if I drag a tab from one pane to the other? And more.

Some of these are just additional detail, but some might derail the feature in a direction I didn’t intend. For example, a legitimate interpretation might be to open up the tab in a new window, which is not what I want.

3) UI/UX design

Product specs are turned into design specs. What it looks like, how it behaves, where it lives.

4) System design

Product and design specs inform the strategy to implement this with code. Abstractions that should be reused or created, data structures (when relevant), migrations, instrumentation, testing, rollout and rollback, and more.

5) Code!

Finally, there’s code! All of this turns into a bunch of LOCs, to be pushed, reviewed, and released in prod.

Phew. That’s a lot of work.

Of course YMMV and you may skip creating actual artifacts for some of these steps, based on the complexity of the work at hand, and your team's workflows. But there are at least decisions to be made about all of these, even without the artifacts:

• Every step adds details that the previous kept implicit or simply did not consider.

• Every step can act as a lossy translation of the original intent. It can miss important details or interpret them incorrectly.

What is our goal with respect to this process? The ultimate goal is always to ship value to customers as fast as possible, so you can get feedback and iterate.

To ship fast you want to avoid rework: you want to reduce the misunderstandings between the various steps and the mistakes that would make work move backwards instead of forwards. You want code abstractions that match the PRD, a PRD that matches the product intent, and not getting to the point where a review fails and some of this gets back to the drawing board.

This angle is relevant with humans, and especially relevant with AI. AI models today are really good, and it feels most of their mistakes now come from not understanding what you wanted, rather than e.g. bad coding skills.

So how do you get good at this? The most convincing way, to me, is:

• Creating good platform for each step — which acts as guardrails and helps you minimize the amount of intent you need to encode into specs.

• Use specs as active collaboration surface — updating it with more details as the work progresses, so it stays at the right altitude all the time. Kudos to Amelia for making me think about this.

Let’s explore both 👇

🧱 Create good platform for each step

Read more

Last year we explored AI adoption, while this year we decided to expand the scope and investigate what the whole product development process looks like for teams in 2026.

We chose this topic because I believe we need to look beyond coding. Coding is now cheaper and faster than ever, which, for many teams, is moving bottlenecks elsewhere.

But is that really the case? And, if so, where are the bottlenecks now?

This is what we tried to uncover this year. A few weeks ago I wrote that the best way to find friction in your dev process was to simply ask your engineers, by doing what I called a Listening Tour. This survey is like our own listening tour, done on 340 teams — and we are here to report on findings.

This research was made possible by our partnership with Atono.

Atono not only funded this work: they helped us with their expertise, insights from their customer base, and domain knowledge. I am a big fan of what they are building and how they think about product development. You should check it out!

Learn more about Atono

So here is the agenda for today:

1. Demographics — a quick note on the data.

2. The Planning Problem — why 60% of teams discover missing work mid-cycle, every cycle.

3. AI in the Workflow — what teams are using AI for (and the one use case almost nobody has tried).

4. The Experimentation Gap — why some teams are compounding their AI advantage while others stay stuck.

5. The Way Forward — our conclusions, along with the three transitions we believe teams need to make.

Let’s dive in!

🗳️ Demographics

We surveyed 340 engineering professionals — a mix of ICs, tech leads, managers, and senior leaders — across companies ranging from 10-person startups to 1,000+ engineer orgs.

The survey was designed for depth over breadth: many questions were open-ended, and we reviewed every response manually. Each engineer took on average more than 15 mins to fill out the survey, so it was not quick, and it gives you an idea of the scale.

5️⃣ The Five Problems

To give you the bottom line up front, there are five key problems that tell the whole story:

1. Product requirements are confusing — Only 27% of engineers say both the problem and the success criteria are clear when they read a ticket. The counterintuitive part is that engineers are more likely to understand why something is being built rather than what done looks like. In many cases, teams share intent but lack a shared definition of the product behavior they’re trying to produce. The definition of done becomes the bigger knowledge gap.

2. Planning is fragile, for companies of all sizes — 59% of engineering teams discover missing tasks, stories, or dependencies mid-cycle. This rate is flat from 10-person startups to organizations with 1,000+ engineers. Scale doesn’t fix it nor does it make it worse.

3. Knowledge doesn’t get shared — 64% of teams store critical knowledge primarily in people’s heads. 1 in 8 say institutional knowledge simply disappears when someone leaves. And the bigger the company, the worse it gets. At companies with 1,000+ engineers, that rises to 17%.

4. Shared AI context is still aspirational — half of the teams (52%) have simply no shared AI context. Each developer manages their own prompts, assumptions, and product definitions. In practice, this means the same AI tools often operate with different understandings of the product across the same team. Large companies are significantly worse at this than small startups (75% vs. 51%).

5. AI isn’t much used for product — Only 9% of teams use AI to generate or help with product requirements. This is the use case most directly tied to every planning problem in this report, and almost nobody is doing it. Teams use AI to write code while upstream problems that cause rework go untouched.

These numbers point to a few larger problems:

1. Most teams have adopted AI for coding, and little else.

2. Teams that adopted AI on top of a process that was already fragile—unclear specs, tribal knowledge, undocumented decisions—aren’t getting a lot out of it.

3. Teams getting the best results are the ones who had a solid product dev process before AI arrived. This is the same insight we found for coding a few weeks ago, which we can now extend to product.

So let’s dive into the details!

🗺️ The Planning Problem

It’s a common belief that engineering teams are plagued by rework and missing requirements. This is confirmed by data:

• 59% of teams discover missing tasks, stories, or dependencies mid-cycle.

• 60% of engineers say they need clarifying questions “often” or “almost always” before starting work. Only 8% say tickets give them everything they need.

When we asked what causes the most delays and rework, the top answer was ambiguous or missing acceptance criteria (50%), followed by edge cases discovered too late (40%).

We tend to assume requirements failures start with poor problem definition, but the data says the gap is usually at the other end, at the definition of done.

35% of engineers say they understand the problem but not the success criteria. Only 13% have the inverse problem. Engineers are more likely to understand why something is being built than what done looks like.

“Developer’s understanding of the story. They don’t ask enough questions during grooming which leads to incomplete ticket/story. At the same time POs provide very generic acceptance criteria making it difficult to reach the expectations.”

— Tech Lead

The mid-cycle discovery rate makes this more concrete: 59% say they find out mid-sprint that a task is bigger than expected, a dependency was missed, or a design doesn’t match the implementation. This rate barely changes with company size. 10-person startups and 1,000-engineer organizations report nearly identical numbers. The “planning problem” isn’t a size or scale problem.

Requirements are also the #1 team bottleneck, by a wide margin. 35% of teams cite unclear or changing specs as the thing that most often slows the whole team down — twice the rate of the next item (QA and testing, at 16%).

“Most delays happen due to unclear or changing requirements that reveal hidden complexity once work begins.”

— Software Engineer

Part of why this persists is where product knowledge lives.

Two teams out of three store critical knowledge primarily in people’s heads. 57% say it’s scattered across Notion, Confluence, and Google Docs. 1 in 8 say it simply gets lost when someone leaves. Standard, agreed upon solutions for documenting technical decisions (like ADRs) are used by only 1 in 5 teams.

It goes without saying that when context lives only in people’s heads: it can’t be handed off cleanly, it can’t be referenced asynchronously, and it can’t be used by AI.

“Knowledge is scattered across Jira, docs, and code lives in multiple microservices working on different domains.”

— Engineering Manager

🪄 AI in the Workflow

It’s a common belief that AI has transformed how engineering teams work. The data seems to confirm this — but with an important caveat about where that transformation is happening.

95% of teams use AI in some form, and 80% use it substantially. So the question has shifted from “are you using AI?” to “are you using it for the right things?”

The answer, for most teams, seems to be no. The top AI use cases look like this:

That last number is worth focusing on. Writing good requirements—the use case most directly tied to every planning problem we covered in the previous section—is used by fewer than 1 in 10 teams.

AI is being applied downstream, but a lot of problems live upstream.

Shared context is the other missing piece. When we asked how teams manage AI context, the majority answer was straightforward: they don’t.

• 54% said each developer manages their own prompts individually, with no shared infrastructure.

• Only 29% use shared files in the repo (AGENTS.md, CLAUDE.md, Cursor rules).

• Only 3% intentionally organize context in their existing docs and tickets, for AI tools to access it.

This matches what Doug, Atono’s CPO, predicted before we ran the survey:

“[What we see so far is that] the greatest consumers of AI-coding are very clever developers who piece together a number of components... so only that clever developer is excelling.”

One engineer also described the mess directly:

“If I want to leverage a Notion doc, a Slack thread, a Jira ticket, and the actual codebase […] I have to manually copy and paste relevant context into the tool I plan to use.”

— Software Engineer

If planning problems were evenly distributed across companies of all sizes, with context problems, enterprises are the ones doing significantly worse. Companies with 500–1,000 engineers have >75% of developers managing AI context individually, vs small startups at 51%. More resources don’t produce more shared practices.

People are also generally aware of this: 54% of respondents agree that most AI quality problems are actually context problems. Leadership agrees even more than ICs. So it seems this is not an awareness problem, but rather about most teams not (yet) doing intentional work to bridge the gap.

AI is also expanding what individual engineers can do. 74% of engineers say AI has helped them work outside their primary specialty, and 59% are handling more of the product process than a year ago:

• Tech leads report the highest scope expansion (72%)

• Engineering managers the lowest (48%)

This pattern appeared in our last report too. Classic line management hasn’t been transformed by AI yet, at least not how much ICs have.

In general, the product engineer thesis holds: AI is accelerating the shift toward engineers owning more of the full product cycle. But without shared context infrastructure, the expanded scope creates individual-level fragility rather than team-level leverage.

🧪 The Experimentation Gap

There is a clear divide in how teams approach AI learning, and it predicts almost everything else.

44% of teams have no dedicated time for AI experimentation at all. They do it on the side, squeezed between deadlines. 31% allow some slack informally. Only 17% have explicit, dedicated time, whether it’s a fixed share of their capacity (e.g. ~10%) or a more structured program.

Out of these cohorts, teams with dedicated experimentation time are substantially more optimistic about the year ahead and report better results with AI. This isn’t exactly a surprise: deliberate practice compounds, while winging it stays shallow.

“The usage of AI needs to be learned on the job while adhering to deadlines.”
— Software Engineer

By going through the open answers about this, the feeling is that, when AI learning happens on the side, under deadline pressure, engineers just stick to what works. This means they are more likely to get stuck into local optima, and never discover workflows that would significantly change their output. That takes trial and error, and most of all, time.

The teams getting the most out of AI are, by and large, those who have just more time to figure things out.

The possibly clearest signal about this is the optimism gap. Teams with dedicated experimentation time are significantly more optimistic about the year ahead. Those without it cluster around neutral.

In other words, time spent on in AI learning is a leading indicator: investment today predictably shows up in results later.

🔭 The Way Forward

All in all, the data in this report points to gaps that are organizational rather than technical. The tools exist. The adoption is near-universal. What’s missing is infrastructure: context, clarity, and shared practices that make these tools work.

We believe three transitions define the difference between teams that are compounding their AI advantage and teams that are stuck into running a broken process faster:

1) From individual AI usage to team-level AI context

52% of teams have each developer managing their own prompts, with no shared infrastructure. Instead, the teams pulling ahead treat context as a shared resource: documented decisions, shared prompts, and product knowledge organized so AI can actually reach it.

This requires treating context as a team asset rather than a personal one. Not a big investment, but a daily, compounding one.

2) From accelerating execution to improving problem framing

Only 9% of teams use AI to generate requirements and acceptance criteria.

This is the highest-leverage untapped use case in this entire report. Before using AI to write more code, teams should ask whether the work is well-defined enough for AI to help at all. Garbage in, garbage out. So, with AI, it’s more garbage, faster!

3) From side-hustle AI learning to structured experimentation

Half of teams have no dedicated time for AI learning. Conversely, numbers show that deliberate practice is the only path to compounding returns.

Teams that carve out even a small amount of time—10% of capacity, or a monthly experiment day—consistently outperform teams that treat AI learning as something to do between tasks.

Overall, this research confirms the role of AI as an amplifier of whatever you already have. Good context practices become great enablers. Fragile planning becomes more fragile, at higher speed. The teams that had their house in order before AI are now compounding that advantage.

The good news is that getting your house in order is not a moonshot. It starts with daily decisions being captured in writing instead of a Slack thread. One set of acceptance criteria generated before development begins. One afternoon a month to experiment with AI without a deadline attached.

The gap is real, but it’s also closable. Let’s get to work!

See you next week!

Sincerely 👋
Luca

I want to thank again Megan, Doug, and the whole Atono team for supporting this work. I am a fan of what they are building — you can check it out below 👇

Learn more about Atono

If you run an engineering team, though, most of these opinions won’t feel useful to you. In fact, when I talk with people about e.g. some AI workflow, I usually get two types of objections:

1. Volatility — the advice may become obsolete in just a few months, or weeks.

2. Applicability — the advice doesn’t seem to apply to their team, because of X, Y, Z.

These problems often come together. I’ll give an example.

One of the recent trends about how to work with AI, on which there is more consensus, is Spec-Driven Development. There exist plenty of articles and frameworks to work with it, even created by prominent companies like Github. So it’s not a total consensus, mind you, but it’s about as much as you can get in these messy times.

Still, as a CTO, you may have legitimate worries:

• Is this worth investing in? Or may the AI tomorrow (i.e. next month) just figure out more of the specs by itself?

• Is this a good fit for our team? How do we harmonize it with how we have been creating PRDs and design docs up until now? Is there a way to work with AI that leverages how we already work, without the need to migrate to a different workflow?

These questions are 100% valid, and the result is often analysis paralysis: teams underinvest in AI because no approach feels durable or authoritative enough to graduate from individual experiment to team practice.

I believe the main problem is that most ideas are just tactical. They may work, but need to be placed within a bigger strategy — a wider map of how to think about our teams, AI, and how to work together.

So today I want to write about the ideas that feel the most durable to me, and on which I am confident we can create good foundations.

These ideas come from many places:

• My own experiments — as you saw last week.

• Talking with 100+ tech leaders — this year alone in 1:1s, masterminds, and community threads

• Our own industry report — where we surveyed 350+ teams and which we’ll release in March

• Our cohort program — where I work with a small group of ~10 CTOs and VPs to help their teams ship faster.

All in all it’s like a small think tank, and I am here to report findings!

These findings are actually quite simple (like all good models!), and are about three areas:

1. 🔧 Developer Experience

2. 🪄 AI

3. 🎨 Product Engineering

In my experience so far, these areas work like layers of a pyramid. Each layer creates value only if what’s beneath is taken care of. Think of it like Maslow’s pyramid of software engineering.

So let’s explore them one by one, recap what we know about them as of today, and how they work together for good.

🔧 Developer Experience

Read more

And it’s not random teams: it’s usually the best ones. If you don’t trust my anecdotal evidence, just look at recent reports. The very best teams, who had the best DX and code quality before AI, are the same who are getting the most out of AI today.

Still, it’s not 100% clear how these teams work with AI. The internet is full of opinion pieces and people sharing their CLAUDE.md files, but these feel tactical at best, and dubious/fake at worst.

I don’t want to add more of these. The proof is in the pudding, so I said to myself: if I want to write about AI coding, I need to build something.

So here we go.

For the last 17 days, I have been working on a personal project for a macOS app. Scope and complexity are daunting enough to force me to think architecture, buy vs build, performance, rich UI, and everything I would need to cover in a real—not toy—software project. And needless to say, I would never be able to pull this off without AI.

Before I give you more details, let’s start with what I got today so far:

• 772 commits in 17 days, for ~20,000 lines of code overall.

• 90% test coverage — via 500+ unit, integration, and E2E tests.

• 9.3/10 code health — as measured by CodeScene.

• A clear, hierarchical set of docs — to navigate architecture, abstractions, and codebase structure.

• A perfectly usable MVP — which I am, in fact, using every day.

I figured out and improved various parts of the workflow over time, so that now I am comfortable with:

• Not writing any code.

• Not reading almost any code. Say I read ~5% of it.

• Not providing UI design for ~90% of the features.

• Managing most interactions async via voice notes.

• Having AI work autonomously for long stretches of time, so I can do something else in the meantime.

So let’s dive into all of this, in detail. Here is what I am going to talk about:

• 🖥️ What I am building — because nothing else matters.

• 🎨 My product workflow — how I work as a PM.

• 🔬 How I keep tech quality — how I work as a CTO, without reading the code.

• 💰 How much I spent — the numbers nobody shows.

• 🔮 What’s next — my takeaways so far, and some obvious predictions.

🖥️ What I am building

Read more

We discussed how AI is changing software delivery, and the conversation continued well after we stopped recording.

A few weeks later, Rob shared an early copy of CircleCI’s State of Software Delivery 2026 report—which comes out today—and the data connected a lot of the dots from our conversations. So we decided to write this piece together: my take on the findings, with Rob’s perspective from the inside.

The report is based on 28+ million CI workflows across thousands of teams worldwide, and reveals something we have long suspected: the performance gap between top and average teams is widening. And it’s widening fast.

Elite teams (99th percentile) are reaching delivery speeds that would have been unimaginable two years ago, while the median team hasn’t moved much at all.

One story from my earlier interview with Rob captures this well. A team at CircleCI was debating whether to run user research for a new feature—the usual approach. Rob pushed back: just build a prototype overnight and test it with real users.

Even if the code was, worst case, 100% throwaway, the learning would be more accurate, and the cost would be just ~$100 in compute and a few hours of an engineer. The alternative would have been weeks for the research, more people involved, and possibly more shallow insights.

For someone like me, who has been involved in startups and lean teams for his whole career, it’s counterintuitive to think code-first. Much of what we know about building products is based on the implicit assumption that writing code is the most expensive part, by far.

So when such cost drops, the initial outcome is that engineers get faster. But when it keeps dropping, like in the last year, we get to a point where a lot of hypotheses don’t hold anymore, and we need to rethink the process as a whole: how we make decisions, how we structure teams, how we think about quality, and so on.

You stop optimizing individual developers, and start designing a new production system. Rob and I started calling this the software factory, and it became the lens through which the rest of this piece came together.

Here is what we’ll cover:

• 🏭 From craftsman to factory — why this is bigger than “AI makes coding faster”

• 📊 The widening gap — data from the 2026 State of Software Delivery

• 🎛️ Control systems thinking — a mental model for running your factory

• ⚡ What elite teams do differently — practices, not tools

• 🛠️ How to start — without rebuilding everything

Let’s dive in!

I am grateful to Rob and the CircleCI team for partnering on this piece and giving me preview access to their report. You can check it out below.

Check out the State of Software Delivery

Disclaimer: even though CircleCI is a partner for this piece, I will only provide my unbiased opinion on all practices and tools we cover, CircleCI included

🏭 From Craftsman to Factory

Let’s lead with an interesting bit from the State of Software Delivery. Actually, three bits:

1. Activity on feature branches (where most coding happens) is up 59% YoY — the largest increase ever observed.

2. Activity on the main branch, though, which is closely correlated with production deployments, is down by 7%.

3. Build success rates are down to 70.8%, the lowest in five years.

The way I see it is that engineers by now are comfortable with AI-assisted coding, and, as a result, teams are generally writing more code than ever. But it also feels that, when it comes to shipping, this confidence drops. Code fails more often, which makes engineers less eager to merge and deploy.

So while AI makes the generation of code faster, everything that comes after (or before) that — testing, reviewing, integrating, deploying — largely stays the same (or gets worse!), unless you do something about it.

I’ll also throw in my own experience into the mix. For the last two months, I have been running a small-group coaching program for CTOs where, among other things, I help them identify the bottleneck in their dev process — the step that limits the throughput of the overall system.

In theory, that bottleneck can be anywhere. In practice, it’s never coding.

For some, it’s manual QA. For others, it’s creating good requirements. For many, it’s code reviews. For one of them, it’s collecting good feedback from customers, so they can act on it.

As coding gets cheaper and faster, it’s changing the cost structure of the whole process, and bottlenecks now live in ‌the parts that AI hasn’t attacked yet. In other words, the whole system is up for discussion, and chances are it’s going to look way more like a factory than today’s craftman’s workshop.

Steve Yegge’s Gas Town is an obvious example that comes to mind. If you forgive the chaos, the waste of tokens, and the Mad Max theme, it looks directionally correct to me: a system of agents coding in parallel, orchestrated by higher-level agents that create and execute plans, and report back to their human overlords.

But as much as Gas Town can look at times like a 360° self-sustaining orchestration system, it’s still only focused on coding! Love this quote from Dan Lorenc:

Gastown is a preview of agent programming, but the future isn’t “code gets written faster.” The future is: change gets shipped faster. And those are not the same thing.

Teams are trapped because CI takes forever, tests are flaky or missing, review cycles are slow, merge conflicts pile up, confidence is low, production is fragile, and there are “oh god please don’t touch that” zones nobody wants to own.

If this plays out the way I think it will, software engineering turns into CI engineering.

Code is cheap. Green CI is priceless.

So how do we build what’s missing? Let’s go back to the data 👇

📊 The Widening Gap

We were saying: more code, more breakage, less delivery.

This problem, though, is not hitting everyone equally. In fact, possibly the most striking finding from the report is how differently teams are responding to the same shift. Let’s look at throughput first:

• The top 5% of teams nearly doubled their output YoY.

• The bottom half is flat, or slightly declining.

And even within the elite, the spread is staggering: this year’s most productive team delivered roughly 10x the throughput of 2024’s leader. At positions 5–15, it’s around 3x. At 20–30, about 2.5x.

Pipeline speed tells a similar story:

• Elite teams run at a median pipeline duration of <3 mins.

• The average sits at 11 minutes.

• Struggling teams are above 25 minutes.

That’s a ~10x gap between top and bottom, and we know the consequences: when your CI takes 25 minutes, you don’t run it as often, you batch more changes together, problems pile up, and the feedback loop slows to a crawl.

Recovery is perhaps the most telling metric. The median team takes about 72 minutes to get back to green after a failure — up 13% from last year. On feature branches, where AI is driving the most activity, recovery times jumped 25%. The average recovery time (as opposed to median) is 24 hours, which gives you a sense of how bad things get for the teams at the tail end.

Now, you might assume the gap is about resources — bigger companies, better tooling budgets, earlier access to AI. But that’s not what the data says. 81% of respondents report using AI in some form, so the tools are everywhere. What’s not everywhere is the ability to absorb what those tools produce.

I saved the best for last, so here is the data point I find the most interesting: teams that had CI pipelines under 15 minutes back in 2023 are 5x more likely to be in the 99th percentile today.

In other words, the teams that are thriving with AI are the ones that had good infrastructure before AI showed up. Fast feedback loops, reliable tests, clean deployment pipelines — all of that was built for humans, and it turns out it’s exactly what you need to make AI-generated code shippable.

How should you feel about this? In a way, this is both encouraging and frustrating. Encouraging, because there’s no secret: what’s good for humans is good for AI. Maybe also frustrating, because if you don’t have them, there’s no shortcut: AI amplifies whatever you already have, good or bad.

🎛️ Control Systems Thinking

So, if we are building a production system now, how should we think about it? Rob has an answer for this, and it comes from a somewhat unexpected place: control theory.

The field dates back to the early 1900s, and the core idea is simple. Think of a thermostat. You set a target temperature. A sensor measures the current temperature. If it’s too cold, the heater kicks in. If it’s too warm, it shuts off. The system continuously adjusts itself based on feedback.

That’s what a control system does, via four elements:

• 🎯 Setpoint — what you’re aiming for.

• 🌡️ Sensor — how you measure.

• 🔧 Actuator — what makes changes.

• ↩️ Feedback loop — that connects them.

Now replace the thermostat with a software team:

• Your setpoint is the quality and speed of your delivery.

• Your sensors are your tests, your CI pipeline, and your monitoring in production.

• Your actuators are the agents and developers that write and ship code.

• The feedback loop is everything that connects output back to input: did the build pass? Did the deploy break anything? Are users behaving as expected?

CI/CD has always been a control system; we just don’t call it like that. The teams that built fast pipelines, reliable test suites, and good observability have been essentially building sensors and feedback loops.

This framing matters today because if you just “unleash the agents” without good feedback mechanisms, you get what the data is already showing us: more code, more breakage, declining success rates.

So what the teams at the 99th percentile have is mostly faster and better feedback loops:

• Their CI runs in under 3 minutes, not 25.

• When something breaks, they know in minutes, not hours.

• They can roll back quickly, which means the cost of a mistake is low, which means they can experiment more aggressively.

If we agree on that, the question becomes: if you are not one of those teams, where do you start?

🛠️ How to Start Building Your Factory

Just like I don’t like big rewrites, I don’t believe in redesigning everything at once. I believe in small steps that compound over time.

So let’s try to start with three simple things: speed up your feedback, share what works, and make experiments cheap:

1) Speed up your feedback

This is the single highest-leverage move for most teams. If your CI pipeline takes 20+ minutes, nothing else matters — every other improvement will be bottlenecked by how long it takes to know if something works.

A simple audit: how long does it take from “developer pushes code” to “you know if it’s good or broken”? If the answer is more than 10 minutes, start there. If you can’t roll back a bad deploy in under 5 minutes, start there. If your test suite is flaky enough that people ignore red builds, start there.

This isn’t glamorous work, and it has nothing to do with AI. But the data is clear: the teams that had this in place before the AI wave are the ones riding it now. It’s the foundation your factory needs before anything else.

2) Share AI practices as a team

One data point from the report stuck with me: 30% of developers say they have little to no trust in AI-generated code. They use it because everyone does, but they don’t trust what it produces.

30% is a lot.

I believe the way to fix this is not to wait for a better model, but to graduate AI adoption from an individual sport to a team one. Turn AI Engineering into Compound Engineering.

This doesn’t require a big investment. I love Will Larson’s series of articles where he displays how his team is navigating this at Imprint, and it’s all about the basics. Here are a few examples:

• Create shared docs that accumulate learnings over time.

• Turn agents instructions (e.g. CLAUDE.md) into a shared artifact (version controlled!) across the team.

• Create easy ways to give feedback to the AI so that it can improve its own instructions (see screenshot from the Claude Code team 👇)

• Create spaces in which people can show how they use AI, what they learned, and something cool they did. It’s as simple as a 30-mins weekly slot.

If you start doing this, the compounding effect is real: better practices lead to better results, which lead to more trust, which leads to more experimentation, which leads to better practices again.

3) Make experiments cheap

Finally, try to make all of this easy. Create opportunities to try frontier workflows in a way that feels low-stakes:

• Run a hackathon where humans can’t write any code manually.

• Start a project that would be impossible to deliver had humans written the code. Like Craft did.

• Default-assign long-tail bugs to the AI and let it draft PRs.

Don’t treat AI adoption as a big decision, like: evaluate for three months, run a pilot, write a report, pick a winner. Treat it as continuous experimentation: try something this week, measure if it helped, keep it or kill it by Monday.

The cost of trying things has never been lower. The cost of not trying things has never been higher.

📌 Bottom line

And that’s it for today! If there’s one thing we hope you take away from this piece, it’s that the shift we’re living through isn’t about AI writing code faster. It’s about the entire system of building software being redesigned. And it’s being redesigned, in real time, by ‌the teams that understood this first, and way before AI.

Here are the main takeaways:

• 🏭 The bottleneck is no longer coding — AI made code generation dramatically faster, but testing, reviewing, integrating, and deploying largely stayed the same. The teams pulling ahead are those redesigning the whole system, not just the coding step.

• 📊 The gap between top and average teams is stretching fast — elite teams nearly doubled their throughput YoY while the median barely moved. The difference isn’t access to AI tools (81% use them), it’s the infrastructure to absorb what those tools produce.

• 🎛️ Think of your delivery process as a control system — with setpoints, sensors, actuators, and feedback loops. The teams at the 99th percentile do ship faster, but also know faster whether something works, which lets them experiment more aggressively.

• 🔧 Good infrastructure before AI = good results with AI — teams that had CI pipelines under 15 minutes in 2023 are 5x more likely to be in the 99th percentile today. Fast feedback loops, reliable tests, and clean deployments were built for humans, and they are even more important for AI.

• 🤝 Graduate AI adoption from individual to team sport — shared docs, version-controlled agent instructions, feedback loops into AI tooling, and regular show-and-tell sessions create compounding returns that solo experimentation can’t match.

• ⚡ Make experiments cheap, not decisions big — don’t evaluate for three months. Try something this week, measure if it helped, keep it or kill it by Monday. The cost of trying has never been lower; the cost of not trying has never been higher.

See you next week!

Sincerely 👋
Luca

I want to thank Rob and the CircleCI team again for partnering on this. You can find out their yearly report below 👇

Check out the State of Software Delivery

Learn how to run a better tech team 🔨

By now, chances are you have heard about the open-source AI assistant OpenClaw / Moltbot / Clawdbot. I have been using it extensively for two weeks now, and I want to share some thoughts about my experience with it.

I feel the need to do it for three reasons:

1) Signal — while there is a lot of information and stories online about OpenClaw, I have found most to be either shallow or inaccurate. Inaccurate is also an understatement: many takes are so comically bad/wrong/false that it is obvious that the author didn’t even bother to install OpenClaw, and is just remixing and regurgitating other (equally bad) content.

2) Impact — my experience with OpenClaw has been absolutely transformative and only comparable, AI-wise, to the launch of ChatGPT. YMMV and I don’t expect my experience to apply verbatim to everyone, but I suspect many people don’t understand what makes OpenClaw special, because it’s hard to see it from a distance.

3) Future — finally, this spectacular success gave me a lot to think about when it comes to the future of software and work in general, on which now I have thoughts that I want to share.

So here is the agenda for today:

• 🦞 What is OpenClaw — very briefly, for those who don’t know.

• 🔨 What I do with it — on a daily basis.

• 🔒 Security — keeping it real but also debunking some misconceptions.

And three theses:

• 🪨 Slaves vs software — AI enables a new (but also old) way to solve problems.

• 🔌 MCPs are dead — AI has clearly outgrown MCPs at this point, and not just them.

• 🪴 Personal leverage — learning from the story of Peter Steinberger, creator of OpenClaw.

Let’s dive in! You are in for a ride.

🦞 What is OpenClaw

OpenClaw is an open-source AI assistant you can install on a computer, plug into a number of tools, and make it do stuff. At its core, that’s it!

It is similar to Claude Code, but it comes with more features that work (kinda) out of the box, including, most notably:

• 🧠 Memory — it has a memory system to store things it wants to remember into files.

• ⏱️ Heartbeats / cron jobs — it can do recurring things when instructed to do so (e.g. every 4 hours send me a recap of my inbox and items that need my attention)

• 💬 Chat tools — it plugs into Telegram, WhatsApp and a few other tools for easy comms outside of the terminal.

It has a number of other features, including the ability to spawn subagents for long tasks, a big gallery of community plugins, and much more, but I believe the three above are what makes it stand out vs other assistants out there.

And the reason is all about UX.

There is nothing in OpenClaw you couldn’t already do with e.g. Claude Code plus a bunch of plugins / duct-taping, but the value here is convenience: the core parts are all pre-packaged, plus you’ll find a long tail of quality of life improvements that stem from the tool being intentionally designed as an assistant, as opposed to a coding agent.

So, it’s similar (on a small scale!) to when Steve Jobs introduced the iPhone as the combination of three things: a 1) widescreen iPod, a 2) mobile phone, and 3) an internet communicator. None of these were mindblowing in isolation, but put together they crossed some invisible line that turned the device into something else.

What is this something else, for OpenClaw? Well, let’s see.

🔨 What I do with it

The best analogy I have for OpenClaw is that of a person you have hired and you manage as your direct report. Yes, I know comparing AI to people is bad and out of touch in many ways, but I still find it the best model to build an intuition of how to relate with it and get the best out of it.

Like you would do with a person, you can tell OpenClaw to do things, do them on a recurring basis, have it report to you at some cadence, improve based on feedback, and it will happily do all of that. You will meet hiccups every now and then and stuff you’ll need to tweak, but for the most part, everything just works.

So, what to do with it is really up to you and what you need the most help with.

For me, as a content creator and owner of a small company, my highest leverage usage right now is that of an executive assistant, or a VA, that can lift some ops / admin work from my shoulders.

For example, right now OpenClaw:

• Sends me morning briefs about what I need to do during my day.

• Sends me prep for my upcoming meetings based on previous meetings and email threads with the same people.

• Stores and organizes meeting notes automatically.

• Does occasional coding work — e.g. it migrated all my Notion workspace to files, linking everything correctly.

• Plus does a lot of glue work that would otherwise require n8n-style automations.

And it’s great at one-off tasks too:

• I told it to draft an agreement with a partner company without adding any further context, because it could fetch it from email, Slack, meeting transcripts, and internal notes.

• I asked it to give me the copy for the next sponsorship placement. It did that by looking at our sponsorship calendar on Airtable to figure out what company was next up, plus fetching the actual copy from the right email thread.

It did both without the need for complex instructions — just explaining the work in a sentence or two like I would with a human.

To enable all of this, we have connected it to basically all the tools we use for work, including:

Read more

Pat’s article touches on a complex subject: the CTO role. He explores how such a role differs based on several factors, defines common sets of responsibilities, and provides insights you can use to improve alignment during hiring, company growth, and career conversations.

If you’d like to connect with Pat, please find him on Linkedin!

Here is the agenda for today:

• 👑 What’s a CTO — why the title carries seniority but rarely comes with documented scope.

• 🧩 Why I use archetypes — tools for sensing misalignment and converging on shared expectations.

• 🎭 CTO archetypes — eight recurring shapes that appear across different organizational contexts.

• 🛠️ How to use these archetypes — practical applications for hiring, growth, and career planning.

Let’s dive in! 👇

👑 What’s a CTO?

I’ve found that many people struggle to describe the scope of the CTO role.

Two people with the same “CTO” title can have radically different responsibilities, spend their days on entirely different problems and be measured by very different outcomes. These differences matter because misaligned and unclear expectations around the CTO role lead to frustration, inappropriate hires, organizational friction or burnout.

Many management and leadership roles often ask: “What is expected of me?”

I hear this frequently from Engineering Managers (EMs) and Tech Leads (TLs) in my training courses. While all roles have some slight differences, answering this for EMs/TLs is relatively straightforward, as I’ve previously written about in “The Definition of a Tech Lead” and “5 Engineering Manager Archetypes.”

Answering this question as a CTO, however, is much harder.

The title carries seniority and authority, but rarely comes with a documented understanding of scope, priorities, or success. After all, if you’re a CTO, you’re supposed to “work it out.”

Over my 25-year career in tech, I’ve worked with and observed many different types of CTOs. As a Principal Consultant at ThoughtWorks, I partnered with CTOs to help them transform and modernize products, platforms, processes, and organizational structures. As the CTO of the German digital bank N26, I met many CTO peers facing both similar and very different challenges. Since then, I’ve advised and coached CTOs across a wide range of organizations and situations.

What this experience has reinforced is that while CTO roles can vary dramatically, they are not always arbitrary. There are recurring shapes to the role that emerge in response to specific organizational contexts and constraints.

In the rest of this article, I describe these recurring shapes as CTO archetypes, which you can use to make sense of what different CTO roles cater for, why mismatches occur, and how the role might evolve over time.

🧩 Why I use archetypes

In software development, we often draw on design patterns such as the Observer, Singleton, or Decorator.

A pattern is a reusable solution to a specific problem in a defined context. Archetypes serve a different purpose. Rather than prescribing how to solve a problem, they describe recurring shapes that appear across many systems. When applied to leadership roles, I feel the term “archetype” fits better with the commonly understood meaning of “a typical example of something.”

Archetypes are not meant to be boxes people fit neatly into. Reality is always messier. Instead, they are tools for sensing misalignment and to converge on shared expectations.

Archetypes can help us turn implicit assumptions into explicit ones and provide a shared language to discuss expectations, trade-offs, and mismatches among an organization’s needs, a role’s scope, and an individual’s skills, experience, and growth opportunities.

No catalog of archetypes will ever be comprehensive or perfect, which is why my favorite quote from George E. P. Box applies so well here:

“All models are wrong, some are useful.”

When I wrote about the Engineering Manager archetypes, many people told me it helped them start productive conversations about which EM role their organization needed or which EM role someone was applying for. Others used it as a vehicle for growth, seeking new opportunities to build experience that allowed them to play other archetypes.

It’s also important to emphasize what these archetypes are not.

They are neither a hierarchy nor a maturity model. Most real-world CTO roles are hybrids, and an organization’s needs will change over time. Just as effective leaders practice adaptive leadership, a CTO’s shape must evolve as the company grows, shrinks, or changes direction. Used well, archetypes act as lenses rather than labels and support reflection and dialogue rather than categorization.

Although these archetypes are not meant to be exhaustive, I hope they’re still useful in practice. Whether you are an existing or aspiring CTO, a CEO or board member, an executive recruiter, or simply curious about what CTOs actually do all day, the goal is not to find the “right” archetype, but to have clearer, more grounded conversations about fit, focus, and context.

🎭 CTO Archetypes

The shape of a CTO role is mainly driven by organizational context and constraints, and because there are common situations, we can loosely group the following archetypes into one of the following categories:

• 🟣 Early-Stage or Small — Founder, Startup and Fractional.

• 🟠 Growth and Rapid Change — Scale-Up, M&A and Turnaround.

• 🔵 Complexity and Coordination — Group and CTPO.

Let’s look at all of them:

1) Founder CTO

The Founder CTO optimizes for turning a personal vision into a successful company, while carrying responsibility for both the business and its technology.

Imagine you want to start a tech company tomorrow, and you’re the most technically skilled person involved. Congratulations! You’re now a Founder CTO, and you wear the distinct hats of both Founder and CTO.

Founder CTOs typically have a much stronger attachment to the business than non-founder employees. While early-stage employees may have strong financial incentives, founders’ attachment is much deeper and more personal. For many Founder CTOs, the company’s success and eventual financial outcome are the positive side effects of seeing a personal mission come to life.

Founder CTOs often begin as the most experienced technical person in the organization. As the company grows, however, this may no longer hold true. Successful Founder CTOs frequently hire people who are more specialized or more experienced in particular technical domains. Some, such as Jack Dorsey (Twitter) and Patrick Collison (Stripe), eventually transitioned into CEO roles. Others, like David Heinemeier Hansson (Basecamp / 37signals) and Mitchell Hashimoto (HashiCorp), remained deeply technical as the company scaled.

The primary tension of the Founder CTO role is balancing the competing demands of the two hats, and in practice, the Founder hat often wins. During fundraising rounds, for example, the Founder CTO may spend significant time with investors rather than on technology leadership. In other situations, the Founder CTO becomes the public face of the business, requiring more time with customers or on marketing than leading the technology organization.

2) Startup CTO

Read more

It’s an 8-week program that blends live teaching and group coaching, and it’s for small groups: only 10 seats. You can reply to this email if you are interested in the next cohort in Q2!

Why am I saying this now? Because today’s topic is inspired by the last session of the program, which was about developer experience.

For some, this will be surprising. Most of the content you can find online these days is about AI, and it seems like learning to use AI well is the most promising route to shipping faster and more often.

But I am going to spill a secret here. AI is not that hard to use 🤷‍♂️

Yeah that’s right. Some people will convince you there is a whole new world to learn about agents, skills, tools, and while it is true that you need to get yourself somewhat comfortable with these, we are engineers, dammit! It’s all kinda easy to wrap our heads around.

So if you look at real teams — not solo engineers, I mean real engineering teams — that are getting the most out of AI, it’s most often not because they are using AI better or differently than the rest of us. It’s because they use AI on top of a platform that is already good. Folks were already productive and efficient before AI, and they got even more so now.

AI benefits teams who have their house in order, which largely means: good developer experience.

So, today we explore a simple but powerful technique to diagnose your devex: the Listening Tour. It’s a structured way to surface friction by talking to your engineers and mapping what you learn to your dev process.

Here is the agenda:

• 🧱 What is developer experience — and why friction is the enemy.

• 🔍 Interview your engineers — run a listening tour to collect stories of friction.

• 🗺️ Map friction to your process — group problems by dev pipeline step.

• 🧮 Score by reach and impact — prioritize without overthinking.

• 🔬 Find the one bottleneck — and why improving the wrong step makes things worse.

Let’s dive in!

Read more

The more the excitement, the wider the gap.

With AI, it feels this has been the case for at least the last couple of years, to the point that it even earned its own name: the gen AI paradox.

In June, McKinsey reported that:

• Nearly eight in ten companies have deployed generative AI in some form, but roughly the same percentage report no material impact.

• Also, 90% of function-specific AI use cases remain stuck in pilot mode.

The answer to these lukewarm results is supposed to be… agents. The thing that turns experiments into impact.

And yet, for most teams, the story is repeating itself. A Gartner poll from this year found that only 15% of tech leaders are actually deploying somewhat autonomous agents, and, from my anecdotal conversations, I confirm this sentiment.

By now, most of us have probably seen more agent demos than we can count. Agents that book flights, write code, handle customer support, or else. Every demo looks flawless — but when you try to put the same thing in production, it falls apart.

So what’s going on?

I have spoken with a lot of teams over the past months, and I believe the gap is not about intelligence. Today’s models are remarkably capable. The gap is about everything else: reliability, infrastructure, and the whole system that needs to be put in place around models.

The teams that are breaking through share a few things in common:

• They are realistic about what agents can and can’t do today

• They start narrow and expand carefully

• They invest in the workflow, not just the model itself

So this article is a primer on this. Let’s have a look at what agents are, why they fail, and how to get them to work.

Here is the agenda:

• 🤖 What is an agent, really? — clearing up the confusion between chatbots, copilots, and agents.

• 🧱 The building blocks — models, orchestration, and tools: how agents actually work.

• 🏆 Use cases for agents — patterns from early winners and use cases with real ROI.

• 🔧 From prototype to production — how to bridge the reliability gap and the compounding errors problem.

Let’s dive in!

I got a lot of help for this piece from Gorka Madariaga and the team at AWS, who work on Amazon Nova and have spent the past year deep in the trenches of enterprise agent deployments. Their perspective on what’s working — and what’s not — was invaluable in shaping this article.

Learn more about Amazon Nova

Disclaimer: even though AWS is a partner for this piece, I will only provide my transparent opinion on all practices and tools we cover, Nova included!

🤖 What is an agent, really?

The word “agent” has become one of the most overloaded terms in tech.

Vendors slap it on everything from simple chatbots to fully autonomous systems, which makes it hard to know what we’re talking about.

To clear this up, I find it useful to think about AI systems on a spectrum of autonomy:

1. 💬 Chatbots — respond to questions. They take an input, generate an output, and that’s it. They possibly keep memory across sessions, but have no ability to take actions. Think classic customer support chat.

2. 🧑‍✈️ Copilots — assist humans in doing work. They can access context (your codebase, your documents), draft outputs, and take some actions. But a human remains in the loop, reviewing and approving. Think ChatGPT with tools.

3. 🤖 Agents — act autonomously to achieve goals. They can reason, use tools, and plan multi-step workflows without waiting for human approval at every step.

The key distinction is that agents do things autonomously — they don’t just respond. They interact with external systems, make decisions, and take actions that have consequences.

Which makes them both powerful and risky. The feedback loop is fundamentally different because chatbots have a human in the loop all the time, while agents have not.

Designing for this is hard, which is the reason why successful deployments usually don’t go full autonomy from day one (or ever). They escalate to humans for high-stakes decisions, and gradually expand the agent’s authority as trust is established.

In other words: the best agents today are only selectively autonomous: independent on routine tasks, supervised on critical ones.

🧱 The building blocks

To understand how to make agents work, we first need to break down what’s inside one. At its highest level, every agent has three components:

1. 🧠 Model — this is the “brain” of the agent. It’s the LLM that does the reasoning: understanding the task, deciding what to do next, and interpreting results. The model is what most people focus on, and it makes sense: a smarter model generally makes better decisions. But there is much more 👇

2. 🔧 Tools — these are the external capabilities the agent can use: APIs, databases, browsers, code execution, file systems. Tools are how agents interact with the world. Without them, you just have a chatbot.

3. 🔀 Orchestrator — this is the control layer that manages the agent’s workflow. It handles things like: breaking a goal into steps, deciding when to call which tool, recovering from errors, and knowing when to stop. Some agents use simple loops, while others use complex state machines or even multiple sub-agents coordinating together.

Some add memory as one of the building blocks. On a semantic level, I kinda disagree with this, as memory doesn’t feel as fundamental as the other three. Model, orchestrator, and tools are all required for any agent to function. Memory is more of an enhancement — many useful agents are stateless within a single task.

Also, technically, memory is often implemented as a tool (e.g., vector database lookup) or managed by the orchestrator (e.g., maintaining conversation state). It’s not a truly separate layer.

But I digress. The point here is that an agent is a full system, not just a model, and the system matters a lot. A better model doesn’t automatically translate into a better agent if you have flaky tools or the orchestrator can’t recover from errors.

🏆 Use cases for agents

Given all of this, where are agents actually delivering value today? This is important to discuss for two reasons:

• Many teams legitimately need ideas and inspiration about what to use an agent for.

• As of today, it is true that some use cases work better than others. Which ones? And why?

If you have to take only one idea away from this section, it’s that agents that work are most often not trying to be general-purpose assistants that can do anything. They are focused on specific workflows, with clear boundaries, and humans in the loop for edge cases.

About this, the most common area is automation — handling repetitive, multi-step tasks across systems: updating CRMs, processing invoices, syncing data between tools. PwC found that 64% of agent deployments focus on workflow automation.

A notable subset of automation agents is UI automation.

AI is better at using tools and APIs than it is at clicking around websites, but hey, many systems don’t have APIs! Or they do, but they are incomplete and/or painful to use. There are plenty of industries like healthcare, insurance, or travel, whose platforms are often utterly legacy and have never been designed for automation. On these systems, agents that interact with UIs directly, clicking buttons, filling out forms, or navigating pages, can unlock an insane amount of value even by doing relatively simple tasks.

As engineers, we often focus on the exciting and sophisticated, and forget there is still a ton of value in the boring.

About UI automation, allow me a quick plug: this is exactly the problem that the Amazon AGI and AWS teams have been working to solve with Amazon Nova Act. It’s a managed service for building agents that automate browser-based workflows. These include navigating UIs to validate functionality in web QA testing, filling out forms, or extracting data from pages.

I also love their focus on reliability over raw intelligence: Gorka prides that, on early enterprise customer workflows, Nova gets 90%+ reliability, vs an industry average of 60-70%.

So, as of today, successful cases do exist, but they are practical and down-to-earth. They focus on well-defined tasks, their blast radius for errors is contained, and there’s a clear baseline to beat (usually: humans doing boring work manually).

Conversely, what doesn’t work well yet is open-ended agents that require a lot of judgment, long-running autonomous workflows, or anything customer-facing with high stakes. The reliability math just isn’t there.

Here are a couple of successful examples from our community 👇

1) Onboarding

One of the first use cases we’re piloting is an agentic onboarding flow for customers, where the agent automates parts of the activation process.

The goal is simple: scale onboarding capacity while shifting human agents toward higher-value interactions. We’re currently A/B testing this against our regular onboarding flow, and just started validating early data and customer feedback.

— Nithin SS • Head of QA at Lodgify

2) Phone Screening

Our AI Operations Team finished a first version of a phone screening Agent using Telli.

The use case is that at Zenjob we are selecting students for certain temporary/short term jobs and for some cases where we need more comittment from them AI Agents do a phone screening interview call + some assessment is also done.

It’s still fine-tuned but recently the team integrated it into Retool Dashboard for our Operators Team.

— Ferit Topcu • Engineering Manager at Zenjob

🔧 From prototype to production

Once you understand how an agent works, and pick a reasonable use case for it, it can still be a long journey from patching together a small prototype to running something that works (and delivers value) in production.

To get there, here are the things you need to pay attention to:

1) Compounding errors 📉

In my experience, this is the most fundamental problem. In any multi-step workflow, small error rates at each step multiply into large failure rates overall.

Quick math: if each step in an agent workflow has 95% reliability (which is optimistic) — then over 20 steps you’re left with just 36% success 👇

This is also why demos look so good: they are short and show the happy path, maybe 3-5 steps, carefully chosen.

The way you counter this is:

• Start small — as said above, pick a single, well-defined use case with clear success criteria. Design a small number of steps and make each one as easy as possible.

• Design for human-in-the-loop — what decisions can the agent make alone? What requires approval? A simple heuristic: if the action is reversible and low-cost, let the agent proceed. If it’s irreversible or high-stakes—like sending money, deleting data, or external comms—require human approval. Build escalation paths into the workflow from day one to cap risk and reduce errors on difficult steps.

• Treat reliability as the key metric — focus on the percentage of tasks completed successfully. Evaluate and iterate all the time!

2) Testing and debugging 🔬

As we all know, agents are non-deterministic: the same input can produce different outputs across runs. This means you can’t write traditional tests with the same confidence you’d have for regular software. When something fails, it’s hard to reproduce.

For this reason, you should invest in observability early on, so you can see what the agent is doing, step by step.

Concretely: log each step’s inputs, outputs, and latency. This advice is frankly good for any software, but especially non-deterministic one. Tools like LangSmith, Langfuse, or even structured logging can help. The goal is a full trace from trigger to completion.

3) Account for scale 📈

Deploying agents even at a moderate scale requires taking into account many factors:

• Authentication — how can the agent act properly on behalf of users across systems?

• Security — are you sure the agent can’t access things it shouldn’t?

• Escalation — does the agent know when it needs to pause and escalate to a human?

• Latency and cost — are you accounting for volume? In the LLM world, everything compounds fast.

Reflect on all the ways your production environment, with real users and real scale, is different from your confined developer environment.

4) Buy vs build 💳

Finally, consider the buy vs build tradeoffs, and keep a bias for buying everything that’s not core to your product.

Building agent infrastructure from scratch—orchestration, tool integrations, deployment pipelines, monitoring—can be a massive undertaking. If it’s not going to be strategic IP, it makes sense to use managed platforms that handle part of the complexity, so your team can focus on the actual business logic.

The options range widely:

• For UI automation specifically, Amazon Nova Act provides a managed service that handles the infrastructure complexity and scales seamlessly to production workloads.

• For no-code workflow automation, platforms like Lindy, n8n, or Zapier Agents let you build agents without writing code.

• If you want to build in-house with full control, frameworks like LangChain and CrewAI give you the building blocks to create custom agents from scratch.

📌 Bottom Line

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

1. 🤖 Agents act, they don’t just respond — The key distinction from chatbots and copilots is that agents take actions with real consequences. This makes them powerful but also risky.

2. 🧱 Focus on the system, not just the model — An agent is made of three parts: the model (brain), the orchestrator (control layer), and the tools (how it acts). Vertical integration across all three is what makes agents reliable.

3. 📉 Compounding errors are the killer — At 95% reliability per step, a 20-step workflow succeeds only 36% of the time. This is why demos look great but production fails—demos are short, production workflows are long.

4. 🎯 Start narrow and specific — The agents that work today aren’t general-purpose. They’re focused on well-defined workflows like invoice processing, CRM updates, or UI automation where APIs don’t exist.

5. 👥 Design human-in-the-loop from day one — Keep humans supervising high-stakes decisions. Agents should be selectively autonomous: independent on routine tasks, supervised on critical ones.

6. 🔬 Invest in observability early — You need to see what the agent is doing, step by step. Log inputs, outputs, and latency to debug non-deterministic systems effectively.

7. 💳 Buy the hard parts — Building orchestration, deployment, and monitoring from scratch is a massive undertaking. Use managed platforms so you can focus on the workflow logic specific to your business.

A special thanks to Gorka Madariaga and the AWS team for partnering on this piece and providing expertise and and insights. They recently presented a lot of new functionality at re:Invent, so I am linking below a few sessions if you want to learn more:

• Building useful, reliable agents with Amazon Nova

• Beyond web browsers: HITL and tool integration

If you want to learn more about what they’re building with Amazon Nova, check out their work at aws.amazon.com/nova/

Learn more about Amazon Nova

See you next week!

Sincerely 👋
Luca

If you like this piece, consider subscribing to the full version of Refactoring to get one every week. It matters a lot to me and it supports our work 🙏

Learn how to run a better tech team 🔨

Last week, going through my reading list, I happened to read these two blog posts on the same day:

• LLMs are not fun

• Web development is fun again

Both authors, Ori and Mattias, are seasoned engineers who have been in tech for ~20 years, but they have opposite feelings about LLMs.

This is not surprising. With AI forcefully getting into their lives, most engineers I know have developed strong feelings about it, and a big divide is happening right now:

• Some folks are finding excitement, hope, and empowerment.

• Others are experiencing anger, fear, or downright grief.

In other words, some find it easy to focus on the new possibilities opened up by AI, while others can’t help but mourn what AI is taking away from them.

Also, this is a largely separate conversation from the one about job anxiety, layoffs, and the future of tech. I know excited engineers who are afraid they might lose their job, and others who feel safe but are still sad about what their job might become.

So, let’s try to unpack this and figure out how we should think about AI, our jobs, and our identities.

🧩 Solving puzzles vs solving problems

Let’s take a quote from the “LLMs are not fun” article:

On the engineering side, using LLMs to write code is as fun as hiring a taskrabbit to solve my jigsaw puzzles.

This is a popular analogy — plenty of people compare engineering to solving puzzles. In fact, I believe many people enjoy coding for two reasons:

• It provides strong intellectual stimulation

• It’s a constrained domain where we can feel in control, as opposed to… people stuff!

The author of the article admits it himself 👇

[I got into programming so that] I could step away from tiring, ambiguous human interaction for a while

However, it’s time for the hard truth. We are not paid to solve puzzles. We are paid to solve problems.

You might think I am nitpicking, but words matter (I am a writer, forgive me):

• We solve puzzles for our own enjoyment. Puzzles have no purpose outside of the intellectual challenge they provide.

• We solve problems to help other people. And these people pay us in return. The fact that problems can also be interesting and puzzle-like is a byproduct of that, not the main point.

So I’ll venture into another analogy.

Let’s say you are a professional gardener, and you grow beautiful gardens for clients. A big part of why you love your job is that you can do daily, blissful walks throughout the gardens, to water the plants.

Watering the plants feels awesome. You don’t talk to anyone, you reflect on your life, and you even get decent exercise.

At some point, irrigation systems get invented. You feel bad about them, because you feel they take away your job. Except, watering plants has never been your job! Your job is to grow and maintain the gardens, which includes making sure plants get enough water, which by chance includes you manually watering them.

Don’t get me wrong, finding a happy corner within your work is awesome — as long as you don’t optimize for it, at the expense of what the true goal is.

And, unfortunately, I know plenty of people who do that, intentionally or not:

• “I only use LLMs as autocomplete so I can check every single line of code“

• “It takes more time to review LLM code than to write it myself“

• “If I make AI write it, my skills will atrophy”

As always your mileage may vary and none of this is necessarily wrong, but you should keep your antennas up and intercept when your behavior is guided by your own comfort, as opposed to what is best for the team / product / business.

But, as we said before, there are also a lot of engineers who are excited about AI. What are these folks getting right that the others are not?

Let’s pull a quote from the “web development is fun again” article 👇

I remember when PHP 4 was a thing. […] If you had an idea, you could probably build it. As a solo developer, you could manage everything. From idea to execution.

For this other engineer, coding is about making ideas come true. What matters is the idea, not how complex / interesting it is to build — quite the opposite: complexity gets in the way of making things happen. The less the better.

With this mindset, AI becomes your savior against the stupid complexity of the modern web, instead of the bad guy that takes away your Legos.

However, if you are feeling bad about AI right now, this is probably not going to help. You spent what feels like a lifetime getting good at something, and that something feels it is getting less valuable by the day.

How can you think of yourself differently? How do you reframe your identity?

↕️ Finding a broader identity

Last week I interviewed my friend Thiago Ghisi on the podcast.

Thiago has had an incredible career in tech in over 15 years. He worked at companies like AMEX, Apple, Thoughtworks, and was Director of Engineering at Nubank up until six months ago.

So what happened then?! He went into a sabbatical, during which he took a step back and explored other things that he liked. He analyzed 15 years of his notes with Claude Code, went through his email data, social media dumps, and found patterns about his behavior.

Right now, he has just applied to start a PhD in Clinical Psychology.

So if you frame Thiago as a Director of Engineering, this is obviously a departure from what he is expected to do for his career. But if you frame Thiago as someone who has worked as a manager for 10+ years, helping people become a better version of themselves, is it still that weird?

What if later on Thiago develops a coaching program for executives and high-achievers in tech, thanks to his unique blend of engineering & psychology chops? And what if he makes great use of AI for that, which he already started doing by scratching his own itch with Claude Code?

All of a sudden you might think that all the dots have been connected, and everything Thiago has done during his life has led him to this.

The problem is: you could never spot this if you simply thought of yourself as a Director of Engineering. You need to find a broader sense of identity for yourself, one that connects more dots, and answers to a deeper why.

I am not telling you to get into a sabbatical to find it, and the good news is you probably don’t need to. You can ask yourself simple questions:

• Why do I do what I do?

• What’s a broader version of what I do? — Does it still look like me?

• What hobbies do I have? — Is there any that connects with some of these broader identities?

What’s the greatest common denominator of the things you do in your life?

If you feel like you are someone who crafts great backend software, would it be comfortable to step back and say you are someone who crafts great software products, in general? Would that still feel like you?

And why software? Could you say you are someone who likes to craft useful stuff, in general? Ha, I see that 3d printer there, gotcha.

Now you might think, why should all these contortions be any useful? Because there is a world of difference between thinking:

1. I am a backend engineer who is an expert in algorithms and data structures, and

2. I am a software engineer who creates great products — and currently works with data structures on this team.

The first guy is going to get mad at AI for becoming equally good (or better!) at their algorithms, while the second one is more likely to say “cool! I’ll do this thing faster and move to something else”.

💂‍♂️ For managers: help your team navigate this

I want to close by addressing managers, because a lot of this is on you.

People can do amazing work at embracing AI individually, but it’s on you to create avenues that allow this work to turn into true leverage.

AI is like a tide that raises the floor — people get higher, but if you don’t also raise the ceiling, they may get trapped. What do I mean?

Let’s say your backend engineer sticks to their typical backend work plus adds Claude Code on top of it. By using AI to do more of the same work, more and more of their day might be spent fixing AI bugs. They might be faster than before, but 1) they are still in their lane, so there is a cap to how fast they can get, and, 2) work is now miserable instead of creative.

So we need to think intentionally about how engineers spend their time. As AI takes over some of the work, the question becomes: what do you do with this residual time?

I don’t buy the answer that you just do more of the same, so the question turns into: what’s a broader scope of work that:

1. Creates professional growth, and

2. Delivers business value?

Both are required. If the scope of work is not enjoyable or doesn’t create growth, people will hate it and leave. And if it doesn’t deliver value, what are we even doing here?!

To me, a big part of this looks like making engineers care about solving problems for people.

• Sometimes these people are customers, and that’s Product Engineering.

• Sometimes these people are other engineers from their team, and that’s Platform Engineering.

• Sometimes it’s co-workers from sales, from customer success, from operations, and it’s about empowering them to do a better job.

Understanding this means aligning how engineers see their work with what success looks like for the business. When this happens, it’s easier for AI to make people not only go faster — but go faster in the right direction. And it’s easier for people to go after new things that make sense, instead of going off on a tangent.

In other words, if people accept to move past solving puzzles and on to solving problems, do they even know what the larger problems look like?

It’s on you to make them know! Let’s get to work 💪

📌 Bottom Line

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

1. 🧩 We are paid to solve problems, not puzzles — the intellectual stimulation of coding is a byproduct of our real job, which is helping people (and making money!) through software.

2. 💡 Reframe AI as an enabler, not a threat — engineers who thrive with AI focus on making ideas come true, viewing complexity as an obstacle rather than the point. AI becomes a tool against tedious work, not a rival.

3. 🪞 Find a broader identity — instead of defining yourself narrowly (e.g., “backend engineer expert in algorithms”), zoom out to something like “someone who crafts useful products.” This makes AI feel like a tool, not an existential threat.

4. 🔍 Watch for comfort-driven behavior — statements like “reviewing AI code takes longer than writing it myself” may signal optimization for personal comfort over team/business outcomes. Keep your antennas up.

5. 🚪 Managers: raise the ceiling, not just the floor — AI lifts everyone’s baseline productivity, but without expanding scope and growth opportunities, engineers get trapped doing more of the same, faster, and more miserably.

6. 🎯 Align engineers with real problems — help your team understand what success looks like for the business. When people move past puzzles and on to solving problems for people, AI becomes fuel rather than friction.

I wish you a great week!

Sincerely
Luca