Transcript
00:00:00コーディングエージェントにリポジトリのマップ作成を頼むと、存在しないKafkaやRedis、APIゲートウェイが生成されてしまうことがあります。
00:00:07図自体はまともに見えますが、多くの重要な部分が抜けています。
00:00:10そこで登場するのが「Archify」です。このツールでは、エージェントが直接図を描くことはしません。
00:00:14型付きのグラフを出力し、Archifyがそれを検証した上で図をレンダリングします。
00:00:19これはアーキテクチャを可視化する上で、最高の方法の一つかもしれません。
00:00:23これからそれを確かめていきます。
00:00:30そもそも、AIモデルに図を描かせるべきではないのです。
00:00:33Archifyの仕組みは、システムを構造化された型付きのJSONとして記述することです。
00:00:37それが検証され、その後に初めてローカルコンパイラが最終的なHTMLへと変換します。
00:00:42グラフが無効であれば、処理は失敗します。
00:00:45それがArchifyです。Cloud CodeやCursor、Codexに直接組み込めるため、わずか数ヶ月で4万4千スターを獲得しました。
00:00:53それでは実際に試してみましょう。
00:00:54Archifyをインストールし、特定のリポジトリを指定して、アーキテクチャに関する1つの質問に答えさせます。
00:01:00その後、この結果をプルリクエストで実際に使用できるかどうかを確認します。
00:01:03このツールを絶対に使用すべきではないユースケースもいくつか存在しますが、それについては後ほど詳しく解説します。
00:01:08ワークフローを効率化するコーディングツールが好きなら、ぜひチャンネル登録をお願いします。
00:01:11役立つ動画を常時公開しています。
00:01:13インストールは、こちらの1つのコマンドを実行するだけです。
00:01:17新しくアプリの環境構築をするわけではありません。
00:01:19これは実質的なエージェントスキルです。
00:01:22一度インストールすれば、先ほど挙げたCloud Codeなどの環境から同じスキルをそのまま利用できます。
00:01:28エディタやワークフローを変更する必要もありません。
00:01:32それでは、実際にタスクを投げてみましょう。
00:01:34このリポジトリのアーキテクチャ全体を描画するように頼むわけではありません。
00:01:37それでも一応動くとは思いますが。
00:01:39結局のところ、それは大量のゴミデータを返すだけになってしまいます。
00:01:42そのため、具体的で的確な質問を1つ投げかけます。
00:01:45「Archifyを使用して、アーキテクチャ図を作成してほしい。ノードは最大8〜12個に抑えること。
00:01:49このサービスでキャッシュミスが発生したとき、何が起きるか？」
00:01:52「このリポジトリに実際に存在するコンポーネントのみを含めること。
00:01:54存在を証明できないコンポーネントは省略すること。
00:01:58自己完結型のHTMLとして出力すること。」
00:02:00これが、1つのプラン、1つの質問の形式です。
00:02:02ノード数はだいたい8から12個程度にします。
00:02:04エージェントにコードベース全体のマップ作成を頼んでしまうと、何かをシンプルにしたのか
00:02:08かえって分かりにくくしたのか分からなくなりますからね。
00:02:10これでは単にリポジトリツリーをフローチャートに変換しただけになってしまいます。
00:02:14エージェントはアーキテクチャをJSON形式で記述します。
00:02:16そしてArchifyがそれを検証します。
00:02:18今からここで行うように、検証プロセスを直接実行することも可能です。
00:02:23これは個人的に見つけて本当に素晴らしいと感じた機能の一つです。
00:02:27各ノードには、コミットや特定の行範囲に紐づいたリポジトリのエビデンスを含めることができます。
00:02:32その裏付けがなければ、回答の中でどれだけそれらしい説明がされていようと、ノードにSRCバッジは付与されません。
00:02:37なるほど。
00:02:39さて。
00:02:39一体これがどう役に立っているのでしょうか？
00:02:41見た目は普通のアーキテクチャ図のようですが。
00:02:43確かにそうですが、単なる図として使うわけではありません。
00:02:46この中から実際のサービスを検索することができます。
00:02:50該当部分をクリックすれば、上流と下流で何がつながっているのかがすぐにわかります。
00:02:55そしてそのルートをたどり、システム内におけるキャッシュミスのパスを確認できます。
00:02:5910本の矢印を見つめながら頭の中で必死に追跡する代わりに、実際にステップをたどって確認できるのです。
00:03:05さらに、
00:03:06それだけでなく、エクスポートも可能です。
00:03:08PNGとしてコピーしたり、1200×36の共有用カードを生成したりできます。
00:03:13ここでの本当の違いは、Mermaidとの違いにあります。
00:03:17Mermaidというツールは通常、ただ「読む」ものです。
00:03:20しかしこれは、質問を投げかけ、検証できるものです。
00:03:23動きのあるアニメーションで拙い構造をごまかすわけではなく、図を静止画としてエクスポートしても意味がしっかりと伝わります。
00:03:28残すべき価値がきちんと残るのです。
00:03:31そして、おそらくさらに有用と思われる2つ目のユースケースがあります。
00:03:35それは何かと言うと、
00:03:36コードレビューでの活用です。
00:03:38例えば、これが変更前のシステムだとします。
00:03:41そこに既存のリトライワーカーを追加したとします。
00:03:44エージェントに対し、勝手に作り話をさせることなく、アーキテクチャの更新を指示できます。
00:03:49Archifyを使えば、検証済みの2つのスナップショット（追加、削除、移動、ルーティング変更など）を比較できます。
00:03:54そのため、生成された2つの図を漫然と眺めるのではなく、何が実際に変更されたのかを把握できます。
00:03:59エディタのインターフェースはあくまでチャットのままです。
00:04:02しかし、このアーキテクチャを次のエージェントセッション以降にも引き継ぎたい場合は、JSONをコミットすればよいのです。
00:04:07現段階において、Archifyを最も簡単に理解するための説明はこうなります。
00:04:11システムマップ用のHTML仮想マシンのようなものであり、コーディングエージェントがフロントエンドです。
00:04:15JSONは中間表現となります。
00:04:19そしてHTMLがコンパイルされた結果です。
00:04:21この中間のレイヤーが、非常に多くの重要な処理を担っています。
00:04:24JSONは厳格なスキーマに従っています。
00:04:26未知のフィールドが含まれていると、検証は失敗します。
00:04:28また、図のモードには5種類あります。
00:04:30アーキテクチャ、ワークフロー、シーケンス、データフロー、ライフサイクルです。
00:04:34しかし、最も興味深い設計上の決定の一つは、「モデルがレイアウトを制御しない」という点です。
00:04:38それはレイアウトです。
00:04:39モデルはシステムについて記述するだけで、
00:04:41すべてのボックスが正確にどこに配置されるかを決めるわけではありません。
00:04:44開発者たちは自動次数レイアウトを備えたテーマ付きMermaidも試してみましたが、
00:04:48通常のMermaidと比べて特に改善されるわけではありませんでした。
00:04:51また、バリデーションはフェイルクローズ方式になっています。
00:04:54不良なJSONが、適当なきれいな図に化けてしまうことは決してありません。
00:04:58診断結果やルールコード、サポートされている修正方法が提供されます。
00:05:02こうした機能全体を踏まえて、私がArchifyを使わないであろうケースをご紹介します。
00:05:06もしREADMEファイルの中に直接図を埋め込む必要があるなら、おそらく避けたほうがよいでしょう。
00:05:10少し時間がかかるかもしれません。
00:05:11GitHubはそれをレンダリングしますが、
00:05:12ArchifyのHTML形式はそのままでは表示されません。
00:05:15Archifyは、まったく異なる性質の課題を解決するためのものです。
00:05:18すでにループ内にエージェントが存在しており、
00:05:20そのエージェントがアーキテクチャの成果物を生成している状況です。
00:05:23PRに含まれることもあれば、
00:05:25デザインレビューに組み込まれることもあるでしょう。
00:05:27そうした場面でこそ、検証済み出力を利用する価値が出てきます。
00:05:30全体として、このツールには気に入った点が多くあります。
00:05:32私たちが日常的にすでに使っているツールの中に組み込んで動かすことができます。
00:05:35また、出力を外部に共有することも可能です。
00:05:38リポジトリのエビデンスが存在するため、実際に自分の目で確認できる確実な根拠が得られます。
00:05:41アーキテクチャが構造化されているため、時間が経つにつれて勝手に内容が変わってしまうことなく、継続的な編集が可能です。
00:05:46さらに、見た目も十分に洗練されているため、Figmaなどの他のツールでわざわざ書き直す必要性を感じずに済みます。
00:05:53とはいえ同時に言えるのは、Archifyはあなたのシステムのアーキテクチャを本来は把握していないということです。
00:05:58グラフ自体は完全に正しく検証されていながら、間違ったシステムを説明しているという事態もあり得ます。
00:06:02そのため、人間が読んで確認する必要があります。
00:06:03ご存知の通り、性能の低いモデルは「動くけれど見栄えの悪いJSON」を平気で生成してしまいます。
00:06:08もし図の最終的な置き場所がREADMEであるなら、Mermaidを使った方が依然として適している場合もあります。
00:06:13Archifyを使用する場合、JSONとHTMLをコミットするか、画像をエクスポートすることになります。
00:06:18そして、絶対に避けるべき間違いが1つあります。
00:06:21巨大なリポジトリに向けて「すべてをマップ化してくれ」と指示しないことです。
00:06:25そんなことをすればどうなるかは、想像がつくでしょう。大量の使い物にならないデータが返ってくるだけです。
00:06:29しかしそれは、Archifyの欠陥ではありません。
00:06:32単に質問の仕方が悪かっただけです。
00:06:34すでにコーディングエージェントを活用しており、自分や他の人が将来見返すための図を日常的に作成しているなら、このツールは理にかなっています。
00:06:42PRレビューや設計ドキュメントの作成において、私はおそらくこれを使用するでしょう。
00:06:47Mermaidのような、すでに手元にある既存のツールの「もっときれいなバージョン」が欲しいという理由だけでインストールすることはありません。
00:06:52また、何かを自動でリバースエンジニアリングしてくれることにも全く期待していません。
00:06:55試してみるためのハードルは非常に低いです。
00:06:58npxコマンドが1つあればよく、マシンにNodeがあれば動きます。
00:07:00モデルのウェイトファイルなどを気にする必要もありません。
00:07:02私のM4 Proの性能も、この作業においてはほとんど関係ありません。
00:07:05ただ、1つだけ守るべきルールがあります。
00:07:07「ファイルごとに質問は1つ」ということです。
00:07:08その図がどのような質問に答えているのかを明確に説明できないのであれば、図を生成すべきではありません。
00:07:14BetterStackのJoshでした。
00:07:15このようなコーディングのTipsやテクニックが気に入っていただけましたら、ぜひチャンネル登録をお願いします。
00:07:19また次回の動画でお会いしましょう。
00:07:20また次回の動画でお会いしましょう。
Community Posts
No posts yet. Be the first to write about this video!
Write about this video