# One sentence in CLAUDE.md did most of what an ADR search skill did, and karasu mapped itself (karasu weekly)

> Source: <https://dev.to/kompiro/one-sentence-in-claudemd-did-most-of-what-an-adr-search-skill-did-and-karasu-mapped-itself-4gd5>
> Published: 2026-11-21 01:31:16+00:00

**Recommendation:** Give coding agents a concrete tool or path to skip a large index instead of instructing them not to read it, and validate cost savings with at least five runs per condition.
More in the playbook "Controlling LLM cost": <https://wpnews.pro/playbooks/llm-cost>

[karasu](https://github.com/kompiro/karasu) is a text modeling language for system architecture, inspired by the C4 model.

You describe your system in `.krs` files and karasu draws the views: system, deployment, and team structure.

I haven't written its code by hand; everything goes through Claude Code.

This is the seventh weekly update.

It covers changes merged from November 14 to 20.

The change in the second highlight merged just after midnight on the 21st, but it belongs with this week's story, so I include it.

**This week in numbers:** 61 PRs merged (14 of them Dependabot) and 7 decisions recorded as ADRs.

6 of the ADRs came in ADR-only PRs; the other one is part of a PR that changed a process rule.

No monthly release this week.

This week I ran an experiment on what changes when karasu gets a skill for finding ADRs.

karasu has about 500 ADRs.

When an agent looks for a past decision today, it reads the ADR index file and opens individual ADRs from there.

The question was whether it pays off to replace that with two scripts: one that searches ADRs by term, and one that lists which ADRs reference a given ADR.

An earlier experiment had shown no difference in whether the agent reaches the ADRs, so I compared whether it answered correctly and what it cost.

There were three conditions:

I ran Claude Code headless on 10 tasks, 5 times each under each condition, for 150 runs.

The model was Opus 5.5, and the karasu commit was fixed.

Subagents judged whether each answer was correct.

I shuffled the reports and masked the words that would reveal the condition, then had the subagents judge against the list of correct answers alone.

A judge who knows the condition may be pulled toward it.

The results:

| Condition | Correct | Total cost | Mean time | 
|---|---|---|---|
| R | 49/50 | $28.22 | 78 s | 
| RS | 48/50 | $22.49 (-20%) | 62 s | 
| RN | 49/50 | $24.38 (-14%) | 66 s | 

Correctness hit the ceiling under all three conditions, and the skill didn't raise it.

Only cost and time differed.

And about two thirds of the cost RS saved came from RN's single sentence alone.

The scripts added the remaining third, and they also made the instruction stick.

Runs that read the index anyway: 8 of 50 under RN, 1 of 50 under RS.

Giving the agent a way not to read the index worked better than telling it not to.

An earlier pilot with one run each had RS 28% cheaper than R.

With five runs each, that shrank to 20%.

The single-run comparison had made the gap look bigger.

One mistake showed up regardless of condition.

Some runs recommended a button CSS class that had already been replaced: 2 of 5 under R, 1 under RS, 3 under RN.

An ADR records the replacement, but the old ADR's status still says "accepted."

Since the skill didn't reduce this, I think it is a problem with how ADR status is recorded, not with how ADRs are searched.

The skill won't go into karasu directly. It moves to [adr-tools](https://github.com/kompiro/adr-tools), a CLI for working with ADRs.

The plan is to add search and reverse-reference commands to the CLI and ship the skill as a Claude Code plugin.

I'll write up the experiment's design and detailed numbers in a separate post.

I turned the karasu repository into a karasu model.

I used the [reverse-architecture skill](https://fukurou.kompiro.dev/en/reverse-architecture/), which reads a repository and writes a `.krs` model of it.

In October I tried it on umami, an open source web analytics tool; this time I pointed it at karasu itself.

The model is [in the karasu gallery](https://karasu-nest.kompiro.dev/g/42963-pjqc2ysntbvw).

There is also a copy with Japanese labels and descriptions.

The model is 4,453 lines long.

It contains:

The umami model had 10 domains, 135 use cases, and 26 entities.

umami's entities were almost all database tables.

karasu's model has only one store, a KV namespace.

Instead, the agents drew in-memory structures, such as the parser's syntax tree and diagnostics, as entities.

That seems to be the main reason there are ten times as many entities.

What surprised me was that karasu could be drawn at all, since it isn't a web service.

umami is a web service: one Next.js app serves both the screens and the API.

karasu is a monorepo where a CLI, a library, a Visual Studio Code extension, a browser SPA, and the gallery's Worker live side by side.

reverse-architecture drew each package of the monorepo as a service.

When I drilled from a service into its domains, what each package is trying to do was cleanly split out.

Honestly, it stunned me.

I didn't fix the output by hand.

Here is how long it took and what it cost.

The cost is token spend estimated at API list prices from the logs of the session and its 19 subagents, not the amount actually billed.

| Step | Time | Cost | 
|---|---|---|
| Reverse-engineer karasu | about 38 min | $28.13 | 
| Split out the editor parts and file an Issue | about 15 min | $3.91 | 
| Add references to client-side storage and prepare the upload | about 10 min | $5.02 | 
| Make the Japanese copy | about 5 min | $4.72 | 
| Total | about 70 min | $41.78 | 

During the reverse-engineering, 13 subagents ran in parallel, one per domain, taking 2.4 to 5.3 minutes each.

Those 14 minutes were the longest stage, and they account for about three quarters of its cost.

The Japanese copy was cheap because the translation subagents ran on Sonnet.

Drawing karasu also showed something its language lacked.

A use case could not point at client-side storage such as the browser's OPFS or localStorage.

6 of the 13 subagents reported this gap, each in a different domain.

The karasu app keeps project files, the API key, and display settings in the browser.

The CLI and the Visual Studio Code extension read and write local files.

With no way to point at that storage, the use cases in those domains could not say anything about what they read or write.

So a `client`'s storage line can now carry an ID, and a use case can point at it.

Taken from the model in the gallery, it looks like this:

```
client WebApp [web] {
  resource opfs ProjectIndex "/meta/projects.json"
}

usecase RenameProject {
  label "Rename a project"

  resource WebApp.ProjectIndex {
    operations write:update
  }
}
```

From filing the Issue to the design, the ADR, and the implementation took four days.

The third step in the table above is the work of adding references to the model with this notation.

The notation is still experimental, and the language version stays at 2.0.

karasu's entity view draws a domain's entities together with the entities from other domains that they relate to.

The ones from other domains are drawn muted so they stand apart.

karasu calls them ghosts.

Until now, the ghosts sat in one row below the domain's frame.

That's fine when there are a few, but with many of them the diagram keeps getting wider.

In the model I reverse-engineered from Dify in September, the IdentityAccess domain had 101 ghosts.

The diagram was a 36,053 × 1,372 pixel strip (26 : 1).

I filed an Issue back then, but other work came first.

I raised its priority because the same thing happened in karasu's model.

For example, the Language domain (which holds the parser and diagnostic entities) has 29 entities of its own and relates to 44 entities in other domains.

Almost all of them are references from other domains.

The parser is used from everywhere, so that's the expected shape.

Seeing those ghosts stretched into one long row in my own model is what made me move it up.

This week, ghosts are laid out like this:

Here is how the Language domain in karasu's model is drawn now.

Most of the 44 ghosts reference Language, so frames for 11 domains are stacked above it.

Below it are only the Modeling frame and a Styling card, which Language references.

[Open it in the gallery](https://karasu-nest.kompiro.dev/g/42963-pjqc2ysntbvw#krs-entity-Language?file=%2Fgallery%2Findex.krs) to zoom in.

I measured it on three reverse-engineered models: Dify, Twenty, and WordPress.

Of the 82 entity views that have ghosts, those with an aspect ratio outside 16 : 9 to 9 : 16 went from 51 to 0.

Dify's IdentityAccess is now 4,360 × 3,514 pixels.

Before the implementation, I had a throwaway branch try only the look of the frames, and decided after looking at its preview.

The ghost cards and lines stay muted, but each frame's dashed outline and domain name are drawn at full strength.

I wanted to be able to read which domain a ghost comes from without zooming in.

The lines to ghosts are still straight.

Routing them like the rest of the diagram is the next step.

**npm publishing now waits for my approval.**

I rebuilt staged publishing on the design I revised last week, and it has merged.

The job that installs dependencies and builds holds no npm token, and the job that holds the token installs nothing.

I compare what CI put in the approval queue against a build I made locally, then approve it with 2FA.

After publishing, a workflow compares the published contents once more and tags only the versions that match.

The flow after approval hasn't run for real yet.

The monthly train on November 29 will be its first run.

**The workflow merged all 11 Low PRs.**

Last week's "coming next" said I'd see whether five Low PRs in a row merge through the workflow.

This week 11 Low PRs merged, and `low-pr-merger[bot]` merged every one of them.

That meets the condition for the last stage, so next I'll take `--auto` out of the session's procedure and turn off the repository's auto-merge.

I also added a rule that raises a Low PR to Medium when it adds a link outside karasu's domains.

Nobody reads Low PRs, so without the rule such a link would go in with no one checking where it points.

Applied to the 380 commits that touched ADRs or TPLs since September, the rule raises 37 to Medium.

**More fixes for karasu misreading the model you wrote.**

`label` or `description`, was missing it, the parser took the start of the next line's arrow as the value. Inside a block, the leftover arrow became an edge with a source you never wrote, and no diagnostic appeared.`resource Orders [table, api]`, was drawn in a different tag's shape depending on the view. It is now drawn by the first tag. This also fixes the same step overwriting ID rules the author had written.`table`, `queue-item`, and `bucket` cards were drawn in a dark default color in every theme. They now use their store's colors.
**Adding guards turned up bugs.**

I added a test that draws about 1,700 diagrams: every example, every view, every grouping.

It found two bugs in compare mode.

I also tested karasu.kompiro.dev's permalinks the way Cloudflare Pages actually runs them, and the test failed on day one.

Responses that always return 404 or 413 were not being cached.

**SVG could be injected through the public image export.**

karasu.kompiro.dev's image export wrote the background color parameter straight into the SVG.

It now accepts only hex colors.

Color names such as `white` are now ignored and fall back to the default white.

**main's lockfile broke without a Git conflict.**

After I merged several Dependabot PRs in a row, the same entries ended up in the lockfile three times.

The Pages build failed because it couldn't read that lockfile.

The three PRs were made from the same base, so squash merging them raised no conflict.

I fixed it by deleting the 66 duplicated lines, and added a rule: a bot PR that touches the lockfile merges only when its base matches the latest main.

**Dependency updates.**

I triaged 16 Dependabot PRs together and took 15.

jsdom 31 needed one test expectation adjusted, so it went in through a PR that replaced Dependabot's.

`--auto` out of the session's procedure and turn off the repository's auto-merge.
