Communitygithub.com

仕組みのステップアニメ

仕組み、原理、手順を一ページにします。一度に一歩だけ進み、左に一文、右に因果の順で動く部品が並びます。

仕組みのステップアニメ とは?

仕組みを開き、スクロール一回で因果を一段だけ追わせる教材アニメです。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/QichangZheng/mechanism-animation/tree/HEAD/mechanism-animation

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

原理アニメーション(mechanism-animation)

「これはどうやって動くのか」を1ページのステップバイステップアニメーションにします。読者がスクロールするたびに1ステップ進み、各ステップでは1つのことだけを説明し、図の要素が因果関係の順に表示され、移動し、消えていきます。

完成品の参考:assets/template.html、テンプレート。4ステップの小さな例(キャッシュなし → キャッシュを追加)が組み込まれており、ブラウザで直接開いて確認できます。

0. まず判断:アニメーションにするべきか

コストの低いものから順に試し、前のレベルで説明できれば次には進みません。

レベル使用するものいつ十分か
1直接文字を書く2、3文で説明できる
2番号付き手順(1. 2. 3.)プロセスだが、各ステップが1文で済み、読者が「見る」必要がない
3番号付き手順 + 2–3枚の静止画(前/後比較)構造、関係、またはプロセスを2、3枚の静止画で理解できる
4このスキル:ステップアニメーション何がどこからどこへ行くのか、順序、同じデータを誰が共有するのか、どのステップで何が省略されたのかを説明する際に、3枚の静止画ではまだ説明が不十分

判断基準は一言で言うと:図を任意のフレームで静止させても読者が理解できるなら ⇒ 静止画で十分。「動き」を見て初めて理解できるなら ⇒ アニメーションにする。

2つの境界条件:

  • コスト。アニメーションは静止画の数倍の時間がかかります(事実確認、順序付け、タイミング調整、セルフテスト、修正の繰り返し)。誰も明示的にアニメーションを要求していない場合は、まず提案し、なぜ最初の3つのレベルでは不十分かを説明し、相手が同意してから作成します。デフォルトで作業を開始しないでください。
  • アニメーションは「初めて理解するため」だけに役立ち、参照資料としては使えません:スキャン読み取りができず、検索もできず、ドキュメントに貼り付けることもできません。したがって、ページの最後には「全プロセス概要」が必要です(テンプレートが自動生成:各ステップ1行のテキスト)。元のドキュメントはテキスト版を保持し、アニメーションページへのリンクを追加します。アニメーションページでドキュメントを置き換えないでください。

1. プロセス

  1. 事実を確認する。アニメーションは誤りを非常に明確に表現します。描く前に、説明するメカニズムをコード/設計ドキュメント/論文と照らし合わせ、「設計上はこう言っている」「コードは現在こうしている」「他社(論文、デフォルト値)はこうしている」を区別します。確信が持てない場合は「推測、未検証」と書きます。
  2. ストーリーボードを書く(コードは書かない)。references/storyboard.md に従って表を作成します:各ステップ1行で、このステップで説明すること、画面上に順に何が表示されるか/動くか、終了時に何が残るか、左側のテキストを明確に書きます。ストーリーボードが以下のセクション2の説明ルールを満たしたら、実装に進みます。ステップ数が多い(> 6ステップ)場合や説明に自信がない場合は、要件を出した人と事前に確認します:表のみと彼が決定すべき1つの質問を送信し、文書として送信しないでください。相手が完成品を直接見ることに慣れている場合は、直接作成します。
  3. テンプレートから開始:cp assets/template.html <成果物ディレクトリ>/<名前>.html。変更するのは3箇所のみ:
    • HTML内の<title>、開始ページ(#top)、図のaria-label、終了ページ(#where、フッターの「更新:年月 · どのバージョンに対して確認したか」を含む)——テンプレート内のこれらの箇所はまだサンプルコンテンツなので、一つずつ置き換えます。
    • スクリプトのAセクション:PAGE、MODULES(モジュール、ステップ、テキスト、各ステップの所要時間)。
    • スクリプトのCセクション:画面(存在するオブジェクト、各ステップでの動き)。 B1 / B2の2つのセクションはエンジンであり、通常は変更しません。書き方、小さなツール、既存のパターンについては references/engine.md を参照してください。
  4. セルフテスト:node scripts/check.js <ページ.html> <スクリーンショットディレクトリ>、10項目がFAILでないこと(contain はページに帰属マークがない場合はSKIP、正常)、さらにスクリーンショットを1枚ずつ確認:step-NN(各ステップ終了時)、mid-NN(各ステップ途中)、page-NN(ページ全体)。スクリプトは「停止しているか、テキストが重なっていないか、枠からはみ出していないか、フォントサイズが十分か」をチェックできますが、「説明が明確かどうか」はチェックできません。4ステップのページは約1分、12ステップは約3分かかります。依存関係のインストールと使用方法については engine.md の最後を参照してください。 4.5 (ステップ数が多いか、初心者向けの場合)「初めて見る人」テスト:このメカニズムを知らず、関連資料を一切読んでいないサブエージェントを起動し、各ステップのスクリーンショットのみを順番に見せ、記憶に基づいて各ステップで何が説明されたか、図から得た情報かテキストから得た情報か、どこが理解できなかったかを口頭で再現させます。彼が理解できなかった箇所はページの問題であり、彼の問題ではありません——自分で10回見直すよりも効果的です。
  5. 納品:ページ(単一のHTML、他のファイルに依存しない)を要件を出した人に渡します。その後、変更があるたびにセルフテストを再実行してから納品します。
  6. (内容が重要な場合)技術的確認:ページが確定したら、読み取り専用の確認を1回実施し、ページ上のすべての文と数字をコードとドキュメントと照らし合わせて1項目ずつ確認し、「誤り/誤解を招く/不正確」なリストを作成し、要件を出した人がどの項目を修正するかを決定します。確認は事実のみを対象とします。説明の良し悪しは、要件を出した人が自分で判断します。

2. 説明ルール(最も重要、すべてリジェクトされてから学んだこと)

順序

  • 易しいものから難しいものへ、まず「問題ないケース」、次に「問題が発生するケース」。読者はまず正常な状態を理解してから、問題点を認識できます。例:まず1台の仮想マシン内で多くのコンテナがメモリを共有する(問題ない)、次に複数の仮想マシンに変更した後、各仮想マシンが個別にメモリを保持する(問題)、最後に解決策を説明します。
  • まず基盤、次に上位層、層ごとに表示。まずホストのみ → データがディスクからホストのメモリへ → 仮想マシンが出現 → データが仮想マシンへ → 最後に内部のプログラムが出現。最初からすべてのボックスを配置しないでください。プログラムが先に出現し、データが後から来るようにしないでください。
  • 1つのステップ内で複数のことに因果関係がある場合は順序を付け、同時に発生させないでください。「コンテナが終了」した後、「そのメモリが空き」、その後「ホストに返却」されます。
  • 図はスクロールが停止してから表示され、最初のステップのアニメーションは最初から再生されます。これらはテンプレートで処理されているので、壊さないでください。

各ステップで説明すること

  • 1ステップで1つのことだけを説明し、タイトルはそのこと(「3つのページがそれぞれ1回読み取る」)であり、名詞(「読み取りフェーズ」)ではありません。
  • メインラインは実際の動作のみを演じます。デフォルト値、他社の方法、過去の方式は、このステップのポイントで「なぜ特別にそうするのか」という1文で触れるにとどめ、独立したステップにしないでください——そうしないと、読者は実際にもそのステップを先に実行する必要があると思ってしまいます。(悪い例:最初に「2 MBで報告」を演じ、次に「4 KBで報告」を演じると、読者は「2 MBはどこから来たのか?結局どちらが先なのか?」と混乱します)。
  • 見た目が同じ2つのステップは、読者は同じことだと思い込みます。2つのシナリオに違いがある場合は、その違いを図に描いてください(複数の矢印が同じデータに集まる、共有部分を丸で囲むなど)。テキストだけで説明しないでください。
  • 図に表示されるすべての数字と単語には出典が必要です。前に説明されていない数字(「18」「2 MB」)は読者を混乱させます。出典を説明するか、削除します。
  • 問題が特定の方式にのみ属する場合は、その方式のモジュール内に配置し、概要に配置して読者にすべての方式に問題があると思わせないでください。
  • 読者が知っている具体的な例を使用し、抽象的な記号は使用しないでください。数本の線、いくつかの点、いくつかの短いバーが動いているだけでは、読者はそれらが何であるかを理解できません(読者の実際の言葉:「あの4つのプログレスバーは…何を意味しているのか理解できない」)。それを具体的に説明できるものに置き換えてください:誰が、誰に対して、何を言ったか(「支払いシステム」のAgentが「データプラットフォーム」のAgentに「注文インターフェースの呼び出し方法は?」と質問し、相手が「インターフェースドキュメントを送信しました」と返答する)。記号を使用する場合は、読者が前に見たことのあるもの(先ほどのリストの行)を使用し、新しく発明しないでください。1つの例を徹底的に説明することは、3組の抽象的なやり取りよりも優れています。良い例があれば、さらに別の例を追加しますが、同じ例を3回繰り返さないでください。
  • このステップで使用しない層やオブジェクトは描かないでください。「層ごとに表示」は、すべての層を表示する必要があるという意味ではありません:「コンテナがメモリを仮想マシンに返却する」を説明するときにホストを描くと、読者は余分な層を認識する必要があり、何も理解が深まりません(読者の実際の言葉:「ホストを再び表示する必要はありません。少し複雑です」)。描く前に自問してください:それを削除しても、このステップの文は成立しますか?成立するなら削除します。
  • 説明が終わったら「だから何?」に答えてください。各モジュールの最後のステップまたは終了ページで、これが読者にとって何を意味するのか、現在どこまで進んでいるのか(本番稼働中/テスト環境のみ/未着手)を明確に書きます。
  • 深さは読者に合わせて決定します。作成を始める前に「読者は誰か、彼は何を知っているか、何に関心がないか」を書き留めてください:専門家に基礎を説明すると冗長に感じられ、初心者に実装の詳細を詰め込むと具体的すぎると感じられます。

テキスト

  • 各ステップ:1文(リード)+ 最大2–3個のポイント。太字は結論となる数字や単語にのみ使用します。左側のテキストが多すぎる場合は詳細を削除し、詳細は終了ページまたは図の右下の注釈に配置します。
  • 後で説明するものを参照しないでください。「それぞれ保存しない」「依然として」「も同様」「その1つ」などの言葉は、参照するものがすでに前に登場している必要があります。章の順序を調整した後、前に移動したセクションのテキストを新しい順序で最初から読み直してください。
  • 初出の用語はその場で半文を使って説明し、ページ全体で同じものには同じ呼称のみを使用します。
  • ページ上に内部名を表示しないでください:RFC番号、PR番号、ファイル名、関数名、コマンド名、内部マシン名。ただし、読者がこのコードの開発者である場合は例外です。
  • 用語と「数字 + 単位」は改行しないでください:テキスト内で{{ }}で囲みます。例:{{4 KB}}、{{1,380 億トークン}}。
  • フッターに「更新:年月 · どのバージョンのコードに対して確認したか」を記載します。ページはその日のスナップショットであり、コードは変更されます。
  • 推測や未検証のものは、「推測」「未検証」と明記します。他社の数字は誰のものか(「論文」「POC」「main上」)を明確にします。

画面

  • 同じものは全体を通して同じオブジェクトです:データブロックはディスクからメモリへ「飛び」、さらに仮想マシンへ「飛び」ます。ここで消えて別の場所に出現するのではありません。読者はそれによってプロセスを追跡します。
  • 色には固定された意味があり、ページ全体で一貫しています(例:シアン = データ、紫 = プログラム、オレンジ = 発生中のアクション、青 = 結論/返却されたもの)。凡例は使用するものだけを配置します。
  • アクションにも固定された意味があり、ページ全体で使い方を変えないでください(例:オレンジの線を描く = リクエストを送信、色付きブロックが飛ぶ = データが届く、オレンジの円 = 全員で共有するもの、グループ全体が薄くなる = もう使用しない)。同じ種類のアクションは速度を一定にします:距離が遠いものは長く飛び、すべてを同じ時間に圧縮しないでください。
  • 状態は色で表現し、2〜3種類のみにします:例えば「青 = 使用中、灰色 = 解放済み」。読者は一目で青色と灰色の数を数えられ、後で「灰色のものが回収される」を理解できます。同じ状態を色とアイコンとテキストでそれぞれ説明しないでください。
  • 読む文字は動かさないでください:文をAからBに伝える必要がある場合は、その文を話し手の側に留め、線に沿って送られるのは小さなマークだけにします。読むのは止まっている文字であり、見るのはマークがたどる経路です。文字が飛んでいくと、読者は両方をはっきりと見ることができません。
  • まず動き、次に停止:ステップ内の主要なアクションは最初の60%の時間内に完了し、その後画面は静かになり、読者が左側の文を読む時間を確保します。2つの重要なアクションは同時に発生させないでください。大きな移動は0.5秒以上、図全体を横切るものは0.7秒以上にします。これより速いと目が追いつきません。
  • 来た方法で去る:線で描かれたボックスは、退場時に線で収縮します。飛び込んできたものは飛び出していきます。ページ全体の出入りには2〜3種類の方法のみを使用し、フェードイン/フェードアウトをデフォルトにしないでください。
  • 複数の線が同じ目標に集まる場合は、異なる方向から進入させます(左端、上部、右端から各1本)。同じ辺に並べて配置しないでください:遅かれ早かれ重なるか、他の図形の後ろを通過します(読者の実際の言葉:「携帯電話の線とクライアントの線が重なり、さらに携帯電話自体がクライアントの線を遮っています」)。
  • 意味は正しいが見た目が悪い場合も、未完了とみなします(読者の雲に対する実際の言葉:「意味は正しいが、雲が醜くて硬すぎる」)。重要なグラフィック(ページ全体で繰り返し登場するもの、最後のステップで使用されるもの)は、まず2〜3種類のパターンを並べて表示し、1つを選択します。選択する際に自問してください:線はページ上の他の要素と同じ感触ですか?比率はバランスが取れていますか?背景の線と区別できますか?
  • 強調マーク(丸、矢印、オレンジ色の小さな文字)は説明時に表示され、説明が終わったら退場します。遅くとも次のステップの開始時には退場し、後のステップに持ち越さないでください。各ステップ終了時の画面は、単独で意味が通じるものでなければなりません(step-NN.png がこの画面です)。
  • 共有/同一を強調する:複数の矢印が1つに合流して同じ目標に到達し、さらにオレンジ色の円を追加します。
  • 「省略された」「返却された」は視覚的に表現する必要があります:オブジェクトが占有バーの対応するセクションに飛び、着地した後にそのセクションが短縮されます。飛んでいる最中に短縮しないでください。飛ぶ位置は、短縮されるセクションと一致している必要があります。
  • 模式図と実際のサイズが一致しない場合は、「模式図」と明記し、模式図のグリッドサイズが存在しない単位を示唆しないようにします。
  • ボックスのネストと名前は実際の帰属に従います:作業を始める前に「オブジェクト → それが実際に存在するネットワーク空間/コンテナ/プロセス/サービス」の表を作成します。独立したコンテナやプロセス(サイドカー、プロキシ)は並列のボックスとして描き、ビジネスコンテナ内には描きません。外側のボックスにはそれが何であるかを明確に書き(「あるコンテナグループのネットワーク空間」)、ボックス名は読者が考える呼称を使用します(「メインコンテナ」ではなく「ビジネスコンテナ」)。同じ名前のものは帰属を明確に区別します(2つのサービスにそれぞれsidecarというコンポーネントがある場合は、それぞれ固定のフルネームを使用し)、図と左側のカラムの両方で混在させないでください。
  • 線の角は少なければ少ないほど良いです:端点は2つのボックスの向かい合う辺に配置し、ボックスの中心を狙わないでください。2つのボックスの高さが重なっている場合は直線にします。曲げる必要がある場合は、明確な1つの曲げ点のみを使用します(障害物を避けるU字型は最大2つ)。曲げ点はテキストを避けます。データパケット、赤い線など、同じ経路をたどるものは、この曲げ点セットを共有します。小さな折れ曲がりは、読者に「ここに特別な意味がある」と誤解されます。check.js の bends 項目が検出します。
  • 説明の小さなテキストはボックスの端に貼り付け、ボックス内のオブジェクトの上に重ねないでください。
  • 図内の文字は14キャンバス単位以上にします。図は13インチのノートPCでは約0.8倍に縮小され、それより小さいと読み取れません。check.js の fontsize 項目は1280×720で11px以上を基準にチェックします。収まらない場合は内容を削除し、文字を縮小しないでください。テンプレートには別途「拡大図」(上部ボタン/Fキー)がありますが、これは読者向けのオプションであり、文字が小さいことの救済策ではありません。

3. よくあるリワーク(このようなフィードバックを受けた場合、直接このように修正します)

フィードバック主な原因修正方法
「このステップのアニメーションが終了していない/終了がおかしい」キーフレームがこのステップの終了後に配置されているか、フェードインが終了タイミングにちょうど重なっているこのステップのすべてのアクションを T(id, 0.88) の前に開始し、T(id, 1) の前に停止させる。check.js の still 項目が報告します
「テキストが枠からはみ出している/位置がおかしい」親ボックスとその中の要素が同じタイミングで動き始めていない、または色のみを変更するキーフレームを1つ多く書き、位置を固定してしまった親子で同じタイミングセットを使用する。data-box / data-in を付与し、contain 項目でフレームごとに確認する。「枠内にあるか」の代わりに他の指標(フォントサイズ、透明度)を使用しないでください
「ステップNとステップMが同じに見える」違いがテキストにのみ書かれている違いを図に描く(上記参照:矢印の収束 + 丸)
「Xはどこから来たのか?」図に説明のない数字/単位がある出典を説明するか、図から削除し、「なぜ」のセクションでのみ言及する
「順序がおかしい。Aの前にBがあるべき」因果関係/階層に従って並べていない「まず基盤、次に上位層」に従ってこのステップのタイミングを再配置する。ついでに他のステップも同じ基準で確認する
「XXは奇妙だ。以前に言及されていなかった」テキストが後で説明するものを参照しているgrep 「不再、各存、還是、也一樣、那一份、對比」で、参照するものがすでに登場していることを各箇所で確認する
「テキストが多い/見にくい/小さい」詳細が左側のカラムに詰め込まれている。図内の文字が14未満1文+ポイントに削減する。図内の文字を14以上に上げ、収まらない場合は削除する。check.js の fontsize、text 項目が報告します
「トップページからスクロールダウンすると最初のステップにアニメーションがない/リフレッシュ後にアニメーションがない」エンジンのエントリーロジックを壊してしまったB2セクションの enteredFirst、pendingShow、開始行を変更しないでください。check.js の wheel 項目が報告します
「なぜこのような角があるのか?」(スクリーンショット添付)矢印が相手のボックスの中心を狙っているか、曲げ点がそれぞれ計算され、小さな折り返しが発生している。同じ経路のデータパケットと線がそれぞれ別の経路をたどっている端点を向かい合う辺に配置し、直線が可能なら直線にし、最大1つの曲げ点にする。データパケットと線は曲げ点を共有する。check.js の bends 項目が報告します。図全体のすべての線を同じ基準で確認する
「Xは独立したYですか?Zの中に描くのは適切ですか?」「この部分は…と呼ぶ方が正確ではないですか?」ボックスのネストが実際の帰属に従っていない(サイドカーをビジネスコンテナ内に描いた)、またはボックス名が内部の呼称を使用しているまず「オブジェクト → 実際の帰属」表を作成してからネストを修正する。外側のボックスにはそれが何であるかを明確に書き、ボックス名を読者の呼称に変更する。同じ種類のボックスは図全体で一緒に確認する

フィードバックを1つ受けたら、まずそのフィードバックが他のステップでも該当するかどうかを考え、一緒に修正します。相手に一つ一つ指摘させるのを避けます。

4. ファイル

ファイル内容
assets/template.htmlテンプレート(エンジン + 4ステップの例)
scripts/check.jsセルフテストスクリプト(10項目 + スクリーンショット)
references/storyboard.mdストーリーボードの書き方、実際の12ステップのストーリーボード
references/engine.mdテンプレート構造、小さなツール、画面のパターン、落とし穴、セルフテストの実行方法
references/lessons.mdいくつかの完成品からのフィードバック記録(ルールの出典)。ルールでカバーされていないケースに遭遇した場合、ここで最も類似したものを探します

関連スキル