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

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

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

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

So here is the agenda:

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

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

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

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

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

Let’s dive in!

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

Download the full report

📊 Speed is real but uneven

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

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

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

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

🧱 Orgs are not multiplying AI output

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

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

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

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

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

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

Read more

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

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

Learn more and RSVP!

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

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

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

Here is the agenda for today:

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

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

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

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

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

Let’s dive in

🔺 Model Selection 101

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

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

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

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

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

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

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

• ⚡ Speed — tokens per second

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

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

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

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

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

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

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

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

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

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

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

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

📊 Public benchmarks are not enough

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

Read more

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

Subscribe now

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

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

1. Roadmap / long-term product strategy

2. Impromptu requests from key customers

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

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

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

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

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

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

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

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

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

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

So here is the agenda for today:

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

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

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

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

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

Let’s dive in!

⚖️ Customer work vs product work

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

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

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

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

• When and how such work spawns

• How urgent it is

• How big it is

• How it fits your overall strategy

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

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

This leads to questions:

• When is it worth to do these things?

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

Let’s start with the first one.

Read more

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

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

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

So let’s dive in!

💧 The State of Tolaria

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

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

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

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

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

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

Enter our tech alliance!

🦸‍♂️ Creating our own Tech Alliance

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

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

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

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

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

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

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

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

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

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

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

So let’s go 👇

🩺 Code Health — with CodeScene

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

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

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

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

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

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

🔒 Security and Quality — with Codacy

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

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

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

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

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

✅ Validation — with CircleCI

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

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

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

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

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

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

📖 Fetching knowledge — with Unblocked

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

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

I was wrong.

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

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

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

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

🔭 What’s next

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

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

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

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

Sincerely 👋
Luca

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

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

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

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

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

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

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

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

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

Here is the agenda, with my main takeaways:

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

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

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

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

Let’s dive in!

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

Check out the full report

🏁 Finishing work is hard

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

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

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

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

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

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

1. More work gets started, but

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

3. The quality of such work is noticeably lower

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

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

• +67% PRs touched / day

• +18% separate tasks

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

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

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

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

• -12% deployments per week

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

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

This is not surprising if we remember that:

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

Enter the elephant in the room: code reviews 👇

🔍 Reviews are completely broken

Read more

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

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

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

So, “my job is to write loops.”

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

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

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

But how do you ensure that?

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

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

Namely, product.

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

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

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

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

So here is the agenda:

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

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

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

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

Let’s dive in!

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

Learn more about Atono

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

⚔️ Why product is harder than coding

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

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

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

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

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

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

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

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

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

🏗️ ADRs

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

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

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

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

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

📋 Towards Product ADRs

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

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

• 🎨 Design — how we decided to do it.

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

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

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

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

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

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

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

📖 Product Glossary

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

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

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

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

An example from Tolaria may include concepts like:

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

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

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

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

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

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

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

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

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

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

🔄 Product process

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

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

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

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

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

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

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

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

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

Sincerely 👋
Luca

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

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

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

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

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

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

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

• 6 open issues — vs 417 closed.

• 14 open PRs — vs 306 closed.

• 1 day — average bug fix time.

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

• ~28 commits / day — on average.

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

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

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

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

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

Here is the agenda for today:

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

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

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

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

Let’s dive in!

🚥 Guides, Gates and Guards

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

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

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

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

These steps are also somewhat sequential:

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

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

• Guards are the last line of defense against enshittification.

Let’s look at all of them:

1) Guides ↪️

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

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

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

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

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

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

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

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

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

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

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

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

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

Read more

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

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

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

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

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

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

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

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

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

5. 🔀 Staged automation of a complex upstream merge

Let’s dive in!

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

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

Subscribe now

1) 🚜 The combine harvester pattern for long AI tasks

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

The markdown file holds:

• The instructions

• The progress so far

• What should happen next

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

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

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

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

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

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

I call these guards.

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

But there are things that are hard to gate:

• Did this change need an architecture decision record?

• Has an opportunity to refactor been missed?

• Is performance drifting over time?

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

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

Read more

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

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

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

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

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

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

• Lifecycle — how information flows and is operated.

Portent was built with a few goals in mind:

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

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

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

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

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

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

• 🍱 Types — the eight main types

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

• 🔄 Lifecycle — capture → organize → archive

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

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

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

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

Hope to see many friends there and say hi!

📹 Walkthrough

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

📖 Backstory

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

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

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

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

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

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

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

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

• Flexible — to accommodate for personal tweaks and preferences.

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

🍱 Types

Portent recommends organizing data into eight main types:

1. Projects

2. Operations

3. Responsibilities

4. Tasks

5. Events

6. Notes

7. Topics

8. People

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

These types are grouped into two clean categories:

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

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

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

🔥 PORT

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

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

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

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

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

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

Responsibilities

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

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

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

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

Projects

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

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

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

Operations

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

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

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

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

Tasks

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

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

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

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

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

🌱 ENTP

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

Let’s look at them one by one:

Topics

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

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

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

Events

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

People

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

Notes

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

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

🔀 Relationships

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

Portent encourages two in particular:

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

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

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

• Belongs to → Has, or Children

• Related to → Referred By

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

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

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

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

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

1) Relational DBs (tabular data)

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

These relationships create a schema that is:

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

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

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

2) Folders (hierarchical data)

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

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

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

3) Graph relationships

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

In fact:

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

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

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

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

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

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

Next, let’s talk of lifecycle 👇

🔄 Lifecycle

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

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

More on each:

1) Capture

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

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

2) Organize

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

• What is this?

• What should I do with it?

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

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

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

3) Archive

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

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

🔌 Extending Portent

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

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

Common ones in my experience are:

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

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

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

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

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

🔨 Tolaria implementation

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

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

Tolaria is good for Portent because:

1) Lifecycle management

Capture → Organize → Archive is directly supported in Tolaria:

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

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

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

2) Types & Relationships

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

3) Multiple vaults

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

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

I wish you a great week

Sincerely 👋
Luca

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

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

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

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

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

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

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

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

So here is the agenda:

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

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

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

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

Let’s dive in!

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

Learn more about Kestra

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

🧹 Cleaning up releases

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

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

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

1. Fetch Github commits shipped with release

2. Match commits to the associated tasks on Todoist

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

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

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

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

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

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

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

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

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

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

⚖️ Pure AI vs Orchestration

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

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

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

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

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

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

So where do we go from here?

🏗️ Agents as scaffolding

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

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

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

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

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

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

🗺️ Workflow engineering journey

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

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

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

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

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

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

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

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

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

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

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

Sincerely 👋
Luca

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

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

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

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

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

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

• 200+ issues on Github

• 150+ PRs

• 150+ feature requests on Canny

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

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

• 15 open issues

• 11 PRs

• 81 feature requests

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

So here is the agenda:

• 📥 Inputs — mapping and normalizing sources and channels.

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

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

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

• 📊 Analytics — tracing what happens in production.

Let’s dive in!

📥 Inputs

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

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

1. Bug reports from users

2. Feature requests from users

3. PRs from contributors

4. Crash reports from telemetry (Sentry)

5. My own ideas (hello 👋)

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

More specifically:

• #1 and #4 spawn bugs

• #2 and #5 spawn features.

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

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

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

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

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

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

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

Still a lot of things go wrong all the time:

Read more

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

Before this one we published:

1. The Era of the Software Factory

2. How to Grow your Software Factory

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

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

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

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

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

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

This seems good enough, so why a third article?

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

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

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

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

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

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

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

Let’s dive in!

Read more

Check out Tolaria 💧

What is Tolaria?

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

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

• Second brains and personal knowledge

• Company docs as context for AI

• OpenClaw / assistants memory and procedures

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

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

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

So, this newsletter will explain a few things:

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

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

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

• 🔧 How Tolaria works — the main parts.

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

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

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

Subscribe now

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

📹 Walkthroughs

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

• How I Organize My Own Tolaria Workspace

• My Inbox Workflow

• How I Save Web Resources into Tolaria

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

🌀 Tolaria + Refactoring

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

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

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

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

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

So far, it scales.

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

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

• 1900+ commits

• 3000+ tests

• 70 ADRs

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

So, my commitment with Tolaria is the following:

• I will keep it free & open source forever.

• I will run my life and business on it.

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

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

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

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

⭐ Principles

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

🔧 How Tolaria works

Tolaria is organized into a few main components:

1. Sidebar — for filtering notes in various ways

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

3. Editor — for editing the current note.

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

Let’s look at each of these 👇

1) Sidebar

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

Tolaria allows you to do so in many ways:

📥 Inbox

Notes that haven’t been organized yet.

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

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

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

🗃️ All Notes

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

📦 Archive

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

🧩 Types

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

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

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

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

⭐ Favorites

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

You can reorder them by dragging them in the sidebar.

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

🔍 Views

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

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

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

📂 Folders

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

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

🗑️ Trash

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

2) Note list

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

⬇️ Sorting

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

Your choice will be remembered for that specific section.

💅 Display Properties

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

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

3) Editor

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

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

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

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

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

4) Git

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

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

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

5) Commands

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

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

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

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

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

🔬 What you will find in the repo

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

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

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

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

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

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

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

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

➡️ Next Steps

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

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

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

Sincerely 👋
Luca

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

Join our AI Club 🪄

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

🎯 Why I am starting an AI Club

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

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

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

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

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

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

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

Yay!

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

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

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

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

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

ℹ️ How it works

Here is the gist:

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

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

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

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

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

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

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

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

🔒 About the Refactoring subscription

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

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

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

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

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

Join our AI Club 🪄

And that’s it for today!

Sincerely 👋
Luca

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

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

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

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

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

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

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

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

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

So here is today’s agenda:

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

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

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

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

• 🎨 Product workflow — how I create specs.

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

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

Let’s dive in!

💧 Building Tolaria

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• ~70K LOCs — about 45 lines / commit

• ~3000 tests — about 85% coverage

• 9.5/10 code health — as measured by CodeScene

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

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

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

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

🦞 OpenClaw vs Claude Code

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

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

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

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

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

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

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

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

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

🔧 Coding workflow

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

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

Read more

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

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

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

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

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

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

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

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

Let’s dive in!

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

Learn more about CircleCI

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

🧮 DORA metrics and LOCs are not enough

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

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

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

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

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

• -6.8% commits in production

• -14% deployment success rate

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

This is both a blessing and a curse.

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

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

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

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

What are the leading indicators of AI success?

Read more

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

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

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

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

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

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

So here is the agenda for today:

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

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

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

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

Let’s dive in!

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

Learn more about Intent

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

🔀 From Intent to Code

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

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

1) Product intent

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

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

2) Product specs

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

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

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

3) UI/UX design

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

4) System design

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

5) Code!

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

Phew. That’s a lot of work.

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

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

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

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

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

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

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

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

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

Let’s explore both 👇

🧱 Create good platform for each step

Read more

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

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

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

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

This research was made possible by our partnership with Atono.

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

Learn more about Atono

So here is the agenda for today:

1. Demographics — a quick note on the data.

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

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

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

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

Let’s dive in!

🗳️ Demographics

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

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

5️⃣ The Five Problems

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

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

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

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

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

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

These numbers point to a few larger problems:

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

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

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

So let’s dive into the details!

🗺️ The Planning Problem

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

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

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

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

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

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

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

— Tech Lead

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

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

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

— Software Engineer

Part of why this persists is where product knowledge lives.

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

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

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

— Engineering Manager

🪄 AI in the Workflow

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

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

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

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

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

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

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

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

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

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

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

One engineer also described the mess directly:

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

— Software Engineer

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

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

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

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

• Engineering managers the lowest (48%)

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

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

🧪 The Experimentation Gap

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

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

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

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

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

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

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

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

🔭 The Way Forward

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

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

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

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

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

2) From accelerating execution to improving problem framing

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

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

3) From side-hustle AI learning to structured experimentation

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

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

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

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

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

See you next week!

Sincerely 👋
Luca

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

Learn more about Atono

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

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

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

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

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

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

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

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

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

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

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

These ideas come from many places:

• My own experiments — as you saw last week.

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

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

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

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

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

1. 🔧 Developer Experience

2. 🪄 AI

3. 🎨 Product Engineering

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

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

🔧 Developer Experience

Read more

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

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

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

So here we go.

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

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

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

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

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

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

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

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

• Not writing any code.

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

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

• Managing most interactions async via voice notes.

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

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

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

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

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

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

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

🖥️ What I am building

Read more