karasu 週報:混んだ図のエッジとラベルを読めるように、巨大ファイル 4 本を割る

  • #karasu
  • #ai
  • #claude-code
  • #architecture
Umami を題材にしたモデルの UmamiApp ビューを、Boards のまわりで切り出して並べた図。10 月 31 日はカードのあいだを何本もの線が束になって走り、カードを貫いている。11 月 7 日は線が減って行き来の組が両端に矢印のある 1 本になり、線ごとのラベルが読める

karasu は、C4 モデルに着想を得た、システムアーキテクチャを記述するテキストモデリング言語です。 .krs ファイルにシステムを書くと、karasu がシステム構成・デプロイ構成・チーム構成のビューを描きます。 コードは一行も手で書いておらず、すべて Claude Code 経由で開発しています。

週報の 5 回目です。 対象は 11 月 1 日から 7 日までにマージした変更です。

今週の数字: マージした PR は 114 件(うち Dependabot が 6 件)、ADR として記録した決定は 22 件です。 ADR のうち 19 件は ADR だけの PR で、3 件は実装の PR の中で足しました。 月次のリリースはありません。 11 月 4 日に、VS Code 拡張の毎週のプレリリースが初めて出ました(0.5.2026110401)。

ハイライト 1:混んだ図のエッジとラベルを読めるようにする

今週は、エッジの多いビューの見え方を 3 つ変えました。 どれも、Umami を題材にしたテスト用のモデルの UmamiApp というビューで測っています。 41 本のエッジが並ぶ、混んだビューです。

UmamiApp ビューの前後を同じ縮尺で描いた図。上は線が束になってカードを貫き、下は線が減ってラベルが並ぶ

上が週の初め(10 月 31 日の main)、下が週の終わり(11 月 7 日の main)です。 同じ縮尺で描いているので、下の図はラベルのために間を広げたぶん大きくなっています。

行き来するエッジを、両端に矢印のある 1 本の線で描くようにしました。 対象は、A -> B と B -> A の両方があり、線の見た目が同じ組です。 カードの位置は動きません。 2 本のエッジはデータとしては別々のままで、線の半分ずつを受け持ちます。 ホバーや diff の表示も、半分ごとに付きます。 どちら向きの半分かが分かるように、ラベルの頭に向きの矢印を付けました。 この見せ方は、spike のブランチで案を並べて選んでいます。 色や太さ、diff の状態が違う組は、区別がつかなくなるので 2 本のまま描きます。

UmamiApp では、線が 41 本から 27 本に、交差が 134 から 58 に減りました。 先週の予告では、試作の数字として交差 157 から 61 と書いていました。 数字が変わったのは、次の不具合を直したあとに測り直したからです。

折り返した行のあいだのエッジが、自分のカードを貫いていました。 karasu は、ビューが横に広がりすぎないように、1 つの層のカードを複数の行に折り返します。 同じ層で、違う行にあるカード同士のエッジは、横に並んでいるものとして左右の辺で接続していました。 すると、まっすぐな線が両端のカードの中を通ります。 カードは線のあとに描くので、矢印の先がカードの下に隠れます。 UmamiApp では 41 本のうち 12 本が自分のカードを貫き、6 本の矢印が隠れていました。 今は、違う行のカード同士なら上下の辺で接続します。 カードを貫くエッジと隠れる矢印は 0 になり、交差は 126 から 110 に減りました。

これは、1 本にまとめる PR をレビューしている途中で見つかりました。 Boards と Identity の組で、1 本にまとめた線の両端の矢印が、どちらも隠れていたのです。 両端が隠れると、線に向きがなくなります。 折り返しは 0.10.0 より前からある仕組みなので、リリース済みの 0.10.0 にもこの不具合は含まれています。 examples/ とレンダラのテスト用モデルの 543 のビューを比べると、描画が変わったのは UmamiApp だけでした。

出せなかったラベルのために、場所を空けるようにしました。 label-display: auto では、ほかのラベルやカードと重なるラベルを出さずに省きます。 省いたラベルがあるビューでは、配置をやり直す候補を 2 つ試します。

  • A: 行と行のあいだを、省いたラベルの高さの分だけ広げる。
  • B: A に加えて、行の中のカードの間隔を、いちばん幅のあるラベルの分だけ広げる。

候補は、省くラベルが元の配置より厳密に減るときだけ採ります。 減らなければ元の配置のままです。 省いたラベルがないビューは、これまでと同じに描きます。

モデル 描けたラベル(前 → 後) 採った候補
UmamiApp 17 → 30(41 本中) B
Dify(405 ビュー) 206 → 216(296 本中) A
WordPress(1,031 ビュー) 156 → 185(258 本中) A
examples/ 変化なし(出力がバイト単位で一致) —

代わりに、描画は遅くなります。 Dify の DifyDB は 173 ms から 403 ms に、WordPress の WordPressApp は 173 ms から 298 ms になりました。 遅くなるのは、ラベルを省いたビューだけです。

3 つとも、karasu.kompiro.dev の app には main から反映されています。 VS Code 拡張では、11 月 4 日のプレリリース版で使えます。 CLI と VS Code 拡張の安定版には、次の月次のトレイン(11 月 29 日の予定)で届きます。

ハイライト 2:600 行を超えた 4 ファイルを割る

先週、パッケージのソースに 1 ファイル 600 行の上限を設けました。 超えていた 33 ファイルは、今の行数で上限を止めてあります。 そのうち大きな 4 ファイルを、今週までに上限の内側へ割りました。

ファイル 前 後
parser/parser.ts 3,066 行 335 行
renderer/svg-renderer.ts 2,965 行 460 行
view/view-extract.ts 2,042 行 523 行
renderer/layout.ts 1,719 行 590 行

4 つとも、よく変わるファイルです。 直近 90 日のコミットは、layout.ts が 46 回、parser.ts が 36 回、svg-renderer.ts が 34 回でした。 上限で止めたままだと、機能を足すたびに行数の壁にぶつかります。

まず、ファイルごとに Issue を 1 つ立てました(10 月 31 日の午後)。 Issue には、ファイルの節ごとの行数の表と、どの順に何を切り出すかの手順が書いてあります。 1 つの手順を 1 つの PR にし、その PR の中で上限の値も下げます。 上限の値が実際の行数より大きいまま残ると、テストが落ちます。 PR は全部で 19 件になり、4 ファイルの系列は並行して進みました。 最後の PR がマージされたのは 11 月 1 日の 23 時 45 分です。 Issue を立ててから、およそ 34 時間でした。

手順の順番は、import の循環を避けるように組んであります。 karasu は madge で循環を検査していて、型だけの import も数えます。 そのため、view-extract.ts では型だけを持つモジュールを先に切り出しました。 これがないと、切り出したモジュールが型を view-extract.ts から読み、view-extract.ts が関数をそのモジュールから読む形になります。 parser.ts では、パーサの状態と基本の操作を 1 つのオブジェクト(parse context)にまとめ、切り出した関数にはそれを渡すようにしました。

どの PR も、振る舞いを変えない移動です。 確かめ方は、テストとスナップショットが変わらずに通ること、循環の検査、それに描画の前後を撮るスクリプトで差が出ないことでした。 並行して進めていた、エッジを 1 本にまとめる PR は、この間に main を 5 回取り込んでいます。 取り込んでも PR のコードの差分は変わらず、動いたのは行数の上限の値だけでした。

上限を止めているファイルは、33 から 28 に減りました。

「振る舞いを変えない」をこの週は人が確かめましたが、11 月 2 日からは機械が確かめます。 それは次の節で書きます。

そのほかの変更

karasu serve が、同じネットワークのほかのマシンから読めました。 karasu serve は、すべてのネットワークインタフェースで待ち受けていました。 同じネットワークにいれば誰でも、/api/* を通して .krs と .krs.style を読めたことになります。 DNS リバインディングを使うページからも、同じオリジンとして扱われていました。 今は既定で 127.0.0.1 だけで待ち受け、--host で広げられます。 /api/* は、Host ヘッダーが IP アドレス、localhost、--allowed-host で指定した名前のときだけ応答します。

/render?src= から、手元のマシンのサービスに届きました。 /render?src= は、渡された URL のホスト名を最初に一度だけ確かめ、リダイレクトはそのまま追っていました。 loopback に解決される名前、IPv4 射影の IPv6 アドレス、リダイレクトを使えば、手元で動くほかのサービスに届きます。 その結果は Access-Control-Allow-Origin: * 付きで返っていました。 今は、つなぐ先のアドレスをリダイレクトのたびに確かめ、リダイレクトは自前で最大 5 回まで追います。 本文の大きさにも 256 KiB の上限を設けました。

どちらも、リリース済みの 0.10.0 に含まれています。 修正は次のトレインで届きます。 それまでは、信頼できないネットワークにつながっているときに karasu serve を動かさないのが安全です。

置き場所を間違えた構文で、エラーが連鎖しなくなりました。 たとえば、サービスの中に本体付きの database を書いたとします。 これまでは、キーワードだけを読み捨て、残りが外側のブロックに流れ込んでいました。 その結果、エラーが 9 件出たり、あとに続く domain がトップレベルの要素として読まれたりしていました。 今は、間違えた構文をまるごと読み飛ばし、エラーは 1 件だけ出します。

細かな変更。 カードをタップしてドリルダウンすると、⇄ Relations のピルが次の階層に残っていたのを直しました。 @azure/identity を 4.14.1 に上げ、依存先の @azure/msal-node の脆弱性(GHSA-xcx6-jx8p-x3h5)を解消しました。残る 2 件のアラートは major を上げないと直らないため、見送っています。

今週のエージェント開発

Medium の PR で私が手で見ていたことを、CI に移しました。 karasu の PR は、変更が触ったパスから 4 つのリスク段階に分かれます。 そのうち Medium では、CodeRabbit を回しません。 ローカルのレビューの記録を読んで、私が最後に判断します。

最近の Medium の PR を見返すと、Medium に入るべきでない変更が入っていました。 上に書いた /render?src= の修正も、Medium でマージしています。 セキュリティの境界に触れる変更でも、決めたパスに当たらなければ Medium になっていたからです。 パーサの振る舞いを変える変更も、言語仕様の文書に触れなければ Medium のままでした。

そこで 11 月 1 日に、Medium で私が手で確かめていたことを書き出し、機械に移すものを決めました。 今週、そのうち 3 つが入りました。

  • 段階の分け方を変えた。 セキュリティの境界に当たるパスと、innerHTML や eval( などの危ない書き方を足し引きする変更は High にし、/security-review も求める。パーサや言語の振る舞いに当たるパスも High にする。
  • テストの扱いを確かめるようにした。 タイトルが fix の PR には、テストの追加か、No test: <理由> の 1 行を求める。既存のテストを弱めたら、Test change: <理由> を求める。refactor の PR では、既存のテストを変えてはいけない。
  • 描画が変わらないことを確かめるようにした。 Render equivalence というチェックが、すべての example と受け入れテストの krs を描く。merge base と PR の先頭の両方で描いて、SVG、診断、フォーマッタの出力を比べる。refactor の PR で差が出たら落とす。描画が変わった PR には rendering-change のラベルを付ける。ラベルはマージを止めず、私にプレビューを見るよう促すだけである。

Render equivalence は、手元で 3,281 の出力を、片側およそ 2 秒で比べます。 試しにレイアウトの定数を 1 つ変えると、2,129 の出力に差が出ました。 テストの扱いのチェックは、過去の PR に当てて試しています。 ハイライト 2 の分割のうちパスを移すだけの 10 件は、refactor として通りました。 テストを消したり書き換えたりしていた 2 件は、refactor としては落ちました。

これで、Medium の PR で私が確かめなくてよくなったことが 2 つあります。 PR の説明が差分と合っているかと、ローカルのレビューで指摘を見送った判断が妥当かです。 Render equivalence は、まだ必須のチェックにはしていません。 誤検知が出ないかを何週か見てから、必須にします。

「事故」が起きるリスクの高いところから、機械で確かめる範囲を広げていくことにしました。 テストを弱めたかの判定には、サブエージェントのレビューで 36 件の指摘が出ました。 多くは判定の抜け道です。 テストをブロックコメントで囲む、return を差し込む、ctx["skip"]() と書く、といったものでした。 まずは、普通に書いて起こりうる形を塞ぎました。 わざわざ偽装しないと書かない形は、今は見送っています。 見送ったものは、当面は人が差分を読む段階に任せます。 信頼できない書き手の PR は、そもそも High に入るからです。

gh pr ready を止める仕組みは、今週も作り直しました。 先週、ローカルのレビューの前の gh pr ready を拒否する仕組みを、gh のラッパーに作り直した話を書きました。 コマンドの文字列から抜け道を塞いでいくと、CodeRabbit のレビューのたびに新しい抜け道が見つかったからです。

今週、そのラッパーが --repo を渡されると、何も確かめずに通すことが分かりました。 最初は、--repo の値が origin の URL と同じかを比べる形で直しました。 もう 1 つ、レビューの記録を比べる base を、origin にある同じ名前のブランチから取る逃げ道もありました。 別のリポジトリの PR を指されると、この逃げ道は違うブランチを読みます。 別のリポジトリを指す方法は、--repo のほかにも、環境変数の GH_REPO、URL での PR の指定、gh repo set-default とあります。 方法ごとに守りが要り、CodeRabbit はそれをラウンドごとに 1 つずつ見つけました。 最後は、URL を比べる形と逃げ道の両方をやめました。 今は、gh pr ready が対象にする PR をそのまま読み、その PR の base のコミットに対してレビューの記録を確かめます。

先週と同じ形でした。 例外を数え上げて塞ごうとすると、数え上げきれません。 2 回とも、確かめたい対象そのもの(gh が受け取った引数、PR の base のコミット)を読む形に変えて収まりました。

機械では見つからない不具合を、CodeRabbit が見つけました。 次回予告で書く初回体験のツアーには、編集の消える不具合がありました。 ツアーの場面は、開いているファイルを読み直します。 保存が終わる前に Next を押すと、エディタの中身が保存前に戻り、次のキー入力で編集が上書きされていました。 CodeRabbit が、ツアーを広げる設計文書の PR のレビューでこれを指摘しました。 エージェントは使い捨ての hook のテストで再現してから、実装の PR で直しています。 直したあとのテストは、修正を外すと落ちることも確かめました。 karasu.kompiro.dev の app は main から出ているので、最初のツアーには 11 月 3 日から 7 日まで、この不具合がありました。 CLI や VS Code 拡張のリリースには入っていません。

この不具合は、Render equivalence では見つかりません。 描画は変わらず、保存とファイルの読み直しの順番で起きるからです。 同じ PR では、ローカルの CodeRabbit CLI も似た点を挙げていました。 エージェントは最初、誤った理由でそれを見送り、CodeRabbit が PR で同じ点を挙げてから判断を改めています。

先週の宿題を確かめました。 先週、「High なのに CodeRabbit が一度もレビューしていない PR が 4 件ある」と書きました。 調べると、そのうち 3 件は CodeRabbit がレビューして、指摘が 0 件だったものです。 指摘がないと、CodeRabbit は PR にレビューを残さず、コメントだけを残します。 私はレビューの件数で数えていたので、この 3 件を取りこぼしていました。 残る 1 件は、CodeRabbit の利用の上限にかかり、レビューされていません。 この PR は、ローカルのレビュー(サブエージェントと CodeRabbit CLI)だけでマージしました。

今週の High は 33 件です。そのうち 11 件には、CodeRabbit のレビューがありません。

  • Dependabot の 6 件は、設定で CodeRabbit の対象から外している。依存の更新は /hane:dependabot でまとめてトリアージしている。
  • 3 件は、指摘が 0 件だった。
  • 1 件は、利用の上限にかかった。
  • 1 件は、レビューの依頼は出たが、CodeRabbit のレビューが走らなかった。原因はまだ確かめていない。

CodeRabbit の上限は、今週ほかにも、手元の CLI で 1 回かかっています。 Render equivalence のような CI のチェックには、この上限がありません。

今週閉じた PR は 117 件で、うち 114 件をマージしました(マージ率 97%)。 段階の内訳は、High が 33 件、Design が 15 件、Medium が 39 件、Low が 27 件です。 Medium が先週の 12 件から増えたのは、ハイライト 2 の分割の PR 15 件が Medium だったからです。 Low の 27 件は私が差分を読まずにマージしており、自動マージ率は 24% です(先週は 20%)。 内訳は、ADR の PR が 18 件、ADR と TPL の索引を毎日作り直す PR が 7 件、TPL の文書の整理が 2 件です。

次回予告

初回体験の改善に取り組み始めました。 karasu.kompiro.dev を初めて開いた人に、5 分ほどで「チームで同じアーキテクチャモデルを見る」価値を体験してもらうのが目標です。 今週は次のところまで実装が進んでいます。

  • 初めて開くと Welcome が出て、3 つの入口を選べる。「Design a service split」を選ぶと同梱のサンプルが開き、小さなパネルが 5 つの手順で案内する。新しい構文や仕組みは足さず、今ある app の操作だけで組んでいる。
  • ツアーのやり直し、リロードしたあとの再開、頼んだ操作をしたら ✓ を出す表示が入った。
  • 残りの 2 つの入口(Understand と Evolve)にもツアーが付いた。

続きとして、2 つ目の題材(給与計算のシステム)でツアーを回す PR がレビュー中です。 初回体験がうまくいっているかを測るために、個人を特定しない利用計測の設計も進めています。

ほかには、次のものがあります。

  • Render equivalence を何週か見てから、必須のチェックにする。
  • 次の月次のトレインは 11 月 29 日の予定で、今週の karasu serve の修正と、ハイライト 1 の描画の変更が CLI と VS Code 拡張の安定版に届く見込みである。