開発misc-dev

なぜメタスキルを足したくなったか

これまでに UI デザインの原則、資料作成の原則、図解の種類という3つのコンテンツを別々に積み上げてきた。サイト上では /design-principles、/presentation-principles、/diagram-types という別ディレクトリで動いていて、Claude Code 側のスキルもそれぞれ独立している。

ところが、いざ「SVG を1枚描こう」「資料を1ページ作ろう」と着手するときに、自分のなかで「どのスキルを先に開けば判断ミスを減らせるか」を毎回考え直していた。原則は60件、24件、29件と粒度がバラバラで、3つの入口を順に開いて記憶を呼び起こすのに毎回時間を溶かす。

「これ読んどきゃ大丈夫」レベルのメタスキルを1冊だけ用意して、そこから既存3コンテンツに枝分かれさせれば、判断の入口が1か所に揃う。そう思って Claude Code に統合計画書から書かせることにした。

計画書を書かせて Codex に殴ってもらう

最初に「3コンテンツを束ねる入口スキルを作りたい。イメージは Claude Code のスキルにしてほしい」とだけ指示して、プランモードで計画書を吐かせた。

計画書ができた段階で、いつものルール通り Codex に殴らせる。瑣末な指摘はいらない、致命的だけ出してくれ、と頼んだ。Codex から戻ってきた指摘は2点で、どちらも痛いところを突かれた。

  • SSOT が二重で持たれていて、片方を直し忘れたら原則の番号や本文が初日からずれる
  • トップ導線を新しく足すのに E2E テストをスキップする計画になっている

修正してから再度 Codex に出したら「致命的指摘なし」で返ってきた。この時点でようやく ExitPlanMode に進めた。Codex に1往復させると、計画書のまま実装に入ったら確実に踏んでいた地雷を、実装前に潰せる。

「SSOTって何？初日からずれるってどういう意味？」

実装を始めたところで、自分から会話を止めた。Codex の指摘文に「SSOT が崩れる」「初日からずれる」と書かれていたが、自分のなかで言葉の解像度が足りていなかった。ここを曖昧にしたまま実装が走ると、たぶん3か月後に「なんでこの構成にしたんだっけ」と自分で迷子になる。

Claude Code に「SSOTってそもそも何かをちょっと記事にして教えてくれませんか。今回の経緯も含めて公開記事にしてほしい」と頼んだ。返ってきた解説で自分なりに噛み砕いたのが以下。

  • SSOT = Single Source of Truth = 同じ事実を表すデータは、システムのなかで1か所だけが「真実」を持つ
  • 同じ情報を別々の場所に置くと、どちらか片方を直し忘れた瞬間にズレが始まる
  • 「初日からずれる」とは、運用が始まる前に原因が仕込まれている、という意味。実装した日にはまだ気づかないが、次に片方を更新したときに別の場所が古いまま残り、そこからズレが累積していく

自分のケースに引き付けると、こうなる。

  • メタスキル側に「15原則」をテキストで持ち、Vue ページ側にも同じ15原則をベタ書きしたら、原則の番号や見出しを直すたびに2か所を直す必要がある
  • 直し忘れたら、サイト上では原則4だが、スキル側では原則5、というズレが生まれる
  • いまの自分は、片方を直す気で実装を始める。明日の自分は、もう片方の存在を忘れている。これが「初日からずれる」

結論として、計画書とコードのどちらが真実かを最初に決める。今回は「TypeScript の SSOT ファイルが真実」で、スキルの markdown は SSOT から生成、Vue ページも SSOT から型として読み込む構成に倒した。SSOT 解説記事のほうも /what-is-ssot-and-day-one-divergence として公開記事に残した。

メタスキル本体の作り

統合スキル名は visual-design-essentials。デザイン・資料・図解の3領域を15原則 + 6行の図解語彙にまで圧縮して、各原則から既存の詳細ページに渡せるようにした。

サイト側の公開ページも /visual-design-essentials として用意した。最初は単純な縦スクロールの読み物にしたが、見せたところで「Miller Column Layout にしてほしかった」と差し戻されたので作り直した。既存3コンテンツと同じ Miller Columns に揃え、共通コンポーネント MillerView.vue を切り出して二重メンテを避けた。

途中で「グッドとバッドの比較を、左右で並べる形にしてほしい。バッドを左右に置いて、グッドはデザインで採用しているものを当てる」と注文が入った。最初は「Good を左、Bad を右」というレイアウトで作っていたので、Bad を比較対象として左右に並べ、もう一方には既存のデザイン原則ページから採用済みの SVG を埋め込む形に組み替えた。

E2E は最初から書かせた。Miller Columns 化したあとに Playwright のクリックが Hydration 前に走って 5/5 が落ちる事故も踏んだが、waitForLoadState('networkidle') を挟んだら通った。

画面の右側がもったいない問題

最後にユーザーから細かい注文が入って詰めた。

  • 「↓ そのまま埋め込み」という見出しを削除して、出典リンク1本にする
  • 1080 縦置きの画面で右側に大きな空白ができているので、右カラムの max-width 制限を外して横いっぱいに広げる

埋め込んだコンポーネント自身が原則番号と出典バッジを持っているので、見出しを増やすほど読者が読む順番に迷う、というのが削除の理由。CSS の max-width をひとつ外すだけで、横の空白が消えてコンテンツが画面を埋めた。Chrome DevTools で 1080 幅にリサイズして目視で確認した。

今日の学び

  • メタスキル＝既存スキルの「入口」を1冊だけ用意するパターンは効く。判断の入口が1か所に揃うので、毎回どのスキルから開くか悩む時間が消える
  • 計画書を書かせたら、必ず Codex に殴らせる。今回は「SSOT が初日からずれる」を実装前に拾えた
  • 用語の解像度が低いと感じた瞬間に手を止めて、解説記事を書かせる。書いてもらった解説を読み返すことで、自分が次に同じ構造に出会ったときに迷わない
  • SSOT は「真実を持つ場所を1か所にする」だけのルールだが、これを最初に決めずに走ると、3か月後に同じデータが2か所にあって片方が古い、という事故を踏む
  • 既存ページとの統合は「左右並び」「Miller Column」「埋め込み」など、見せ方を後で詰めることになる。最初から既存の作りに揃えにいくほうが、書き直しのコストが軽い