{"slug": "one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu", "title": "One sentence in CLAUDE.md did most of what an ADR search skill did, and karasu mapped itself (karasu weekly)", "summary": "A developer running karasu, an open-source text modeling language for system architecture, tested whether giving Claude Code a dedicated ADR-search skill improved how the agent retrieves past decisions from roughly 500 architecture decision records. Across 150 headless runs on 10 tasks, correctness stayed at the ceiling under all three conditions (49/50, 48/50, 49/50), but adding a single sentence to CLAUDE.md cut cost 14% and the full skill cut it 20% while reducing mean time from 78 to 62 seconds; runs that read the index anyway fell from 8 of 50 to 1 of 50. The developer concluded that giving the agent a way to skip the index worked better than telling it not to, and is moving the skill into the adr-tools CLI as a Claude Code plugin rather than shipping it in karasu.", "body_md": "[karasu](https://github.com/kompiro/karasu) is a text modeling language for system architecture, inspired by the C4 model.\n\nYou describe your system in `.krs` files and karasu draws the views: system, deployment, and team structure.\n\nI haven't written its code by hand; everything goes through Claude Code.\n\nThis is the seventh weekly update.\n\nIt covers changes merged from November 14 to 20.\n\nThe change in the second highlight merged just after midnight on the 21st, but it belongs with this week's story, so I include it.\n\n**This week in numbers:** 61 PRs merged (14 of them Dependabot) and 7 decisions recorded as ADRs.\n\n6 of the ADRs came in ADR-only PRs; the other one is part of a PR that changed a process rule.\n\nNo monthly release this week.\n\nThis week I ran an experiment on what changes when karasu gets a skill for finding ADRs.\n\nkarasu has about 500 ADRs.\n\nWhen an agent looks for a past decision today, it reads the ADR index file and opens individual ADRs from there.\n\nThe question was whether it pays off to replace that with two scripts: one that searches ADRs by term, and one that lists which ADRs reference a given ADR.\n\nAn earlier experiment had shown no difference in whether the agent reaches the ADRs, so I compared whether it answered correctly and what it cost.\n\nThere were three conditions:\n\nI ran Claude Code headless on 10 tasks, 5 times each under each condition, for 150 runs.\n\nThe model was Opus 5.5, and the karasu commit was fixed.\n\nSubagents judged whether each answer was correct.\n\nI shuffled the reports and masked the words that would reveal the condition, then had the subagents judge against the list of correct answers alone.\n\nA judge who knows the condition may be pulled toward it.\n\nThe results:\n\n| Condition | Correct | Total cost | Mean time | \n|---|---|---|---|\n| R | 49/50 | $28.22 | 78 s | \n| RS | 48/50 | $22.49 (-20%) | 62 s | \n| RN | 49/50 | $24.38 (-14%) | 66 s | \n\nCorrectness hit the ceiling under all three conditions, and the skill didn't raise it.\n\nOnly cost and time differed.\n\nAnd about two thirds of the cost RS saved came from RN's single sentence alone.\n\nThe scripts added the remaining third, and they also made the instruction stick.\n\nRuns that read the index anyway: 8 of 50 under RN, 1 of 50 under RS.\n\nGiving the agent a way not to read the index worked better than telling it not to.\n\nAn earlier pilot with one run each had RS 28% cheaper than R.\n\nWith five runs each, that shrank to 20%.\n\nThe single-run comparison had made the gap look bigger.\n\nOne mistake showed up regardless of condition.\n\nSome runs recommended a button CSS class that had already been replaced: 2 of 5 under R, 1 under RS, 3 under RN.\n\nAn ADR records the replacement, but the old ADR's status still says \"accepted.\"\n\nSince the skill didn't reduce this, I think it is a problem with how ADR status is recorded, not with how ADRs are searched.\n\nThe skill won't go into karasu directly. It moves to [adr-tools](https://github.com/kompiro/adr-tools), a CLI for working with ADRs.\n\nThe plan is to add search and reverse-reference commands to the CLI and ship the skill as a Claude Code plugin.\n\nI'll write up the experiment's design and detailed numbers in a separate post.\n\nI turned the karasu repository into a karasu model.\n\nI used the [reverse-architecture skill](https://fukurou.kompiro.dev/en/reverse-architecture/), which reads a repository and writes a `.krs` model of it.\n\nIn October I tried it on umami, an open source web analytics tool; this time I pointed it at karasu itself.\n\nThe model is [in the karasu gallery](https://karasu-nest.kompiro.dev/g/42963-pjqc2ysntbvw).\n\nThere is also a copy with Japanese labels and descriptions.\n\nThe model is 4,453 lines long.\n\nIt contains:\n\nThe umami model had 10 domains, 135 use cases, and 26 entities.\n\numami's entities were almost all database tables.\n\nkarasu's model has only one store, a KV namespace.\n\nInstead, the agents drew in-memory structures, such as the parser's syntax tree and diagnostics, as entities.\n\nThat seems to be the main reason there are ten times as many entities.\n\nWhat surprised me was that karasu could be drawn at all, since it isn't a web service.\n\numami is a web service: one Next.js app serves both the screens and the API.\n\nkarasu is a monorepo where a CLI, a library, a Visual Studio Code extension, a browser SPA, and the gallery's Worker live side by side.\n\nreverse-architecture drew each package of the monorepo as a service.\n\nWhen I drilled from a service into its domains, what each package is trying to do was cleanly split out.\n\nHonestly, it stunned me.\n\nI didn't fix the output by hand.\n\nHere is how long it took and what it cost.\n\nThe cost is token spend estimated at API list prices from the logs of the session and its 19 subagents, not the amount actually billed.\n\n| Step | Time | Cost | \n|---|---|---|\n| Reverse-engineer karasu | about 38 min | $28.13 | \n| Split out the editor parts and file an Issue | about 15 min | $3.91 | \n| Add references to client-side storage and prepare the upload | about 10 min | $5.02 | \n| Make the Japanese copy | about 5 min | $4.72 | \n| Total | about 70 min | $41.78 | \n\nDuring the reverse-engineering, 13 subagents ran in parallel, one per domain, taking 2.4 to 5.3 minutes each.\n\nThose 14 minutes were the longest stage, and they account for about three quarters of its cost.\n\nThe Japanese copy was cheap because the translation subagents ran on Sonnet.\n\nDrawing karasu also showed something its language lacked.\n\nA use case could not point at client-side storage such as the browser's OPFS or localStorage.\n\n6 of the 13 subagents reported this gap, each in a different domain.\n\nThe karasu app keeps project files, the API key, and display settings in the browser.\n\nThe CLI and the Visual Studio Code extension read and write local files.\n\nWith no way to point at that storage, the use cases in those domains could not say anything about what they read or write.\n\nSo a `client`'s storage line can now carry an ID, and a use case can point at it.\n\nTaken from the model in the gallery, it looks like this:\n\n```\nclient WebApp [web] {\n  resource opfs ProjectIndex \"/meta/projects.json\"\n}\n\nusecase RenameProject {\n  label \"Rename a project\"\n\n  resource WebApp.ProjectIndex {\n    operations write:update\n  }\n}\n```\n\nFrom filing the Issue to the design, the ADR, and the implementation took four days.\n\nThe third step in the table above is the work of adding references to the model with this notation.\n\nThe notation is still experimental, and the language version stays at 2.0.\n\nkarasu's entity view draws a domain's entities together with the entities from other domains that they relate to.\n\nThe ones from other domains are drawn muted so they stand apart.\n\nkarasu calls them ghosts.\n\nUntil now, the ghosts sat in one row below the domain's frame.\n\nThat's fine when there are a few, but with many of them the diagram keeps getting wider.\n\nIn the model I reverse-engineered from Dify in September, the IdentityAccess domain had 101 ghosts.\n\nThe diagram was a 36,053 × 1,372 pixel strip (26 : 1).\n\nI filed an Issue back then, but other work came first.\n\nI raised its priority because the same thing happened in karasu's model.\n\nFor example, the Language domain (which holds the parser and diagnostic entities) has 29 entities of its own and relates to 44 entities in other domains.\n\nAlmost all of them are references from other domains.\n\nThe parser is used from everywhere, so that's the expected shape.\n\nSeeing those ghosts stretched into one long row in my own model is what made me move it up.\n\nThis week, ghosts are laid out like this:\n\nHere is how the Language domain in karasu's model is drawn now.\n\nMost of the 44 ghosts reference Language, so frames for 11 domains are stacked above it.\n\nBelow it are only the Modeling frame and a Styling card, which Language references.\n\n[Open it in the gallery](https://karasu-nest.kompiro.dev/g/42963-pjqc2ysntbvw#krs-entity-Language?file=%2Fgallery%2Findex.krs) to zoom in.\n\nI measured it on three reverse-engineered models: Dify, Twenty, and WordPress.\n\nOf the 82 entity views that have ghosts, those with an aspect ratio outside 16 : 9 to 9 : 16 went from 51 to 0.\n\nDify's IdentityAccess is now 4,360 × 3,514 pixels.\n\nBefore the implementation, I had a throwaway branch try only the look of the frames, and decided after looking at its preview.\n\nThe ghost cards and lines stay muted, but each frame's dashed outline and domain name are drawn at full strength.\n\nI wanted to be able to read which domain a ghost comes from without zooming in.\n\nThe lines to ghosts are still straight.\n\nRouting them like the rest of the diagram is the next step.\n\n**npm publishing now waits for my approval.**\n\nI rebuilt staged publishing on the design I revised last week, and it has merged.\n\nThe job that installs dependencies and builds holds no npm token, and the job that holds the token installs nothing.\n\nI compare what CI put in the approval queue against a build I made locally, then approve it with 2FA.\n\nAfter publishing, a workflow compares the published contents once more and tags only the versions that match.\n\nThe flow after approval hasn't run for real yet.\n\nThe monthly train on November 29 will be its first run.\n\n**The workflow merged all 11 Low PRs.**\n\nLast week's \"coming next\" said I'd see whether five Low PRs in a row merge through the workflow.\n\nThis week 11 Low PRs merged, and `low-pr-merger[bot]` merged every one of them.\n\nThat meets the condition for the last stage, so next I'll take `--auto` out of the session's procedure and turn off the repository's auto-merge.\n\nI also added a rule that raises a Low PR to Medium when it adds a link outside karasu's domains.\n\nNobody reads Low PRs, so without the rule such a link would go in with no one checking where it points.\n\nApplied to the 380 commits that touched ADRs or TPLs since September, the rule raises 37 to Medium.\n\n**More fixes for karasu misreading the model you wrote.**\n\n`label` or `description`, was missing it, the parser took the start of the next line's arrow as the value. Inside a block, the leftover arrow became an edge with a source you never wrote, and no diagnostic appeared.`resource Orders [table, api]`, was drawn in a different tag's shape depending on the view. It is now drawn by the first tag. This also fixes the same step overwriting ID rules the author had written.`table`, `queue-item`, and `bucket` cards were drawn in a dark default color in every theme. They now use their store's colors.\n**Adding guards turned up bugs.**\n\nI added a test that draws about 1,700 diagrams: every example, every view, every grouping.\n\nIt found two bugs in compare mode.\n\nI also tested karasu.kompiro.dev's permalinks the way Cloudflare Pages actually runs them, and the test failed on day one.\n\nResponses that always return 404 or 413 were not being cached.\n\n**SVG could be injected through the public image export.**\n\nkarasu.kompiro.dev's image export wrote the background color parameter straight into the SVG.\n\nIt now accepts only hex colors.\n\nColor names such as `white` are now ignored and fall back to the default white.\n\n**main's lockfile broke without a Git conflict.**\n\nAfter I merged several Dependabot PRs in a row, the same entries ended up in the lockfile three times.\n\nThe Pages build failed because it couldn't read that lockfile.\n\nThe three PRs were made from the same base, so squash merging them raised no conflict.\n\nI fixed it by deleting the 66 duplicated lines, and added a rule: a bot PR that touches the lockfile merges only when its base matches the latest main.\n\n**Dependency updates.**\n\nI triaged 16 Dependabot PRs together and took 15.\n\njsdom 31 needed one test expectation adjusted, so it went in through a PR that replaced Dependabot's.\n\n`--auto` out of the session's procedure and turn off the repository's auto-merge.", "url": "https://wpnews.pro/news/one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu", "canonical_source": "https://dev.to/kompiro/one-sentence-in-claudemd-did-most-of-what-an-adr-search-skill-did-and-karasu-mapped-itself-4gd5", "published_at": "2026-11-21 01:31:16+00:00", "updated_at": "2026-11-21 01:41:56.948318+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": ["karasu", "Claude Code", "Anthropic", "adr-tools", "Opus 5.5", "umami"], "also_reported_by": [], "takeaway": "Adding one CLAUDE.md sentence steering the agent away from the ADR index cut cost 14%, and pairing it with search and reverse-reference scripts cut cost 20% and index reads from 8/50 to 1/50, with no correctness gain over the 49/50 baseline.", "recommendation": {"advice": "Give coding agents a concrete tool or path to skip a large index instead of instructing them not to read it, and validate cost savings with at least five runs per condition.", "playbook": "llm-cost", "playbook_url": "https://wpnews.pro/playbooks/llm-cost"}, "alternates": {"html": "https://wpnews.pro/news/one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu", "markdown": "https://wpnews.pro/news/one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu.md", "text": "https://wpnews.pro/news/one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu.txt", "jsonld": "https://wpnews.pro/news/one-sentence-in-claude-md-did-most-of-what-an-adr-search-skill-did-and-karasu.jsonld"}}