DEV Community: Hiroki Kondo

From requests to mechanisms: a week of risk-tiered review and a gh wrapper for agent PRs (karasu weekly)

Hiroki Kondo — Sun, 01 Nov 2026 00:13:52 +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 fourth weekly update.
It covers changes merged from October 25 to 31.
This time I start with what I learned building with agents, then go through what shipped.

This week in numbers: 70 PRs merged (12 of them Dependabot) and 18 decisions recorded as ADRs.
15 of the ADRs came in ADR-only PRs, and 3 were added inside implementation PRs.
On October 25 the monthly release train left for the first time, shipping karasu 0.10.0 and the Visual Studio Code extension 0.5.0.

Lessons from building with agents this week

Risk tiers that set how deep a review goes are now running.
Last week I wrote that the design was merged and the implementation was still to come; it landed on October 27.
Each PR falls into one of four tiers by the paths it touches.

High: changes to the review machinery itself, CI, lockfiles, and the like. CodeRabbit reviews until no Critical or Major findings remain, and I read the diff.
Design: design documents. CodeRabbit reviews once when the PR leaves draft, and I read it too.
Medium: no CodeRabbit. I decide from the local review record.
Low: adding an ADR, or only adding tests. If the local review record and CI pass, I merge without reading.

Every tier except High puts a local review record in the PR body.
It's a table of who reviewed and, for each finding, whether it was fixed or declined.
A required check confirms the record is for the PR's latest commit.

This week 76 PRs were closed and 70 of them merged (a 92% merge rate).
Of the 50 merged with a tier label, 18 were High, 10 Design, 12 Medium, and 10 Low.
I merged the 10 Low PRs without reading the diff, so the auto-merge rate is 20%.
9 of the 10 were ADR PRs, and the other was the monthly review of test perspectives.
9 were merged within 3 minutes of leaving draft.
The 22 Medium and Low PRs were merged without going through CodeRabbit.

High is common because much of this week's work touched the review and process machinery itself.
Changes to that machinery are set to land in High.
It'll take a few more weeks of counting to see how the tiers split in everyday development.

While counting, I found 4 High PRs that CodeRabbit never reviewed.
I haven't checked yet whether they slipped through or were left out for a reason.
I'll look into it before the next update.

Over the past week I came across several talks and posts on not reading code (all in Japanese).

Minodriven's talk "Should we read AI-generated code? Abstraction design and code quality assurance" says it isn't the case that you never need to read code at all. It then argues that design by contract, isolating side effects, and abstraction reduce the need to read. It rephrases being able to use something without caring about its insides as "trusting" it.
Yosuke Furukawa's talk "In an age when AI writes our code, what do we verify?" says it isn't a binary of reading or not reading. People decide what the criteria are, and checking whether they're met can be left to AI.
nrs's post on Zenn gives two preconditions for a "no look merge," merging a PR without a person reading the code: quality checks good enough to stand in for human review, and agreement within the organization.
Yohei Watanabe's "Agentic Coding and harness engineering" puts the key point in deciding what stays a "request" and what moves to a mechanical check.

I never kept reading all the code of the systems I build at work.
Even in reviews, I don't read much of the surrounding code.
Since I started using AI, I have it check the surrounding situation while I read the parts that concern me in depth.
The parts that don't concern me, I now skim.
I think I can do that because I trust AI about as much as a capable contractor.

The trust I mean is close to Minodriven's "using it without caring about its insides."
But what I want to get right is less the code itself than the ground the code is written on.
Even a capable contractor, not knowing the team's agreements and not following its steps, writes code full of places that concern me.
Agents are the same.
If the material to work without hesitation arrives before writing starts, and the steps are followed while writing, I should be able to read less.
In karasu, I set up those two like this.

Before writing: leave the agent less room to get lost.
In karasu, a large change merges a design document first and is implemented after.
This week's risk tiers (#3358 → #3365) and the docs/process.md split described in this section (#3394 → #3402) both went in that order.
Past decisions are recorded as ADRs, and a step to check them before designing is in the skills.

On top of that, I cut down how much has to be read.
docs/process.md is the development guide every session reads in full first.
It had grown to 46 KB.
When all of it is read every time, the step needed right now gets buried in the others.
So I kept only the flow that's always needed, at 14,876 bytes, and moved the rest into topic files under docs/process/.
The guide has an index that says when to read each file.
For example, the review tiers and how to write the record are read in the step just before a PR leaves draft.
I measured how far this read-it-when-needed approach (Progressive Disclosure) reaches current models in a September post.
Then, path-scoped rules that load when a file is opened almost never fired, while steps written into skills got through.
This split doesn't rely on loading on file open either.
The always-read guide names which file to read at which step.

While writing: move "requests" into mechanisms.
I had shrunk docs/process.md to 12.7 KB once before.
It had grown back to 46 KB.
Tidying by hand was undone as steps were added.
This time I added pnpm lint:process-index, which checks the index-to-file mapping, the links, and the guide's size in lefthook and CI.

Last week I wrote that a check refusing gh pr ready before the local review was in a PR. That's merged too.
The first version was a Claude Code hook that inspected the text of the command about to run.
But each CodeRabbit review found another way around it: gh after a heredoc, gh behind env -u or timeout -s, gh through eval or xargs.
The command text can't tell you what will finally run.
After 20 CodeRabbit reviews, it was rebuilt as a gh wrapper placed first on the session's PATH, deciding from the arguments gh actually receives.

What wasn't followed when it was written in the guide, I'm moving into lint, the gh wrapper, and required checks.
That's Watanabe's move from "request" to mechanical check.

Low's auto-merge sits on top of these two.
I'll keep counting the merge rate and the auto-merge rate in the coming weeks.
I also plan to track whether bugs later turn up in PRs merged without reading.
I'll write about "ground that lets me read less" in a separate post.

Fold a video into one image, and the agent can check it

The two demo videos in last week's update were recorded by an agent.
This week added the skill behind them (demo-video) and pnpm demo-video:record <scenario> --lang en|ja.

It works like this:

Run the real karasu app (through karasu serve), or Visual Studio Code with the extension, on an Xvfb virtual display.
The scenario moves the pointer, clicks, and types into the editor, while ffmpeg records the whole screen.
Join title cards at the start and end, lay a caption over each scene, and write a 1920×1080 MP4.

Captions and title cards are kept per language, so one scenario produces both an English and a Japanese video.
Visual Studio Code is driven over CDP (Chrome DevTools Protocol).
ExTester, a UI testing tool for Visual Studio Code extensions, isn't used, because its ChromeDriver doesn't run in the arm64 devcontainer.

Once the video is made, the agent looks at it.
The agent can open images with Read, but not videos.
So the recording is cut into a frame every 3 seconds and tiled into one image (a contact sheet), which the agent opens with Read.
The skill's end state says: don't report "done" without having looked at what's in the video.

Below is last week's serve-import video (71 seconds), cut every 3 seconds.

The cards are blue up to the first frame of the second row and green in the second frame.
The code panel at the top right of that same frame shows the diff that changed the colors in theme.krs.style.
A single frame with the green cards only tells you the cards are green.
Laid side by side, the frames show the change: the style sheet was saved and the view was redrawn.
The caption text, and the flow from the Share dialog to the public app opening, can also be read from this one image.

The skill also has a table of pitfalls hit while recording.
It has rows like "a 'Do you want to save your changes?' prompt shows at the end of the video", "right-clicking an edge opens another edge's menu", and "a translation bar appears".
None of these show up in an exit code or a log; they show up only on screen.
The save prompt appears when Visual Studio Code closes.
A screenshot taken just before closing wouldn't catch it.

I brought the same practice to fukurou.
In the repository where I write this update, I added ffmpeg to the devcontainer and rewrote the weekly-update steps.
Until then, the session couldn't see inside the videos, so I checked that the text matched them myself.
Now the session builds the contact sheet, opens it, and checks for itself.
The image above was made with those steps.
Looking back, the only reason it couldn't check before was that ffmpeg wasn't installed.

I've been writing "the agent looks at the video," but what it actually opens is one still image.
"Looking" here means reading time folded into a single image.
Even so, it can read changes over the course of a video that a single screenshot can't show.
Reading a screen recording of a bug the same way might help reproduce it or guess at the cause.
But I don't yet have a karasu bug that was found or fixed from a video.
The next time a screen-related bug comes in, I'll start by handing the recording to the agent.

Ship on a schedule, and make sure "unchanged" is decidable before skipping

On October 25 the monthly release train left for the first time.
On the last Sunday of each month, it ships whatever is unreleased.
That morning, a branch with the version bumps and a tracking Issue open automatically.
All I do is open the PR from the Issue's link, read the CHANGELOG, and merge.

Package	From	To
`karasu` (CLI)	0.9.0	0.10.0
`@karasu-tools/core`	0.4.0	0.4.1
`karasu-vscode` (Visual Studio Code extension)	0.4.0	0.5.0
`karasu-skills`	0.2.0	0.2.1

It ships 16 pending changesets.
The first train ran without stopping, all the way to npm and the Visual Studio Code Marketplace.
It was the first time the Marketplace publish rode the train.
Both highlights from last week (import resolution in karasu serve, and the Visual Studio Code preview running the app's viewer) arrived on this train.
The .krs language is unchanged.
One change in .krs.style, though: a stray - or non-ASCII character that isn't part of any name used to be dropped silently.
Now it's an error.
Lines you thought were taking effect but weren't will now show up.

The Visual Studio Code extension also gets a weekly prerelease.
With only a monthly train, a change merged to main can take up to a month to reach the extension.
So every Wednesday the extension is built from the tip of main and published to the Marketplace prerelease channel.
The version carries the date: <stable major>.<minor>.<YYYYMMDDNN>.
A week whose contents match the previous version is skipped.

"The contents match" means every file in the .vsix is the same, except for the version number in package.json.
I checked beforehand that this can be decided.
I compared the Marketplace 0.5.0 .vsix with one built locally from the same commit, and every file matched except THIRD_PARTY_NOTICES.md.
That one file differs only in the platform of a bundled binary (linux-arm64 locally, linux-x64 on CI).
Two CI builds should match.
To use it, switch to the prerelease version on the extension's page in the Extensions view.
The first one is due on Wednesday, November 4.

Other changes this week

Edge labels no longer sit on frame borders.
Drill-down and group borders are now obstacles for labels.
Across four models and examples/en (5,061 cases), labels crossed by a border went from 132 to 0, and labels pushed to the far side of a frame went from 57 to 0.
In exchange, labels omitted under auto went up from 1,745 to 1,784.

Edges no longer cut through cards when a route exists.
These are edges between cards in the same row.
The cause wasn't the route: all five candidate spots where an edge leaves the card were taken.
As a last resort, it now searches the whole side of the card for a spot.
Edges cutting through a card went from 4 to 1.

Style diagnostics and rendering agree now.
The valid ranges for .krs.style values were written in three places, and they disagreed.
A diagnostic would say a value was ignored while the value got clamped or drawn anyway.
The ranges now live only in the schema, and a declaration a diagnostic rejects isn't used for rendering either.
So rendering changes too.
An out-of-range label-position is dropped instead of clamped.
A non-zero length without a unit, a wrong unit, a bad hex color, or a color name with the wrong case (White) isn't drawn.
An empty value like color: ; makes karasu render fail.
This ships on the next train (November 29).

karasu serve returned what a symlink pointed to.
Say the served directory held a symlink pointing outside it (like notes.krs -> ~/.ssh/id_rsa).
Then /api/file/:name returned the contents of the link's target.
This is in the released 0.10.0.
Paths are now resolved to the real file, and nothing outside the served directory is returned.
/api/watch also stopped sending Access-Control-Allow-Origin: *.
The fix ships on the next train.
Until then, it's safer not to run karasu serve in a directory with symlinks that point outside it.

Smaller changes.
analyze() wrote a cycle flag into the model it was given, so the same model rendered differently before and after analyze(). Cycles are now computed when the model is built, and analyze() only reads.
Package sources now have a 600-line limit per file. The 33 files over it are pinned at their current length, and the pin goes down as they shrink. Splitting svg-renderer.ts (2,965 lines), layout.ts (1,719 lines), and view-extract.ts (2,042 lines) has started.
GitHub Actions versions are now pinned with actions.lock (GA on October 28). It also pins actions that workflows use indirectly.

Coming next

The first weekly prerelease of the Visual Studio Code extension is due on Wednesday, November 4.
A design for drawing two-way edges (A -> B and B -> A) as one double-headed arrow is merged. In the prototype, one view of the Umami model went from 41 edges to 27 and from 157 crossings to 61. The implementation PR is in review.
Work is underway to stop committing files generated from ADRs in each PR, and to regenerate them in a daily scheduled run instead. Parallel ADR PRs almost always conflicted on them.
A design is in progress to limit karasu serve to connections from your own machine and to check the Host header.
Splitting the three files over 600 lines has more steps to go.

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

Rate limits, skipped steps, and hooks: what tuning AI code review for agent PRs taught me (karasu weekly)

Hiroki Kondo — Sun, 25 Oct 2026 01:57:47 +0000

This is the third weekly update.
It covers changes merged from October 18 to 24.
This time I start with what I learned building with agents, then go through what shipped.

This week in numbers: 50 PRs merged (11 of them Dependabot) and 6 decisions recorded as ADRs.
No release went out this week.
The unreleased changes, including both highlights below, are due in today's monthly release (see "Coming next").

Lessons from building with agents this week

CodeRabbit's review works where I can't follow the details.
CodeRabbit reviews karasu's PRs.
In one earlier PR, it pointed out a case in edges between cards in the same row: the two points of the route around a card sat at the same height.
The route check treated a corridor of zero height as invalid and threw away the clear route.
So the straight route through the cards stayed.
karasu's layout logic is complex enough that I had found it hard to review in detail.
Findings like this, ones I would never have thought of, help a lot.

But a re-review on every fix uses up the quota.
Each time the agent fixes a finding and pushes, CodeRabbit reviews again.
Repeat that and you hit the rate limit, and the PR waits.
On one PR, CodeRabbit reviewed six times.
Two would have been enough: the first review and one round of fixes. Three of the extra runs found one class of problem one instance at a time.
The quota then was 2 reviews an hour, and each wait was 38 to 39 minutes.
After four pushes in a row, CodeRabbit paused automatic reviews, and from then on each one had to be requested by hand.

Dropping re-reviews isn't the answer either.
I counted the 37 CodeRabbit-reviewed PRs among the last 60 merged.
They took 80 reviews, 43 of them re-reviews.
Re-reviews raised 10 new findings on 5 PRs, all in files that the fix commits touched.

So I cut problems down before the web review.
This is the order I follow now.

Set a risk tier from the paths a change touches, and review deeper where the tier is higher (the design is merged; implementation is next). Changes to ADRs or tests alone merge automatically after approval; changes to workflows, releases, or dependencies get a human reading the diff.
Before taking a PR out of draft, run the /engineering:code-review skill locally.
Then run the CodeRabbit CLI once. The CLI's quota (10 an hour) is separate from PR reviews.
If that comes back clean, mark the PR ready and send it to the web review.

Written steps weren't followed.
The step to run the CLI used to live only in a local memory note of the agent.
Of about 290 sessions since October 1 that created or readied a PR, one ran the CLI.
Even after I added the step to the procedure, a session the next day readied a PR without the local review.
The step that hands a readied PR over to working through CodeRabbit's findings ran in about 7 of about 40 sessions.
Most of those times, I typed it myself.
So the steps are becoming Claude Code hooks.
A hook that hands over to that step right after gh pr ready is merged, and a hook that refuses gh pr ready before the local review is in a PR now.

The trial and error turned up holes in the process.
The main checkout had a Stop hook that reported uncommitted changes when a session ended.
It was meant to prevent commits made straight onto main.
It never blocked such a commit; it only reported at the end.
On October 24, it kept a session from exiting over changes I had left behind by hand.
I dropped the Stop hook and made lefthook's pre-commit refuse commits on main.
Because it is a Git hook, it applies to whoever commits.
The ADR also records what still gets through, such as cherry-pick and --no-verify.

In another project, I'm trying automatic merges decided by a change's impact.
It started with How the Claude Code team does code review.
The Claude Code team describes how they review code there, and their way of trusting agents to land changes on main influenced me strongly.
I'm trying it in a private project.
The idea matches karasu's risk tiers and goes one step further.

The tier comes from the paths a change touches, not from its author. Docs alone skip the AI review; ordinary changes go through the AI review, the checks, and the end-to-end tests. Touching migrations, authentication, outbound sends, or the gate itself adds a human approval.
Approval works only from a human's terminal; the agent can't approve.
An unresolved finding from the AI review blocks the merge. Reviews stop at three rounds, and from the second round on they look only at what changed since the last one.
An eval built from past fixes measures how many of 19 bugs the reviewer finds. Revising the review guidelines took it from 5 to 7. The number is generous, since I revised and measured on the same 19 cases.
The AI review also found holes in the gate itself. A change could rewrite the rules that judge it and rate itself low. The gate now judges with the rules from the version on main.

It's still being built, and no change has gone through it yet.
I'll report once it runs.

Hand over the whole import graph, not just the open file

Last week I fixed karasu serve from npm, which hadn't worked at all.
Even so, serve in 0.9.0 couldn't draw a model that imports other files.
It put only the opened file into the browser's in-memory file system, renamed to /serve/index.krs.
Every import reported "File not found".

The design compared three options.

A: hand over the whole served directory. A new GET /api/project on the server returns every .krs and .krs.style under it in one response.
B: read files one at a time over HTTP. Two new endpoints that take a path, and one round trip per file on every compile.
C: walk the imports on the server and return only the files needed. It would add a new public helper to core to save a few tens of KB.

The cost of A is sending the whole directory.
Measured on the entire karasu repository, that came to 108 files and 164 KB, so I went with A.

The app places the files it receives at their real paths and fetches them again whenever a file changes.
Imports now resolve by the same rules as karasu render, and saving an imported file or a style sheet redraws the preview.
When only an imported file changes, the view you drilled into stays where it was.
GET /api/project takes no path from the request and doesn't follow symbolic links.
Nothing outside the served directory comes back.
Along the way, a file in a subdirectory (/services/order) can now be opened; before, it couldn't be opened at all.

The nightly end-to-end test for serve got a fix too.
It had been serving the regular app build instead of the serve build that the npm package actually ships.
It's the same lesson as last week, that only a test running the packaged artifact catches this kind of bug, and the test now runs the shipped build.

Share is back in serve.
Share links point at the public app (karasu.kompiro.dev), so whoever receives one can open the diagram without running karasu.

One viewer for the app and the editor, reading unsaved buffers first

The Visual Studio Code extension's preview used to be a webview written by hand for the extension.
Every feature added to the app's preview had to be ported to Visual Studio Code separately.
Now the webview runs the app's viewer as it is.
The work came in three PRs.

Add the seams on the app side. A host can now drive the viewer: tell it where to read files, get notified of jumps, and switch the theme and language.
Replace the Visual Studio Code preview. The hand-written webview is gone, and the webview runs the app's viewer. Pan and zoom, the CRUD view, facets, and edge hover with the detail panel now work in Visual Studio Code without a port.
Write preview edits back to the editor. Picking an edge direction from the right-click menu puts the change into the editor's buffer, unsaved. The editor's undo takes it back.

The viewer asks the extension for every file it reads.
The extension reads the open editor buffer first and falls back to the disk.
So unsaved edits show up in the preview as you type.
That holds for imported files as well as the open one.
The old preview read from the disk, so unsaved edits never reached the diagram.
I found this by reading the code during the design survey and haven't reproduced it in Visual Studio Code.

On a write, the extension compares the buffer with the text the viewer last read.
If you typed something in between and the text changed, nothing is written.
The check keeps a write from overwriting your own edit.
Jumping to a node defined in an imported file now opens the right file, too.

Other changes this week

karasu fmt no longer moves comments to the end of the file.
karasu fmt and format-on-save printed every comment written above or beside a property line at the end of the file.
Property lines have no position in the AST, and every block kind had the same problem: edges, deploy, organization, and more.
Comments now stay next to the line they annotate.
All 16 new tests fail against the formatter on main before the fix.

The two bugs last week's e2e tests found are fixed.
Last week's post listed them as not yet fixed.
The first: shortcuts such as Ctrl/Cmd+B fired while you typed in the editor.
In Chromium, Monaco takes input through a div with the EditContext API attached.
That element now counts as a text input.
The second: reloading while the deployment view or the matrix was open dropped you back on the system view.

Lanes stay inside a drill-down frame.
In a drill-down view, the lanes for edges running beside the cards went onto or past the frame's sides.
Across 4 models and 1,542 views, vertical runs on or outside the frame went from 3,100 to 31.
The canvas grew by 1.5% in exchange.
One view got more crossings (TwentyServer in the Twenty model, +2,018), and a separate Issue tracks it.

translate --from db handles migration history.
It now replays migrations, from drizzle and others, in order, so dropped tables and temporary tables from rebuilds no longer remain.
That fix opened a hole of its own, though.
A ) inside a string literal ended the CREATE TABLE body early, so a value such as DEFAULT ') DROP TABLE a' replayed a DROP TABLE.
Another PR closed it before any release.

Small fixes.
Edges tagged [inferred] were drawn in the same color as untagged edges, against the spec. I measured three color options and switched to one that stands apart.
The .krs.style lexer silently dropped every non-ASCII character, so a Japanese selector such as #注文 had no effect.
179 relative links in the reference docs bundled with the skills broke once installed. They are now rewritten when the files are copied.

Coming next

Today, October 25, is the last Sunday of the month, when the monthly release train leaves. 16 unreleased changesets, including both highlights, are due on npm and the Visual Studio Code Marketplace.
The implementation of review depth by risk tier is still ahead (its Issue is open).
An Issue is open to make /coderabbit-converge fix every instance of a finding's class before pushing.

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

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

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. It was also Claude Code that caught the private repository's name in 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.
I had that in mind, but the captioned prototype put the repository name in the opening caption, and I missed it.
Claude Code was the one that caught it.
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.