codepawl/machine-anatomy

Machine Anatomy

共有キット：新しい機械は、そのモデル、レイアウトと描画、ライブフック、事実のみを記述します。 キットがページ、テーマとスタイル、ズームフレーム、分解図、トゥルースリント、 レコーダー、サウンド、チェックを担当します。 動作例は examples/edison-light-bulb/ です；その構造をコピーしてください。

1. 一度だけ質問し、その後構築する

コードを書く前に、ホストの質問ツール（Claude Code では AskUserQuestion）を使用して、1回のラウンドでユーザーに質問をしてください。各質問には推奨デフォルト値を設定し、ユーザーが既に述べた内容はスキップします。その後は追加のゲートなしで進めてください。質問、デフォルト値、各回答が設定にどうマッピングされるかは references/intake.md を参照してください。

2. 調査、そして事実

実際の情報源（特許、製作者の論文、博物館のページ、百科事典）を読んでください。reference/notes.md に URL と引用文を書き、次に facts.json を作成します：事実ごとに 1 エントリとし、text、source、quote または note、status（verified または inferred）を含めます。ルールと lint が強制する内容は references/truth-control.md を参照してください。情報源から機械のすべての機能とその設定を functions にリストアップします。

次に、機械とその設定の実際の写真または図面を少なくとも 3 点収集し、reference/images/ に sources.json とともに保存します。描画前にそれぞれを開いてください。すべてのアセンブリは、その描画元となった画像を名前で参照します。lint がこれを強制し、record は shots/reference-compare.png を書き出して照合します：references/reference-images.md を参照してください。

3. 機械フォルダを構築する

node cli.mjs new <folder> --title "..." で Edison の例からスキャフォールドします。以下の順序で置き換えてください：

1. model.mjs — 純粋なモデル、DOM なし；すべての動作と表示される数値。test-model.mjs で実際の値または不変条件に対してテストします。テストは必須です。
2. layout.mjs — ワールド単位でのサイズと計算された曲線（パスは実際の部品に従い、コードにはしません）。
3. figure.mjs — drawFigure(draw)：実際の部品をキットのヘルパーを使用して番号付きアセンブリの項目として描画します；ラベル、defs、CSS、バッジアンカー、ステップポイント、ズームターゲットを返します。
4. live.js — createMachineHooks(kit)：状態、可動部品の描画、コントロール、読み出し、アクション。ばね、慣性、ジョイントには kit.Motion を使用します：references/motion.md を参照してください。
5. machine.mjs — 分解軸と出典を持つアセンブリ、すべての表示テキストは { text, facts } として、読み出しテンプレート、コントロール、フィルムストーリー、サウンドボイスを含めます。

各ファイルを書く前に、対応する例のファイルを読んでください。ビルドされた *.html ファイルは読まないでください。

4. 見た目

テーマと描画スタイルは独立したレイヤーです：references/themes-and-styles.md を参照してください。デフォルトは machine.mjs（theme、style）で設定します。ページで ?theme= と ?style= を使って切り替えられます。

5. フィルムとサウンド

デフォルトのフィルムは承認された 30 秒の形状です（動作中から開始、1 回のズームイン、1 回のスローラベル付き動作、コントラストのある瞬間を含む通常動作、段階的な分解、再組み立て、最後に動作中で終了）：references/film.md を参照してください。サウンドは静かな近接マイクタップ音で、ビープ音やリミッターはありません：references/sound.md を参照してください。フィルム投稿用のキャプションルール：references/caption.md を参照してください。

6. コマンドとチェック（引き渡し前にすべて必須）

node cli.mjs lint   <folder>     # テキストを事実、情報源、最上級表現、出典に結びつける
node cli.mjs test   <folder>     # モデルテスト
node cli.mjs build  <folder> [--format 16:9,9:16,square]
node cli.mjs audit  <folder>     # 分解図の描画順序と透過チェック
node cli.mjs verify <folder>     # ヘッドレスChromeで実際のページを各テーマ・スタイルでチェック
node scripts/lines.mjs <folder>/<slug>-anatomy.html   # テクスチャ線が何かで終わっていること
node cli.mjs record <folder> [--format 9:16] [--style dither] [--no-sound]
node cli.mjs remux  <folder>     # 録画フレームに対するサウンドのみの変更
npm test                         # キットのユニットテスト

Playwright はバンドルされていません：npm install --no-save playwright を実行するか、MACHINE_ANATOMY_PLAYWRIGHT に既存の Playwright の index.mjs を設定してください。録画は通常の優先度より低く、GPU なしで実行されます。

その後、shots/<variant>/video-sheet.png、3 枚のスチル、verify のスクリーンショット、shots/reference-compare.png を自分で開き、クリッピング、重なり、読みにくいテキスト、スイミングパターン、および参照画像との宣言された単純化以外のすべての差異を修正してください。

オーナーが設定したルール（チェックが存在する場合は強制されます）

• 何も何かを覆ってはいけません：record と verify で 1 つの衝突チェックを行います（references/film.md）。物理的に実際の重なりがある場合のみ、その理由とともに film.overlapAllowed で宣言してください。
• 機械を実際の完全な設定（質問 10）で、出典付きで表示してください。
• 被写体はすべてのフェーズでフレーム高さの少なくとも 25% を占め、主要なイベントは画面上で発生します（minimum.subject、film.onScreen）。可動機械は hooks.camera() でカメラを動作させます。
• パターンは表面に固定され、スイミングしてはいけません。scripts/swim.mjs で測定してください（references/themes-and-styles.md）。
• 火、蒸気、煙、グローは kit/effects.mjs を使用し、モデルによって駆動されます（references/motion.md）。
• すべての可動部品は動作しているか、その理由が明記されている必要があります。描画され、能動的な原因のない動きは禁止です。圧縮された時間は画面上に表示されます（references/completeness-and-causality.md、lint と record）。

レポート

ページ、公開フラグメント、フィルムのパス；lint、テスト、監査、verify、lines のカウント；ラウドネス、トゥルーピーク、フィルムのスペクトラム（誰も聴いていないことを明記）；フィルムのタイムライン；各キャプションの事実とその出典；簡略化、推測、未検証の内容。

クレジット：Ryan による Anatomy をベースに構築（github.com/wheresryan22/anatomy、MIT）。THIRD_PARTY_NOTICES.md を参照してください。