Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today's guest is James Stanier, CTO at Nordhealth, former director at Shopify, an author of several books about engineering management, remote work, and more.

With James, we talked about what senior engineers will look like in the future, taking from a great article he wrote just recently, and then regarding how engineering management is changing, what's expected of managers today, and what you need to thrive.
We also talked about AI adoption in his team, in our personal lives, and discussed the state of remote work in 2026.

🥇 Interview Summary

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

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

Here is the agenda for today:

1. 🔮 The senior engineer of 2035

2. 🧑‍💼 How engineering management is changing

3. 🤖 AI adoption: from chaos to creativity

4. 🏠 The state of remote work in 2026

⠀Let’s dive in 👇

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

🔀 Open-source workflow orchestration

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

Last week I published this primer about workflow orchestration, together with the team at Kestra, which builds a great open source platform to scale AI agents into more deterministic and observable workflows.

I have been playing with it to replace some of my OpenClaw chaos cron jobs, and I am pretty happy with the result so far! Will probably write more about it in the future.

You can learn more about Kestra below 👇

Learn more about Kestra

💡 ADRs are the reviewable artifacts of AI coding

Last month I wrote that the most recent and most valuable addition to my AI coding workflow have been ADRs.

Since then, I realized they are especially valuable because they help turn design judgment into reviewable artifacts. What does it mean?!

I don’t want to inspect every line of code an agent writes, but I can definitely review a short decision record that explains the chosen approach, alternatives, consequences, and what would trigger reconsideration. This gives me a way better control point than reviewing code details in isolation.

ADRs also improve future agent work. Before making a structural choice, the agent can read past decisions, reuse the system’s current principles, and avoid debates that were already settled.

I especially like that ADRs are immutable. When a decision changes, the agent creates a new record that supersedes the old one, instead of rewriting history.

As of today, Tolaria has 120+ ADRs. Are they perfect? Not at all — but they don’t have to be. They are good enough to 1) make me understand key design choices, and 2) steer agent behavior to make it compliant with what exists.

You can find the full article below:

Refactoring

Updates to my AI Coding Workflow

About a month ago I wrote an article about my AI coding workflow, and it instantly became the most popular Refactoring article of all time…

Read more

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

🎙️ Use AI by default to learn its failure modes

Speaking of AI coding, last month I interviewed Stuart Caborn, Distinguished Engineer at loveholidays, and one of the few tech leaders I know that is really doing it at scale, documenting the process.

One of the things he told me is that teams do not learn how AI works by waiting for perfect use cases.

They learn by using it by default, even in moments where typing the code directly would be faster. This sounds inefficient locally, but the point is building the feedback loop, rather than optimizing the single task.

Stuart explains that every failed AI attempt teaches the team something: which instructions are missing, which docs are unclear, which conventions are invisible, where the agent needs guardrails, and so on.

Stuart cares about making failures public, instead of private, and for this, he creates pressure for the failures to surface. The team runs showcases, shares patterns, and even forces engineers to go through AI before asking for human support 👇

“At one of the platform showcases, the core engineering team said: we’re not going to support you if you have a problem with your Terraform, if you haven’t asked Claude to do it first. That was bold — but the reasoning was: we need the feedback now.”

You can find the full interview here:

📚 Weekly Readings

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

🥇 Sensors for Coding Agents

15 min • by Birgitta Böckeler

Great primer on using sensors — like ESLint rules and static analysis — as feedback loops for coding agents. The idea is that agents need guardrails to maintain code quality, and these automated checks act as their “senses” on the path to production.

🥈 Apple Silicon Costs more than OpenRouter

5 min • by William Angel

Yet another reminder that, for 99% of us, running LLMs locally makes absolutely zero sense. This time backed by numbers.

🥉 Not So Locked In

2 min • by Simon Willison

Programming languages used to be lock-in — they’re increasingly not. LLMs are making it feasible to port entire codebases across languages and frameworks, which changes how you think about tech choices, risks you can take, and more.

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

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

Make your team ship faster!

See you next week!
Luca

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 also write an article about how to ship good software fast, and interview a world-class tech leader on the podcast.

I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

📋 Unblocked is the context layer for modern teams

This newsletter is brought to you by Unblocked!

Agents can generate code, but getting it right for your system, team conventions, and past decisions is the hard part. MCPs give agents access to information but not understanding – so you end up wasting time and tokens in correction loops.

For this reason, the teams pulling ahead use a context layer to give agents exactly what they need.

Unblocked is the context layer that turns code, docs, tickets, and conversations into actionable context, so engineers move faster and agents stay on track 👇

Book a demo today

🔍 Rate your team on the pyramid of engineering

A couple of months ago I argued there is a new pyramid in software engineering, made up of the areas you should take care of to get your team to their best potential.

These areas are Developer Experience, AI, and Product Engineering, and need to be nurtured exactly in this order.

To understand how you are doing about each of these, here is a short self-assessment you can run on yourself. Rate how much you agree, from 1 to 5:

1) Developer Experience

• 1.1 — It is easy to do work as a developer on my team

• 1.2 — Engineers on my team get enough focus time

• 1.3 — My team ships fast and often

• 1.4 — I have a good strategy to improve the developer experience of my team

2) Artificial Intelligence

• 2.1 — Engineers on my team make good use of AI

• 2.2 — We have a shared understanding of how to use AI as a team

• 2.3 — I have a good strategy to improve the impact of AI on my team

3) Product Engineering

• 3.1 — I am happy with the level of autonomy the engineers on my team work with

• 3.2 — Engineers on my team know what our customers’ problems are

• 3.3 — Engineers on my team know if a feature is successful or not

• 3.4 — I have a good strategy to make the engineers on my team more autonomous over time

You can find the full article below:

Refactoring

The New Pyramid of Software Engineering 🏔️

There are a lot of opinions around these days about the future of software, including of course my own…

Read more

3 months ago · 50 likes · Luca Rossi

🎙️ The business impact of code quality

One of the interviews I keep coming back to is the one I did last year with Adam Tornhill.

Adam is the founder of CodeScene and one of the sharpest thinkers on software quality: he combines behavioral data analysis with code metrics to identify the parts of a codebase that actually hurt you.

The conversation centered on a question most engineering leaders struggle with: how do you make the business case for refactoring?

Adam’s team tackled it head-on with the Code Red study — a large-scale analysis of the correlation between code health and real development performance.

Their findings confirmed what many engineers know by heart:

• ⚡ Development Speed — healthy code enables teams to develop features more than 2x as fast as unhealthy code.

• 📉 Predictability — unhealthy code creates massive variance in task completion times, making estimation extremely hard.

• 💸 Hidden Costs — some tasks in unhealthy code can take up to 10 times longer than expected.

“Doing a task in unhealthy code can actually take up to an order of magnitude longer — 9 times, 10 times longer. And that translates into a bunch of undesirable side effects for the business.”

One finding that stuck with me is also that who makes the change matters enormously. Developers unfamiliar with the codebase take twice as long to work in unhealthy code. This is a hidden onboarding cost that nobody ever budgets for, but that compounds every time a team grows or rotates.

Here is the full interview with Adam 👇

You can also find it on Spotify and Substack

📚 Weekly Readings

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

🥇 Software Engineering May No Longer Be a Lifetime Career

6 min • by Sean Goedecke

Using AI to code means you don’t learn as much about coding itself, but refusing to use it puts you at a disadvantage today. So, is software engineering becoming more like professional sports? That is, a career with a finite window rather than a lifetime of compounding skill accumulation.

🥈 GitLab Act 2

19 min • by Bill Staples

GitLab’s CEO lays out their vision and plan for a major restructuring of the company around agentic AI and the future of software delivery. Interesting both as a product vision and as a case study in leading a public company through a platform shift.

🥉 Thin Harness, Fat Skills

6 min • by Garry Tan

By now we know that AI agents become far more productive by using purpose-built skills. It’s still unclear how all of this scales, but Garry’s mental model about growing skills instead of the general harness is solid, and I agree with him.

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

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

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today’s guest is Doug Peete, Chief Product Officer at Atono, with whom over the last few months we have developed a deep industry report about the state of product development.

In this chat we’ll go through the main findings of the report, match them to our respective experience and explore ideas about how teams can do better with product development and AI.

🥇 Interview Summary

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

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

Here is the agenda for today:

1. 📋 Why planning is so fragile

2. 📝 The requirements problem

3. 🧠 Knowledge sharing and tribal knowledge

4. 🤖 AI adoption: individual vs. team

5. ✏️ AI for product specs, the untapped opportunity

⠀Let’s dive in 👇

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 🙏🙇‍♂️

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

Become an investor in AI infra startups! ✨

Today’s sponsor is Alumni Ventures!

If you ever thought about doing some angel investing in AI products you like, you can do so via our friends at Alumni Ventures, that give you access to high-growth startup opportunities, co-invested alongside top VC firms like Andreessen Horowitz (a16z), Bessemer, & YCombinator.

You can signup for free and get:

• A curated deal flow of high-potential AI infrastructure startups

• Deals in which AV is already investing alongside elite lead venture firms

• No cost to see deals, and no obligation to invest

Join Alumni Ventures AI Infrastructure Syndicate Today →

💡 Never start from a blank page

A lot of people ask me how I take notes and write articles — even more so recently, since I shipped Tolaria.

I have often talked about this in the newsletter. I am quite opinionated about it, and a lot of these opinions made it into Tolaria.

One of these is about the (in)famous blank page.

There is this romantic view of writers sitting in front of a blank page and crafting their work through sheer inspiration. In reality, if you’re starting from nil, you’re doing it wrong.

About this, I love a famous quote from an Italian singer-songwriter, who once was asked how long it takes to write a song. He said:

“It takes me about 10 minutes — but only if I spend the rest of my life making sure that eventually it takes me 10 minutes.”

This applies to all knowledge work. Good writing is about connecting and refining ideas you already captured, rather than creating from scratch. The prep work is the work.

To make prep work easier, I am a big believer in dividing it into multiple steps:

• Capture — store the thought on a durable support.

• Organize — refine it, place it where you’ll need it, and connect it to other thoughts.

• Express — use it to do something larger.

These are different tasks, and are best done at different times. Conflating them leads to predictable failure modes:

• Capture + Organize leads to exhaustion (every note becomes a chore).

• Organize + Express leads to chaos (missed insights, no scalability).

• All three at once leads to writer’s block.

Luhmann’s Zettelkasten and Tiago Forte’s CODE system are both built around this separation. You don’t need to follow either to the letter, but the principle matters.

I wrote a full piece about note taking a while back 👇

Refactoring

How To Take Notes 🌱

Hey there! Last week we had our book club review of How to Take Smart Notes, by Sönke Ahrens…

Read more

10 months ago · 53 likes · 3 comments · Luca Rossi

🎙️ Principles for better decisions

One of the interviews I go back to the most often is the one I did last year with Annie Duke.

Annie is a former world-class poker player, author of Thinking in Bets, and one of the clearest thinkers on decision-making.

The conversation was packed with useful frameworks, and one that stuck with me was her four-principle checklist for high-quality decisions:

• Speed assessment — before anything else, decide how much time this decision deserves. Ask: how long-term is the impact, and how reversible is it? Spend time and effort accordingly.

• Make the implicit explicit — we often decide by “feel.” Annie’s view, instead, is to articulate what that gut feeling actually is. What are the real criteria? Making reasoning explicit helps you catch flawed logic before you commit, and makes it harder to rationalize a bad choice after the fact.

• Quantify qualitative opinions — instead of calling a market “great,” rate it. Even in a shallow way, e.g. on a scale from 1 to 10. This forces precision and, in teams, surfaces hidden disagreements otherwise masked by vague language.

• Collect opinions independently — never gather important input in a group setting. Anchoring bias and groupthink are real. Collect individual perspectives first, then compare differences without forcing consensus.

Here is the full interview with Annie:

📚 Weekly Readings

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

🥇 Sometimes Your Job Is to Get in the Way

5 min • by Rands

Good leaders know when to stay out of the way — but great leaders also know when to step in and draw a hard line. Fantastic story by Rands, about how a major Slack outage led to a complete transformation of their development process, driven by strong leadership.

🥈 Why Can’t They Just…

5 min • by Lara Hogan

“Why can’t they just…” is a phrase we all use when frustrated with other teams or roles. Instead of dismissing it, Lara explains how to use it as a signal to dig into the complexities behind decisions you don’t understand, and turn frustration into collaborative problem-solving. Loved it.

🥉 Contributor Poker and AI

6 min • by Loris Cro

Open source maintainers don’t bet on PRs, they bet on contributors. This is a great take by Zig and the best articulated thesis I have heard about banning AI-generated contributions. Worth a read.

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

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

Make your team ship faster!

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

Stop babysitting your agents! 🙅‍♂️

Today’s newsletter is brought to you by our friends at Unblocked!

Agents can generate code, we know it.

But getting it right for our system, conventions, and past decisions is still the hard part — we waste time and tokens in correction loops. Patching many MCPs together may give agents access to information, but not necessarily understanding.

That’s why I am a fan of what Unblocked is building with their context engine — giving agents exactly what they need to understand things and succeed. Join their webinar on May 6th (free) to see:

• Where teams get stuck on the AI maturity curve

• How a context engine solves for quality, efficiency, and cost

• Live demo: the same coding task with and without a context engine

Learn more and register!

💡 Personal leverage is now unlimited

A couple of months ago I wrote about my experience with OpenClaw — what I do with it, what procedures it runs automatically, and so on.

I also argued that the story of OpenClaw itself seems to point to the idea that a good solo engineer can now achieve… pretty much anything. Look at the progression of AI assistants and coding tools:

1. At first, it was VS Code + Copilot. Created by Github/Microsoft, which is a big tech.

2. Copilot was surpassed by Cursor, created by a team around 1/100th its size.

3. Cursor was then surpassed by Claude Code, which has been created literally by 2 engineers inside Anthropic, and whose team to this day is ~20 engineers.

4. OpenClaw has been created by Peter Steinberger. That’s it.

In my (very small, comparably) experience with Tolaria, I am seeing this as well. If you are equipped with the right set of ingredients, it’s hard now to see the limits of what a single engineer can do. But what are these ingredients? To me it’s:

1. 🔧 Tech skills — you still need these! Especially to steer a sizable project. E.g. Peter is first and foremost a world-class engineer.

2. 🧑‍🍳 Taste — your personal taste for what good looks like, your domain expertise, how knowledgeable you are about the problem you want to solve, your product senses — these are the things that AI is not going to replace anytime soon, if ever.

3. 🏃 Drive — above all, the drive and discipline needed to put something out there. I know an awful lot of people who have the first two ingredients, but kinda miss this one.

My OpenClaw article is one of the most popular pieces I have ever written, you can catch up with it below 👇

Refactoring

My experience with OpenClaw 🦞

Hey, Luca here! This is a 🔒 weekly essay 🔒 from Refactoring! To access all our articles, library, and community, subscribe to the full version…

Read more

4 months ago · 53 likes · Luca Rossi

🎙️ Junior engineers will just be fine

Last month I interviewed the legendary Chris Lattner on the podcast. Chris created LLVM, Swift, led Tesla autopilot, brought TPUs to the market at Google, and more! He is now the founder of Modular, where he creates portable infra to work with GPUs.

Chris told me that, despite the industry-wide narrative that AI favors senior engineers, Modular is actively hiring a ton of new college grads and interns. Chris’ reasoning is based on two observations:

• 🧠 AI-native thinking — junior engineers bring a completely different expertise. They are native to the tools and adapt faster than many experienced engineers.

• ⚖️ Team balance — good teams need people at multiple levels learning from each other. All-senior or all-junior teams both fail in different ways. (we wrote about this also here!)

You can find the full interview with Chris below:

You can also find it on 🎧 Spotify and 📬 Substack

📚 Weekly Readings

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

🥇 The Last Software Engineer

10 min • by Kent C. Dodds

Fast forward to the moment right before AI takes over everything engineers do — what’s the last valuable thing left? I won’t spoiler! Fantastic article by Kent.

🥈 Why Sell Software If Anyone Can Make It?

2 min • by Clemens Adolphs

It’s not hard to make bread at home — even better than the one you buy at the bakery. Yet nobody really does it at scale. Don’t let the “everyone can code now” narrative scare you out of building a software business.

🥉 How I use AI to Code

19 min • by Chris Sherwood

A thorough, opinionated guide on AI coding, updated to April 2026. Covers both the mindset and the practical tools. I liked it!

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

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

Make your team ship faster!

See you next week!
Luca

Today’s sponsor is Intent by Augment.
Intent is a developer workspace built for orchestrating agents: it starts with the living spec that updates as agents make progress, so every task stays aligned with no manual coordination. Try it for yourself at https://www.augmentcode.com/product/intent

Today's guests are Jean Hsu and Cate Huston!

Jean and Cate are extremely experienced engineering leaders and coaches, accomplished authors, and have held leadership roles at companies like DuckDuckGo, Automattic, Medium and more.

They now run a program to help engineers and managers become directly responsible individuals for their careers, to navigate these complicated times.

With Jean and Cate, we talked about exploring what you want from your career, how to be intentional about it, how to use feedback to assess how you're doing, and how AI is changing and not changing the picture.

Also check out DRI Your Career — their course! If you use the code REFACTORING you get 15% off!

If you like the podcast, please give us a rating on your platform of choice! It means a lot to us — that’s how other people discover the show! ⭐⭐⭐⭐⭐

🥇 Interview Summary

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

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

Here is the agenda for today:

1. 🌪️ Why these times are uniquely challenging

2. 🧭 Figuring out what you actually want

3. 🔁 Feedback, accountability, and the power of coaching

4. 🤖 AI: Identity shifts and finding your way

5. 💡 Minimizing emotional work, maximizing outcomes

⠀Let’s dive in 👇

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

Reporting from Salesforce’s TDX event! 🧑‍💻

This week’s sponsor is Salesforce!

Our friend Conor Bronsdon was our eyes and ears on the floor at TDX last week, and wrote a full breakdown on Chain of Thought.

He says Agentforce is now Salesforce's fastest-growing product, and the signs were everywhere at TDX:

• 60+ new MCP tools in Headless 360

• Agent Script open-sourced on GitHub

• Agentforce Vibes 2.0 (their vibe coding tool),

• plus new Slack agent capabilities.

Salesforce went as far as publishing the full language spec, grammar, parser, and compiler for their agent-definition language.

They're betting an open agent ecosystem wins developer adoption, while enterprise-grade upgrade paths let businesses actually ship reliable agents to production.

Read the full TDX breakdown

💡 Coding is not solved, but bad code… kinda is

Last week I launched Tolaria, which by now is one of the fastest growing repos on the whole Github! It got 6000+ stars in less than a week.

Tolaria is a lot of code: 100K+ LOCs, 2K+ commits, 3K+ tests, 70+ ADRs. I publicly said many times I didn’t write any of it, which made some people think I believe coding is solved.

I don’t think coding is solved at large, but bad code feels solved. To understand what I mean by that, a useful way to think about tech debt is to split it into two kinds:

• Bad code

• Misaligned code

Bad code is basic hygiene failure: lack of tests, high complexity, tight coupling, duplication, outdated libraries. It is bad regardless of business context, and we know it increases lead time, outages, and maintenance cost.

As of today this kind of debt is largely avoidable if you choose to enforce quality. On Tolaria, AI-generated code must meet three gates: high test coverage, strong CodeScene health scores, and current library/docs usage. These rules live both in CLAUDE.md and CI, because agents still forget or ignore instructions. Once those checks are in place, the basics can be trusted without manually reviewing every line.

Misaligned code is harder, and is definitely not solved yet. Code may be clean, tested, and well-structured, but still wrong for the product direction you want. It’s code that is a good circle when you really needed a square: a leaky abstraction, an old design assumption, or a model that no longer matches intent.

Reviewing architecture and abstractions still feels supremely important, because they're the things that the AI model can’t figure out by itself, because they are about what you want to build in the future, and why.

I wrote more about this in my series of articles about my AI coding workflow:

1. My AI Coding Workflow (Feb 2026)

2. Updates to My AI Coding Workflow (Apr 2026)

3. Introducing Tolaria (last week!)

🎙️ Progressive disclosure of complexity

In May last year I interviewed Guillermo Rauch, founder and CEO of Vercel

Guillermo talked about the qualities of great technology, and one principle that stuck with me was what he called the progressive disclosure of complexity.

A defining feature of great tech is that’s approachable for beginners but powerful enough for enterprise needs.

This principle guides the design of Vercel, Next.js, and everything they do.

“I’m building a platform that should not be intimidating for your first line of code, and gives you the superpower that you could be one day a top 30 internet website with the same infrastructure, with the same tools, with the same access.”

Guillermo draws inspiration from products like the iPhone, which can be used by both children and the elderly while still serving business professionals with complex needs.

His approach to API design focuses on what he calls token minimization (not AI tokens!) — requiring minimal code to get started, then gradually introducing more sophisticated features as needed:

• 🏁 Low barrier to entry — a new Next.js project can be started with just a few lines of code.

• 🌱 Growing with users — complexity is only introduced when needed for specific requirements.

• 🔄 Same technology at all scales — the technology that powers a beginner’s first project is the same that can scale to handle millions of users.

Here is the full interview with Guillermo:

You can also find it on 🎧 Spotify and 📬 Substack

📚 Weekly Readings

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

🥇 My CTO Daily Driver

8 min • by James Stanier

I basically recommend all of James’ articles, and this makes no exception. He explains how he uses Claude Code to drive a personalized CTO workspace with memory. With custom slash commands tied to Linear, Notion, and BetterStack.

🥈 The Peril of Laziness Lost

12 min • by Bryan Cantrill

Laziness has always been a programmer’s virtue — it’s what drives us to build abstractions instead of doing the same thing twice. LLMs don’t have that instinct: you have to supply it to them. If you don’t, you lose the elegance, efficiency, and maintainability that comes from human constraints.

🥉 99% of Our Production Code Is Written by AI

20 min • by Peter Pang

Took a lot of ideas from this post. Feels a bit AI-generated at times, but the ideas around feature gates, self-healing feedback loop, and bug fixing are awesome. Peak “harness engineering”, as kids call it these days.

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

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

Make your team ship faster!

See you next week!
Luca

It went viral on X, got a ton of replies via email (sorry if I didn’t get back to everyone yet!) and an insane 700 stars on Github.

As a refresher, if you missed yesterday’s email, Tolaria is a free & open source desktop macOS app for managing markdown knowledge bases. It’s similar to Obsidian, but:

• The look & feel and editor is closer to Notion

• Has opinionated ideas about how to organize notes into types and views

• Has first-class git support for syncing files

• Is 100% open source

We have also been hunted on Product Hunt and I would be incredibly grateful if you could upvote it 🙏

Upvote Tolaria on Product Hunt 🙏

Thank you so much! Tell me your thoughts if you try it!

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

Stop babysitting your agents 🍼

Today’s sponsor is Unblocked!

Agents can generate code. But getting it right for your system, conventions, and past decisions is the hard part — you end up wasting time and tokens in correction loops.

More MCPs give agents access to information but not understanding. The teams pulling ahead use a context engine to give agents exactly what they need.

Join our friends at Unblocked on April 23 (FREE) to see:

• Where teams get stuck on the AI maturity curve

• How a context engine solves for quality, efficiency, and cost

• Live demo: the same coding task with and without a context engine

Register now!

💡 Developer Experience is your floor

By now we all largely agree that AI amplifies your existing dev practices — good and bad. I think what most people don’t realize is just how strong the amplification is.

Last month I commented on the recent State of Software Delivery report. With respect to one year ago, the median team sees:

• 📈 +15% activity on feature branches

• 📉 -7% activity on the main branch

• 📉 -15% success rate on the main branch

These numbers are brutal: the average team sees exactly zero impact from AI. Even negative in some cases, as displayed by activity on the main branch.

On the other end, if you look at the top quartiles, the reality is different. Top 5% teams are ~2x as fast, with the same success rate. Top 10% teams are +50% faster, and top 25% are +25% faster.

These are big numbers, and they come from the teams who were already at the top 3 years ago. So, paraphrasing the famous quote, the best time to invest in good devex was years ago, but the second best time is now.

Good devex is the floor that enables a team to profit from AI. I like the idea that good devex is enabled by three factors:

• 🧠 Balanced cognitive load — work is challenging but achievable.

• 🔄 Tight feedback loops — engineers are continuously informed that are going in the right direction.

• ⏱️ Enough focus time — engineers have enough uninterrupted time to do what they need to do.

When these three things happen, engineers can enter a flow state: complete immersion in their activity with extreme focus, productivity, and personal enjoyment.

Here are some questions you can ask yourself to assess where you at with these:

• Reduce cognitive load → What feels hard as a developer? How can I make it easier?

• Tighten feedback loops → What feels slow? How can I make it faster?

• Improve focus time → What feels wasteful? How can I reduce interruptions?

I wrote a full piece about DevEx, AI, and Product Engineering, and how these are the new pyramid of software engineering 👇

Refactoring

The New Pyramid of Software Engineering 🏔️

There are a lot of opinions around these days about the future of software, including of course my own…

Read more

3 months ago · 49 likes · Luca Rossi

🎙️ Why did the day need saving?

Last year I interviewed Rands—one of my heroes—and we talked a lot about AI, engineering management, and things we are getting wrong in tech.

Rands believes, as an industry, we are too attached to hero culture that celebrates heroics and save-the-day moments.

“Good job saving the day. Why did the day need saving? We screwed up and you had to save the day so good job cleaning up your screw up.”

Rands believes in proactive prevention rather than reactive heroics: addressing issues when they are still yellow flags, instead of big red ones. Effective management goes unnoticed because teams function smoothly — but that should be a badge of honor.

Acts of prevention sometimes are hard because they go against your instincts, like giving early corrective feedback before problems escalate. It feels easy and innocuous to avoid these small-scale conflicts, but these are exactly what you need to prevent the big fuck-ups.

Here is the full interview with Rands:

You can also find it on 🎧 Spotify and 📬 Substack

📚 Weekly Readings

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

🥇 Who Will Be the Senior Engineers of 2035?

11 min • by James Stanier

Great article by James, who put together a lot of resources and ideas (also from different industries), and connected the dots to understand what may happen to the software engineering job market. Recommended read.

🥈 Open Source Isn’t Dead

3 min • by Alex Schapiro

Cal.com recently announced it’s going closed source, citing AI vulnerability scanning as the #1 reason. This piece pushes back, and I actually agree with it: closing source code doesn’t remove the attack surface — AI can still attack you black-box, at runtime. The better response is continuous AI defense (fire with fire!).

🥉 Agents as Scaffolding for Recurring Tasks

4 min • by Will Larson

Great practical pattern for introducing agents into your workflows: start by prototyping with agent-driven automation, then refactor some agentic parts away into deterministic code, keeping the agent only where it truly shines: navigating ambiguity.

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

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

Make your team ship faster!

See you next week!
Luca

Today’s sponsor is Intent by Augment.
Intent is a developer workspace built for orchestrating agents: it starts with the living spec that updates as agents make progress, so every task stays aligned with no manual coordination. Try it for yourself at https://www.augmentcode.com/product/intent

Today's guest is Stuart Caborn, Distinguished Engineer at Loveholidays, an online travel agency with millions of customers worldwide.

Stuart's team is doing AI coding for real:

• Each engineer deploys to production more than 80 times a month

• Over 60% of production code is written by AI

• All while maintaining an elite change failure rate under 1%, and perfect code health.

If you like the podcast, please give us a rating on your platform of choice! It means a lot to us — that’s how other people discover the show! ⭐⭐⭐⭐⭐

🥇 Interview Summary

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

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

Here is the agenda for today:

1. ✈️ The complexity of online travel

2. 🏥 Code health before AI

3. 🤖 Becoming an AI-first engineering team

4. 🛡️ Guardrails, reviews, and trusting the machine

5. 🔄 How AI is changing the development process

⠀Let’s dive in 👇

Read more

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

How Augment Code is going AI-native

Today’s sponsor is Augment Code!

The guys at Augment have been documenting how they are transforming their engineering team to be AI-first, in several great blog posts:

• How we hire AI-native engineers now

• Confidence is the new bottleneck

They would also love to hear from other leaders going through the same thing, and have been running a quick survey for this. You can find it below 👇

Check out the 5-min survey

💡 Just ask engineers

By now, as of 2026, there is solid consensus that good developer experience is upstream of how your engineering team performs as a whole. And good devex is, in turn, mostly about removing friction from the daily work of engineers.

To remove friction you first need to know where it hides. What are the biggest blockers for your team? What is slow, hard, or simply a waste of time?

As engineers, we have a natural bias towards telemetry — quantitative data taken automatically from our processes, so we can debug it as if it were software. This is increasingly backed by research, from Accelerate onwards, and I have written extensively about it:

• How to get started with engineering metrics

• What’s next in measuring dev productivity

• You have metrics, now what?

To summarize what I think about metrics: they are good, but they are not enough. Most metrics are cues that something is (or is not) working, but they don’t tell you what the problem is. They are lagging indicators: to find the actual blockers, you need to dig deeper.

How? The answer is usually deceptively simple: ask engineers. They know.

If you combine qualitative signal from engineers’ opinions with quantitative data from your systems, you’ll be unstoppable. But counterintuitively, most managers find it harder to do the former—have good conversations to identify problems—than the latter.

So, I am a fan of doing the so-called Listening Tour, whose name I lifted from Frictionless, but whose execution I tweaked based on my own experience. I wrote a full piece about it at the start of the year, and I still stand by it 👇

Refactoring

The Listening Tour 📞

For the last month I have been running a program for CTOs and VPs of small to mid-size companies to help them make their engineering teams ship faster…

Read more

4 months ago · 35 likes · 3 comments · Luca Rossi

🎙️ Past behavior predicts future results

With tech chops getting a bit diluted by AI, behavioral interviews have recently gotten into the spotlight as a crucial way to select good engineers. Always have been? Probably — but today, even more so.

I recently talked about this on the podcast with Austin McDonald, former hiring committee chair at Meta. Austin said behavioral interviewers are essentially forecasters: they study your past performance to predict your future results. And, with people, this generally works (unlike with financial portfolios!)

Austin breaks down what interviewers look for into signal areas:

• 🎯 Scope & ownership — how large a project can you handle, and do you drive it forward without being asked?

• 🌫️ Ambiguity & perseverance — how do you navigate unclear situations and push through setbacks?

• 🤝 Conflict resolution, communication & leadership — how do you handle disagreements, convey ideas, and rally teams?

These signal areas map closely to most company values, but not always one-to-one. Newer AI companies like Anthropic, for instance, look for safety-oriented signals about thinking through the implications of building AI.

So Austin recommends combining general areas with company-specific research—their website, recruiter conversations, YouTube talks—to build a complete picture of what you’ll be assessed on.

“Every question they ask has this kind of thing behind it. Especially follow-up questions. People often forget — when they get a follow-up question, they just think the person wants more information. Instead, think: why are they asking me this?”

In fact, companies exist on a wide spectrum:

• Amazon sits at one extreme end with 16 rigorously enforced leadership principles.

• Meta is in the middle with five structured behavioral areas.

• Google has traditionally leaned more technical.

Here is the full interview with Austen:

You can also find it on 🎧 Spotify and 📬 Substack

📚 Weekly Readings

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

🥇 The Git Commands I Run Before Reading Any Code

3 min • by Ally Piechowski

Great piece that makes you understand the power of version control history. There is so much you can understand about a codebase (and a team) by running simple git commands. Hotspots, bus factor, bug clusters, crisis patterns — all from git history.

🥈 Feedback Flywheel

10 min • by Rahul Garg

I really liked this article — it’s very practical and proposes some novel angles to AI feedback. Every AI interaction generates signal: prompts that worked, context that was missing, patterns that failed. Rahul proposes a structured practice that takes learnings from AI sessions and feeds them back into the team’s shared artifacts.

🥉 The Human Weight of It

7 min • by Cate Huston

Can Claude replace coaching? Cate has been experimenting: using AI for structured issues, but keeping her human coach for the messier stuff. AI is great when you need structure and validation. But when you need to feel seen, you need the human weight of someone else’s confidence in you. I loved it.

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

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

Make your team ship faster!

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