karasu 週報:Low の PR のマージをワークフローへ移し、マージ前の確認をスキルにする

  • #karasu
  • #ai
  • #claude-code
  • #architecture
/pr-verify が PR #3771 について出したレポートのページの上部。PR の見出しの下に「マージしてよい」という結論の枠があり、必須の CI がすべて通ったこと、CodeRabbit の再レビューの指摘が 0 件だったこと、判断待ちの項目がないことが書かれている。その下に「手順 1: 差し戻すべきか」の節が続く

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

週報の 6 回目です。 対象は 11 月 8 日から 13 日までにマージした変更です。 今週から週報を出す日を日曜から土曜に移したので、いつもより 1 日短い 6 日間になりました。

今週の数字: マージした PR は 72 件(うち Dependabot が 14 件)、ADR として記録した決定は 9 件です。 ADR は 9 件とも、ADR だけの PR で足しました。 月次のリリースはありません。 11 月 11 日に、VS Code 拡張の毎週のプレリリースの 2 回目が出ました(0.5.2026111101)。

ハイライト:給与計算の題材と、チームで試してもらう準備

先週の次回予告で書いた、2 つ目の題材でガイドを回す PR がマージされました。 karasu.kompiro.dev の「Design a service split」のガイドは、ネットショップの題材で、サービスの分け方を 5 つの手順で考えてもらうものです。 その最初の手順で、同じ 5 つの手順を給与計算のシステムで進めるほうへ切り替えられるようになりました。 ネットショップに戻ることもできます。 行き来しても、手を入れていない題材は使い回すので、プロジェクトは増えません。

この題材を足すかどうかは、設計の段階で私が決めました。 足すと、サンプルとその説明文、ギャラリーのページに加えて、@karasu-tools/core に公開の定数が 2 つ増えます。 公開の定数は、あとで消すと互換性を壊します。 app には利用の計測がないので、足しても使われているかは分かりません。 設計文書は、初回体験の要求文書に 2 つ目の題材が挙がっていることを理由に、足すほうを勧めていました。 私も足すほうを選びました。

初回体験の改善は、段階に分けて進めています。 この PR で、第 2 段階の作業が終わりました。 第 3 段階は、実際のチームに使ってもらって、チームで同じモデルを見る価値が伝わるかを確かめることです。 今週は、そのための準備を 2 つ入れました。

チームで 60 分、karasu を試すセッションの台本を書きました。 ドキュメントサイトのガイドに、ja と en で置いてあります。 流れは 3 つです。

  1. 参加者がそれぞれブラウザのプライベートウィンドウで、「Design a service split」のガイドを最後まで進める。
  2. チーム自身のシステムのモデルを見る。見る前に、どこがどうつながっているかを予想してもらってから見て、話す。
  3. ふりかえる。

台本は ja を先にエージェントが書き、私と一緒に直しました。 直したのは、パートを減らして余裕を持たせたこと、その場でのインタビューをやめてあとの短いアンケートにしたこと、最後にふりかえりを置いたことです。 アンケートは、当日に 4 問、2 週間後に 2 問です。

感想を集める場所を、GitHub Discussions に作りました。 Feedback というカテゴリで、投稿にはフォームが付きます。 karasu.kompiro.dev の各ガイドの最後の手順に、「感想を聞かせてください ↗」というリンクを置きました。 app の中でリンクを置いたのは、ここだけです。

フォームの先頭には、公開していないシステムのモデルの共有リンクを貼らないよう、注意と必須のチェックボックスを置いています。 karasu の共有リンクは、モデルをまるごと URL の # より後ろに入れて運びます。 この部分はブラウザが karasu のサーバに送らないので、サーバにはモデルが残りません。 その代わり、リンクを知っている人なら誰でもモデルを見られます。

チームで試してくれる方を探しています。 台本どおりでなくても構いません。 ガイドを 1 つ進めてみて引っかかったところ、チームで使えそうか、使えなさそうならその理由を、Feedback に書いてもらえると助かります。 台本は、今のところ Chrome か Edge を前提にしています。 ほかのブラウザのプライベートウィンドウでは、app がファイルを保存する仕組みを使えずに失敗するおそれがあり、まだ確かめていないからです。

今週のエージェント開発

今週は、PR をマージするまでの流れを 2 か所で変えました。 私が差分を読まない Low の PR は、マージを Claude のセッションから GitHub のワークフローへ移しました。 私が読む High の PR は、マージの前の確認をスキルにしました。

Low の PR のマージをワークフローへ

karasu の PR は、変更が触ったパスから 4 つのリスク段階に分かれます。 いちばん低い Low は、ADR だけの PR や、ADR の索引を作り直す PR などで、私は差分を読まずにマージしています。 これまでは、PR を作った Claude のセッションが gh pr merge --auto を流し、GitHub の自動マージに任せていました。

この形には、問題が 2 つありました。 1 つは、マージがセッションに頼っていることです。 手元のセッションの記録では、128 回の --auto のうち 3 回が、Claude Code の auto モードの判定で拒否されていました。 拒否されたりセッションが止まったりすると、マージも止まります。 マージまで約 7 時間かかった PR もありました。 もう 1 つは、GitHub の自動マージが、段階を判定するチェック(Review tier)を待たないことです。 このチェックが失敗した 16 秒後にマージされた PR がありました。

新しい形では、ワークフローが 2 つのジョブで Low の PR を扱います。 判定のジョブは、読み取りの権限だけを持ち、main にある段階の判定スクリプトを PR の先頭のコミットに当てます。 PR のファイルをディスクに展開したり、PR のコードを動かしたりはしません。 マージのジョブだけが GitHub App の鍵を持ち、判定したときのコミットを指定してマージします。 鍵は、main から動くワークフローでしか使えない environment に置きました。

この形にすると、鍵が 1 つ増えます。 これまでの設計は、新しい鍵が要らないことを理由の 1 つにしていました。 鍵が漏れると、Low に限らず、CI を通った PR なら何でもマージできてしまいます。 それを承知のうえで、GitHub App を作りました。 なお、ワークフローが確かめるのはマージの条件までで、変更の中身の良し悪しではありません。 ローカルのレビューの記録は、今もエージェントの自己申告です。

移行は 3 段階に分けています。 最初の段階のワークフローは、開いている Low の PR を判定して、結果を書き出すだけです。 マージやコメントはせず、マージはそれまでどおりセッションの --auto が行います。 この段階の PR では、同じ判定のスクリプトを手元から実際の PR に当てました。 必須のチェックが走っている間は「待つ」、終わったあとは「マージする」と判定しています。 次の段階で、ワークフローが判定に従ってマージするようにしました。 最後の段階で、セッションの手順から --auto を外し、リポジトリの自動マージを止めます。

11 月 13 日に、ワークフローが初めて PR をマージしました。 最初の実行は、私が environment に登録した秘密鍵を読めずに失敗しました。 鍵を登録し直して実行し直すと、low-pr-merger[bot] としてマージしました。 5 件続けてワークフローだけでマージできたら、最後の段階に進みます。

待つ手順を、文章からスクリプトへ

2 つ目の段階に入っても、セッションはまだ --auto を流していました。 すると、必須のチェックが通った数秒後に GitHub の自動マージがマージしてしまい、ワークフローの出番がありません。 そこで、Low の PR はワークフローに任せて待つ、という手順をセッションのルールに書きました。 最初は文章で書いたのですが、レビューのたびに抜けが見つかりました。 場合分けが多かったからです。 セッションは、自動マージを外すか、拒否された PR を直すか、止まったチェックを流し直すかを決めます。 30 分待っても進まなければ、--auto に戻します。 最後は、待つ手順をテストのあるスクリプトに移し、ルールにはコマンドと、結果ごとにすることの表だけを残しました。

先週書いた gh pr ready を止める仕組みでも、抜け道をコマンドの文字列から数え上げて塞ごうとして、数え上げきれませんでした。 今週も、場合分けを文章で書き切れず、実際に動かせるスクリプトに移して落ち着いています。 次にセッションの手順を書くときは、場合分けが多ければ、最初からスクリプトにできないかを考えます。

マージ前の確認を /pr-verify に

High の PR は、今も私が読んでマージします。 マージの前には、PR の説明を読み、CodeRabbit の指摘と CI を確かめ、プレビューを開いて受け入れテストの項目を手で試しています。 PR の説明は長く、英語です。 いちばん時間がかかるのは、app の変更を手で確かめるところでした。

/pr-verify <PR 番号> は、このうち機械でできる部分を受け持つスキルです。

  • CodeRabbit の未解決の指摘、失敗した必須のチェック、base との conflict のどれかがあれば、そこで止まり、実装したセッションに貼る英語の依頼文を出す。
  • そうでなければ、PR の説明と私に判断してほしい点を日本語でまとめる。
  • 受け入れテストや e2e のテストを変えた PR では、プレビューを Playwright で動かす。手で確かめる項目のスクリーンショットと、変わった e2e のテストの動画を撮り、レポートのページにする。
  • 最後にマージしてよいかの意見を出す。マージするのは、私がセッションで OK と言ったときだけである。

このスキルの PR では、エージェントのレビューを 3 回回し、CodeRabbit にも見てもらって、合わせて 41 件の指摘が出ました。 目立ったのは、GitHub からの読み取りに失敗したときや、チェックの結果がまだ出ていないときに、「進めてよい」と判定してしまう穴です。 今は、読み取りに失敗したら「止まる」か「待つ」として扱います。 マージには --match-head-commit を付け、確かめたあとに push があればマージが失敗するようにしました。 スキルの出来は、skill-creator で 3 つの PR を相手に評価しています。 確認項目を満たした割合は、スキルありで 97%、スキルなしで 87% でした。

マージしてから、実際に High の PR で使っています。 レポートが私に判断してほしい点を先に挙げるので、私は確認すべきことに集中できています。 動作の確認を Playwright の動画にしたのもよかった点です。 エージェントが確かめていないであろう点を、動画から見つけやすくなりました。 テストが通ったという結果からは、テストが画面のどこを見ていないかまでは分かりません。 動画には、テストが見ていない部分も映るからだと考えています。

段階ごとの内訳

今週マージした 72 件の段階の内訳は、High が 42 件(うち Dependabot が 14 件)、Design が 10 件、Medium が 7 件、Low が 13 件です。 閉じた PR は 73 件で、マージしなかったのは検証用の spike の 1 件です。 Low の 13 件は私が差分を読まずにマージしており、自動マージ率は 18% です(先週は 24%)。 内訳は、ADR の PR が 9 件、ADR と TPL の索引を作り直す PR が 2 件、TPL の文書の整理が 2 件です。

そのほかの変更

書いたモデルを、karasu が読み違える不具合をいくつか直しました。

  • a -> "b->c" と "a->b" -> c のように、ノードの名前に -> を含むエッジが 2 本あると、あとに書いたエッジの色と向きが両方に効いていた。エッジを見分けるキーを、端点を単につないだ文字列で作っていたからである。リリース済みの 0.10.0 にも含まれている。
  • x -> y と x -> "y#sync" の 2 本があると、色のルールや direction: up が、書いた順によって両方に効いたり、どちらにも効かなかったりしていた。診断も出なかった。
  • エッジの直後の行が、クォートで囲んだ名前から始まるエッジだと、その名前が前の行のエッジのラベルとして読まれていた。ノードのブロックの中では、エラーを出さずに、間違ったラベルと、書いていないエッジを持つモデルになっていた。
  • 2 つのファイルが同じスタイルシートを @import すると、循環していると誤って報告していた。サブディレクトリにある .krs の @import は、そのファイルではなく入口のファイルの場所から探していた。

どれも、次の月次のトレイン(11 月 29 日の予定)で CLI と VS Code 拡張の安定版に届く見込みです。

診断に短い ID を付けました。 すべての診断に KRS001 から KRS114 までの ID を付け、CLI は Warning[KRS041]: ... のように表示します。 karasu check --format json で、スクリプトやエージェント向けに JSON でも出せます。 karasu-skills のスキルは、これまで診断のメッセージを grep して、壊れたモデルかどうかを判断していました。 メッセージは翻訳されるので、grep が何も拾わず、壊れたモデルがスキルの止まる条件を通ってしまうことがありました。 今は JSON の code で判断します。 app と VS Code 拡張に ID を出すのは、これからです。

karasu-nest の秘匿化が、入力によっては極端に遅くなっていました。 karasu-nest は、自分のリポジトリから起こした .krs を投稿して公開できるギャラリーです。 投稿のたびに、パスワードや鍵のような秘密を含んでいないかを検査しています。 そのうち 3 つのパターンが、入力の長さの 2 乗に比例して時間がかかっていました。 手元の Node.js 24 で 1 MiB の入力を試すと、接続文字列のパスワードの検査は 277 秒かかっていましたが、直したあとは検査全体で 260 ミリ秒です。 Cloudflare Workers 上では 1 回の処理の CPU 時間を 5 秒に制限しており、本番で処理が打ち切られたことは確認していません。

npm への公開に、私の承認を挟む設計を決めました。 karasu は npm に 3 つのパッケージを出しています。 今は、リリースのワークフローがそのまま latest に公開しています。 これを、npm が 5 月に正式に提供した staged publishing に移します。 CI は承認待ちの列に入れるところまでを行い、私は手元でビルドした中身と比べてから承認します。 実装のセキュリティレビューで、承認待ちの列では manifest(package.json にあたる情報)を見られないと分かりました。 そこで、実装をマージする前に設計を直しました。 依存を入れてビルドするジョブと、npm のトークンを持って列に入れるジョブを分けます。 実装は、直した設計に合わせて作り直します。

依存の更新。 Dependabot の 14 件をまとめてトリアージし、マージしました。 新しく入るパッケージはなく、既知の脆弱性の報告もありませんでした。

次回予告

  • npm の staged publishing の実装を、直した設計に合わせて作り直す。リハーサルをもう一度行う。
  • Low の PR を、ワークフローだけで 5 件続けてマージできるかを見る。できたら、セッションの手順から --auto を外す。
  • 診断の ID を、app と VS Code 拡張にも出す。
  • 次の月次のトレインは 11 月 29 日の予定で、今週の不具合の修正と診断の ID が CLI と VS Code 拡張の安定版に届く見込みである。