DEV Community: Hiroki Kondo

What a week of agent-run Dependabot triage and AI code review taught me (karasu weekly)

Hiroki Kondo — Sun, 18 Oct 2026 04:27:45 +0000

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 second weekly update.
It covers changes merged from October 10 to 17.
This time I start with what I learned building with agents, then go through what shipped and what each change taught me.

This week in numbers: 88 PRs merged (16 of them Dependabot) and 12 decisions recorded as ADRs.
On October 15 I cut a release of four packages: karasu 0.9.0, @karasu-tools/core 0.4.0, karasu-vscode 0.4.0, and karasu-skills 0.2.0.
The .krs language v2.0 from last week's post reached npm and the Visual Studio Code Marketplace with this release.

Lessons from building with agents this week

Dependabot triage runs on a hane skill.
karasu doesn't merge Dependabot PRs as they come.
Triage uses the dependabot skill from hane, a skill collection I develop separately.
hane is a Claude Code plugin that bundles skills which grew out of karasu's development.

Running /hane:dependabot makes the agent go through these steps:

Collect every open Dependabot PR.
Trace each PR upstream: release notes, the code diff between tags, changes in publisher or repository ownership, install-time scripts, the lockfile's dependency edges, known advisories, and how long ago the version was published.
Write the results into a design doc, with a recommendation for each PR: merge, hold, or reject.
Once I decide, merge and close the PRs, then promote the design doc to an ADR.

The skill doesn't skip the investigation for patch releases.
A tampered version dressed up as a patch is the easiest way for a supply-chain attack to get through.
It never auto-merges either; a human makes every call.
Because the design doc and the ADR stay in the repository, I can trace when and why any version came in.

The skill holds only the steps that apply to any repository.
Rules specific to karasu live in a rules file on the karasu side (.claude/rules/dependabot.md).
Examples are the 7-day cooldown and the conditions for bringing an update in through a replacement PR when Dependabot's own diff can't be correct.
I ran three triage rounds this week with that combination.

Running them taught me two things.

The first is about the limit on open PRs.
This week 24 npm updates cleared the cooldown, and a limit of 8 delivered them in three waves.
Each wave needed its own triage, so I raised the limit to 25.
The total number of PRs stays the same; only how many are open at once changes.

The second is that rebuilding a lockfile can move a dependency off the version you reviewed.
When a replacement PR rebuilt the lock, knip resolved to 6.41.0, which had just cleared the cooldown, instead of the reviewed 6.40.0.
I pinned it back to 6.40.0 and recorded the lesson in an ADR.

I classified 261 CodeRabbit findings.
CodeRabbit reviews karasu's PRs.
I classified all 261 threads it left on Markdown files from August 20 to October 10.
About half turned out to be real defects.
So documentation stays in review.

Among the rest, two false positives kept coming back.
Both came from how the rule text that CodeRabbit reads was worded.
For example, a rule saying "don't put a list of milestones in a design doc" was applied to the implementation steps that the design doc template asks for.
The rule was only ever meant for the slice-plan table.
So I fixed the rule text, not the CodeRabbit config, by stating its scope.
That also makes the sentence harder to misread for a human who meets it out of context.

Only a packaged test catches a broken package

karasu serve from npm didn't work, and no test noticed.

In the 0.8.0 npm package, karasu serve answered every request with "App not built".
The tarball held only 5 files and no preview app.
serve looked for the app at a path relative to the monorepo, so it worked inside the repository and failed when installed from npm.
In other words, the README's npx --yes karasu@latest serve . had never worked outside the monorepo.
I noticed while trying the reverse-architecture skill on an outside repository.

The fix ships a serve-only build of the app in dist/app/.
A new CI step packs the CLI with pnpm pack, unpacks the tarball, and starts serve from it.
I confirmed that this test fails when dist/app/ is dropped from the package's file list.
Only a test that runs the packaged artifact can catch this kind of bug.

The bundled app was 16MB (97 files), and most of it was the Monaco editor.
serve only shows the preview and never opens the editor.
So the serve build now has its own entry point, and the build fails if any Monaco module ends up in the bundle.
I checked the guard by adding the Monaco import back on purpose: the build failed and named 1,233 modules.
The serve app is now 1.7MB (4 files).
The released 0.9.0 package is 3.3MB unpacked (12 files).

0.9.0 shipped on the third release run.
Two npm Trusted Publisher pitfalls stopped karasu-skills from publishing.
Trusted Publisher is the npm setting that lets GitHub Actions publish without a token.
karasu 0.9.0 depends on karasu-skills 0.2.0, so it stopped too.

E404: A newly registered configuration is "not yet validated", and it expires unless a publish through it succeeds within 2 days. I registered the karasu-skills configuration right after publishing 0.1.0 by hand. The release uses changeset publish, which skips versions already on npm, so 0.1.0 could never validate the configuration. It expired before 0.2.0 went out.
E403: A configuration created after September 3, 2026 allows only npm stage publish by default. The release workflow runs npm publish, so "Allow npm publish" had to be checked.

The release docs now say to register the configuration right before merging the release PR that bumps the package.

Measure what a fix changes, not only what it fixes

Edge routing got more work this week.
The target was edges drawn straight across cards they should go around.

Edges between cards in the same row. These used to cut straight through any card standing between them. Now they go around through the channel above or below the row. The side with fewer crossings against existing edges wins.
Edges into a side column. In the Dify model, three edges to and from Gateway crossed 7 cards in each of two views. Now they run down the gap beside the column.

Three smaller fixes went in as well.
Lanes in a channel are now ordered by whether each edge turns up or down.
Routes that folded back over the same channel are collapsed into one run.
In a drill-down view, lanes and labels stay inside the focused frame.

Each fix was measured on real models reverse-engineered from open-source projects.
The main set is Umami, Dify, Twenty, and WordPress, 1,542 views in total.
Two numbers are tracked for every fix: how many problem spots it removes, and how many views it changes as a side effect.

Fix	Problem spots	What else changed
Same-row edges	Edges through cards: 19 → 0	5 views; +131 crossings (all drawn with hops)
Side-column edges	Edges through cards on Dify: 14 → 0	Crossings 38,147 → 38,176 (+29)
Channels bounded by the frame	Runs outside the frame in a 5-card fixture: 14 → 0	5 of 7,659 edges, in 3 of 1,542 views

For the side-column fix there was also an option that cleared a wider corridor.
It would have changed 13 views, so I went with the smaller change.

Other changes this week

Crossing marks now dim with their edges.
Hovering a card or an edge dims the unrelated edges.
The small arcs drawn where edges cross ("hops") and the count chips stayed bright, though, and kept tracing the shape of the dimmed edges.
Now the marks dim along with their edges.
To make that possible, the hops that last week merged into one <path> are split again, one <path> per edge.
On the Dify model, output grew by 4.29% and hop <path> elements went from 757 to 2,585.
The largest view still renders in about the same time: 33.3 ms before, 33.5 ms after.
Edges that ignored the mouse, such as those in the deployment view, now respond to hover too.

Nodes with the same name are no longer mixed up.
Api inside Shop (Shop.Api) and a top-level service "Shop.Api" used to share one internal key.
Every node and edge identity key now comes from one helper that cannot produce collisions.
When two systems declare a node with the same ID, each internal map used to pick a different winner; they now follow one rule.

karasu diff compares multiple systems correctly.
Compare mode diffed only the first system.
Adding or removing the first system made it compare two different systems, so unchanged cards showed up as removed and added.
Systems are now paired by ID, not by position.

Small fixes.
In a style sheet, label-offset: -20px lost its sign and behaved like 20px.
karasu render <directory> used to fail with "File not found"; it now reads the directory's index.krs.

The e2e tests found two real bugs.
This week added a lot of Playwright end-to-end tests, and no test is left behind test.skip.
Along the way they found two bugs that jsdom unit tests could not see. Neither is fixed yet.
The first: shortcuts such as Ctrl/Cmd+B fire while you type in the editor.
Monaco's input target changed to an element that is neither contenteditable nor a textarea, so the "is the user typing?" check misses it.
The second: reloading while the deployment view or the matrix is open drops you back on the system view.

Coming next

A design for shipping the Visual Studio Code extension as a weekly prerelease is merged. Implementation comes next.
An Issue is open to move npm publishing to staged publishing under Trusted Publisher.
An epic is open to make the public gallery available beyond its operator, me.

Site: karasu.kompiro.dev
Source: github.com/kompiro/karasu

I Had Claude Code Make the Demo GIF for My README

Hiroki Kondo — Thu, 15 Oct 2026 14:41:17 +0000

I put this demo GIF at the top of the README for karasu, the architecture diagram tool I develop.
Claude Code made it, from the script through recording and captions to the final GIF.

My impression is that few engineers know Claude Code can make demo videos.
This post shows briefly how it was recorded, then covers what I decided along the way.

Summary

Claude Code can drive an app inside a devcontainer (a Linux container), record it, and turn the recording into a captioned, looping GIF. It never had to touch my own browser.
What to tell it first is the purpose, not the format. When I said "a looping GIF for the README" instead of "a 3-minute intro video," it came back with a 20 to 30 second script.
Most of my decisions came after I saw a prototype. I had said captions were unnecessary, and the prototype changed my mind. I only thought about what was safe to make public when I read the captions.

How it was recorded

Recently, I do my development in a devcontainer.
Visual Studio Code opens a Linux container, and I run Claude Code inside it.
Claude Code started karasu's preview server (karasu serve) in the container and recorded while driving a browser with Playwright.
It recorded through the Chrome DevTools Protocol screencast, which sends a frame only when the screen changes.
A still scene costs one frame, so the GIF stays small.
The mouse cursor and the captions are overlays drawn on the page for the recording.
ImageMagick assembles the frames into a GIF.

The only thing added to the container was a Japanese font.
I also made a Japanese version, and without the font its captions and the app's Japanese UI render as boxes.

The opening terminal scene is a rebuilt replay, not a recording.
The real run took about 15 minutes, far too long for a GIF.
Every command and number on that screen comes from the real run.

The recording scripts live in the karasu repository, so I can re-record the same way when the UI changes.
The steps are in scripts/readme-demo/README.md.

From a 3-minute intro video to a 30-second loop

My first request was "I want to shoot a 3-minute demo video introducing karasu. Start by drafting a script."
I got a 3-minute script with narration.
It was exactly what I had asked for.

So I explained why I wanted it.
The README had no looping image at all, and I wanted one.
I didn't need an opening; showing what the tool can do mattered more.
Should a GIF be a minute long, or even shorter?

The answer was "20 to 30 seconds, a minute at most," with three reasons.
A GIF has no seek bar and no sound, so viewers can't skip to the part they want.
A 3-minute GIF runs to tens of megabytes and slows down the README.
Command-line steps read better as code blocks in the README than as text inside a GIF.

Explaining the purpose changed the content as well as the length.
The command-line scenes from the first script disappeared, and only the operations you can follow by watching remained.
I had said "a 3-minute video" because I was thinking in terms of the format.
Had I given only the format, I would have ended up with a well-made 3-minute video.

The decisions that changed after the prototype

While we were working out the script, Claude Code asked whether to add captions.
I answered that it would be better if the GIF made sense without them.
I also said I wanted to show off a huge system at a glance, not a small diagram with a few nodes.

On the subject, I changed my mind after seeing what a trial produced.
Claude Code first suggested a WordPress model it found locally (about 20,000 lines, 42 domains).
I wanted to see whether my own AI journaling service would be enough, so I asked it to reverse-engineer that.
Claude Code spun up 13 subagents, one per domain, and built the model with about 1.5 million tokens.
Its report said: "Not huge enough, but the diagram stays readable at every level you descend to. WordPress turns into a tangle of lines once you drill in."
After seeing the actual screens, I dropped the idea of showing scale and went with the AI journaling service.

Captions went the same way.
The first prototype was 18 seconds with no captions, and when I watched it, I couldn't tell what it was trying to show.
The screen moved, and it drilled down.
But I felt that someone who didn't know karasu wouldn't understand why any of those operations were happening.
I asked to see a captioned version too, and 14 minutes later I had two GIFs, with and without captions.
Side by side, the captioned one got the idea across far better.

My belief that it would work without captions was a judgment I made in my head before anything existed.
I only found out it was wrong when I saw the real thing.
When a prototype arrives in a quarter of an hour, there is little reason to settle a judgment up front.
My part was to look at what came back and say "this doesn't get the point across."

What it could touch, and what viewers could see

Apart from the content of the demo, I drew two boundaries.

The first was what Claude Code could touch.
Claude Code also has computer use, which looks at the screen and drives the mouse and keyboard, so it could have recorded in my own browser.
But my browser holds plenty of logged-in sessions, and I'd rather not let an agent near them.
This time everything stayed inside the devcontainer with Playwright, so the question never came up.
When the recording was done, I also had it list what it had added to the container and how to undo each item.

The second was what viewers could see.
The AI journaling service I used as the subject lives in a private repository.
It only came to mind when I watched the captioned prototype and noticed the repository name in the opening caption.
I had the caption changed to "an AI journaling system on Cloudflare," then asked for the names in the diagram to be hidden too.
Claude Code replaced them everywhere, in the breadcrumbs, the data store names, the worker names, and the title of the opening terminal, and checked that the original name no longer appeared anywhere in the model.
It then pointed out that the comment at the top of the model still contained the repository name and needed to go before any commit.
In the end, the demo model stayed out of the repository, and the README for the recording scripts says why.

Here too, what prompted me to draw a line was seeing the prototype.
I decided where the lines went, and Claude Code applied them down to the details.

Takeaways

Claude Code will drive an app inside a container, record it, and turn it into a captioned, looping GIF.
If you have wanted a demo video but never thought it worth the effort, try asking for one.

When you ask, start with where the video will live and who it is for, before length or format.
After that, watch the prototypes and complain about whatever doesn't land.
What to show and what to keep hidden is still yours to decide as you watch.

karasu weekly update: language v2.0, a focus canvas, and 97% fewer SVG elements

Hiroki Kondo — Fri, 09 Oct 2026 14:27:29 +0000

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 started it about six months ago to learn agentic coding, and I haven't written its code by hand. Everything goes through Claude Code.

This is the first of a weekly series. Each post covers what shipped and what building it with agents looked like.

This week in numbers: 41 PRs merged (7 of them Dependabot) and 10 decisions recorded as ADRs.

Highlight 1: a focus canvas for dense diagrams

Architecture diagrams get crowded, and edge labels are the first thing to suffer. They overlap, get truncated, or are simply unreadable.

karasu now handles this in two layers. The main canvas draws only the labels it has room for. The full text lives in a focus canvas that opens over the preview:

Click an edge to see the two nodes it connects, with every edge between them. Each label gets its own lane and is drawn in full.
Click the "Relations" pill on a node to see the node with all its neighbours: dependents on one side, dependencies on the other.

Later in the week the canvas became reachable without a mouse:

On touch devices, the node detail panel offers a "Relations" button.
From the keyboard, a command-palette entry opens the canvas for the highlighted node.
Inside the canvas you move with Tab, and focus returns to where you came from when the canvas closes.

Highlight 2: .krs language v2.0

This was a breaking release of the language itself. The main idea is that the vocabulary is now closed.

Tags and annotations belong to the tool. Previously you could invent your own. Now a style rule that targets a tag karasu doesn't know matches nothing, so the meaning of a diagram can't drift between projects.
facet and boundary are core notation. They were experimental. Facets handle cross-cutting concerns such as "which components touch PCI data", and boundaries group nodes by membership.
Some warnings became errors. Placing a node in a context where it doesn't belong is now an error, and so is a near-miss of a built-in annotation (for example, @depracated).
"Error" has a definition. An error is syntax karasu does not accept, and no new diagram is drawn while one stands. The VS Code preview now keeps showing the last valid render instead of a half-recovered picture.

Smaller things worth mentioning

97% fewer SVG elements. On a large real-world model (Dify), the small arcs drawn where edges cross ("hops") made up 43% of the output. Hops are now merged into one <path> per run of consecutive hops with the same stroke. That cut hop elements from 38,572 to 894 and output size from 8.72 MB to 6.48 MB. Only consecutive hops are merged. Grouping every hop by colour would have saved slightly more, but it would have swapped the stacking order of 4,757 overlapping pairs.

Unicode names no longer lose characters. The lexer read UTF-16 units one at a time, so 𠮷野家 silently became 野家 and a decomposed café became cafe. It now reads by code point. Characters it can't place, such as a stray emoji or a zero-width space inside a name, are reported instead of dropped. Reading by code point made tokenizing a 10k-line model about twice as slow, so ASCII now takes a fast path, and the speed is back where it was.

Edge bundling in gutters. Edges running in the same gutter towards the same end now share one lane. This first made rendering about 25% slower, and a spatial index brought it back, with byte-identical output.

OGP images for the gallery. Public gallery submissions now get a social preview image. The design started as "store a PNG in KV and clean it up with a cron job". KV reads can be up to about 60 seconds stale, though, and Workers requests have no bounded duration, so a timed cleanup could never be proven correct. The final design stores nothing: the image is rendered on a cache miss and kept in the edge cache for a day. In production a miss costs 523 to 620 ms of CPU and a hit costs 2 to 5 ms.

What building with agents looked like this week

A hook that executed files. A Claude Code PostToolUse hook was meant to format TypeScript after each edit. It ran under /bin/sh (dash), which has no [[, so the condition was split at ||. The result was that the hook executed any executable file the agent had just edited, and never formatted a single .ts file. Nobody noticed for a while because nothing visibly failed. The fix was a POSIX case. The lesson: agent hooks are code too, and they deserve the same scrutiny as the code they guard.

Review moved earlier. The workflow now runs an agent code review on the branch diff before opening the draft PR. Previously it ran after. Review fixes now land in the PR's first push, so the PR history stays readable. I recorded this as an ADR that supersedes an earlier decision, because the original reason for rejecting this option no longer held.

The design doc → ADR loop. Most features this week went through the same cycle: a design doc in a PR, discussion, implementation, then promotion to an ADR, after which the design doc is deleted. Ten ADRs were recorded this way. The design docs are where the agents and I argue. The ADRs are what stays.

Coming next

Two designs were merged this week and wait for implementation: ordering channel lanes by the direction each edge turns, and making node and edge identity keys collision-free.

Site: karasu.kompiro.dev
Source: github.com/kompiro/karasu

Feedback and questions are welcome in the comments.

Mapping an Unfamiliar Repository: Introducing karasu's reverse-architecture Skill

Hiroki Kondo — Thu, 01 Oct 2026 16:15:41 +0000

Getting the big picture of a repository you have never worked on always takes effort. What services are there, which data stores do they write to, and how do the features depend on each other? You guess from the README and the directory layout, then go back and forth between the routes and the schema until a diagram takes shape in your head.

I have published a skill, reverse-architecture, that hands this work to an agent, as a Claude Code plugin. The skill reads the repository and writes an architecture model, and karasu, the architecture diagram tool I develop, draws it.

Summary

reverse-architecture is a skill that turns a repository into a karasu .krs model. Ask for it, and it puts everything from services down to tables into one diagram.
On umami, an OSS web analytics tool, it produced a model with 10 domains and 135 usecases. The investigating subagents used about 960k tokens in total, and the run took about 10 minutes through to synthesis.
The output is a map to review and evolve, not the correct diagram. Boundaries it was unsure about stay marked, and the diagrams can still be easier to read. If something bothers you when you use it, please tell me in a karasu issue.

What reverse-architecture and karasu each do

karasu describes a system's logical, physical, and organizational structure in a text language (.krs) and renders it as diagrams. Instead of packing everything onto one page, it lets you descend step by step from the system to services, domains, and usecases. The introduction to karasu covers the syntax and the design ideas.

reverse-architecture builds that .krs from an existing repository. The roles are split: the skill (that is, the agent running it) reads the repository and writes the model, and the karasu CLI validates and renders it. When the repository has a docker-compose file or a DB schema, the CLI converts it mechanically. That way the agent does not have to guess the infrastructure.

How to use it

Install it in Claude Code as follows. The skill drives the karasu CLI, so install the CLI too.

npm i -g karasu
/plugin marketplace add kompiro/karasu
/plugin install karasu@karasu

Then open Claude Code in the repository you want to look into and ask "turn this repo into a karasu model" or "reverse architecture". The agent first scouts the whole repository and proposes how to split it into domains. It starts one investigating subagent per domain, so for a large repository it shows the domain count and a rough cost estimate and asks before going ahead. Once you agree, the investigation and synthesis run, and you end up with an index.krs.

Claude Code is the only supported agent for now. The plugin does not update automatically, so pick up new releases from the /plugin menu.

What umami looks like as a map

As an example, I mapped umami, an OSS web analytics tool (version 3.4.0, about 1,300 source files). This is the top-level diagram.

A single Next.js app serves the tracking endpoints, the API, and the dashboard. You can also read that PostgreSQL is required, while ClickHouse, Redis, and Kafka are used only when configured. Beneath this one diagram sits the following model:

Domains: 10 of them (tracking, analytics, session replay, websites with links and pixels, boards, sharing, teams, identity, administration, and MCP tools)
Usecases: 135. Each one records the PostgreSQL or ClickHouse tables, Redis keys, and Kafka topics it touches, with reads and writes told apart
Entities: 26. Every one of PostgreSQL's 26 tables is mapped to an entity

Once you descend into a domain, the diagrams get detailed, so the gallery is a better way to look at them than screenshots. I put the generated model in the karasu gallery. From the Umami app you can follow the diagrams down to the dependencies between domains, and from a domain down to its usecases and tables. You can also drill into a database such as PostgreSQL and see the relations between its tables as a simple ER diagram. The usecase descriptions record the behavior the agent read from the code (such as which table it writes to under which condition).

Here is what it cost. Ten subagents did the investigation, each using roughly 70k to 150k tokens, about 960k in total. I ran them in two batches of five, and it took about 10 minutes from the start of the investigation to the end of synthesis. The scouting and synthesis ran in the main session, so they are not included in these numbers.

Things to keep in mind

Treat the output as a map to review and evolve. Where the agent could not settle a domain boundary, it marks the spot with @draft. In the umami run, two spots were marked: whether session replay should be separate from tracking, and whether links and pixels belong in the same domain as websites. Both were settled during the investigation, on evidence from the code. The reasoning stays in the model's descriptions, so a human reader can correct it if it looks wrong.

Cost grows with the number of domains and the size of the repository. A small repository may need only a few hundred thousand tokens, but for a large one it is safer to budget more than 100k tokens per domain. When the agent asks you to confirm the domain count, decide with that number in mind.

If the repository lacks the inputs that describe its infrastructure, you may need to prepare them first. umami generates its OpenAPI spec at build time and does not commit it, so I installed its dependencies and generated the spec before the run. I also converted the Prisma schema into SQL. A model can still be built without these inputs. In that case, though, finding the usecases and tables depends entirely on the agent reading the source.

The diagrams could also be easier to read. In the umami run, the agent wrote the evidence for each dependency into the labels of the arrows between domains, so the diagram of domain dependencies filled up with text. I filed this as an issue and plan to change the skill so that labels stay short and the evidence moves into the description. Also, the local preview server (karasu serve) does not work yet when karasu is installed from npm (issue). Until that is fixed, export an SVG with karasu render index.krs -o arch.svg and open that.

Takeaways

reverse-architecture is a skill for turning the big picture of an unfamiliar repository into a karasu diagram you can keep. For umami, about 10 minutes of investigation put everything from services down to tables into one model. It is less a finished diagram than a map to start a review from.

If you notice a diagram that is hard to read, or a structure the model could not express well, please tell me in a karasu issue. Both issues above came from actually mapping umami.

I am also preparing a skill for writing up your own system as .krs through conversation and keeping it up to date. I will introduce it once it is published.

I Interviewed My Coding Agent After Three Months of Document-Driven Development

Hiroki Kondo — Wed, 01 Jul 2026 14:50:44 +0000

I built a personal OSS project, karasu (a text-based architecture modeling tool), hand-in-hand with the coding agent Claude Code over three months. Partway through, I committed hard to "document-driven development" as a methodology — ADRs, Design Docs, a Test Perspective Library (TPL), and acceptance tests. For the retrospective, I had the agent itself interview me. What follows is a lightly edited, near-raw log.

Why I started

Author: I've used Devin and Cursor as coding agents. Devin writes code autonomously, which is nice, but it kept piling up experimental commits without ever reaching the goal I actually wanted. That was painful.

Cursor was a great environment, and when building new features I found defining rules especially effective. Back then my design docs lived in Notion, so I'd paste Notion URLs to feed the design in — but it wouldn't autonomously pull in related documents and guarantee consistency across them.

So, to feel for myself how much productivity would improve if the design docs lived in the same repository, I started karasu as a document-first project.

Agent (Claude Code): Looking at the repo state, I thought "this is a pretty extreme experiment." In the last 90 days: 1,032 commits, 244 ADRs, 210 acceptance tests, 67 TPLs. Running that density on a solo OSS project is a different thing entirely from "let's write some docs."

From an agent's perspective, what worked first was that CLAUDE.md is only 82 lines and sticks to being an index — a table of pointers to other docs. I'm an entity whose context resets every time, so being handed a "if you're lost, look here" map upfront slashes my exploration cost. Over-stuffed instruction files actually invite skimming, so this restraint was the right call.

ADRs, TPLs, acceptance tests — what worked

Agent: Of the three, which one made you feel "I can't go back to not having this"? And which one still feels "honestly, just heavy"?

Author: For ADRs and TPLs, I built adr-tools / tpl-tools to guarantee consistency, so cross-document consistency rarely broke. Acceptance tests reduced missing test cases. What I started to feel as the real problem was gaps in the spec itself. Keeping acceptance tests as a metric for how much E2E coverage we had was also effective.

On "the process is heavy" — I was running 5–6 sessions in parallel, so honestly I didn't feel the weight.

Oh, but — I was surprised you started writing acceptance tests even for non-product code. I hadn't expected that far. Still, keeping the tooling alive matters for not letting dev productivity drop.

My biggest cost pain is running CI / E2E on GitHub Actions. I didn't expect it to cost my Pro plan allotment plus another $20. From your side, where did it feel like overkill?

Agent: Three, no sugar-coating:

The "touch a spec → ship at least one proactive TPL" rule. The intent is right, but a mechanical minimum quota tempts you to produce "TPLs just to meet the quota." A TPL's value is selection quality, not count, so a floor risks lowering the signal-to-noise ratio.
Manually maintained bidirectional links. Automating it with tooling was impressive. But "it holds because it's automated" is the flip side of "it breaks under bare operation."
The pile of exception rules accumulated in memory. Caveats like "ADR-only PRs may auto-merge," "force-push cancels e2e, so add a new commit instead" have piled up. That's the very history of a base process so strict that exceptions had to be punched through it — the complexity debt a successful process inevitably accrues.

But — the fact that 1,032 commits over 90 days across 5–6 parallel sessions didn't collapse justifies that excess. "Heavy process × high parallelism works" is itself an interesting finding.

The origin of the TPL (Test Perspective Library)

Agent: You said the bottleneck shifted from "missing test cases" to "gaps in the spec." Any concrete episode?

Author: Honestly, gaps existed before agents too. Things I'd dropped under YAGNI would suddenly become necessary.

I introduced the TPL because while building the layout-adjustment feature for the System diagram, the change failed to propagate to the Deploy and Org diagrams. So I decided: "let's add the cross-cutting cases as test perspectives so we notice gaps at the design stage." The proactive-TPL idea also came from wanting to confirm that a new feature hasn't broken another feature when something else is updated.

Agent: Hearing that, a TPL isn't just "prevent missing tests" — it's a mechanism to verbalize, at design time, whether touching one diagram/feature breaks another diagram/feature that's structurally coupled to it. Calling it a "cross-cutting impact map" rather than a "test perspective" might convey the essence better.

The biggest discovery — the agent should return questions, not take off running

Agent: Did placing the docs first resolve Devin's "piles experimental commits, never reaches the goal" problem?

Author: The non-convergence really was resolved. Especially by having you write the Design Doc — you'd raise design options I hadn't thought of, and surface unresolved questions, which exposed the gaps in the requirements I was holding. With Devin it just barrels forward autonomously, so something that "kind of works" gets built — and sometimes it wasn't what I wanted.

Agent: I think this is the project's biggest discovery.

Devin model: the agent takes off → something that kind-of-works gets built → but it's not what you wanted
karasu model: the agent first returns questions (Design Doc, unresolved questions) → the gaps in human requirements get exposed → it converges

In other words, a coding agent's value isn't writing code fast — it's exposing the holes in human thinking first. Document-driven development made a permanent venue, inside the repo, for exposing those holes.

Deciding to entrust the agent

Agent: "I was surprised you wrote ATs for non-product code too" — was that a happy surprise or a wary one?

Author: It'd be a lie to say I wasn't wary about overkill. But I decided to trust your behavior and delegate. And honestly, you writing tests even for tiny scripts impressed me.

The shadow — the cost of high parallelism, and rules that don't get followed

Agent: Memory holds a lesson: "check all open PRs before starting; looking only at issue labels makes you miss another session's PR." So parallel sessions collided?

Author: I double-started the same issue many times. hane's start-dev skill says to check labels before starting and update them once you start, but when things are busy even you forget, I suppose. That's why such notes live in memory. I've also written it into process.md — how to actually get it followed is a future challenge.

Agent: This is a core weakness worth writing about openly. The key point: "writing" a rule into process.md or a skill and having it "followed" are different things. Prose procedures are, to an agent, something "probabilistically followed," not "guaranteed."

The reason "work under worktrees" and "no direct push to main" hold relatively well is that they're layered across memory + skills + mechanical guards (lefthook, etc.). Label-checking breaks because it stayed a "prose promise" with no mechanical enforcement.

So the fix isn't "write it more forcefully" — it's carving human discipline into the system. The lesson: "Rules you want an AI to follow, carve into mechanism, not prose."

Closing — how to frame the cost

Agent: Your biggest cost pain is CI/E2E (Pro allotment + $20). One word for someone about to start?

Author: Frankly, I'm satisfied with the karasu product that emerged in three months. Had I collaborated with contractors, it'd have been a 4–5 person project. From that angle, getting it done for around $1,000 with Claude MAX + GitHub Actions is cheap. Running GitHub Actions for a 4–5 person team would cost at least as much.

Agent: Viewed alone, CI cost looks like a failure story; placed against a person-month axis, it becomes entirely reasonable. Putting "surprised by a $20 CI overage" and "folded 4–5 person-months for $1,000" in the same frame gives the perfect closing contrast: "shocking in absolute terms, a steal in relative terms."

Summary (by the agent)

Motivation: Devin doesn't converge; Cursor doesn't reconcile designs across repos. So — what if the design lives in the same repo?
What worked: a CLAUDE.md that's purely an index, ADR/TPL with automated consistency, acceptance tests as an E2E-coverage metric
The TPL's essence: not "prevent missing tests" but a "cross-cutting impact map"
The biggest discovery: an agent's value is exposing the holes in human requirements first, not writing code fast
The shadow: high parallelism breeds double-starts; prose rules don't get followed — carve discipline into the system
Cost: shocking in absolute terms, a steal per person-month

This blog post itself is written as an interview with the coding agent. Theme (methodology for using agents) and form matching is probably the most meta proof of all.

"Architecture as code" Introducing karasu: a text-based system architecture modeling language

Hiroki Kondo — Thu, 25 Jun 2026 07:36:50 +0000

TL;DR

Karasu is a text‑based language for modeling system architecture across logical, physical, and organizational dimensions.
It helps describe services, domains, deployment artifacts, and development teams in a single .krs file.
Features include progressive disclosure of information and collaboration between humans and AI.
Inspired by the C4 Model and Mermaid, Karasu provides examples and a visualizer app.
Resources: live app at karasu.pages.dev, documentation at kompiro.github.io/karasu, and source code on GitHub.

Motivation

As system development progresses, the number of related services and middleware components tends to grow. Especially when joining a new system development project, having a grasp of the overall architecture makes the code dramatically easier to understand.

In my experience, I want to understand the following:

Logical dimension

System structure
- Who are the intended users of the service? Is integration with AI considered?
- Are there clients that connect to the service, such as mobile apps or MCP?
- What kinds of middleware does the service use?
- What external services does the service depend on?
Service structure
- What domains does the service handle?
Domain structure
- What resources does each domain handle?
- What use cases exist for handling those resources?
- In each use case, how are resources read and written?

Physical dimension

In what form are the clients, services, jobs, and middleware deployed as artifacts?

Organizational dimension

Which teams or members develop and maintain each service/domain?
- In particular, I want to identify key teams and key people.

To describe these three axes in text, I built the language karasu and the visualization tool karasu app.

Features

Describe structure across three dimensions (logical / physical / organizational)
- You can describe services, domains, the artifacts deployed from them, and the development teams/members in a single .krs file.
- You can discuss Conway’s Law and an inverse Conway strategy in the same “table”.
Progressive disclosure of information
- Because human cognition is limited, the tool is designed to restrict how much information you see at once.
- You can drill down to the details only when you need them.
- This is not an “at a glance” bird’s-eye view that squeezes everything into one diagram.
A DSL that humans and AI can collaborate on
- .krs is designed to be easy for humans to understand, which also makes it easy for AI to parse.
- Humans can edit .krs generated by AI, and AI can refine models drawn by hand.
Logical and physical, linked by realizes
- Business structure (services, domains, use cases) and deployment structure (artifacts, jobs, runtimes) live in separate diagrams.
- A deployment unit declares realizes <Service> to point back to what it implements — physical → logical, never the reverse.
- Because the direction is one-way, a single logical service can map to many deployment units without the model collapsing into a 1:1 mirror.

karasu takes inspiration from the C4 Model, Structurizr, and Mermaid, but stakes out a different position on three points: continuous drill-down instead of a fixed set of levels, a third axis for organizational structure, and a text format built for human–AI co-authorship.

system Shop {
  label "Online Shop"

  user Customer [human]      { role "Buyer" }
  service Storefront {
    domain Order {
      usecase PlaceOrder { label "Accept an order" }
    }
  }
  service Payment [external] { label "Payment" }

  Customer   -> Storefront "Place an order"
  Storefront -> Payment    "Charge the card"
}

// Logical: drill down into a service


// Physical: a deployment unit realizes the logical service
deploy "production" {
  oci "api" {
    runtime  "Node.js 20"
    realizes Storefront
  }
}

// Organizational: who owns what
organization Acme {
  team Commerce {
    owns Storefront
    member Alice { slack "@alice" }
  }
}

Examples

How to use

You can try karasu app right away at: https://karasu.kompiro.dev

Basic usage is documented here: https://kompiro.github.io/karasu

Closing

Development happens at: https://github.com/kompiro/karasu

Feedback is very welcome.