ZOZOの技術ブログで「Claude Codeで構成図を自動生成・自動更新する仕組み」を読んだ。CI連携・専用DSL・チーム運用を前提にした、作り込まれた仕組みだった。そのまま真似ても個人開発には合わない。何を削り、何を残せば1人の開発でも回るかを考えて実装し、実際に3つの自分のプロジェクトで検証した記録。
大きな組織向けの仕組みを個人開発サイズに落とし込む時の「何が規模に依存していて、何が規模に関係なく効くか」の見極め方。実際に削った要素と残した要素、既存のプラグインスキルを壊さずに機能を足す方法、そして複数プロジェクトで実際に動かして初めて見えた注意点。
ZOZO Technologies社のテックブログに、Claude Codeで構成図を自動生成・自動更新する仕組みの記事があった。CI（GitHub Actions）でリリースの度に差分を判定して自動更新し、専用のテキストDSL（D2）でレンダリングする——チームでの継続運用を前提にした、作り込まれた仕組みだった。
面白かったが、そのまま真似ても個人開発には合わない。CIパイプラインを組むほどの更新頻度は無いし、専用DSLを覚えるコストも1人の開発には見合わない。だから最初にやったのは要約して紹介することではなく、この仕組みのうち、どこが規模に依存していて、どこが規模に関係なく効くアイデアなのかを見極めることだった。
規模が違えば、必要な装備も違う。大きなエンジニアリング組織が定期的なCI差分検知やチーム全体で共有する規約に価値を見出すのは当然だが、1人の開発でそのまま採用すると、運用コストの方が図の価値を上回る。個人開発サイズへ最適化する作業そのものが、今回やったことの核になる。
個人開発サイズのdiagram-syncという自作スキルにする過程で、実際に3つの判断をした。
ここで大事なのは「面倒だから削った」ではないということ。元の仕組みが解決している課題を1つずつ確認し、その課題が個人開発にそもそも存在するかを見た。
| 元の仕組みが解決していた課題 | 解決策（ZOZO） | 個人開発での実情 | 判断 |
|---|---|---|---|
| 大勢が触るコードとドキュメントがズレる | CIで強制的に自動同期 | 触るのは自分1人。変更した瞬間、自分が一番よく分かっている | CIの強制同期は不要。会話の流れで「今直したから図も直して」と頼める方が自然 |
| 見る人ごとに描き方の解釈がブレる | D2という専用DSLで表記統一 | 見るのも自分だけ。統一すべき"複数人の解釈"が存在しない | 専用DSLの学習・運用コストが丸ごと不要。Mermaidなら普段使うツールでそのまま見られる |
| 変更量が多く、人力の更新漏れが起きる | GitHub Actionsで自動トリガー | 変更頻度は体感できる規模。漏れても実害が小さい | 常時稼働のCIインフラを維持するコストの方が高くつく。頼んだ時だけ動けば十分 |
これは最適化そのもの。D2やCI連携が解決している課題（大勢で触る・解釈がブレる・更新漏れが起きる）は、そもそも1人の開発には存在しない。存在しない課題への備えを外し、身軽さと引き換えに得るものだけを残す——それが規模に合わせた最適化。
上の表の通り、解決している課題ごと存在しなかったので削った。惜しんで残す理由が無い。
「どう描くか（表現ルール）」と「何を描くか（構造データ）」を別ファイルに分けるという設計思想そのものは、誰が・何人で触るかに関係なく効く。1人でも、規約を書かずに毎回描き方がブレるより、ルールを1つのファイルに育てていく方が図の質は上がる。ここだけは丸ごと引き継いだ。
D2を捨ててMermaidだけにしたのは妥協ではなくアップグレードでもある。専用のビューアが要らず、GitHubでもVS Codeでもこのブログの記事内でも、Markdownがある場所ならどこでもそのまま図として表示される。CIの代わりに「頼んだ時だけ動く」スキルにしたのも、変更した本人が一番タイミングを分かっているという個人開発の強みをそのまま生かした設計。
もう1つ、個人開発ならではの判断がある。Claude Codeにはプラグイン提供のapp-doc-writerやapp-spec-writerのようなスキルが既にあるが、それらのファイルは直接編集しなかった。プラグインが更新されると上書きされて消えるリスクがあるからだ。代わりに、プロジェクト固有の場所に新しいスキルとして追加した。既存の資産を壊さずに、機能だけ足す形。
作って満足せず、実在する3つのプロジェクト（ブログの自動投稿パイプライン、経済学メディアの記事生成パイプライン、サッカーくじの予想エンジン）に実際に適用した。
「動くはず」と「動いた」は別の情報。読んで面白かった設計を自分のコードに移植する時、頭の中では動く気がしていても、実際に描画してみると文字がはみ出す・矢印が重なるといった細かい破綻が必ず出る。そこを潰して初めて、記事に書く価値のある一次情報になる。
構成図を見せたところ、「これはいつどう積み上がってきたか、時系列でも見たい」というリクエストが来た。diagram-syncは「今の構造」を描くスキルだったので、「ここまでの推移」を描く姉妹スキルとしてtimeline-syncを新たに作ることになった。
各プロジェクトに1行1件のログファイルを置き、そこに記録が溜まるほど自動生成される年表の精度が上がる。既存の日次ダッシュボードの仕組みに相乗りさせ、3日に1回自動更新されるようにスケジュールタスクも組んだ。1つの検証が、想定していなかった2つ目の資産を生んだ形になる。
元記事: ZOZO Technologies Tech Blog — Claude Codeでアーキテクチャ図を自動生成・自動更新する仕組み