Software development
-
Boring Is a Feature
What does boring look like in the age of AI? And I’m not talking about uninteresting. I’m talking about highly maintainable.
JavaScript?
I mean I guess models are good at it. Everybody knows it. It runs everywhere. The biggest problem with JavaScript is that TypeScript is better.
Certainly it’s better than picking a novelty language that you haven’t built anything with before. Does anybody on the team actually know Haskell? And how long ago did they know Haskell? You need to evaluate the cost of adopting it just as you would evaluate how long it would take to learn it and train the team on it.
The upfront cost can be easier to measure. But the recurring ones are much harder to predict. What happens when a maintainer moves on from a package that everyone uses, and the speed it takes to find a new maintainer is not as fast as you need it to be?
Boring tools are ones where the recurring cost of maintenance is as close to zero as you can get it. If you come back to it in eight months, it should work the way you remember it. This is a fairy tale that we tell ourselves, that nothing ever changes and we can control that change.
Is boring even possible in the age of AI, when it feels like everyone has their own particle beam cannon that they can point at your codebase?
I think it’s worth talking about what I mean by boring, because it can be used as a synonym for old, but that’s not what I mean. Boring means predictability.
Take all your npm packages. Can you answer these questions about all of them? Probably not.
- How often do the release notes contain the word “breaking”? Skim a year of them. This is the single best signal available and it takes ten minutes.
- How many people can merge? One is a risk regardless of how good that one person is. People change jobs, burn out, and lose interest.
- What happens to old versions? A project that supports the previous major for a while is telling you something about how it thinks about your time.
- Can you read the source? Not all of it. Enough to fix something yourself when you’re blocked and nobody’s answering.
Learn the new tool. Experiment. Try new things. Stay passionate about software. Just because you can use the new thing doesn’t mean you should.
Don’t always pick the boring option, just like you don’t always pick the new option. It takes wisdom to know what the right answer is.
You have to understand your failure modes, and when it’s an appropriate time to take a risk, and the scale of the risk.
Pick boring for the parts you don’t want to think about. Save the interesting decisions for the places where being interesting is the point.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
DevOps Developer-tools Software-development Engineering Tooling
-
The Best Automation Has a Manual Escape Hatch
Automation earns trust by being easy to override, not by being impossible to question.
That sounds backwards. The pitch for automating something is usually that it removes the human, and a system you keep reaching into feels like a system that didn’t finish the job. But the automation you actually trust, over years, is the one you know you can stop.
Most automation that you set up is enforcing some sort of policy, and that’s right most of the time, but not always.
The mistake isn’t automating a default way of working. It’s building a system where the default is ingrained so deeply that there’s no way out of it.
The automation must be flexible. You must be able to adapt the automation as the requirements change.
Do you have contingency plans on what to do if the automation fails?
Now I’m not talking about how to get around the automation, or always forcing an outcome that disables the automation. Instead, I’m talking about what a real escape hatch looks like.
It’s one operation. You run a command. You don’t perform a sequence of five steps where forgetting the third leaves things inconsistent.
It maintains the invariants. This is the big one. When I override a post’s date, the file and the database both get updated. If the override only touched one of them, I’d have created a split-brain problem in the name of fixing a scheduling problem.
It’s discoverable. It shows up in the help output next to everything else. An escape hatch nobody knows about is not a feature, it’s trivia.
It’s supported, not tolerated. It has tests. It survives refactors. Nobody has to feel clever for using it.
If your answer to “what if the automation is wrong” is “go around it manually,” you don’t have a hatch. You have a hazard with a tradition attached.
If you design the escape hatch first, it forces a question that’s worth thinking about. At least what happens when the automation is wrong. What are your plans to do something about it?
Log When the Hatch Gets Used
Don’t forget about the log. It’s not one that you should skip over. You should be logging when your escape hatch gets used, even if it only happens once a quarter.
You probably don’t need to update your policy every time. But your escape hatch log is a good indication of when you might consider updating the policy.
Building an escape hatch changes the risk. The worst case is not that the tool did something irreversible, but rather that the tool did something I fixed in one command.
So build the hatch. Make it one command, make it maintain your invariants, put it in the help text, and count how often it gets pulled.
The automation you trust isn’t the one that’s always right. It’s the one you know you can overrule.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
`updated_at` Is Not a Conflict-Resolution Strategy
In the last post we talked about the problems with a distributed system, and touched on the fact that timestamps are not as reliable as you think they are.
If you have two
updated_atfields and you compare them, how do you decide which side is the correct one?The
updated_atfield only tells you that a write happened. It doesn’t tell you the meaning, or if it was intentional. Conflict resolution is fundamentally a question about causality. Did side A intend for this change to happen? A wall clock timestamp can’t tell you the answer to that.Two independent clocks can drift, and will drift. Yes, it will get corrected by NTP occasionally. But you can’t always rely on their NTP service working. Timestamps are a fine signal that something occurred, and they’re a reasonable way for a human to sort a list and answer roughly when we think a change occurred. But if you use them as a foundation to decide what data to keep, you’re gonna end up destroying and losing data.
Things That Actually Work
The good news is the alternatives are not exotic, and you don’t need all of them.
Content hashes. Hash the meaningful content and compare hashes instead of times. This kills the metadata-edit problem outright: if the hash matches, nothing changed, no matter what the timestamp claims. It’s the highest-value change on this list and usually the easiest, because it’s a pure function of data you already have.
Version counters. A monotonic integer per record, incremented on every meaningful write. Immune to clock skew entirely, because it isn’t a clock. The cost is that somebody has to own the increment, which is straightforward with a single authority and gets harder without one.
Sync checkpoints. Record what was confirmed at the last successful sync, not just when it happened. Then the question becomes “has this changed since the last agreed state,” which is answerable, instead of “is this newer,” which is a guess.
Operation logs. Store what happened rather than only the result. Heavier, but it’s the only option that lets you reconstruct intent after the fact, and it turns “which one wins” into a question you can actually audit.
You can get most of the benefit from the first one. Hash the content, and let the timestamp go back to being a display field.
When Last-Write-Wins Is Fine
I’m not gonna lie, last write wins is often the correct engineering choice, and replacing it with something more complicated can be its own mistake. Sometimes it’s fine. If a write gets lost and the data is recoverable, that’s a trade you can live with.
If it’s a simple tool without a ton of users, adding a lot of complexity is not the way to go.
If the data is just a cache or a projection, then who cares? You can rebuild it from the authoritative source anyway.
What I’d Actually Do
Keep
updated_at. It’s useful. Sort by it, display it, log it.Just stop letting it decide things. Add a content hash and check that first, so a no-op edit stays a no-op. If a field can be written from two sides independently, give it a version counter or an explicit authority rule, and write the rule down somewhere the next person will find it.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Databases Software-development Distributed-systems Local-first Data-modeling
-
The Moment You Add Sync, You Have a Distributed System
How do you keep two sets of data in sync? Like, by definition, you now have a distributed system.
It could be something simple, syncing files or talking with a remote service somewhere. Maybe it’s not a lot of code. Initially, it might not feel like a distributed system, because there’s no cluster or consensus protocol. There’s no leader election system. You have multiple leaders that need to stay in sync.
How do you maintain state between two independent systems, when their only connection is an over-the-network connection that’s allowed to fail?
Sync can be a verb that you apply to the data on one side, but it’s also describing the negotiation that happens between two distributed systems.
Here is the set of questions you have to answer if you are trying to build a distributed system that maintains sync.
- What’s new here that isn’t there?
- What’s new there that isn’t here?
- What changed in both places since we last talked?
- What happens if we get halfway through and the connection dies?
- If I retry, do I create a duplicate?
All of these sound like problems from a paper you read about replicated state machines. Congratulations, they’re now your problem too.
Just because the request succeeded doesn’t mean that the two systems now agree.
The problems that you’re going to run into are either caused by or solved by a timestamp.
Recovering from an error state is crucial for building a durable system.
Idempotency Is the Cheapest Insurance You Can Buy
It is a guarantee, or pretty much a guarantee, that if your sync can be interrupted, it will be. Idempotency is how you ensure that the same request can be retried safely. If you run the same request twice, you either need to produce the same result or no result.
Every item on both sides of the system needs its own stable identity that each side agrees on. The create needs to always be create-if-absent, basically an upsert.
How do you decide which copy of the data has authority?
When you start needing to do resolution logic, this is where your subtle data loss can occur. Your point-in-time recovery window is likely 30 days or less, and chances are you aren’t going to go back and check the old copy that is about to expire.
Last write wins is the default because it’s easy, and it’s what everybody assumes. It works when there aren’t a whole lot of writes and when one side is clearly the primary. It breaks down when the data can’t be replayed safely.
Do your timestamps actually mean what you think they mean? Can you trust time? It’s complicated to get correct. And if the difference between two timestamps is very small, and the drift is larger than the difference, problems occur.
Things to look into for later: CRDTs, vector clocks, operational transforms.
Chances are these are not the right answer for a personal tool that you’re building on the weekends. It’s good to have discipline and understand the solutions we’ve come up with for resolving synchronization problems. At the end of the day, you’re just gonna want something that works.
You have a distributed system. It has one user and it runs on a laptop, but it has all the failure modes, and it doesn’t care that you didn’t mean to build one.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Software-development Architecture Distributed-systems Local-first Apis
-
Your Local File Should Not Have to Argue With Your Database
Sync bugs usually all start the same way. Two copies of something, both of them mostly right, and no written rule about which one wins.
The problems occur when you don’t notice The bug. When the file says one thing and the database says another. It’s not a problem until it is. And then you have to spend time figuring the why and when’s of the drift.
So let’s talk about authority. Not storage, not sync, not “where does the data live.” Authority. Which copy is allowed to be right when two copies disagree.
The Question Nobody Writes Down
Most systems that hold the same data in two places never actually decide this. The decision gets made accidentally, by whichever code path happened to run last, and then it gets re-made differently by the next feature.
The failure is duplication without a stated rule.
Here’s a concrete version. I run a content pipeline for this blog. Posts are Markdown files with YAML frontmatter sitting in a directory. There’s also a Turso database holding metadata about those same posts. Two copies of what looks like the same information.
Ask the naive question, “which one is the source of truth,” and you get a bad answer, because the honest answer is neither, and both, depending on the field.
Split Authority by Field, Not by Store
You might try to pick an authoritative source based on store. Files win, or the database wins. But the useful granularity is usually the field.
In my pipeline it breaks down like this:
- Post content and tags: the Markdown file wins. The frontmatter is authoritative. If the database has a different tag list, the database is wrong, and it gets rebuilt from the file.
- Scheduling: the database wins. What time a post goes out, what slot it holds, whether it’s been claimed. The file does not get a vote.
Those are different answers for the same post, and that’s fine, because each one is written down and each one has a reason.
The content lives in the file because content is the thing I edit by hand, in an editor, with Git history behind it. I want
git logto be the real record of what changed. Putting that in a database would mean my writing history lives somewhere that is harder to access.The schedule lives in the database because scheduling is a coordination problem. It needs uniqueness constraints, it needs to answer “what’s in the 10am slot on Tuesday,” and it needs to do that without me parsing 241 files. A database is genuinely better at that. It just isn’t better at holding prose.
A Database Can Be Useful Without Being Authoritative
I think there’s a reflex where adding a database feels like promoting the data into it. You put the posts in Postgres and now Postgres is where posts are.
It doesn’t have to work that way. A database can be a query layer over data that lives somewhere else, and that’s a completely respectable job. Indexes, joins, counts, “show me every post tagged local-first published before June.” All of that is worth having, and none of it requires the database to be the authority.
The test I use: if I deleted the database right now, what would I lose forever?
For me, it would be the scheduling state because that’s what I put in the database. The important thing is I wouldn’t lose a single word that I’ve written. Every post would still be in a directory. This choice is deliberate.
It’s easy for the database to become a Cache and not an authoritative source.
What Should Happen When They Disagree
If you have documented your authoritative source, then the disagreements stops becoming a crisis, and it just is a routine. Resolution event
You should be able to rebuild it. There should be nothing to decide. The decision is documented and how you resolve conflicts. Just depends on. Which authoritative source owns Which s segment of your data?
In my case, there’s actually a third authoritative source, and that’s the remote blog system that hands back an ID every time I schedule a new post.
So, this is totally fine if you pick the authority at the field level and Document that decision to prevent trip-ups in the future.
Your files and your database shouldn’t be arguing, all it requires is a bit of planning.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Databases Software-development Architecture Local-first Data-modeling
-
The Decision Log: A Lightweight Artifact for Agentic Coding
Coding agents are remarkably good at reopening decisions you already made.
Imagine a content pipeline where posts live as local Markdown files and a database holds the scheduling metadata. You open a fresh session. Which one does the agent think is authoritative?
It has to guess. And the database looks like the better answer, because databases usually are. So it proposes the obvious cleanup: make the database the source of truth and treat the files as an export format.
It’s wrong, for a reason the code never states. You can rebuild the database from the files. You cannot rebuild the files from the database. Drop the database and you re-index from markdown, losing some operational history on the way. Lose the markdown and the posts are gone.
Some questions are still better answered by the database, scheduling among them. But the authoritative copy is whichever one you could regenerate the other from, and that asymmetry is the entire argument. It appears nowhere in the schema, nowhere in the file layout, and nowhere in the diff.
So you explain it. The agent takes the point immediately, drops the idea, and gets on with the actual work. Good outcome.
Then the session ends, and the next one arrives with the same instincts and the same blank slate. Nothing’s wrong with its reasoning. It’s missing the one piece of context the repository doesn’t contain: that road has already been walked.
That’s what a decision log is for.
Issues and Skills Leave a Gap
Agentic projects tend to accumulate two useful artifacts.
Issues describe work. Add a field, fix the retry logic, move the cache, update the API client. They tell an agent what needs to change and, if the issue is any good, what done looks like.
Skills and project instructions describe process. Use this package manager. Run these tests. Never call this destructive command. They tell an agent how work should happen, repeatedly.
Both matter. Neither is a natural home for, “We considered Redis, rejected it because this service has to run without another dependency, and we’ll reconsider if the process moves to multiple instances.”
Artifact The question it answers Issue What needs to change? Skill or instruction How should work be done? Decision log Why this path instead of another one? The code records the result. Git records the diff. A closed issue might contain the discussion, if somebody thinks to go looking for it. The decision log keeps the conclusion and the rejected alternatives somewhere an agent can find them before it starts planning.
The Rejected Option Is the Important Part
I wrote recently about decision debt, the gap created when code gets produced faster than anyone records what it means or why it exists. A decision log is one small way to pay that debt as you go.
The useful part isn’t “We chose SQLite.” The repository already contains a SQLite database. The useful part is why SQLite won, which alternatives lost, and what would have to change before the decision should be reopened.
Without that negative history, an agent sees an absence and treats it as an oversight. No Redis? Add Redis. No abstraction around this HTTP client? Generate one. No Kubernetes deployment? Surely the project just hasn’t matured enough yet.
Sometimes the missing thing is missing on purpose.
Humans do this too, of course. We reopen old arguments when the people who remember them leave, or when the conclusion is buried in a meeting recording. Agents just compress the cycle. Every fresh session is a new developer joining the project with excellent technical instincts and absolutely no institutional memory.
Keep the Entry Small
Architecture Decision Records have been around since Michael Nygard described the pattern in 2011. They preserve the status, context, decision, and consequences of an important architectural choice. Lightweight templates like MADR also capture the options considered, the decision drivers, and why one option won.
That’s the right idea. I just don’t need a formal architecture record for every consequential choice in a personal project.
I’d start with some sort of log file, holding entries like this:
## 2026-07-26: Keep Markdown as the publishing source of truth **Context:** Posts exist as local files and as database records. **Decision:** Frontmatter controls publish state. The database owns scheduling metadata and is not authoritative for publishing. **Rejected:** Making the database authoritative, or newest-write-wins. **Why:** The database can be rebuilt from the files. The files cannot be rebuilt from the database. **Revisit when:** Editing moves to a multi-user hosted application. **Links:** the repository module, the publishing documentation.That’s the whole artifact.
An agent that reads that before it starts planning knows the database-as-source-of-truth idea isn’t a fresh insight. It also knows exactly what would have to change before it becomes one again.
I’ll be honest that I haven’t started doing this yet, but it sounds like a good idea right?
The entry doesn’t need a transcript of the debate. It needs enough context for a future person or agent to understand that the alternative was considered, why it lost, and which changed condition would make it worth discussing again.
What Belongs in the Log
If every choice becomes an entry, the log turns into another file nobody reads. I’d record a decision when at least one of these is true:
- Two or more reasonable approaches existed
- A future agent is likely to propose the rejected option again
- The choice establishes a source of truth, security boundary, schema, dependency, or workflow
- Reversing it later would be expensive or dangerous
- The reason isn’t obvious from the code
Don’t log naming arguments, routine implementation details, or every library function you picked. “Used a dictionary here” isn’t institutional knowledge. “Kept provider integrations on raw HTTP because the SDK doesn’t support the endpoint we need” might be.
Major decisions can still become full ADRs in
docs/decisions/or whatever. The lightweight log is for the big middle ground between an architectural record and a comment somebody vaguely remembers leaving on a pull request.
Make Agents Read It at the Right Time
Creating the file isn’t enough. The agent needs a retrieval rule. One sentence in the project instructions:
Before proposing changes to architecture, dependencies, data ownership, security boundaries, or core workflows, search `docs/decisions.md` for related decisions and revisit conditions.Then the other half:
After a consequential decision is approved, propose a short decision-log entry. Do not record a new project policy without human confirmation.The instruction defines the recurring behavior. The log supplies the project-specific facts. That keeps settled choices out of a giant instruction file while still putting them in the agent’s path when they matter.
When a decision changes, don’t quietly rewrite history. Add a new entry that supersedes the old one and say which revisit condition actually showed up. Version control preserves the edit, but the document should make the change legible without requiring repository archaeology.
Not Another Memory System
A chat transcript contains every false start, tool result, and half-formed idea. It’s too noisy to act as a project constitution. Agent memory can help retrieve past context, but it might be private to one tool, unavailable to a collaborator, or hard to review in a pull request.
A decision log needs to be deliberately boring. Plain text. Searchable. Reviewable. Stored next to the code, or accessible by it. Any human or agent can read the same entry and argue with it in the open.
None of this guarantees an agent will make the right call. It removes one wasteful failure mode: spending another session rediscovering a settled tradeoff and confidently proposing the option the project already rejected.
Issues tell the agent where to go. Skills tell it how to move. The decision log marks the roads we already closed, why we closed them, and when they might be worth opening again.
That feels like context worth keeping.
Sources
- Documenting Architecture Decisions — Michael Nygard’s original 2011 ADR proposal.
- MADR — a lightweight decision-record format covering options, rationale, consequences, and revisit conditions.
- The GDS Way: Documenting architecture decisions — keeping decision rationale in the repository while using issues to track implementation.
- How Claude Code works — fresh session context, compaction, project instructions, and persistent memory.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
The Human Job Is Choosing What Not to Build
Coding agents have made one word much harder to say.
No.
You describe a feature, and the agent can already see the model, the migration, the command, the tests, and the docs it needs to touch. The whole thing sounds like an afternoon instead of a week.
So why not build it?
That question used to contain its own answer. We didn’t have the time or the people, and the feature wasn’t worth interrupting everything else for two weeks. Now the implementation might take twenty minutes. The old constraint is gone, but the need to choose is not. If anything, choosing matters more, because we can say yes faster than we can understand what all those yeses are doing to the product.
The agent’s job is to make the thing we asked for. The human job is deciding whether the thing should exist.
Yes Produces Better Receipts
Building something leaves evidence. There’s a diff. Tests pass. A new command shows up in the help output. You can take a screenshot, close an issue, and point at the feature. Work happened, and the artifacts prove it.
Choosing not to build produces almost nothing. Maybe you leave the idea in a notebook. There’s no demo for the dependency you avoided or the interface you never had to support.
That makes restraint feel less like engineering.
It can look like indecision, or lack of ambition, or an empty afternoon of planning.
A good “no” can preserve more value than a clean implementation.
You protected the shape of the product. You kept it understandable. You left room for the features and the users that actually matter.
Agents Make Local Ideas Look Great
Coding agents are strongest when the task is concrete. Add this flag. Support this file format. Create an adapter for this provider. Cache this response. Put a dashboard on top of these logs.
Given one of those, the agent inspects the local code and produces a reasonable path forward. It sees where the new feature fits.
What it doesn’t automatically carry is the opportunity cost.
You can put that context in the prompt, but somebody still has to decide how much product is enough.
A human has to protect the product.
Cheap Is Not the Same as Free
I recently argued that code is cheap now, but decisions are not. The mistake is pricing a feature only by how long the first implementation takes.
A twenty-minute feature can create a permanent interface, another concept every future agent has to understand, or a second way to do a task when the first way was already fine.
The implementation estimate answers: how quickly can we make this work?
The product decision asks: is this worth changing what the system is?
Four Ways to Say No
Not building something doesn’t always mean rejecting it forever. Here are four versions of no.
No, this is not the product
Some ideas are useful and still don’t belong. A small command-line tool doesn’t automatically need a web dashboard. A personal publishing pipeline doesn’t need multi-tenant permissions because it could theoretically serve a team. A library doesn’t need a plugin system before a second plugin exists.
These features may solve real problems. But they solve somebody else’s version of the product.
This is the cleanest no.
Write down the boundary and move on.
Not yet, we don’t have the evidence
Sometimes the problem is plausible but unproven. The database might need caching. The API might need another abstraction. Users might want a second export format. “Might” is doing all the work.
Wait for the system to produce evidence. Measure the slow query. See a second provider show up. Hear the same request from someone who actually has the problem. The agent will still be there when the need is real.
Deferral is only useful when it has a condition: “Revisit imports when we have enough data to support the decision.”
All the “maybe laters” are not backlogs; they are fossils that deserve to be buried.
Yes, but smaller
Plenty of ideas contain one valuable piece surrounded by a feature-shaped cloud.
Build something that you think is useful. Not everything needs a dashboard.
You don’t need a generic provider framework until you have a reason for the generic provider to exist.
You don’t need a rules engine if you’ve only got three rules.
Ask for the smallest change that provides the most value.
Narrow the solution before it becomes a broad one.
No longer
The hardest no is the one aimed at code that already exists. How do you determine whether it’s actually being used or not? This is how we get features that outlive the reason they were built. You added an experiment that became a supported path, and now everybody’s afraid to remove it.
Prune the branches of the product tree. Before you decide what to build next, make sure you’re not letting the system grow forever.
You should be asking yourself: what choices are you deciding against? Sometimes it’s important to know what already exists before deciding what should exist.
My Filter Before I Say Yes
Product committees suck, especially for small changes. Before I accept an idea as a feature, I ask myself the following questions. Or I should ask myself. Or I hope I ask myself. Whatever version of that makes sense for the day.
- What problem gets easier?
- Why now?
- What new promise does this create?
- What gets harder after this exists?
- Can a smaller change prove the value?
- What would make us remove it?
These help you tell the difference between what’s easy to generate and what’s worth owning. Sometimes they help you solve for a hypothetical problem. It’s a good thing to try to figure out whether the tests will pass before you build them.
Taste Is the Remaining Bottleneck
As implementation gets cheaper, the scarce skill becomes taste.
Not taste as in fonts and rounded corners. Taste is recognizing when a product has enough concepts. It’s choosing the boring interface people can understand. It’s seeing that a flexible abstraction makes the current problem worse. It’s knowing which rough edge gives the tool character and which one just wastes time.
Then decide.
The future of software isn’t a world where we finally build every idea in the backlog.
That sounds exhausting.
The future of software is a world where we get to decide, and be honest about which ideas were actually good to begin with.
Don’t forget you’re allowed to say no.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
When I Use a Subagent and When I Don't
Give a good harness access to subagents and everything starts looking like a team project.
You’ve got one agent working with the database layer. Another can research the API. Another can write the tests. Another can check the work. Another can manage moving the data. As work starts happening in parallel, colored dots appear, and the whole thing starts looking like an org chart.
That sounds like fun to me, but it can also be a mess.
Having more agents doesn’t automatically produce better results.
Sometimes they duplicate work. Sometimes they edit files at the same time, producing unexpected changes or behavior.
I mean, I still use subagents constantly. They are definitely the default.
Sometimes we need, like, a subagent arena. Two agents enter. One survives.
The Subagent Context Boundary
I started using subagents as a way to protect the main context window. I wrote about that back in March: the delegated agent can read files, inspect logs, and grind through intermediate reasoning in its own context.
It’s still one of the best reasons to delegate. When finding the right answer means searching through 20 files, reading five of them, tracing a configuration value, and checking the tests, that sounds like a subagent task to me.
The search is noisy, and the output needs to be compact.
Using subagents keeps the main context window free for the larger task.
I Delegate Bounded, Independent Work
The tasks I delegate have one thing in common: I can define the output before the work begins.
Here are some areas where a subagent makes sense:
- Repository research.
- A separate implementation surface.
- Specialist review.
- Independent verification.
- Real parallel work.
Don’t Delegate an Unclear Problem
Delegation is not a substitute for deciding what the work is.
If a request is vague, spawning more agents isn’t going to help with the vagueness. It’s just more output with no clear direction. The parent still needs to choose the requirement and figure out what we’re building.
Before I delegate, I want to handle the following in the parent context:
- what question the subagent is answering,
- which files or systems it owns,
- whether it may edit anything,
- what constraints it must preserve,
- what evidence it should return,
- when it should stop and ask instead of guessing.
If we can’t figure out answers to those, the next step should be planning, not delegation.
Don’t Split Tightly Coupled Work
Avoid having two agents edit code in neighboring areas. The code may share an interface, a fixture, or a schema, and if you start changing things in multiple places without coordination, you’re going to have problems.
Each agent has its own context window. When it reads a file, block of code, or dependency into that window, the context is only current at that moment. If another agent changes the same thing, how does the first agent know its context needs to be updated?
It’s a complicated problem, for sure.
So your best bet is to avoid parallel edits where agents are working in the same or similar areas of the code. The agent work areas need to be distinct.
If humans can have coordination problems, agents can too.
I Don’t Delegate Five Minutes of Work
Delegation has a cost. The parent needs to describe the task and load enough context for the subagent to do the work and summarize it. Then the parent needs to verify the result. All of that burns a bunch of tokens. Obviously, for one-line changes or small amounts of text, this handoff should never happen in the first place. To decide whether to pass the work to a subagent, ask: will using a subagent substantially improve the output?
Sometimes the answer is just to do it in the parent context window, even if that means you have to compact sooner.
A good subagent task looks a lot like a good software interface. It has a narrow purpose, explicit inputs, clear permissions, and predictable output.
Compare these two assignments:
Look into the tests and fix anything missing.Review the unchanged-record tests for Book. Identify provider-owned fields that are not covered. Add focused tests only in tests/test_books_client.py. Do not change production code. Run the focused test file and report the result.The first transfers uncertainty. The second transfers work.
The difference does matter.
The Parent Still Owns the Result
Subagents report completion. They don’t make completion true.
The parent still has to inspect the changes, reconcile conflicting findings, run the combined quality gate, and decide whether the original requirement was satisfied. If three agents each report that their piece passes, you have three pieces of evidence. You don’t yet know whether the assembled system works.
Delegation changes who gathers the evidence. It doesn’t remove the need to judge it.
The goal isn’t keeping every agent busy. The goal is finishing the work without turning yourself into middle management for robots.
Oh God, I think that’s my job title.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Not Every Agent Task Needs an Issue
I’ve written before that your AI agent needs a task manager, and I stand by it. Chat history is not project state. Context windows compact. Sessions end. If the work matters tomorrow, it needs to live somewhere tomorrow’s agent can find it.
The part I didn’t mention: not every task matters tomorrow.
Some work should disappear with the session. Turning all of it into durable project state doesn’t make your agent more organized. It gives the next session a bigger pile of bookkeeping to misunderstand.
Tasks Have Different Lifetimes
When we say “task,” we’re lumping together several different things.
“Add filtering to the search API” is a project commitment. It might take several sessions, affect other work, and need a record of why the behavior changed.
“Inspect the existing query code” is not a project commitment. It’s one step the agent needs to finish the larger task.
“Run the focused tests” is even shorter-lived. Once they pass and the result has informed the work, that checklist item has done its whole job.
These all deserve attention. They don’t all deserve permanent storage. I think about them in two buckets:
- Session tasks help the current agent organize execution. They live in a plan or checklist, then disappear when the work is complete.
- Durable issues preserve commitments, decisions, dependencies, and unfinished work across sessions.
The distinction isn’t importance. A database backup check can be a critical session task. The distinction is whether the information needs to outlive the work happening right now.
If it doesn’t, let it die.
Ephemeral Does Not Mean Sloppy
There’s a temptation to treat ephemeral tasks as unstructured work. Just tell the agent,
plz fixand see what happens.A session still benefits from a clear plan. The agent should inspect before editing, break a change into steps, mark progress, run focused tests, run the full quality gate, and verify the result. A visible checklist makes long work easier to supervise, and it reduces the chance the agent quietly skips the boring last step.
The checklist just doesn’t need to become part of the project’s permanent record. Picture something like this:
- inspect the repository method - find every caller - update the shared comparison helper - add focused tests - run the full suiteThose are excellent session tasks. They tell the agent how to move through one change. After the implementation lands, keeping all five around adds nothing. The commit and tests preserve the result. The issue, if one exists, preserves the reason.
An Issue Should Earn Its Permanence
A durable issue is more expensive than it looks. Someone has to write it clearly, connect dependencies, update its state, close it, and eventually decide whether it’s stale. An agent also has to read it. Every open issue becomes part of the project’s apparent reality.
That cost is worth paying when the issue preserves something important. I create one when at least one of these is true:
- The work will survive the current session. If we’re likely to stop before it’s done, the next session needs a reliable handoff.
- Other work depends on it. A dependency belongs in a system that can represent blocked and ready work, not in a paragraph buried in chat history.
- It represents a real commitment. A user-reported bug, an accepted feature, or a promised follow-up shouldn’t vanish because a terminal closed.
- The decision needs a record. If future maintainers will ask why the system behaves this way, the issue preserves context a diff can’t.
- The work crosses boundaries. Changes spanning repos, services, migrations, or people need coordination beyond one agent’s checklist.
- We found valid work but aren’t doing it now. That’s exactly what a backlog is for.
If none of those apply, a session task is probably enough.
Promote Work When It Changes Shape
You don’t have to pick the perfect tracking level before the agent starts.
Begin with a session plan. During inspection, the agent may discover that the “small fix” requires a migration, depends on another repository, or exposes a separate bug. If the work changes shape. Promote it.
Agents are very good at expanding scope. They inspect one path, notice three adjacent problems, and offer to fix everything while the files are open. Sometimes that’s useful…
Your Backlog Is an Agent Prompt
Humans are pretty good at looking at an old issue and thinking, “yeah, we don’t care about that anymore.”
Agents are more literal. If the tracker says the issue is open and ready, the agent has a strong reason to treat it as authorized work. A stale backlog can send a perfectly capable agent down an obsolete implementation plan just as it easily as it can with a valid one.
No issue hygiene needs to be a part of your process. An open issue tells the agent this work is still wanted, this description is still accurate, these constraints still apply, and finishing it would improve the project.
If any of that is false, the issue isn’t harmless clutter. It’s a bad prompt waiting to be executed.
Use the Smallest State That Survives Long Enough
After six months with git-native issue tracking, my workflow has gotten a lot more varied.
I use a session plan when the current agent only needs help organizing the work in front of it. I use an issue tracker when the project needs to remember something after that agent is gone. For local projects i’m very rarely reaching for Beads. For team work it’s always GitHub or GitLab.
Too little tracking and the project forgets real commitments. Too much and it accumulates stale instructions, duplicate tasks, and chores whose only purpose is maintaining the tracker.
Start small. Let the agent make a checklist. Promote the work when it makes sense. Close it when the feature is satisfied. Delete old tasks like you are pulling weeds to make space for the flowers to bloom.
Your agent needs a task manager. It does not need a permanent record of every box it checked along the way.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Tests Are Evidence, Not a Definition of Done
I’ve watched thousands of tests run over the years.
When they pass it has felt good. A huge screen of green checks in the terminal is incredibly rewarding as a software developer.
But the work is never finished.
The tests are always valuable. They are evidence, but they were never the definition of done.
Tests Prove the Claims We Give Them
I’ve written before that testing is how we show our work, and I still believe it. If software is meant to run more than once, test it. No excuses, just testing.
The mistake is treating a passing suite as proof of more than it covers.
A test makes one specific claim about a system:
given this setup when this action happens then I expect this resultRun enough of those claims and you build confidence. You know the parser handles a missing field. You know the repository preserves an identifier. You know the command returns a failure code when authentication breaks.
What you do not know is whether you wrote the right claims.
If the requirement was misunderstood, the implementation and its tests can agree perfectly. If your fixture contains a field the real API never sends, every parser test can pass while production fails. If your mock accepts a request the provider rejects, you’ve proven compatibility with the mock.
That’s useful, but let’s not get carried away.
The Agent Can Test Its Own Misunderstanding
Coding agents make this distinction more important, because they generate code and tests together.
You ask for a feature. The agent interprets the request, implements that interpretation, then writes tests asserting the implementation behaves exactly as it wrote it. Everything passes.
Sometimes that’s a clean, efficient workflow. Sometimes it’s one misunderstanding with excellent test coverage.
Picture asking an agent to add a
published_atfield from an external service. It sees another timestamp calledcreated_at, assumes they mean roughly the same thing, and uses one as a fallback for the other. Then it writes tests proving the fallback works.The suite is green. The code is wrong.
The issue isn’t that an agent wrote the tests. Humans have spent decades writing tests around their own bad assumptions. The difference is speed. An agent can turn a vague requirement into a thoroughly tested wrong answer before you notice the semantic choice it made.
More tests don’t rescue a bad premise. They preserve it.
Mocks Prove You Understand the Mock
Mocks are one of the best tools we have for keeping tests fast and deterministic. I use them a lot. I don’t want every local run hitting a real provider, burning rate limits, changing remote data, or failing because somebody’s service is having a bad Tuesday.
Still, a mocked integration is a model of reality, not reality.
Your fixture may be stale. The provider may omit fields you marked required. Auth may use a header you never modeled. Pagination may stop differently than the docs imply. Error responses may arrive as HTML because a proxy had opinions.
Unit tests prove your code handles the world you described. A live, read-only check tells you whether the world still resembles that description.
That doesn’t mean turning the whole suite into live integration tests. It means picking a small amount of extra evidence proportional to the risk:
- Fetch one real response and inspect the fields you depend on.
- Exercise authentication without modifying remote state.
- Run a dry run through the production code path.
- Validate a migration against a realistic database copy.
- Confirm the deployed service reports the expected version.
Tests stay fast. Reality gets a vote.
Passing Is Not the Same as Shipped
There’s another gap between tested and done that has nothing to do with correctness.
Code can pass every check and still exist only in a working tree. A migration can be valid but unapplied. A config change can be committed but missing from the deployment environment. A feature can reach production without the logs you’d need to understand its first failure.
This sounds operational because it is. Software isn’t finished when the implementation works in the place where it was written. It’s finished when the intended system has the change, and you can tell whether that change is healthy.
For a small personal script, that might mean committing it and running it once with real input. For a web service, deployment, a health check, logs, metrics, and a rollback path. For a database change, verifying both the schema and the application behavior after migration.
The evidence changes with the risk. The principle doesn’t.
pytestcannot tell you whether you forgot to push the commit.
Done Is a Decision Built From Evidence
A definition of done should answer a broader question than “did the tests pass?” It should answer: what evidence would make us comfortable owning this change?
For most work, I look in a few categories:
- Intent: The behavior matches the actual requirement, not the first interpretation of it.
- Implementation: Automated tests cover the important paths and failure cases.
- Quality: Static analysis, formatting, types, and review caught what they’re designed to catch.
- Integration: Real boundaries behave the way our fixtures and mocks claim.
- Operations: The change is delivered, observable, and recoverable in proportion to its risk.
- Durability: Code, migration, docs, and task state are saved where the next person or agent can find them.
Not every change needs all of them. Fixing a typo doesn’t require a rollback drill. Changing how customer data is stored deserves more than one unit test and a thumbs-up from the agent that wrote it.
Good engineering is choosing the right amount of evidence, not applying the largest checklist to everything.
Green means the evidence looks good. Done means you have enough of it.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
DevOps AI Testing Software development Engineering practices