DEV Community: Isamu Arimoto

ever-better: 13 commands that make a codebase only able to get better

Isamu Arimoto — Sat, 15 Aug 2026 09:43:57 +0000

Adding a strict linter to an existing repository produces four thousand errors and gets reverted. The usual workaround — set everything to warn — enforces nothing, and the count grows quietly.

ever-better is the way around that. It records every violation that exists today as a ceiling: old code is grandfathered, new code is held to the whole rule set, and the ceiling can fall but never rise.

Below is every command, what it does, and the problem it exists for.

npx ever-better <command>

MIT, zero runtime dependencies, Node 20.11+.

`diagnose` — what is missing, and what each gap costs

ever-better diagnose            # read-only
ever-better diagnose --write    # also writes QUALITY.md

What it does. Surveys the repository — package manager, language, framework, runtime, ESLint setup, formatter, test runner, dead-code and duplication scans, agent instructions, CI, file sizes — and lists the gaps with the phase each belongs to.

Why. "Add linting" is not a task; it is six of them in an order that matters. Formatting has to land before linting or the first cleanup PR is a diff nobody can read. Type-aware rules cannot run without TypeScript. This prints that order instead of leaving you to discover it.

`bootstrap` — install the tooling, generate the configs

ever-better bootstrap
ever-better bootstrap --dry-run

What it does. Adds the dependencies, writes eslint.config.mjs, Prettier config, .gitattributes, knip.json, the package scripts CI needs, workflows for three platforms, dependabot.yml, and a secret-scan workflow. Prices each TypeScript strictness flag by enabling it in a temporary config and counting the errors — turning on the free ones, reporting what the rest would cost.

Why. Every rule it writes is an error, not a warning. That is only survivable because of the next command.

`freeze` — pin today's violations as the ceiling

ever-better freeze

What it does. Runs eslint --suppress-all, which records how many violations each rule has in each file, then stores the totals in .ever-better/state.json.

Baseline pinned: 4,942 violations across 72 rules are now grandfathered.

Why. From this commit on, the 4,942 are silent and violation 4,943 fails the build. You do not have to fix anything today to start enforcing everything tomorrow.

The ratchet itself is ESLint's own bulk-suppressions feature. ever-better is the part around it: knowing which rules to add, keeping the ledger, and failing CI when a number goes up.

It refuses to run twice. A second freeze would grandfather everything added since — which is the one thing the baseline exists to prevent.

`check` — the gate

ever-better check

What it does. Compares current counts against the ceiling and exits non-zero if anything rose.

8 unsuppressed error(s) — these are new since the baseline:
  2  id-length
  1  prettier/prettier

Why. A baseline is only a ratchet if something rejects a regression. Without CI it is a note.

Do not pipe it. ever-better check | tail exits with tail's status and reports a failing gate as success.

`prune` — lower the ceiling after a fix

ever-better prune

What it does. Removes suppressions for violations that no longer exist, so the recorded ceiling matches reality.

Why. Without it, fixing 100 violations changes nothing: the ceiling still permits them, and they can come back. This is what makes the number monotonic.

`next` — what to drain first

ever-better next
ever-better next --fan-in

What it does. Ranks the backlog by which edit enforces the most, not by which rule is biggest.

take these first — one or two edits, and the rule is enforced in that file for good:
    1  src/browser.js  @typescript-eslint/no-require-imports
    1  src/common.js   no-param-reassign

Why. The ratchet is per file per rule. A file with no suppression left for a rule fails on its next violation, whatever that rule's total is elsewhere — so two violations in one file buy more enforcement than twenty spread across twenty files.

--fan-in adds how many files import each one, because a fix in a widely imported module lands errors in files the diff never opened.

`report` — what the debt actually looks like

ever-better report
ever-better report --json

What it does. Prints the backlog as a rule × area table, and appends it to $GITHUB_STEP_SUMMARY when that is set.

Why. next answers "which edit enforces the most". This answers "what shape is this repository's debt". And because the generated workflow runs it after check with if: always(), the run where the gate just failed is the run where the backlog is visible — no one has to edit a workflow to get a report.

`secrets` — scan the history for committed credentials

ever-better secrets

What it does. Runs gitleaks over both the history and the working tree, failing on any finding.

Why both. Either alone passes a repository that is holding a secret. A history scan misses the key you pasted an hour ago and have not committed. A working-tree scan misses the key that was committed and then deleted — which is still in every clone.

This is the one check with no baseline. A leaked key is not debt you ratchet down.

`migrate` — JavaScript to TypeScript

ever-better migrate            # show the plan
ever-better migrate --all      # rename everything in one pass
ever-better migrate --file src/foo.js

What it does. Renames with git mv so history follows, and lets the lint fallout land in the ratchet instead of blocking the migration.

Why. Types are the cheapest rule set there is, and the tier that finds the most real bugs cannot run without them. On a 13-year-old JavaScript project, renaming 49 files and changing no logic produced 2,641 type errors — every one of them a question nobody had answered.

`emit-diff` — prove a refactor changed nothing

ever-better emit-diff --against main

What it does. Compiles the working tree and a git ref, then compares the emitted JavaScript.

Why. Types erase at compile time, so a change that only moves types must produce byte-identical output. That is a proof, in seconds. No amount of test coverage states it as strongly, because tests only cover the paths someone thought of.

`catalog` — the helpers that already exist

ever-better catalog

What it does. Writes docs/shared-helpers.md: every exported function, grouped by directory, with the first sentence of its doc comment. Point your CLAUDE.md at it.

Why. A linter sees inside one file. Duplication detection only notices copies once they are textually similar, and two independent implementations of the same idea rarely are. Nothing else reports the same function written a sixth time under a sixth name.

`status` — where you are

ever-better status

What it does. Prints the phase, the frozen date, the current backlog, which rules improved or regressed, and the smallest remaining backlogs.

STALE      100 commits since the diagnosis; re-run diagnose before trusting it
phase      drain
backlog    3532

Why. That STALE line matters more than it looks. A diagnosis from a hundred commits ago is a description of a repository that no longer exists.

`log` — why, not how many

ever-better log --kind drained  --rule max-depth "6 violations, 1 real bug"
ever-better log --kind deferred --rule max-lines "router.ts is 1400 lines; its own project"
ever-better log --kind issue    --rule no-floating-promises "opened #42 — product decision"

What it does. Records what happened against the current commit — the only command that writes the Work log in QUALITY.md. Everything else records counts.

Why. deferred is the one that earns its keep. It renders as a Carried over checklist stamped with the commit it was seen at, because "router.ts needs splitting" is useless four hundred commits later unless a reader can tell when it was true.

The whole loop, in five commands

The other eight are for when you need them. This is the shape:

npx ever-better diagnose     # what is missing
npx ever-better bootstrap    # install it
npx ever-better freeze       # pin today's count
npx ever-better check        # gate CI on it
npx ever-better prune        # lower the ceiling as you fix

Or hand the repository to an agent

The commands are the deterministic half — count, record, gate, refuse. The judgement half is eight Claude Code skills that ship with it: which violation is a real bug, when to stop and ask, what deserves an issue rather than a fix.

/plugin marketplace add isamu/ever-better
/plugin install ever-better

Then say clean this repo up. It formats, installs, freezes, and works the backlog down one rule per pull request — fixing violations, extracting the pure functions that make the fixes testable, writing the tests, and lowering the ceiling as it goes.

It is not unattended. Anything it can decide from the code, it decides. Anything it cannot — ambiguous behaviour, a public API change, a refactor that is its own project — becomes an issue with the options written out, and it moves on.

Try it on something you did not write

That is the honest test. Pick a repository you have never read:

git clone --depth 1 https://github.com/debug-js/debug.git
cd debug
npx ever-better diagnose
npx ever-better bootstrap
npx prettier --write .
npx ever-better freeze

Then add a file with a violation and run npx ever-better check. The 72 existing violations stay silent; the new ones fail.

On this particular repository you will also see five (parse error) entries — /* eslint-env */
comments and stale eslint-disable directives that flat config rejects. Those are real, they have
no rule id, and --suppress-all cannot record them, so freeze names the file and line for each.
It is a fair first impression of what the tool does: it tells you where, and it does not pretend the
number is smaller than it is.

Results welcome — docs/RESULTS.md collects what people froze and how much of it turned out to be real defects. It has two rows and both are mine, which is enough to notice a pattern and nowhere near enough to claim one. A run that found zero real bugs is the most useful row that table could get.

→ github.com/isamu/ever-better (MIT)

Handing an AI a big spec and letting it build the whole thing is like buying a lottery ticket

Isamu Arimoto — Fri, 07 Aug 2026 07:27:28 +0000

Ever since I wrote I stopped reviewing my own code, I keep getting the same question.

I ended up with a huge pile of code and I can't review it. What should I do?

The comments say the same thing in different words. The volume the AI writes went up. The reading side did not keep up. So what now?

Here is the blunt answer first.

Don't get into that state.

Taking something that already exists and rescuing it with review alone is, I think, very hard. You can split it, scope it down, throw parts away — but none of those is a substitute for actually reading it. And "just have the AI review it" probably isn't the answer either.

And this is not only a team problem. It happens exactly the same way when you work alone. The cause isn't headcount. It's writing a big spec up front and having the whole thing built in one go.

That is like buying a single lottery ticket where you don't find out whether you won until the very end. This post is about why, with arithmetic and with measurements.

The second half spills over into a related question: how many people should be on a product.

Note: the numbers here are measured from my own repository. But treat commit and PR counts as observational data about how I work, not as evidence of productivity.

Why you end up with "too big to review"

Most of the time, I think it's because the whole spec was decided first and built in one shot.

You write the spec. You hand it to the AI. A large amount of code comes out. And now, to judge whether any of it is right, you have to read all of it.

But there's a prior question.

You can't write a spec for something when you don't know if it's possible or if you even want it

The starting point for MulmoTerminal, which I build, was an experiment: can a terminal run inside a browser? It worked, so I widened it into a grid. After that I just used it and added what I wanted. That's all.

There was no room for a spec at that moment.

I didn't know if it was possible — nine real terminals side by side in a browser tab, usable in practice?
I didn't know if I wanted it — would putting them side by side actually be nice? I couldn't tell.

With those two unknown, what exactly is there to write? Anything you write is a wish, not a spec.

There are, clearly, cases where a spec works well. Building an Amazon clone. Building an internal system where the UI doesn't matter much. The reason a spec is writable there is that the thing already exists in the world.

A spec is a compression of knowledge that already exists. It is not a way to discover what doesn't exist yet.

You cannot compress something that isn't there to compress.

It's like buying a single lottery ticket

Deciding everything before you know anything is, to me, betting the outcome on one ticket.

And it's worse than a lottery in one specific way.

A lottery tells you whether you won on the spot.
A big spec doesn't tell you until you've finished building and started using it.

Let's compute the odds that "all of it works"

Hand over a big spec and let it build. Some of it comes out good, some of it doesn't. You can specify the UI in detail and sometimes get exactly that, sometimes not.

So what are the odds that all of it comes out the way you wanted?

Say each individual decision has a 90% chance of landing the way you intended. That's a generous assumption.

(This is a simple calculation that assumes the items don't affect each other. In reality they interact, so don't take it literally — it's for the order of magnitude.)

Number of decisions	Chance all of them land
3	73%
5	59%
10	35%
20	12%
50	0.5%

It's a product, so it falls much faster than people expect. Even at a near-ideal 95% per item, twenty items gives you 36%.

And a big spec holds twenty or fifty decisions without trying.

Here's the part that matters. At twenty items, the chance that at least one of them does not land is about 88%. So what happened to that "at least one"?

Usually it gets accepted with "well, it runs, good enough." Because nobody checked which parts didn't land. Checking would mean reading all of it, and the amount that came out is exactly the amount you can't read.

Are you actually satisfied with that?

"Just write a more detailed spec" ends at implementation

Some of you are thinking:

Then write the spec in enough detail that it can't miss?

Correct. The only way to raise the per-item odds is to remove ambiguity.

But writing it out in full means enumerating, in advance, every decision you would otherwise make while implementing.

Where the button goes, what happens when you press it, what shows up when it fails, what to do when the value is empty. Write all of that and yes, you get closer to what you wanted — but the volume you write, and the volume you think, moves toward implementation.

And there is one decisive difference.

A spec doesn't run.
No matter how detailed it is, it will not tell you whether it's right.

Detailing a spec looks like raising your odds. In practice it tends to be "postponing the answer while increasing the bet."

And AI flipped this trade-off

"Settle it on paper first" used to be the correct call.

Before   rewriting is expensive  → building big and then fixing costs a lot
                                 → cheaper to be wrong on paper

Now      rewriting is cheap      → rebuilding doesn't cost much
                                 → cheaper to be wrong in working code

Being wrong on paper was rational because rewriting was expensive. That premise moved.

That said, not everything got cheap. What got cheap is transcribing something whose shape you can already see. Migrations, public APIs, anything wired to another company — rewriting those is still expensive. Settle those up front.

So: once you've reached the point of "let me spec this out in detail," you may as well build it there.

Give the AI instructions in small increments and you get something running in about the time it takes to write the detailed spec. And the running version has a decisive advantage.

A spec stays silent when it's wrong.
Something that runs tells you immediately.

If you're spending the time either way, spend it on the one that tells you. That's the whole argument.

So how do you build? Tighten the implementation, not the spec

First, look at what happens when you build big in one go and it turns out to be wrong.

Everything produced up to that point sits on top of that spec. You aren't fixing a part; you're restacking. And you usually notice "restacking would have been faster" only after you've finished stacking.

So keep it small enough to throw away. There's one thing to do.

Cut down to the smallest unit that needs a judgement, implement them one at a time, and judge each time.
What you tighten is the implementation, not the spec.

On odds, it's just the table read backwards: decide five at a time and you're at 59%; three and you're at 73%.

But odds aren't the only thing that improves. Cutting small changes three other things.

1. The judgement itself gets more accurate

Looking at twenty things at once and asking "is this fine?" versus looking at them one at a time — the second is more accurate. Detail drops out when you look at everything together. And as above, you end up waving it through with "well, it runs."

2. You can change direction partway

If you realise at the third one that the whole direction is wrong, you can turn there. Realise it after finishing all twenty and the cost of turning is everything you already stacked.

3. You can put it in front of people early

This might be the biggest one. Getting something running early also means getting it used early.

Later in this post I describe how the purpose I built the thing for turned out to be wrong. The only reason I found that out is that people could actually touch something running. Had I shown nobody until it was all finished, it would have been completed against the wrong purpose.

"Isn't one at a time slow?"

Yes. Done serially, of course it is.

So do it in parallel.

Run about ten independent things at the same time. Then evaluate them as they land and feed corrections back.

cut small, serially     →  slow. which makes you want to batch it up
cut small, in parallel  →  not slow. it can stay small

Cutting small only becomes practical once you can run things in parallel. Conversely, in an environment where you can't run in parallel, betting big is all that's left. That, I suspect, is why "write the whole spec first" still looks rational.

And what happens when you do run in parallel? You end up evaluating finished work, one after another. When that clogs, everything stops. If there's one person evaluating, their spare attention is the ceiling.

That's why the second half of this post ends up being about headcount and parallelism.

That said, cutting small isn't automatically safe

It isn't as simple as "cut it smaller and per-item accuracy is preserved." Cut in the wrong place and new mistakes appear at the seams.

What is decisively different is this: you find out you were wrong sooner, and you can throw away only what you built so far.

Every number in the second half of this post exists to serve that.

This isn't AI's fault. It was always like this

Something worth remembering.

Back when only humans wrote code, specs were wrong too.

You write the spec, hand it to engineering, and it comes back: "this doesn't work as written." You touch something running and only then realize "no, not this." Those round trips did not happen because implementation was slow.

They happened because the spec was wrong and nobody could tell until they touched it.

What AI made fast is mostly implementation, and the planning around it.

what was slow       implementation  → got fast
what was wrong      the spec        → barely changed

The cause of failure is largely unaddressed. If anything, wrong specs now become real faster and in larger volume.

The same thing happens under Agile

"That's why we do Agile" is a fair objection. Short cycles, build, check, correct. The distance really does shrink.

But it stops when the product owner and the team are separated. The person deciding is in a meeting, not at a keyboard. Decisions lag, and in the worst case the kind of judgement you only discover while writing code never reaches anyone.

I don't think the real variable is waterfall vs. Agile.

The distance between the person deciding and the code.

spec everything first   the decider is farthest from the code, and decides once, from there
Agile (separated)       the decider is in a meeting; decisions come at sprint granularity
working alongside       the decider is at the keyboard

Agile shortened the distance. It didn't take it to zero. And there are decisions that only reach you at zero. The examples below are what I mean.

The tool got smarter. You didn't

Some of you are thinking:

But AI helps write the spec now. Isn't that different from before?

I think this is the biggest misunderstanding around.

AI did get smarter. Throw it requirements and a plausible-looking spec comes back. And that makes it feel like your own ability went up.

It didn't. The tool got smarter. You are still the bottleneck.

Leverage is a multiplier, not the number being multiplied

AI is powerful leverage. People with a clear vision of what they want to build use it astonishingly well. That part is real.

But leverage is multiplication, and the thing being multiplied hasn't changed.

A plausible spec appears instantly. But reading it and deciding "this is sound" or "this is wrong" is still you. And the ability to produce a good spec is still yours to have or not have.

Writing makes this easy to see.

Plausible prose is easy to get out of an AI.
Getting genuinely excellent prose out of one is still extremely hard.

Anyone who writes knows this in their gut. Specs and design are exactly the same.

Former CTOs joining AI labs as individual contributors is probably the same story

This is actually happening.

Peter Bailis — CTO of Workday (from May 2025). Left in March 2026 and joined Anthropic as a Member of Technical Staff, working on reinforcement learning engineering (The Next Web, 2026-04-09)
Bryan McCann — co-founder and CTO of You.com. Also moved to Anthropic as a Member of Technical Staff (The Information)

CTOs of public companies and fast-growing startups, dropping the title for an IC seat. At minimum, several moves in the same direction have been reported recently.

The Next Web characterises it this way:

executives at the top of established technology companies choosing proximity to cutting-edge research over the authority that comes with managing large organisations

That is where the reporting ends. Both moves are documented. Why they did it is not in those articles.

From here on, this is my speculation.

If the goal were a bigger title or better terms, being CTO somewhere else was available. Not taking that reads, to me, like a statement about priorities.

Until now, building something large required a large team. For a CTO-level person to realise an idea, they needed capable people and an organisation. AI is filling that part.

If so, taking an IC seat where the smartest model and unlimited access to it live, instead of leading an organisation, is an entirely reasonable choice.

This is also a story about people with a clear vision being able to move with fewer people — the same direction as this post's conclusion.

But again. What changed is leverage.

AI increases the material for a decision. It lists options, it catches omissions. But the criteria for picking among those options exist only inside you. More material without criteria means you feel like you can choose, and you can't.

Without something to multiply, a multiplier means nothing.

Some decisions don't exist until you build

Abstractions don't land, so here are two real ones.

Example 1: the purpose I built it for was wrong

MulmoTerminal, which I build, is a tool for running many AI agents side by side. The screen is a grid of cells, each running its own work.

My assumption while building was clear.

This raises the ceiling on how many you can run in parallel.

If I were writing a spec, I would have written exactly that. It's why I built it.

Once people were actually using it, I asked four of them. How many do you actually run? What's good about it?

Here's what came back.

agents actually run in parallel                1 to 6
people who said "I can run more now"           0

Not one. What all of them said was something else entirely.

I can handle the same number more easily.

One person runs one to three and dropped VS Code entirely. The count didn't go up. They switched anyway.

So the value of this tool was not "raising the ceiling." It was "not losing track." The person who built it had it wrong.

And then it got worse

From the same conversations:

I got up to eight, but the notifications became a storm and I got tired and stopped

Notifications exist to let you run more. So you can walk away and still be called back.

Those notifications were creating a new ceiling. One part of the tool was lowering the ceiling another part had raised.

The cause was concrete: "finished" and "waiting on you" played the same sound. Indistinguishable, so you end up caring about all of them.

There is no way to know this before building. At the moment you add notifications, you assume they only push in one direction. Nobody finds out until someone actually runs eight and gets tired.

Example 2: the AI said "don't do it" — and it was wrong

There are tools that find duplicated code automatically. At one point ours reported a lot of "the same shape appears in many places."

The shape was something like this:

read A → error if missing → catch the failure and log it
read B → error if missing → catch the failure and log it
read C → error if missing → catch the failure and log it

When I went to consolidate it, the AI told me not to. From the dev log:

The checker reports many duplicates, but this is a structural repetition — read, error if not found, catch the exception — and each site is readable precisely because it is self-contained. Consolidating would mean rewriting large parts of a 2,700-line file, and readability would get worse, not better.

The reasoning holds together. "A wrong abstraction is worse than duplication" is in fact a principle we've written down. I read it and thought, fair enough.

But when I opened the code myself later, it was wrong.

What had been flagged was not a coincidental resemblance. It was genuinely the same thing written over and over. Consolidating it made things noticeably cleaner. We ended up doing it as a separate task.

Laid out, what happened was:

the tool said "duplicate"              →  correct
the AI said "don't consolidate"        →  plausible, and wrong
I opened the file and checked          →  consolidating read better

AI can justify not doing something with a plausible reason. And the principle it cites is generally correct, which is why you nod along.

Whether an argument is convincing and whether it's right for this code are different questions. And the second one can't be settled until you open the file.

Which brings us back to distance.

If I had turned this into a ticket that said "reduce duplication" and handed it to someone, the AI's explanation would probably have won. It's well written; there's nothing to argue against. Only the person who opened the file can overturn it.

What these two share is that the right answer wasn't knowable until something actually ran.

Example 1 — the purpose it was built for turned out to be wrong, and only usage revealed it
Example 2 — a plausible explanation from an AI was, in fact, wrong

Neither fits in a spec or a ticket. By the time it fits, you've already checked.

What you can decide before building is only what you already know.

AI doesn't shorten the distance

This is where the original question comes back.

What AI made fast is mostly implementation and planning — and the benefit lands on whoever is at the keyboard. If the authority to decide sits far from the keyboard, that speedup doesn't reach it as-is.

authority at the keyboard   →  fast, and corrected as you go
authority still far away    →  fast, and still far away

"Fast while still far away" is the worst state. When the person judging stays distant, the speed at which mistakes are noticed barely changes, while the speed at which they accumulate goes up.

The result of that is "too big to review."

Why "just have the AI review it" doesn't fix it

AI reads far more text far faster than a human. That's true. So I won't claim "the AI can't read it."

Two things matter, though.

First, there's a ceiling on how much it can hold at once (the context — how much text the model can look at simultaneously). Depending on the model and your tooling, a large diff may not fit in one pass. Split it up and it fits, but splitting makes it much harder to surface "A and B don't line up." It only ever sees one side. And bugs usually live at exactly that seam.

Second, passing review doesn't mean the design is good. I have a concrete example of what survives after every machine check is green.

At one point I eliminated every "function that is too long" in my repo. Machines had nothing to complain about. Three months later:

CollectionView.vue   2,945 lines   187 functions   longest 61 lines
server/index.ts      3,020 lines   212 functions   longest 82 (most under 10)

There are no long functions. Nobody is being warned. And the files are 3,000 lines.

Because the machine only looks at "how long is this one function," never "how many different jobs live in this one file." CollectionView.vue had eleven separate jobs in it — list rendering, filtering, editing, chat, and more.

187 small functions added up to 3,000 lines, and the machine never once complained.

"The machine passed it, so it's fine" doesn't hold for review or for design. And a setup that puts AI review as the last line of defence collapses right here.

So what do I actually do

Numbers from my own way of working. Again: this is not proof of correctness, it's observational data about how I work.

MulmoTerminal (2026-06-14 → 2026-08-06, 53 days)

  commits        3,235
  merged PRs     1,170
  releases          64      about 1.2 per day
  written by     effectively 2 people (2,990 / 221, plus one at 24)

Time from opening to closing, last 400 closed issues
  median          1.6 hours
  within 6h       77%
  within 24h      92%
  over a week      2%

Diff size, last 400 merged PRs
  median          286 lines
  under 300       51%
  files changed   median 7

How I measured

Closed issues: gh issue list --state closed --limit 400, taking the difference between created and closed timestamps. PRs: the last 400, additions plus deletions. Both are cut as "the most recent 400," so if the way I work changed partway through, that shows up in the number. Commits and releases are git rev-list --count and git tag.

Issues shaped like this are not specs written before building. They're notes of something I noticed while using the thing, fixed the same day. That's why they're short-lived. If everything had been decided up front, the distribution wouldn't look like this.

Also: all these numbers can show is that things were built fast. Whether what got built is good is a separate question. Please read them separately.

On that basis, I keep the state from ever producing a giant diff. Not "what do I do with unreviewable code" — don't get there.

I do write plans. 351 of them. But the AI writes them.

To be clear, I'm not building with nothing written down.

351 files in plans/
  features 166 / fixes 132 / cleanups 37 / other 16

  278 of them (79%) carry an issue number

But these are not specs. They're the steps for clearing one issue. And the AI writes them — I read and judge.

The order looks like this:

1  I notice "this is wrong" while using it
2  I open an issue          ← me. deciding what to do
3  the AI writes the steps   ← automatic
4  I read it, correct it     ← me again
5  it gets implemented       ← automatic

The AI can only write step 3 after step 2 is settled. For something where what-to-do isn't decided, having it write is pointless. As above: plausible output appears, and whether to take it is still my call.

Which is to say —

You can only write it once the shape is already known.

Our own process turned out to be the inverse statement of the argument. I'm not rejecting writing things down. I'm keeping to the conditions under which it can be written.

Adding one person doesn't add just one channel

From here on, this is about having more than one person. If you work alone, feel free to skip.

Judgement and alignment grow with the number of channels, not the number of people. It's pairs, so for n people it's n(n-1)/2.

People	Channels	vs. 2 people
2	1	—
3	3	3×
4	6	6×
5	10	10×
8	28	28×
10	45	45×

Go from two to four and you double the hands — and multiply channels by six. At eight, four times the hands and twenty-eight times the channels.

This is a simplified model; not everyone talks to everyone. But it does show that what grows when you add someone isn't only hands. Brooks' The Mythical Man-Month — "adding people to a late project makes it later" — is rooted in the same place.

The question is what AI changed and what it didn't.

Before
  what you gain   implementation   grows with headcount (n×)
  what you pay    channels         grows as n(n-1)/2
  → there's a point where it stops paying, but below it the gain won

Now
  what you gain   implementation   the AI produces it; barely tied to headcount
  what you pay    channels         still n(n-1)/2. unchanged
  → the gain side shrank; the cost side stayed

At least the reason "we need more hands to write it" got weaker, while the price of adding people stayed put.

This connects back to the former CTOs

Earlier I mentioned CTOs from Workday and You.com joining Anthropic as individual contributors. I think that's this formula too.

Lead a large organisation and you get implementation capacity proportional to headcount. At the same time, you carry n(n-1)/2 channels. A decision only becomes real after it has been through all of them.

What happens if you step off that?

take it from an organisation   capacity × headcount  +  carry n(n-1)/2 channels
take it from AI                capacity              +  one person's worth of channels

Sit somewhere you can focus purely on judgement and use AI without limits. Get the implementation capacity from the AI rather than from an organisation.

None of them said this, of course, so this is my reading. But looking at what the people closest to the frontier just gave up and what they went to get, it points this way.

What they gave up was the organisation. What they went for was distance — between judgement and the AI.

That said, the formula doesn't give you a number

This formula does not produce "so the optimal number is N." Channel count is neither productivity nor decision speed. All the formula says is that one side of the scale got lighter; the specific number comes from my own experience below.

There's a ceiling on how much you can run in parallel

The same thing happens inside one person. Honestly, here's mine:

Within one project
  just skimming and judging        about 10 is reachable
  thinking about design            5 is the limit

Across projects
  work that takes no thought       3 to 4 projects
  dependencies / design work /
  chasing a repro                  can't parallelise (1)

The tool can show nine. The one that can't is me.

And adding "one more, I can probably take it" slows everything down. The closer your own utilisation gets to 100%, the more sharply the agents' waiting time grows (picture a convenience store with one register and a clerk who is essentially never idle — a small bump and the queue stretches).

So the way to raise parallelism isn't "add agents," it's reduce the part that can't move without you. Decide design up front, write the repro steps first, cut dependencies early. Though that carving-out is also your work, so it never reaches zero.

Which leads to: teams should be small too

Everything up to here holds for one person. What follows is the multi-person case.

The variable that should set headcount is not implementation volume. It's the amount of judgement. By judgement I mean setting priorities, settling design, deciding how exceptions are handled — the kind of decision that loses accuracy when handed to someone else.

The premise of sizing by implementation volume has broken down, at least around me, because implementation volume no longer tracks headcount. What's left is judgement, and splitting judgement is where the formula above bites.

So here's where I land.

If you're building something whose shape isn't settled yet, and the owner can touch the code:
one to three people per product.
The owner, or someone who can back them, does the implementing.

This is not a universal optimum. It's a conditional rule of thumb. It roughly holds when these are true:

What to build isn't fully decided — you're still exploring the shape
The product's owner can touch the code — the decider is at the keyboard
One person can hold the whole thing in their head — when they can't, that's your split line
You can ship on your own judgement — no approval queue

If any of those is missing, you can't cut headcount. Work that needs deep specialist knowledge, anything running 24/7, industries where the author legally can't review their own work. Those aren't headcount problems.

The two-pizza rule isn't about meetings any more

Amazon's two-pizza team idea was, originally, a design principle for small autonomous teams — meetings being part of it. When implementation needed people, capping communication on top of that was the rational move.

Implementation no longer scales with headcount. What's left is judgement, and judgement is what eats alignment cost.

then   "we need the people. at least keep meetings and teams small."
now    "we don't need the people. the unit of building can be small."

There are things you genuinely want more people for

Read this far and it may sound like "cut headcount, always." It isn't.

The only thing that should be small is the unit of building.

The number of ideas — more is better
The number of people giving you feedback — more is better
The number of people using it — more is better

As in Example 1, I did not find out that the purpose was wrong until I asked four people. That doesn't happen without people around you.

So it splits like this:

the unit of building     smaller is better    because judgement can't be divided
the people around it     more is better       because it grows the material for judgement

That "around" is your community, and your company.

Separate the place you build from the place opinions gather. Two people inside is fine; outside, more is better. If anything, the smaller you make the unit of building, the more you need material from outside — with fewer people inside, your perspective narrows.

Cut people per product, not people

Easy to misread, so: this is not "turn eight people into two."

✗  make eight people into two
✓  stop putting eight people on one product
   → 2 people × 4 products

Reduce the headcount per product, not the headcount.

Though, as above, three or four projects at once only works for the low-thought work. If all of them are in design mode, one is the limit — so "two people, therefore six to eight products" doesn't follow. In practice it's one you're thinking hard about, plus a few you're coasting.

In the end, this is what I think it comes down to

I've written a lot above, but the essence is one line.

The product's owner, in a small group, building it while using it themselves in detail.

That's the shape I think fits building products in the AI era.

If you aren't the heaviest user, it won't get good

In Example 1, the purpose I built it for turned out to be wrong. The only reason I caught that is that I use it every day too.

If I didn't, someone saying "I can handle the same number more easily" would mean nothing to me. I wouldn't know the weight of the answer.

The material for judgement only accumulates through use. A tool its owner doesn't use can't be fixed by anyone's judgement.

You probably don't need to be a strong programmer

This is the hopeful part, I think.

What's required is being clear about what you want to build, and being able to look at the output and say "no, not this." Not writing code quickly.

If you have those two, an era where non-engineers build good products is coming into view. If anything, the clearer you are about what you want, the more the leverage pays.

But you can't just hand it off

You give the AI the spec and the implementation, and what comes out is "somehow not right."

Of course it is.

Without settling the details yourself, you don't get a product with substance. Micromanagement is not usually a compliment when the subject is a person. With an AI, though, I think it's simply the correct approach.

It doesn't complain. It'll redo it as many times as you like. So you may as well push until you're satisfied.

What this post said

Rescuing "too big to review" with review alone is very hard. The answer is to not get there
The cause is writing a big spec up front. This happens when you work alone too
You can't write a spec for something when you don't know if it's possible or whether you want it
This isn't AI's fault. Specs were wrong in the human-only era too, and nobody could tell until they touched it
Even when AI helps write the spec, deciding whether to take it is still you. The tool got smarter, not you
Leverage is a multiplier, not the number being multiplied. Without something to multiply, it means nothing
Adding people grows channels as n(n-1)/2. Hence one to three per product (a conditional rule of thumb)

Handing over a big spec and letting it build in one go is buying a single lottery ticket where you don't learn the result until the end. And if you try to fix that by writing the spec in more detail, where you arrive is implementation. Same effort — write the one that runs.

Rough out the base, then work alongside it, using it yourself in detail. That isn't "being sloppy." It means increasing the number of judgements.

And the only person who can increase that number is the one sitting at the keyboard, using the thing themselves.

One small plug at the end

Every number above came out of building MulmoTerminal. And I'll admit it: it's also the tool for working the way this post describes.

Cut small and draw often, and this always happens:

Wait — which one is waiting on me right now?

Run three or four agents and you'll leave one waiting for tens of minutes without noticing. Since your own attention is what caps parallelism, everything stalls when that clogs.

I built it to solve that with cell colour, sound, and a push to your phone.

This tool is specialised for how far one person can run in parallel. There is nothing in it for splitting work across a team. If you're comfortable in a terminal and don't mind working in parallel, it probably suits you best.

In practice, ten is reachable

Earlier I wrote "measured, it's one to six." That was the result of asking four people.

I myself run about ten when I'm purely skimming and judging. Someone at a US startup I spoke to said twelve.

That may look like a contradiction. It isn't.

thinking about design       5 is the limit
just skimming and judging   about 10 is reachable

Mix them and you get dragged down to the lower number. Which also means: reduce the things that can't move without you, and the number goes up.

Ten to twenty for one person. If you're comfortable in a terminal and don't mind parallelism, I think that's reachable.

Getting there doesn't take more agents. It takes exactly what this post has been about: cut to the smallest unit that needs a judgement, cut dependencies early, write the repro steps first. Shave down the part that can't move without you, as far as it will go.

What raises the ceiling isn't the tool. It's how tightly you work. Give it a go.

But the tool alone won't get you to ten

If you go and read every one of them thinking "is this okay?", you'll cap out at five. To grow the number you have to reduce the attention each one costs.

What I do for that is written up in the other posts in this series (Japanese):

I stopped reviewing my own code — the whole picture of not breaking without reading
Green is not evidence — whether the checks you have are actually checking anything

Without that machinery in place, ten in parallel doesn't hold. With it, your attention goes to judgement only.

It's all connected. "Cut small and run in parallel" here, and "don't break without reading" over there, are the same one thing written from two sides.

It runs on your own machine and you look at it in a browser. It starts with npx, so there's nothing to install first.

npx mulmoterminal@latest
# → http://localhost:34567

→ receptron/mulmoterminal (MIT)

If you're running things in parallel on your own, or with a small group, it may well help.

When your GUI isn't the whole input language

Isamu Arimoto — Mon, 03 Aug 2026 20:59:42 +0000

I spent a week of my life on where a button should go. I don't think I'll do that again, and it took porting a benchmark tool to work out why.

Let me concede the obvious thing first, because otherwise it's the only thing anyone will want to talk about: GUIs are still input devices. Direct manipulation, menus, palettes, keyboard shortcuts, drag targets, accessibility affordances — all input, all irreplaceable. I'm not arguing for chat-instead-of-UI. Command palettes, scripting and macro systems have absorbed open-ended commands inside GUIs for decades, and they work.

The argument is narrower, and it's about a specific failure: designing controls first, for a system whose set of valid operations won't hold still.

Where I noticed

I'd built a benchmark tool. It evaluates combinations of LLM/SLM models × skills, and scores each combination on four things: accuracy, runtime, turn count, and total cost.

It also tracks the moving parts. New models arrive constantly. Prices change constantly. Both are part of the tool's state.

It ran inside Claude Code. I decided to port it to a proper web tool, sat down to design the interface, and got about as far as two dropdowns before it fell apart.

The two dropdowns were fine. Pick a model. Pick a skill set. Both are finite, both need to be shown to you — you can't ask for a model if you don't know it exists — and both are cheap to render.

Everything else was the problem.

What the work actually is

The tool isn't really "run a benchmark." It's maintenance. Every time a model or a skill is added or updated, work appears:

A model was added. Re-run it against which skills? All of them, or the ones where the previous best is close? Compare against which baseline?
A price changed. Recompute historical cost, or only from here? Are last month's cost comparisons still meaningful?
A skill was updated. Which stored results are now invalid? Re-run the whole matrix, or the affected column?

I kept trying to design controls for these and kept discovering the same thing: each one is a slightly different task. Not a variant of a task — a different task, shaped by what changed and what I already knew.

To put that in a UI I'd have to enumerate them. Every one, in advance, before knowing what the next model release would make me want. And each new axis creates more cross-combinations with all the others.

In chat it's a sentence. "gpt-5-mini is in — run it against every skill and put it next to haiku." The agent works out which runs are actually needed. Nothing was designed for that request specifically, and nothing had to be.

That's the whole of it. Not "chat is better." Just: when the set of valid operations keeps changing, a control surface has to keep growing, and it's always one release behind.

Where the line fell

Not "finite versus infinite." I had it wrong at first. The line is:


UI keeps it	Things that must be enumerated and shown — available models, available skills, the price table, the four scores
Chat takes it	Things where the task is different every time — what to re-run, against which baseline, which results to invalidate

The model list has to be a UI, and not because it's short. It's because you cannot ask for something you don't know exists. Enumeration is the whole value.

The four scores are the same. Accuracy, runtime, turns, cost — you read them. They update when a price moves. There is nothing to click, and clicking would not help.

The part I didn't expect

When a user gets stuck in a GUI, you often get nothing usable. They can't find the control, conclude the thing can't be done, and leave. You may see that they dropped off; you rarely learn what they were trying to do.

When a user gets stuck in chat, they type what they were trying to do. Now you have a sentence describing a task your product doesn't support, in their words.

I want to be careful here, because there's an obvious objection and it's correct: chat users also leave silently. Plenty do. And GUIs have telemetry, funnels, session recordings — this isn't a categorical difference, and I'd be overselling it if I said it was.

What it is, I think, is a difference in recovery. A failed GUI interaction usually leaves you an event, not an intention. A failed chat interaction leaves a sentence, which means someone — you, a support person, or the agent itself — has something to answer while the user is still there. Not always. But it's the difference between a signal you have to interpret and one that states itself.

For a tool whose task list changes every week, that mattered more than I expected. The unsupported requests are the roadmap.

A second data point, honestly labelled

I also maintain a browser terminal grid for supervising several coding agents at once. Different product, different problem, built for different reasons.

Counting one cell's header: roughly 11 buttons and 9 status chips. The chips are directory, git branch and change count, model and context percentage, token counts, which PR or issue the cell is on, a diff badge, usage, and a one-line summary of what the agent is currently doing. None of them is clickable in that configuration. They are read.

And every button that survived does the same kind of thing: expand, close, show files, open the canvas, open the timeline. They change where you look. Not one of them makes the agent do anything — that gets typed.

The same boundary appeared in another product, one I wasn't thinking about the benchmark tool while building.

But I should not call that convergence. Same author, same period, same tools, same assumptions. It's a personal design pattern showing up twice, not independent validation. Take it as evidence that the boundary isn't specific to one benchmark workflow, and no more.

Where this stops being true

Precisely, because a claim that never fails isn't saying much:

Precision and spatial feedback. You do not describe a crop, a curve, or a fillet. Photo editors and CAD tools aren't going to move that to a prompt, and shouldn't.
Repetition and muscle memory. An action you take fifty times a day should be one keystroke. Typing it is a downgrade every single time.
Discovery. A new user doesn't know what to ask for. This is the strongest argument for keeping the control surface, and it's why the model list stayed a list.
Safety. "Delete the failed runs" should require pointing at something, not a sentence that could be parsed generously.

Spreadsheets, IDEs and design tools stay hybrids. They should. Chat is an orchestration layer over stable primitives, not a replacement for them.

The thesis, as narrowly as I can put it

A visual interface is excellent at exposing stable objects, state, constraints, and high-frequency actions. It becomes expensive and brittle when the valid operations are numerous, compositional, state-dependent, and continuously changing.

In those systems: let the UI enumerate what has to be chosen and inspected, and let a conversational layer absorb the requests that would otherwise need a new control every week.

The gain isn't that chat replaces the interface. It's that changing intent becomes observable, recoverable and extensible without shipping a button for every new combination.

So: stop agonising over button placement — in the parts of your product where the verbs won't hold still. Everywhere else, the button is still the right answer — as it has been the whole time.

If you've shipped a control surface for a workflow that kept changing underneath it, I'd like to hear how that went. My honest position is that I found the boundary in two of my own products and I don't yet know how far it generalises.

Green is not evidence. Two of my checks were covering less than I thought.

Isamu Arimoto — Mon, 03 Aug 2026 08:25:55 +0000

Someone left this on a post of mine about how I stopped reviewing my own code:

Most teams test the output of a rule (e.g., does this code pass linting?) but rarely test the rule itself.

I'd been writing about pulling decisions into pure functions so they can be tested. They took it one level up: fine, but who tests the thing doing the checking?

I had two answers to that lying around. I just hadn't connected them to each other.

The first one: a typecheck that checked half the repo

We run yarn typecheck in CI on every PR. It had been green for months.

It had also never looked at our server code, or any of our tests.

The root tsconfig.json referenced two of five projects. vue-tsc -b walks the references it's given, so everything else was simply out of scope. Not skipped with a warning — never enumerated in the first place.

Here's the part I want to underline. I fixed the references — and the check stayed green, exactly as green as before. Of course it did; the code was fine. Green looks identical whether you're checking five projects or two, which means it could not tell me whether my fix had worked. So I did this:

const x: number = "nope";

One of those in each of the four areas I cared about, then run the check and confirm it fails.

Where I planted it	Before	After
`server/config/workspace.ts`	passed	✗ caught
`src/utils/focusTrap.ts`	✗ caught	✗ caught
`test/common/readString.spec.ts`	passed	✗ caught
`test/server/git/prs.spec.ts`	passed	✗ caught

Three of four had been silently passing. The one that already worked is why nobody noticed — you get some type errors, so the check is obviously running, so you stop wondering. (Fixed now: the root config references all five.)

There's a footnote to this. Our contributing guide had a line saying "yarn typecheck alone passes while CI fails — run all three commands." Somebody had hit this, worked around it in prose, and moved on. A rule in your docs that tells people to be careful is often a bug you can fix in config.

The second one: a rule set to `error` that reports zero

This one is better, because there is nothing to fix in the config. The config is correct.

We ban type assertions. Not "discourage" — banned, at error severity:

$ npx eslint --print-config src/components/SettingsField.vue \
    | jq '.rules["@typescript-eslint/consistent-type-assertions"]'

[2, {"assertionStyle": "never"}]

Severity 2. Error. For that exact file.

That exact file, line 14:

@input="$emit('update:modelValue', ($event.target as HTMLInputElement).value)"

And:

$ npx eslint src/components/SettingsField.vue
$

Nothing. yarn lint reported 0 errors across the repo.

Both facts are true and neither is a bug. vue-eslint-parser exposes the <template> as a separate AST, and typescript-eslint rules don't walk it. They see <script>. A cast in a template was never in scope for the rule — it just looks like it is, because --print-config will happily tell you the rule is on.

I measured the other frameworks, expecting this to be a template-language problem generally. It isn't:

	script side	template / JSX side
React, Solid, Preact (`.tsx`)	✅	✅
Svelte	✅	✅
Astro	✅	✅
Vue	✅	❌

JSX is part of TypeScript's own grammar, so it lands in the same tree. The Svelte and Astro parsers expose their template expressions in a way these rules can visit. Vue keeps them separate. It's an implementation choice, not something inherent to having a template language — which is what I'd assumed before measuring.

And it's fixable. typescript-eslint can't reach that AST, but eslint-plugin-vue can — vue/no-restricted-syntax is the one rule that walks it:

{
  files: ["**/*.vue"],
  rules: {
    "vue/no-restricted-syntax": [
      "error",
      { selector: "TSAsExpression", message: "Narrow in <script>, pass the result to the template." },
      { selector: "TSNonNullExpression", message: "Same." },
    ],
  },
}

One subtlety worth copying: exclude as const.

selector: 'TSAsExpression:not([typeAnnotation.typeName.name="const"])',

consistent-type-assertions already exempts it, and the two halves of one SFC must not disagree about what's banned. It's also not what the ban is for — a const assertion narrows a literal the compiler can already see, rather than claiming a type it couldn't prove.

We ran this on a sibling project first and it found 16 casts that had been outside the gate the entire time the ban was at error. Six were already unnecessary: a v-if above them had started narrowing the type at some point, and nobody re-checked, because nothing was looking.

The rest moved into <script>, which is where a DOM type check belongs anyway:

<input @input="onInput" />

function onInput(e: Event) {
  if (!(e.target instanceof HTMLInputElement)) return;   // bail if it isn't
  emit("update:modelValue", e.target.value);
}

The cast wasn't protecting anything. It was hiding that the check had been written in the wrong place.

Same file, same line, after the rule went in:

$ npx eslint src/components/SettingsField.vue

  18:41  error  Do not use type assertions — narrow in <script> and pass
                the result to the template   vue/no-restricted-syntax

✖ 1 problem (1 error, 0 warnings)

That is the whole point of this post, in one command. The config didn't get stricter — consistent-type-assertions was already at error. What changed is that something is now looking at the place where the violation lives.

Why this keeps happening: the config composes

Neither failure was carelessness, and I don't think either was avoidable by being more careful. Lint and compiler config compose, and composition is where simple pieces stop behaving simply.

Two examples I only found by measuring.

strict doesn't include what you'd guess. It's eight flags. These six are not among them:

noUncheckedIndexedAccess        exactOptionalPropertyTypes
noImplicitReturns               noPropertyAccessFromIndexSignature
noImplicitOverride              noFallthroughCasesInSwitch

The rule that bans as is not in strict. I loaded each typescript-eslint preset and read back what was enabled:

rule	`recommended`	`strict`	`stylistic`	`recommendedTypeChecked`	`strictTypeChecked`
`no-explicit-any`	✅	✅	—	✅	✅
`no-non-null-assertion`	—	✅	—	—	✅
`consistent-type-assertions`	—	—	✅	—	—
`no-floating-promises`	—	—	—	✅	✅
`no-unsafe-assignment`	—	—	—	✅	✅

It lives in stylistic only. Not in strict, not even in strictTypeChecked. If you reached for strict because casts worried you — which is exactly what I did — you got the opposite of what you wanted, and nothing told you.

Then there's a second-order version, which is the one that actually unsettled me.

sonarjs/different-types-comparison flagged nine comparisons as always-false. All nine were false positives, and they looked like this:

const command = process.argv[2];
if (command === undefined) { /* the rule says this can't happen */ }

Without noUncheckedIndexedAccess, TypeScript types process.argv[2] as string. The rule believed it and concluded the guard was dead. Following the advice would have deleted a real check.

Turning that flag on took it from nine to four — and the remaining four turned out to be genuinely redundant. The rule was never wrong. It was reasoning correctly from a type that was lying to it.

So: when a rule produces false positives, suspect a missing setting upstream before you suspect the rule.

The method, such as it is

Three commands. None of them take more than a few seconds.

# what is ACTUALLY enabled for this file, after all inheritance
npx eslint --print-config src/index.ts

# effective tsconfig, after all extends
./node_modules/.bin/tsc -p tsconfig.app.json --showConfig

# how many errors would this flag produce, before I commit to it
./node_modules/.bin/tsc -p tsconfig.app.json --noEmit --pretty false \
  --noUncheckedIndexedAccess 2>&1 | grep -c "error TS"

Three notes, each from getting it wrong.

Use the project's own tsc. A global one installed by a package manager can be a completely different program wearing the same name, and it will tell you so in a way you won't expect.

Pass --pretty false. With pretty output, tsc writes colour escapes between the two words you're grepping for:

- \x1b[91merror\x1b[0m\x1b[90m TS2322: \x1b[0mType 'string' is not …

The literal string error TS isn't in there any more, so grep -c "error TS" returns 0 — which reads exactly like "no errors." Mine didn't drop colour when piped, either. (And grep -c counts matching lines, so treat it as a gauge, not a census.)

Point -p at a real project, not a solution file. This one is the same bug as the whole post, and I walked into it while writing this section. Our root tsconfig.json is files: [] plus five references — a solution file. -p doesn't follow references, so it compiles nothing and exits clean. I planted one error in server/ and measured:

command	errors reported
`tsc -p tsconfig.json --noEmit` (the root)	0
`tsc -b tsconfig.json`	72
`tsc -p tsconfig.server.json --noEmit`	1

Zero, from a repo with a deliberate type error in it. If your root is a solution file, -p on it is a green light that means nothing — use -b, or name the leaf project.

Then the part no command does for you:

Break it on purpose. --print-config tells you what the config says. It cannot tell you whether the rule can reach your code, and -p can't tell you whether it compiled any. The only thing that answers either question is planting a violation and watching the check fail.

What turned up once the checks were actually running

The point of all this is that the checks then find things. A sample of what came out:

A type claimed a field the API never sent. /api/session/:id doesn't return id. Adding a runtime guard broke four tests, which is how we found out. The type had said id was there since the beginning.
fetchJson<T> returned whatever the caller named it. No validation. If you wrote fetchJson<Config>(...), you got Config — as a claim, not a fact.
Config was validated on save and not on load. Broken entries came straight back in at startup.
String(x ?? ""), seventeen times. When x is an object you get "[object Object]", no exception. That string was used as a lookup key and rendered as a session title. The real damage isn't the display — it's that missing and corrupted stop being distinguishable.
An await on a synchronous function. It waited for nothing and told every future reader "this line is I/O."
A sort whose answer depended on who ran it. A rule suggested localeCompare for filenames — which are zero-padded dates and ISO timestamps. Locale order would have made the result machine-dependent. Following that advice would have introduced the bug.
A guard that could never fire. matchAll always populates index, per spec.

And on the server side, where I cleared 145 of the 407 no-unsafe-* findings, they came from just three entry points:

entry point	why it's `any`
`await import(name)`	a dynamic import with a computed specifier returns `any`, and everything reached through it stays outside the type checker
`JSON.parse(...)`	returns `any`
`req.body`	Express types it `any`

All three are "a value from outside." One validating function at each boundary cleared all 145. The client side had a wider spread — socket frames, Response.json() — but the shape was the same every time: a boundary where an untyped value walked in and nothing stopped to look at it.

If you only do one thing from this post, grep for those three.

One trap in there: typeof x === "function" doesn't narrow enough. You get Function, and calling a Function returns any, so the result escapes again.

Not everything is worth turning on

Two flags I measured and deliberately left off.

noImplicitReturns — 58 findings, and nearly all of them are this:

if (bad) return res.status(400).json({ error });
res.json(result);   // no explicit return

That's correct Express. Nobody reads a handler's return value. Satisfying the flag means adding 58 meaningless returns and closing zero holes.

noPropertyAccessFromIndexSignature — 1,785 findings, all of them obj.key → obj["key"]. Access safety is unchanged.

Compare with noUncheckedIndexedAccess: 118 findings in shipped code, every one of them "write down what the code already assumed." All 118 were worth it.

The count isn't the signal. The question is whether the work closes a hole, and 118 real fixes beat 1,785 renames.

(Tests got their own answer: noUncheckedIndexedAccess is off there. A test indexing its own fixture with rows[0] doesn't need T | undefined — the test is the thing guaranteeing that value. That's 233 findings that were pure noise. exactOptionalPropertyTypes stays on in tests, because that one is about meaning, not fixture ergonomics.)

The thing I'd tell myself six months ago

Both failures had the same shape, and so did the sibling project's — where yarn lint turned out never to reach scripts/, batch/ or config/. That's 21 files, 92 errors, nine of them the very casts we'd banned. The code that decides whether a PR can merge had no gate on it.

Gates don't fail loudly. A gate that isn't running produces the same output as a gate that's running and finding nothing. There is no error message for "this never executed," because from the inside those two states look identical.

So the commenter had it right, and their framing is better than what I'd written. Testing that your code passes the check is not the same as testing the check.

You can't fix that by reading configs more carefully. You fix it by making the check fail on purpose, once, and watching.

Anything you've found this way, I'd like to hear it — particularly if your green was hiding something dumber than mine.

Two things broke when I shipped my Claude Code plugin — and one of my fixes was cargo cult

Isamu Arimoto — Mon, 03 Aug 2026 06:26:37 +0000

My skills worked. I'd been using them locally for weeks. Then I packaged them as a plugin, installed it the way a stranger would, and hit things that don't exist locally — and that don't produce an error message pointing at the cause.

Two of them were real. The third was a rule I'd been repeating for months, which turned out to be about something else entirely. Writing this post is what made me check it.

1. Your skill's name changes, and skill-to-skill calls break silently

A skill in ~/.claude/skills/story/SKILL.md is invoked as:

/story

The same file, shipped inside a plugin named mulmocast, is invoked as:

/mulmocast:story

The plugin name becomes a prefix. Which is fine, until you remember that skills can call other skills.

My mulmocast skill is a router: it reads what you asked for and hands off to story, narrate, illustrate and so on. Written the obvious way, that hand-off says story. So:

locally — mulmocast → story → works
installed from a marketplace — mulmocast → story → no such skill

I never saw an error that named the cause. The hand-off simply didn't happen, and the skill carried on as though that step had been optional.

The fix is to write both names, qualified one first:

1. Try `mulmocast:story` → if not found, try `story`
2. Try `mulmocast:narrate` → if not found, try `narrate`

One note on notation: a user types /story to invoke a skill. Inside a SKILL.md you are naming a skill for the model to dispatch to, not typing a slash command — so write it without the slash, as above.

2. Your CLI's name changes too

Same shape of problem, different layer.

My skills drive a CLI that ships as its own npm package. The plugin repo carries the skills, references and example scripts — not the CLI. While developing the CLI, I ran it from inside its repo:

yarn run cli images script.json

That line is fine in a terminal I own and wrong in a SKILL.md, because the person reading it installed a plugin. They don't have that checkout, so yarn run cli resolves to nothing.

The obvious fix is to write the published bin name instead:

{
  "name": "mulmocast",
  "bin": {
    "mulmo": "lib/cli/bin.js",
    "mulmocast": "lib/cli/bin.js"
  }
}

That works — if they installed the package globally. Which they may not have, and which you have no way to check from inside a skill.

So what my skills actually say is this:

npx mulmocast@latest movie script.json

npx resolves the package and downloads a temporary copy when what's installed doesn't satisfy the spec. No install step to document, and no version to keep in sync with your prose. If you keep a yarn run cli line at all, mark it as the one for people working in the repo — it is not a fallback for your users, it's a note to yourself.

Both of these have the same root cause: you are writing instructions from inside an environment your reader is not in. Every name you put in a SKILL.md — a skill, a command, a path — gets resolved somewhere else.

3. The one I was wrong about

Here is advice I had been giving, including in writing:

Never give your marketplace and your plugin the same name. If you do, installation fails on Linux with an EXDEV error.

I believed it. I set my repo up that way. I couldn't tell you where I first picked it up.

I don't use Linux. I never hit this, never reproduced it, never checked it. Writing this post is what finally sent me looking for the source — anthropics/claude-code#14799.

It has nothing to do with names.

Error: Failed to install: EXDEV: cross-device link not permitted,
rename '/home/user/.claude/plugins/cache/…' -> '/tmp/claude-plugin-temp-…'

On most current Linux distributions /tmp is tmpfs, while ~/.claude sits on your real disk. Two filesystems. fs.rename() can't move a file across that boundary, and the installer was renaming between them.

So it fired for any plugin, whatever anything was called. The workaround was to put the temp directory on the same filesystem:

export TMPDIR="$HOME/.claude/tmp"

And it's fixed — the issue closed in February. On a current Claude Code there's nothing here for you to do.

Why a wrong rule survived that long

This is the part I want to keep.

The rule was harmless. Giving the marketplace and the plugin different names costs nothing, breaks nothing, and looks tidy. So I followed it, everything worked, and nothing ever contradicted me.

A rule that's expensive gets challenged — sooner or later someone asks whether it's worth it. A rule that's free just accumulates. I'd been passing on a diagnosis I had never once tested, and the only reason I found out is that I sat down to write it as fact.

For the record, here are the names in a working setup — and note that two of them are supposed to match:

// .claude-plugin/marketplace.json
{
  "name": "mulmocast-plugins",          // the marketplace
  "plugins": [
    { "name": "mulmocast", ... }        // ← must MATCH plugin.json
  ]
}

// .claude-plugin/plugin.json
{ "name": "mulmocast" }

While we're here: there are three names, not one

The reason the above is confusing at all is that a plugin involves three separate names, and the docs use them in different places:

receptron/mulmocast-claude-plugin        ← GitHub repo
        ↓
marketplace.json  "name": "mulmocast-plugins"     ← marketplace name
marketplace.json  plugins[0].name: "mulmocast"    ← plugin name
        ↓
install:  mulmocast@mulmocast-plugins
          ^^^^^^^^^ ^^^^^^^^^^^^^^^^
          plugin    marketplace

Name	Defined in	Used by
GitHub repo	GitHub	`marketplace add`
Marketplace name	`marketplace.json` → `name`	after the `@` in `install`
Plugin name	`marketplace.json` → `plugins[].name`, and the plugin's own `plugin.json` → `name`	before the `@` in `install`

The repo name is used once in this sequence, when registering the marketplace. After that you work from the names inside the JSON:

claude plugin marketplace add receptron/mulmocast-claude-plugin   # repo name
claude plugin install mulmocast@mulmocast-plugins                 # plugin@marketplace

Minimum layout. These can be two repos or one — mine is one:

my-plugin-repo/
  .claude-plugin/
    marketplace.json     # the catalogue
    plugin.json          # this plugin's metadata
  skills/
    my-skill/
      SKILL.md           # the actual skill

Which distribution method to pick

There are three, and they're not competing for the same job.

	Reach	Ships MCP servers	Ships hooks	Install
Your own marketplace	Claude Code	✅	✅	`/plugin install name@market`
Official store (claude-plugins-official)	Claude Code, no setup step	✅	✅	`/plugin install name@claude-plugins-official`
Skills CLI	Cursor, Codex, OpenCode and dozens more	❌	❌	`npx skills add owner/repo`

Roughly:

Claude Code only, and you use MCP servers or hooks → plugin. Start with your own marketplace, apply to the official store once it's proven.
You want it to work in Cursor, Codex and the rest too → Skills CLI. It symlinks SKILL.md into each agent's directory, so one repo covers all of them. You give up MCP and hooks.

The columns say ships deliberately. Skills CLI distributes SKILL.md files; it does not install plugin manifests, so MCP servers and plugin hooks don't come with them. The target agent may well support hooks on its own.

And the thing I'd actually weigh about the official store isn't discovery — it's that users skip marketplace add entirely. One less step where someone gives up.

What the three have in common

The first two live in the same place: I had only ever run this where the names happen to be right. Locally the skill is story and the CLI is yarn run cli. Published, it's mulmocast:story and mulmocast. Both failures sit in that gap.

The third is the same gap from the other side. I'm on macOS, so a Linux-only failure was never going to reach me — and because my workaround for it was free, no evidence was ever going to reach me either. I'd built a belief that couldn't be falsified from where I was standing.

So the useful habit isn't "test the plugin" — it's install it the way a stranger would, on a machine that isn't yours, before you tell anyone it exists.

And if you're carrying a rule you've never seen fail: that isn't evidence it works. It might just be cheap.

Docs: Claude Code plugins · Marketplaces · Agent Skills spec

I stopped reviewing my own code. Here's what had to be true first.

Isamu Arimoto — Sat, 01 Aug 2026 06:38:10 +0000

Most days now, I merge pull requests without reading the diff.

That sentence used to describe someone I would not have hired. So let me be precise about what changed, because it isn't confidence and it isn't recklessness. It's that I moved the things review was catching to somewhere that catches them earlier.

Here's the honest version of how that happened.

The problem was arithmetic, not philosophy

I run several coding agents in parallel. That produces more diff per day than I can read. Not "more than I feel like reading" — genuinely more than fits in a working day.

When that happens you have exactly two options:

Generate less, so it fits what you can read.
Make it safe to not read.

I picked the second one. Not because I'm brave, but because option 1 means throwing away the reason I set this up.

The uncomfortable part: option 2 is not a mindset. It's a list of specific things that have to be true. Here's mine.

1. The rules live in a file, not in review comments

Every code review I've ever done, the majority of my comments were mechanical. This function is too long. This nesting is too deep. Why is this any?

Machines can say all of that. So I made them say it, as errors:

"max-lines-per-function": ["error", { max: 60, skipBlankLines: true }],
complexity: ["error", 20],
"max-depth": ["error", 4],
"max-nested-callbacks": ["error", 4],

Plus eslint-plugin-sonarjs with cognitive-complexity as an error, and @typescript-eslint's strict preset — any banned, non-null assertions banned.

Nothing here is novel. What's different is the next part.

2. The rules are stricter than a human team would tolerate

This is the part I find genuinely interesting.

If you put those thresholds on a human team, you get a PR relaxing them within a week. Not because engineers are lazy — because "this function is 63 lines and splitting it makes it worse" is sometimes true, and arguing about it every time is exhausting.

Lint strictness has always been a trade-off between machine correctness and human patience. And loosening the rules was never really a technical decision. It was a social one.

An agent doesn't get annoyed. It reads the rule, splits the function, moves on. It has no opinion about being told to do it again tomorrow.

So the social cost went to zero, and once that happens the trade-off only tips one way. I turned everything up until it hurt, and nobody complained, because nobody was there to complain.

3. Exceptions live in the config with a reason, never inline

The moment rules get strict, real exceptions appear. If you allow // eslint-disable-next-line, the rules are dead within a month — that comment is invisible in review and permanent in practice.

So exceptions go in the config file, one line per reason:

files: [
  "src/components/Sidebar.vue",       // @keyframes — the "thinking" spinner ring
  "src/components/GuiPanel.vue",      // `.frame + .frame` sibling-combinator spacing
  "src/components/FilesOverlay.vue",  // :deep into CodeMirror's injected root
],
rules: { "vue/no-restricted-block": "off" },

Every entry says why. And the comment above the block says: delete the entry when the reason goes away.

The difference is visibility. An inline disable is invisible. A growing allowlist in a config file is a thing you can look at and be embarrassed by.

4. The rules themselves are pure functions, and they're tested

This is the part most setups skip.

If a rule decides something — which file extension goes where, how a path is normalised, what counts as a valid session id — that decision is code, and code that is only exercised through a UI is code nobody tests.

So decisions get pulled out into pure functions in a shared module, and those functions get tested against the awkward cases: empty, null, boundary, wrong-cased, wrong-platform. That project currently has a few thousand test cases, and the vast majority are testing small pure functions rather than flows.

The point is not the count. The point is: when the rule is a pure function, the rule can be tested. When it's embedded in a component, it can only be reviewed. And I stopped reviewing.

5. CI runs on the OS your users have, not the one you have

Our whole team is on macOS. Our users are not.

So CI runs Linux and macOS on every PR, and Windows on a nightly schedule (it's slow, and daily is enough to catch drift).

This one paid for itself immediately, and not in the way I expected. It's the only environment where I can reproduce a Windows bug report at all. Before, a Windows issue meant asking the reporter to test my guesses. Now I push a branch.

We also write Windows-specific test cases deliberately — path separators, realpathSync behaviour, fs.watch differences — so that fixing one doesn't quietly break the others.

6. Something else reads the code — and it isn't the thing that wrote it

Claude Code writes. Then Codex reviews, and CodeRabbit reviews, and the loop runs until they stop objecting.

The mechanism that matters here isn't "AI review is good." It's that the writer and the reader are different models. A model reviewing its own output shares its own blind spots. Two different ones don't, mostly.

This is the closest thing to a replacement for what I stopped doing. It isn't as good as a careful human reviewer. It is much better than a tired human reviewer at 11pm on the fortieth PR of the day, which was the realistic alternative.

What I still look at

I want to be honest about the boundary, because "I don't review anything" would be a lie:

UI changes. Nothing in the list above can tell me a layout is ugly or a flow is confusing.
Anything I couldn't verify by running it. If the change is about behaviour under conditions CI doesn't reproduce, I go look.
Anything touching auth, permissions, or data loss. The blast radius is wrong for automation.

Everything else, I let through on green.

The honest cost

Three things I'd want to know if I were reading this skeptically:

It front-loads a lot of work. None of the six items above is free. If you set up two of them and stop, you have strictness without a safety net, which is worse than neither.

It only works if the stack is uniform. The reason my per-repo config files are nearly empty is that every project uses the same language, the same test runner, the same CI shape. If your repos disagree with each other, you'll be writing the same rules over and over. Fix that first; it's cheaper.

Speed is not correctness. Things do get shipped fast and fixed fast. What this setup buys is not "no bugs" — it's that the bugs that survive are the ones review wouldn't have caught either.

The thing I actually took away

I set all this up to save time, and it did. But that isn't the interesting part.

The interesting part is that lint strictness, test coverage, CI breadth — the whole category of "engineering discipline we know we should do but don't" — was never really blocked on knowing better. It was blocked on how much friction a human team will absorb before it starts negotiating.

That constraint just got removed. Not gradually. It's gone.

I don't think most of us have updated for that yet.

Everything above runs in the open: my global config
and the project it runs on, both MIT.
Copy whatever's useful.

AI Changed the Bottleneck of Software Development

Isamu Arimoto — Thu, 23 Jul 2026 08:27:52 +0000

For decades, software engineering was constrained by one thing: writing code.

Today, that bottleneck is disappearing.

With tools like Claude Code, Codex, and other coding agents, generating thousands of lines of code is almost free. The new constraint is no longer how fast we can write code—it's how fast we can keep a codebase healthy.

That is a fundamentally different problem.

AI Doesn't Create Bad Code. It Creates Code Too Easily.

Modern coding agents are remarkably good at producing working code.

But they also tend to:

create another helper function instead of reusing an existing one
leave dead utilities after refactoring
grow functions to hundreds of lines
fall back to any when type inference becomes difficult
introduce subtle architectural violations that are hard to notice in code review

None of these are catastrophic individually.

Together, they slowly increase technical debt.

The challenge isn't intelligence—it's scale.

When an AI can generate code 10× faster than a human, it can also generate technical debt 10× faster.

Human Code Review Doesn't Scale Either

Even experienced reviewers can't remember a 300,000-line codebase.

Suppose a pull request adds another truncate() function.

Is there already one somewhere else?

Maybe.

Maybe there are six.

No reviewer can reliably answer that from memory.

The same applies to unused exports, circular dependencies, or architectural boundaries.

These aren't problems humans should spend their time searching for.

They're mechanical problems.

Let Machines Enforce Code Hygiene

The obvious solution is to automate the boring parts.

Our development workflow combines several layers of static analysis:

ESLint for complexity and coding standards
SonarJS for maintainability and type safety
jscpd for duplicated code
Knip for dead code detection

Each tool catches a different class of problems.

No single tool is sufficient.

Together, they continuously protect the codebase while developers—and AI agents—focus on solving actual problems.

DRY Matters Even More in the AI Era

Many people think DRY ("Don't Repeat Yourself") is mainly about maintainability.

Today, it has another benefit.

AI agents consume context.

Six duplicated implementations don't just increase maintenance cost—they also increase token consumption.

Large functions require more context.

Duplicate utilities require more searching.

Dead code increases noise.

A cleaner codebase is also a cheaper codebase for AI.

Good architecture now directly improves AI efficiency.

CI Should Prevent Regression, Not Punish History

One lesson we've learned is that not every static analysis tool should block a pull request.

Some checks can accurately identify new problems.

Those belong in CI.

Others can only report the current state of the repository.

Those should provide visibility rather than block development.

The goal isn't to eliminate all technical debt overnight.

The goal is simple:

Never create new debt faster than you remove the old one.

The New Engineering Skill

As AI continues to improve, writing code becomes less valuable as a competitive advantage.

The differentiator shifts toward something else:

Designing systems that remain understandable, modular, and maintainable—even when most of the code is written by machines.

Software engineering is becoming less about typing code and more about managing the quality of an ever-growing codebase.

The bottleneck has moved.

The teams that recognize this early will build software faster—not because their AI writes more code, but because their systems stay clean enough for AI to keep writing it.