When Confidence Feels Like Understanding

Reading an agent's recommendation, realising I haven't understood it, and deciding whether this is a moment to delegate or to learn.

This is part of a response I got from Claude while working on a command-line tool. It’s the kind of recommendation I can find myself reading hundreds of times a day.

Load scenarios with bun, not Node.

Why:
- The build loads .scenarios.ts via Node's built-in type
  stripping: works on 24/26, refuses node_modules files,
  untested on our minimum (22.18). Any stderr warning
  would break the catalogue tests.
- Bun has none of those limits and fits your direction.

What changes:
- The prepacks (src/package.json and the example published
  package): bun build-dist.ts && bun dist/cli.js catalog build.
- Docs: record bun as loader in ADR 2026-031's Node-dependency
  section, writing-a-pack.md and flight-state.md; remove
  node_modules and 22.18 limits from the follow-up list.

The no-bun-on-PATH end-to-end test covers installing and
running bounded, not packing it, so it's unaffected.

My first reaction is that this sounds sensible, and it’s so confident that I feel reassured before I’ve really thought it through. It has reasons, it has considered the direction of the project, it knows which documents need updating, and it has even explained why a particular test is unaffected. I think I understand it enough, and I can say yes and carry on.

Then I try to explain to myself what I’ve just agreed with.

What’s built-in type stripping? I have a rough idea, but why does it refuse files under node_modules? Is that about older packages, or something else? I can follow that it’s recommending Bun over Node, but I couldn’t yet explain the limitation that makes this a good decision.

Then I get to “the prepacks”. What are ours doing now? Did we add that catalogue build step earlier, and was that in another exchange like this one, where I read the explanation and thought I understood enough?

There’s an architecture decision record to change. I don’t have its contents in my head. Is this implementing the decision recorded there, or revising it? Then it casually names writing-a-pack.md and flight-state.md. What’s in those again, and why does this change affect them? And which end-to-end test is that last sentence referring to?

I have read the whole response, and its confidence has carried me quite a long way past my own understanding.

A little at a time

I wrote in Understanding Is the New Luxury Good about how understanding used to accumulate while we slowly built things. Working with an agent, I keep encountering the smaller, everyday version of that problem: do I stop here and work out what this means, or let it go ahead?

Mostly I stop, and it becomes a conversation. Explain type stripping. Show me where that happens. What does this script do, and who runs it? The agent can help me get there, but I still have to think. Reading another explanation isn’t necessarily enough.

Other times it’s late, the recommendation sounds reasonable, and its confident tone convinces me that I understand what I’m approving, so I wave it through. Nothing necessarily breaks, and the change might be entirely correct. But the next recommendation refers to something introduced in this one, and now there’s another piece of context I don’t quite have.

That’s the part I find unsettling. I start with a project I understand, then gradually find myself being asked for guidance about mechanisms, scripts and decisions I no longer recognise. And if I’m not careful, I find myself increasingly accepting the agent’s recommendation because understanding enough to question it would mean going back through several earlier decisions.

I wonder how this plays out in a team, too. When I come across an unfamiliar architectural choice in a shared codebase, I tend to assume another developer has thought it through, even if I haven’t caught up with their reasoning yet. But they might have approved it in exactly the way I’ve just described. A commit or a decision record tells me what was accepted; it doesn’t necessarily tell me whether someone understood it or whether it just sounded convincing enough to wave through. I could be building on an assumption that nobody on the team has really examined, while each of us imagines somebody else has.

The language can make this harder. I often find Claude’s explanations dense with references to things it assumes I know. I’m not sure how much is the writing and how much is the missing context, but “the prepacks” is a very efficient phrase if we both know what it means.

What I actually need to know

I don’t think the answer, for me, is to understand every detail before anything moves. Some of the acceleration comes from being able to leave a piece of work with the agent.

In this example, I can see a possible boundary around how the tool builds its catalogue and packages what it needs. I care about what a pack author has to install, what commands they run, and whether the resulting tool works in the environments I intend to support. I may not need to retain every detail of how TypeScript gets loaded inside that process.

But I need enough understanding to know whether the change stays inside that boundary. If Bun is bundled inside the binary and the same commands still work, I’m comfortable leaving much of that to the agent. If pack authors now have to install Bun separately before they can build a pack, that’s a change to their experience I’d want to think through. Passing tests helps when they cover the behaviour I care about; the agent assuring me that one test is unaffected doesn’t settle all of that.

When I can identify the outside of the box and see how I would check or reverse the change, I’m more comfortable leaving the interior to the agent. When the decision changes the core structure I’m trying to build, I usually want to stay much closer. But on more than one occasion, the agent’s confident tone has persuaded me to wave through a change without realising it was moving one of the boundaries I cared about.

Give me something concrete!

What I’ve been finding useful is asking the agent for something concrete I can inspect and question while I’m still working out what I want.

When I’m working on system-level design, starting the implementation too quickly can make the boundaries harder for me to see. So I’ll often work with the agent on just the public interface, sometimes in a scratch.ts file, with nothing behind it and nothing wired into the application. Once I can look at the names, inputs and outputs, I can challenge them, change them and get the shape exactly as I want it. Only then do I ask the agent to implement it, or reshape the existing code to match. That gives me a boundary I’ve actually thought through, and something concrete to check the implementation against.

I find a similar process helps when I’m learning a tool. I’m currently streaming IoT data into the cloud, with infrastructure managed in Pulumi, and exploring database schema management led me to pgschema. I could follow the explanation, but I couldn’t quite picture using it, so I asked the agent to set up a small IoT table in an empty directory.

Looking through that example gave me a more specific question: what if every existing tag ID needed an ID/ prefix? The agent added a manual data migration step and ran it, and I could inspect what changed and explore how to undo it. We had something to examine together, and each answer helped me work out what to ask next.

In one case I keep the interface and build behind it; in the other I might throw away all the code. Both help me get from a plausible explanation to a picture I can reason about. I’ll usually capture the decisions and compromises in a decision record afterwards, while I still remember why we chose them.

These feel like two different ways of going faster: getting more work done with the understanding I already have, and acquiring understanding that would otherwise take me much longer. I move between them, sometimes within the same conversation.

Looking back at that terminal response, the uncomfortable part is how easily I can confuse the two. I feel as though I’ve learned something because I’ve read a detailed explanation, when really I’ve decided to trust it. I’d like to get better at noticing that moment, while I still remember what I don’t understand.

I’ve spent twenty years trying to get better at the craft of software engineering. I’m starting to think that agentic engineering is a distinct but related craft, and that much of the skill lies here: deciding what I need to understand and what I can leave to the agent, and finding better ways to build the understanding faster.