archify skill introduction

はんなりプログラミング 生成AI LT会 in 京都
https://hannari-python.connpass.com/event/408082/

Transcript

1. archify スキルの紹介 Claude Code × archify の応用 2026年10月23日 Tetsuya Morimoto はんなりプログラミング 生成AI LT会 in 京都
2. 01. 目次 02. 自分：理解する 03. チーム：共有する 04. 顧客：公開する 05. © 2026 Kazamori LLC archify とは まとめ 2
3. archify とは プロンプトにて指示を出して構成図をつくる 01 入力 03 検証 © 2026 Kazamori LLC 文章を書いて説明すればよい リポジトリであればソースコードや そのドキュメントを読ませればよい JSON がスキーマに沿っているか 02 中間表現 (型付き JSON) 04 描画 LLM が書いた図の意味と配置の意図を、 レンダラーと検査が使う 唯一の入力として固定する契約に使う 配置の計算、経路とラベルの決定 SVG を生成して単一の HTML とする 3
4. リポジトリから 図解をつくる プロンプト(例) このリポジトリを読んで、archify スキルで構成図を作ってください。 主要コンポーネントは 8〜12 個、主経路は 1 本に、 外部依存と信頼境界を示し、詳細は線を増やさずカードにしてください。 © 2026 Kazamori LLC コードが根拠になる ノードからソースの該当行へリンクする (コミット固定) 初見のコードベースの全体像をつかむ 4
5. archify の仕組み AI が書き、ツールが検証する AI エージェント(SKILL.md に従う) archify CLI(Node、決定論的) 1. 図の種類を 5 種類から選ぶ validate ：スキーマと配置を検査する 2. スキーマと例を必要な分だけ読む deliver ：描画、検査、原子的な置き換える 3. 候補の JSON を書く(主経路 1 本、主要 12 個まで) visual-check ：ブラウザで実測する 失敗したら、診断の supportedFixes から修正を選ぶ © 2026 Kazamori LLC 5
6. 失敗の扱い 直す回数を絞り、出力を壊さない 修正ループに上限 失敗しても壊さない 1. 幾何の調整は 1 回に 1 つ 1. 検査に通った HTML だけが前の出力を置き換える 2. 2 回続けて改善しなければ止めて、 (SHA-256 の受領記録つき) 未解決の診断を報告する © 2026 Kazamori LLC 6
7. 型付き JSON と 検証の役割分担 スキーマ (ajv の strict) { "schema_version": 1, "diagram_type": "architecture", "components": [ { "id": "api", "type": "backend", "label": "API", "sources": [{ "path": "app/api.py", "line": 12 }] }, { "id": "db", "type": "database", "label": "PostgreSQL" } ], "boundaries": [ { "kind": "region", "label": "VPC", "wraps": ["api", "db"] } ], "connections": [ { "from": "api", "to": "db", "variant": "dashed" } ] } 型、enum、範囲。未知のフィールドは拒否する レンダラー (レイアウト検査) 重なりやラベルの衝突などの幾何 ビューア (作成者の定義のみ) 書かれた関係だけをたどり、推測しない 検証器は生成済みで同梱(実行時ネットワーク不要) スキーマとのずれはテストで検出する フィールド名はスキーマに沿った簡略例 © 2026 Kazamori LLC 7
8. 図のスコープが 広がっていく 01 02 03 © 2026 Kazamori LLC 自分：理解する チーム：共有する 顧客：公開する インタラクティブな HTML (例：Deno × Cloudflare の記事) claude.ai の Artifact (例：図解をベースにして調べた内容を足していく) SVG をドキュメントへ (例：プロダクトのドキュメント) 8
9. 理解する 図が「問い」を生む 1. 違いが分からない：従来の構成と何が違う？ 2. 図にしてもらう：分からない箱と矢印が見える 3. 問いが自然に出てくる：読むより先に、 聞きたいことが決まる 4. 壁打ちして図を更新：答えは一次情報で裏を取る (例) 出てきた問い ルーティングの役割は？ LTX 形式とは？ Durable Object のモデルは？ 出典：Cloudflare Blog(2026-10-09)をもとに作成 © 2026 Kazamori LLC 9
10. なぜ図を見ながらだと 理解が進むのか 文章だけ 図 ＋ 壁打ち 上から順に読むしかない 全体を一度に見渡せる 分からない所を読み飛ばしやすい 分からない箱や矢印が目に見える 質問が漠然とする(「全体的によく分からない」) 質問が具体的になる(「この矢印は何をしている？」 ) © 2026 Kazamori LLC 10
11. 問いの順番が、 そのまま自分に合った学習の順番になる © 2026 Kazamori LLC 11
12. 共有する HTML を Artifact に変換する Before archify が描いた図のみ © 2026 Kazamori LLC After Artifact にあげるときに解説、対応表、出典を足す 12
13. 共有する LLM と会話しながらアップデート 手順 共有相手にわかりやすいように 1. archify の HTML (1 ファイルで完結) 「BEFORE と AFTER で同じ役割を縦に揃えて」 2. claude.ai の Artifact にアップロード 「役割ごとの対応表を足して」 3. リンクを共有する 「開発者と運用者の視点を分けて」 © 2026 Kazamori LLC 13
14. 公開する 製品ドキュメントの mermaid 外部サービスのデータフロー(約 18 ノード、6 サブグラフ) 1. 空のサブグラフ： subgraph cloud-server … end を ノードの代わりに置いている 2. サブグラフへの矢印： cloud-service --> agent は何に つながるのかが曖昧 3. o--o が 2 つの意味： client o--o mongodb が DB 接続と 「人が UI を使う」を兼ねる 4. レンダラーを elk に変更： defaultRenderer: elk 。 統合図は標準の配置で破綻する 公開ドキュメント(1.10.0)の mermaid ソースを描画 © 2026 Kazamori LLC 14
15. 同じ構成図の比較 mermaid と archify mermaid 1.10.0 ドキュメント archify dev ドキュメント 2つもまったく同じ「UCIDM サーバーと外部サービスのデータフロー」 © 2026 Kazamori LLC 15
16. 使い分け どちらが優れているかではない mermaid のまま archify 置き換え ノード数が少ない小さな図 境界や関係の種類が多い複雑な図 README やチケットにすぐ書きたい 回避策(空サブグラフなど)が要る図 誰でもエディタだけで直せる 色や矢印で見た目を整えて人に見せたい図 一番の理由は見やすさ 製品ドキュメントの図を置き換えている © 2026 Kazamori LLC 16
17. 置き換えのコツ 失うものを先に塞ぐ 01 03 © 2026 Kazamori LLC JSON と PNG をセットで管理 JSON が正本 エクスポートした PNG をコミットし、 レビューや README でそのまま見る AI や検索向けの代替を残す llms.txt や .md 版には、 ノードと関係を代替テキストとして入れる 02 CI で検証する archify validate を CI で実行し、 壊れた図はビルドで落とす 04 バージョンを固定する 変化の速いプロジェクトなので、 更新時は全図を再生成して差分を確認する 17
18. まとめ 図解の応用は広い 01 自分 理解する 02 チーム 共有する 03 顧客 公開する © 2026 Kazamori LLC 18
19. ありがとう ございました！ © 2026 Kazamori LLC
20. リファレンス 1. archify https://github.com/tt-a1i/archify 2. What are artifacts and how do I use them? https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them 3. Unicorn Cloud ID Manager オンプレミス版ドキュメント https://www.osstech.co.jp/resource/ucidm/docs/on-premise/index.html © 2026 Kazamori LLC 20