mowgli

Mowgli Sync

Mowgliは、AIを活用したプロダクトのデザインとスコープ設定のためのツールです。この スキルを使うと、Mowgli にプログラムからアクセスできる mowgli CLI を通じて、実際のコードベースからデザインを Mowgli プロジェクトにプッシュし、またプルして戻すことができます。

Mowgli は、デザインをすばやく反復できる Figma のようなキャンバスです。ユーザーは大幅な変更や細部の調整を行い、さまざまな形式にエクスポートしたり、プロトタイプを作成したり、バージョン履歴を利用したりできます。ユーザーはアプリやウェブサイトなどのプロジェクトについて、視覚的な実験、再デザイン、比較、アイデア出しを行うために Mowgli を使っている場合があります。コーディングエージェントとして、実際のコードベースと Mowgli プロジェクトの連携を支援してください。

作業を始める前に、このドキュメント全体を読んでください。最も重要な点は、Mowgli プロジェクトは仕様に基づいているということです。画面、SPEC.md、frontend.xml は常に同期させてください。edit コマンドはベストプラクティスに従い、この3つを自動的に処理します。

---

1. Mowgli プロジェクトとは

Mowgli プロジェクトでは、プロダクトのフロントエンドを、自己完結した小規模なファイルセットとしてモデル化します。

• SPEC.md - マークダウン形式の仕様書です。エレベーターピッチ、ユーザージャーニー、データモデルを記述します。

• frontend.xml - <frontend_common> ブロック（共通のクロームに関するメモ）に続いて、<screens> リストが記述されています。各 <screen> エントリーは次のようになります。

  <screen name="Account Settings" component="SettingsScreen">
    <summary>One-line description of the screen.</summary>
    <contents>
      The overall content and design elements, deliberately staying away from tiny
      details (exact layout, colors, spacing). Markdown bullets are fine here.
    </contents>
    <state id="default" name="Active Subscriber">1-2 sentence description.</state>
    <state id="freePlan" name="Free Plan">...</state>
  </screen>
  

  • component は .tsx ファイル名（{component}.tsx）と一致し、コンポーネント名になります。name は人が読むためのタイトルです。
  • <summary> は1行の説明で、<contents> はより詳しい、ただし引き続き概要レベルの説明です。
  • 各 <state> には id（コンポーネントの state prop に渡されます）、name、本文として1〜2文の説明があります。

• <id>.tsx - 画面ごとに1つの React コンポーネントです。このコードには次の制約があります。

  • アイコンは lucide-react のみを使用します。
  • スタイルには bg-[#abcdef] や text-[#0F172A] などの正確なクラスを指定した 純粋な Tailwind を使用します。
  • すべての Google Fonts が、たとえば font-['Open_Sans'] のような任意のフォントファミリー構文で利用できます。
  • コンポーネントは state prop を1つだけ受け取り、該当する state を描画します。

標準的な画面ファイルは次のようになります。

import * as React from 'react';
import * as Icons from 'lucide-react';

export type OnboardingScreenProps = { state: string };

/**
  ...docs about OnboardingScreen...
  States:
  - `step1`: Step 1, consisting of a name for the user's first event, and a skip
    button to avoid creating a first event.
  ...
*/
const OnboardingScreen = (props: OnboardingScreenProps) => (
  <div className="min-w-full h-full overflow-y-auto">
    <div className="bg-[#abcdef] text-[#112233] text-lg">Onboarding</div>
    {/* ... */}
  </div>
);

export default OnboardingScreen;

frontend.xml、特に画面の説明と state のリストは、.tsx の全内容がトークン数の点で多すぎる場合に、画面の要点を簡潔に伝える重要な記述として使用されます。正確な内容に保ってください。

Mowgli はバージョン管理されています。プロジェクトには HEAD（現在のバージョン）と直線的な履歴があります。edit を実行するたびに新しいバージョンが作成されます。プロジェクトごとに1つの自由形式文字列を保存するプロジェクトレベルのメタデータと、バージョンごとに1つの自由形式文字列を保存するバージョンレベルのメタデータがあり、コードベースと Mowgli の関係を時系列で追跡するために使用します。

---

2. CLI

インストールせずに npx mowgli-cli ... で実行できます。すべての出力は JSON または生の文字列として標準出力に書き込まれ、終了コードで成功または失敗が示されます。サーバーのデフォルトは https://app.mowgli.ai です。--base-url <url> または $MOWGLI_BASE_URL で変更できます。

コマンド	内容
mowgli login / mowgli logout	保存済みの認証情報（ブラウザーで承認された CLI の許可）を管理します
mowgli projects	認証情報でアクセスできるプロジェクトを一覧表示します
mowgli -p <projectId> info	プロジェクトレベルの相互運用メタデータを含む、プロジェクト情報を表示します
mowgli -p <projectId> set-meta [text]	プロジェクトレベルのメタデータを読み取るか、設定します（テキスト引数または標準入力）
mowgli -p <projectId> versions [--limit N --offset N]	ページ分割されたバージョン履歴を表示します
mowgli -p <projectId> version <n>	1 つのバージョンを表示します
mowgli -p <projectId> version <n> set-meta [text]	バージョンレベルのメタデータを読み取るか、設定します
mowgli -p <projectId> files [--version <v>]	論理ファイル（SPEC.md、frontend.xml、画面）を一覧表示します
mowgli -p <projectId> read <path> [--version <v>]	1 つのファイルの内容を出力します
mowgli -p <projectId> diff [--stat] [--from <v> --to <v>] [paths...]	統合 diff、または --stat の概要を表示します
mowgli edit --lint -f <file>...	オフラインでの事前チェック：-f ファイルからインポートされているものの、提供されていないローカルファイルを検出します（API 呼び出しなし）
mowgli -p <projectId> edit [--instruction <text>] [-f <file>]...	Mowgli エージェントを通じて自然言語による編集を適用します

コマンドの例

# Who can I see? (find the target project's id)
mowgli projects

# First-contact recon on a project
mowgli -p <projectId> info                 # includes the project metadata string
mowgli -p <projectId> versions --limit 20  # history; check userdata on recent versions
mowgli -p <projectId> files                # what screens exist at HEAD
mowgli -p <projectId> read SPEC.md
mowgli -p <projectId> read frontend.xml
mowgli -p <projectId> read DashboardScreen.tsx

# What changed between two versions (cheap overview, then full patch)
mowgli -p <projectId> diff --stat --from 6
mowgli -p <projectId> diff --from 6 --to 9 DashboardScreen.tsx

# Write project metadata (first connect) - via stdin
echo "Codebase: github.com/acme/app (branch main, commit a1b2c3d).
Stack: React 18 + TS, Tailwind v3 semantic tokens, lucide-react. Font: Geist.
Path map: DashboardScreen.tsx <- src/pages/DashboardPage.tsx (+ ShellHeader, Dropdown).
Theme: light only; token->hex bg #FFFFFF, fg #0F172A, primary #E51A4C ..." \
  | mowgli -p <projectId> set-meta

# Apply an edit: instruction on stdin, real source files appended with -f
mowgli -p <projectId> edit \
  -f src/pages/DashboardPage.tsx \
  -f src/components/ShellHeader.tsx \
  -f tailwind.config.ts \
  < /tmp/dashboard-instruction.txt

# Record what you did on the resulting version
mowgli -p <projectId> version 7 set-meta "Synced DashboardScreen from commit a1b2c3d ..."

edit に関する注意事項：

• 指示は --instruction またはパイプで渡された標準入力から取得されます。
• -f <file> を指定するたびに、そのファイルの内容が --- BEGIN FILE: <name> --- / --- END FILE: <name> --- マーカーで囲まれて指示に追加されます。-f を使って、画面、その依存関係、テーマなど、実際のコードベースのソースをエージェントに渡してください。
• 成功すると、エージェントの自由形式のメッセージと簡潔な統計概要が返されます。概要には、vN -> vM のバージョン更新、ファイルごとの A/M/D <path> +added -removed 行、合計、および完全なパッチを確認するための mowgli -p <id> diff --from N --to M が含まれます。完全なパッチはインラインで出力されません。概要に問題がある場合に限り、diff で取得してください。
• diff がない場合、編集による変更はありません。メッセージを読み、指示やコンテキストを修正して、処理全体を新しい呼び出しとして再実行してください。

---

3. Mowgli プロジェクトでの行動規範

前提条件

• プロジェクトレベルの相互運用メタデータ。 コーディングエージェントは、プロジェクトに関連付けられた任意の文字列を読み書きできます。エージェントは、コンテキストにまだ含まれていないプロジェクトに遭遇した際、この情報を必ず読み書きするべきです。このメタデータは、Mowgli プロジェクトに接続されているリポジトリ／コードベース、Mowgli プロジェクトと実際の稼働中の製品との関係（忠実な複製、大規模な製品の一部など）、実際のコードベースにおけるコンポーネントライブラリとデザインシステムへの準拠状況、実際のコードベースと Mowgli プロジェクト間のパスの対応関係やディレクトリ構成に関する情報を特定するために使用してください。
• バージョンレベルの相互運用メタデータ。 Mowgli ではバージョン管理が全面的に行われます。プロジェクトには HEAD（現在の）バージョンがあり、作成以降の変更が直線的なバージョン履歴として記録されます。バージョンレベルの相互運用メタデータは、バージョンに関連付けられた自由形式の文字列で、エージェントが読み書きできます。Mowgli とコードベース間で何らかの同期を行う際、エージェントはこの情報を必ず読み書きするべきです。エージェントは、次のような情報を書き込むべきです。
  • エージェントがプロジェクトに適用した編集のコンテキスト（実際のコードベースとの同期や、食い違いの修正など）
  • そのバージョンに対応する現在のコミットの短縮ハッシュ
  • 省略した機能や実際の状態との意図的な差異など、今後エージェントに役立つ追加メタデータ

運用ルール

Mowgli のプロジェクトは仕様に基づいており、画面や状態の表現の忠実性に依存します。

画面に対するあらゆる変更には、アプリケーションの変更を完全に反映した SPEC.md ファイルと frontend.xml ファイルへの適切な変更を必ず伴わせてください。

画面や機能が実際のユーザーフローにどう関わるかを理解するため、アプリケーションのバックエンド側も含め、周辺情報を収集することが特に重要です。単にデザインを Mowgli に反映するだけでは不十分です。Mowgli は仕様駆動型のデザインツールであり、状況に即した提案やブレインストーミングを提供し、プロジェクト全体にわたる変更を可能にするため、SPEC.md と画面デザインが常に同期している必要があります。

さらに、frontend.xml の画面情報、特に状態の一覧は、アプリケーション全体を俯瞰するための、プロジェクトを支える基礎文書として使われます。これはハッピーパスだけを示すものではありません。重要なモーダル、ドロップダウンメニュー、ポップオーバー、画面に関連するすべての状態やサブ状態を漏れなく洗い出し、Mowgli に忠実に反映してください。

画面を変更するたびに、frontend.xml の該当箇所も変更してください。エージェントを介して処理される edit コマンド／エンドポイントを使えば、これらの変更をまとめて適用できます。

プロジェクトに初めてアクセスする際は、必ずプロジェクトのメタデータを確認し、必要に応じて書き込みまたは更新してください。これにより、エージェントのプロジェクトに対する認識と、以前に記録された情報との食い違いを防げます。

Mowgli プロジェクトに変更を加えたら、最後に必ずバージョンメタデータを書き込みます。変更内容の簡単な記録、Mowgli とコードベースのバージョンを結び付けるコミットの短縮ハッシュまたはその他のバージョン識別情報、今後同様の作業を忠実に実施するために必要な追加情報を記録してください。

4. 同期 SOP

Mowgli からコードベースへの同期

1. すべてのプロジェクトを一覧表示します。
2. ユーザーが示しているプロジェクトを特定します。複数の候補があり、判断できない場合はユーザーに確認してください。プロジェクト ID を控えます。
3. 選択したプロジェクトのメタデータを確認します。矛盾する情報が含まれている場合は、ユーザーと確認して解決します。
4. まだ記録されていない場合は、Mowgli プロジェクトに次のメタデータを書き込みます。
   • 現在のコードベース（GitHub 名、目的など）
   • ソフトウェアスタック
   • 使用しているコンポーネントライブラリや、コードベースレベルのその他の詳細（あれば）
   • この初回同期時点の現在のコミット（あれば）
   • 将来のコーディングエージェントの実行時にプロジェクトの背景を再確認するのに役立つ、その他のトップレベルのメモや所見
5. バージョン情報を取得し、バージョンレベルのメタデータタグがあるか確認します。（曖昧な点があれば、ユーザーと確認して解決します。）
6. Mowgli プロジェクトから仕様ファイルと frontend.xml ファイルを取得し、プロジェクトを把握します。前の手順のタグからすでに作業が行われていたことが分かる場合は、差分エンドポイントを使って、最後に確認されたバージョンから新しいバージョンまでの変更を確認します。変更内容を控えてください。
7. 必要に応じて、画面ごとに差分も取得しながら情報を取得し、コードベースに変更を適用します。ユーザーは Mowgli の状態を確認済みなので、これを信頼できる唯一の情報源として扱い、差分で示された範囲に従ってください。変更された内容だけを正確に反映し、それ以外は変更しないでください。バージョンのタイトルや説明から意図を推測しないでください（これらは差分を理解するための背景情報であり、追加の指示ではありません）。ただし、ユーザーが明示的に依頼した場合、または変更を忠実に適用するために意図の確認が不可欠な場合は除きます。
8. 最後にバージョンメタデータを書き込み、日時とコミット情報を記録して、コードベースと同期済みであることを示します。

コードベースから Mowgli への同期

1. 上記の手順 1～2 と同じ方法で、すべてのプロジェクトを一覧表示し、対象のプロジェクトを特定します。 プロジェクト ID を控えておきます。
2. プロジェクトのメタデータを確認します。欠落している、または古くなっている場合は、メタデータ（コードベースの識別情報、ソフトウェアスタック、コンポーネントライブラリ、実際のコードベースと Mowgli プロジェクト間のパスマッピング）を書き込み、更新します。矛盾があれば、先に進む前にユーザーと解決します。
3. バージョン情報を取得し、バージョンレベルのメタデータを読んで、最後に同期したバージョンと記録されたコミットの短縮ハッシュを確認します。これを基準にコードベースの差分を取ります。
4. 基準以降にコードベースで変更された内容を特定し（例：git diff <lastSyncedCommit>）、変更されたソースファイルを、影響を受ける Mowgli の画面、SPEC.md、frontend.xml に対応付けます。記録された基準がない場合は、関連するすべての画面が変更されたものとして扱います。
5. 影響を受ける各画面について、編集エージェントに必要なコンテキストをまとめます。対象の Mowgli ファイルを @メンション（@SPEC.md、@frontend.xml、@<Screen>.tsx）し、実際のコードベースのコードをインラインで貼り付けます。これには、忠実にレンダリングするために必要な依存関係（tailwind.config.ts などのテーマファイル、src/components/ui/button.tsx などの共有コンポーネント、依存関係ツリー内のその他のファイル）も含めます。画面がすでにあるプロジェクトに新しい画面を追加する場合は、変更禁止の参照として既存の画面を少なくとも 1 つ @メンションします。エンドポイントで必須であり、新しい画面をプロジェクト共通の外枠とスタイルに合わせるための基準になります。
6. edit --lint を実行します。1 回の呼び出しで渡す情報は、大きな画面 4～5 画面分以下にまとめます（複雑な変更の場合はさらに減らします）。エージェントが参照または変更する可能性のあるファイルは、すべて同じ呼び出し内で @メンションする必要があります。呼び出しはステートレスなので、毎回、単独で完結する内容にしてください。
7. lint は、インポート階層で不足しているファイルを通知します。lint の出力を確認し、結果に納得できるまで指定するファイル一覧を調整します。その後、最後に edit を呼び出して変更を Mowgli に適用します。
8. 結果を確認します。応答に差分が含まれていない場合、編集による変更はありません。エージェントのメッセージを読み、指示またはコンテキストを修正して、リクエスト全体を新しい呼び出しとして再実行します。残りのバッチについても、手順 5～6 を繰り返します。
9. SPEC.md と frontend.xml に、変更されたすべての画面と状態が反映されていることを確認します。編集エージェントは両ファイルを同期させる想定ですが、システムの残りの部分にとって重要なファイルなので、必ず確認してください。
10. 変更を適用した簡潔な説明、このバージョンが対応するコードベースのコミット短縮ハッシュ、今後の参照用として意図的に異なる点や省略した機能を、生成されたバージョンのメタデータに記録します。

---

5. 優れた edit の作成方法（プッシュの前に毎回お読みください）

edit エージェントは、エージェントを活用しながらも厳密さを重視しており、発想を広げるのではなく、忠実な変換に最適化されています。正規の .tsx 形式、指定されたテーマファイルからセマンティックな Tailwind トークンを正確な 16 進数カラーに解決する方法、SPEC.md と frontend.xml の同期、新しい画面の <screen> エントリの作成方法は、すでに把握しています。これらを指示で繰り返す必要はありません。エージェントが Mowgli 内から把握できない 2 つのことに、指示を集中させてください。

1. -f で指定する、本当のソース

画面と、目に見える UI を描画するすべての依存ファイルです。リーフコンポーネント、テーマ／トークンファイル（tailwind.config、トークンを定義する CSS）、共有ウィジェットが含まれます。UI の一部のソースを省略すると、エージェントはそれを判断する手がかりがなく、独自に作り上げます。説明文が推測や曖昧な内容であれば、エージェントはその推測を忠実に描画します。ほとんどの問題のある実装はここから生じます。以下のインポートツリーと忠実度に関するルールを参照してください。16 進数の一覧を手作業で書き起こすのではなく、テーマファイルを指定してください（エージェントが自分でトークンを解決します）。渡したファイルから対応関係を導き出せない場合に限り、対応関係を明記してください。ソースがライトテーマとダークテーマの両方に対応している場合があるため、どちらのテーマで描画するかを指定してください。エージェントは推測しません。-f でファイルを渡すからといって、事前にそのファイルを読む必要はありません。エージェントは渡されたファイルを読み取るため、ファイル名を指定してリーフを惜しまず渡し、ご自身で読む時間は動作の把握に使ってください（以下の、まず lint を行うという注意事項を参照）。

2. プロジェクトの理解――本当のアルファ

これは頭の中や、単一のファイルではなくコードベース全体に存在するため、あなたにしか提供できない情報です。簡潔に伝えてください（エージェントが内容を膨らませるため、詳しく書きすぎないようにします。ただし、曖昧に済ませないでください）。

• 各画面が何であり、プロダクト内でどのような役割を担うのか。
• 画面同士がどうつながり、ユーザーがどのように画面にたどり着くのか。エントリーポイント、ナビゲーション、画面が属するフローを含めます（画面ファイルだけでなく、ルーティングとバックエンドも確認してください）。
• 画面が扱うユーザージャーニーと、データモデルのエンティティ／フィールド。
• 画面ごとの状態の完全な一覧（最初の状態がデフォルト）。画面が描画できる状態を列挙できるのは、コードを確認したあなただけです（以下の状態に関するルールを参照）。

引き続き必要ですが、手間はかかりません

• エージェントが読み取りまたは変更する可能性のある、Mowgli 側のファイルをすべて @ メンションしてください（@SPEC.md、@frontend.xml、@<Screen>.tsx）。ファイルの可視性は厳密です。エージェントが必要とするファイルがメンションされていない場合、リクエスト全体を拒否します。
• 空ではないプロジェクトに画面を追加する場合は、既存画面を少なくとも 1 つ @ メンションしてください（@<ExistingScreen>.tsx）。@SPEC.md と @frontend.xml だけでは不十分です。エンドポイントの要件であり、満たさない場合は拒否されます（「コンテキストに既存画面を少なくとも 1 つ含めてください」）。これは形式的なものではなく、重要な指定です。既存画面を参照することで、エージェントは共通の UI（ヘッダー、ナビゲーション、フッター）、配色、レイアウトの慣例を把握し、新しい画面が微妙にずれることなく調和します。参照専用となるよう、変更禁止に指定してください（次の項目を参照）。
• 既存プロジェクトに追加する場合は、「変更禁止」の範囲を明記してください。バイト単位で変更せず、そのまま維持する必要がある既存の状態／画面を指定します。

まず lint でツリーを把握し、その後は編集のたびに必ず lint を再実行してください（省略しないこと）

プッシュの失敗で最もよくある原因は、UI を実際に描画する子コンポーネントを含めずに親コンポーネントを送信し、子について記憶を頼りに説明してしまうことです。エージェントはその推測を忠実に描画するため、画面が誤ったものになります。

そのため、読み始める前に lint を早めに実行してください。ルートファイル（ページ／画面と、おそらくその最上位のビュー）だけを対象にすれば、リーフを1つも開かずにインポートツリー全体を低コストで列挙できます。

mowgli edit --lint -f src/pages/DashboardPage.tsx

出力されたツリーが UI を描画するファイルのマップです。これを使って送信するファイルを決めてください。また、大半のリーフコンポーネントは、すべてを読まなくても、名前を指定して -f で追加するだけで済みます。エージェントは渡されたソースを読みます。ボタン、カード、バナー、テーマファイルを転送するためだけに、事前に読む必要はありません。読み込みにはコストがかかるため、その価値があるところに時間を使いましょう。画面の目的、ユーザーフローとエントリーポイント、データモデル、状態の全一覧（セクション5.2）といった、PRODUCT BEHAVIOR の把握に使ってください。ソースだけでは分からないこと（たとえば、内部状態のどれを描画するか）を説明する必要がある場合に限り、リーフを事前に読んでください。ファイルを低コストで転送し、動作を深く読む方が、ツリー内の全ファイルを開くよりもはるかにトークン効率が高くなります。

その後、ファイルセットを確定したら、送信するすべてのファイルを対象に最後の lint を実行し、edit を呼び出す前に [missing] のノードをすべて解決してください。

mowgli edit --lint -f <every file you plan to send>

[missing] がある場合は、それぞれ意図的に判断してください。ファイルを -f で追加するか、目に見える UI を描画しないもの（フック、型、コンテキスト、純粋なロジックのユーティリティ）だと判断し、その理由を記録してください。未確認の [missing] を残したまま edit を実行するのは許容されません。確認していないそのリーフこそ、誤った状態で戻ってくるファイルです。

このチェックはベース名のみを対象とし、npm の単独パッケージとアセットは無視するため、確実な判定ではなく候補を示します。解決できないパスエイリアス経由で読み込まれる子コンポーネントは検出できず、[ok] が意味するのも、同じベース名のファイルが提供されたということだけです。そのため、問題のない実行結果は最低ラインと考えてください。リーフまでの描画経路を実際に読み、画面を把握する必要があることに変わりはありません。

状態の列挙（ここを手抜きしないこと）

「状態」とは、見た目が異なる描画のことです。次の方法で見つけてください。

• オーバーレイの表示を制御するすべての真偽値（モーダル、確認ダイアログ、インラインフォーム用の useState(false)）を追跡します。開いた状態と閉じた状態は、それぞれ別の状態です。
• 複雑なコンポーネントを単一の状態ではなく、状態マシンとして扱います。1つのモーダルにも内部のステップがある場合があります。プラン選択画面から、課金プレビュー、料金リファレンス、チーム作成、キャンセル確認の各サブビューに分岐するなら、それぞれを独立した状態として列挙してください。
• 通常の成功パターンだけでなく、空、読み込み中、エラー、成功の各パターンも対象にします。

バッチサイズ

• 新しい画面： edit の呼び出し1回あたり、概ね2～5画面にします。新しい画面の .tsx ごとに、同じ edit 内で frontend.xml に対応する <screen> エントリーを必ず追加してください。これがない場合、"has no spec" というエラーで編集が拒否されます。画面を作成するときは、この点をエージェントに明示してください。
• 複雑な単一画面（状態が多い、またはレイアウトが大規模）：呼び出し1回につき1画面にします。数だけでなく、複雑さに応じて規模を調整してください。
• 既存画面への段階的な追加を1状態ずつ行わないでください。必要以上に細かくなります。既存画面には、1回の編集で複数の状態を追加してください。

反射的に確認せず、シグナルを見極める

編集の応答には、すでに統計の概要（変更したファイル、ファイルごとの +/-、バージョン更新）が返されています。それを読んでください。よくあるケースとして、期待どおりであれば、つまり適切なファイルが変更され、新しい画面には想定どおりの行が追加され、「変更禁止」と指定したものには手が加えられていなければ、完了です。次に進んでください。編集のたびに反射的に .tsx と frontend.xml を再度 read しないでください。たいてい問題なく動いた結果を確認するためだけに、トークンと時間を浪費します。

概要を見て確認する理由がある場合に限り、diff --from N --to M でパッチ全体を取得するか、ファイルを再度 read してください。理由としては、差分がない（編集で何も変わっていないため、修正して再実行する）、予期しないファイル構成、疑わしい行数（「小さな」変更でファイル全体を書き換えた、または「追加」の変更で行が削除された）、変更禁止ファイルに手が加えられている、あるいはユーザーから問題が報告された場合などがあります。

---

6. 苦労して学んだ教訓（避けるべき忠実度の失敗パターン）

これらは、実際に問題のある結果になった作業から得た教訓です。原因はすべて指示、またはコンテキストの選択にあり、エージェントのせいではありません。

• インポートツリーをリーフコンポーネントまでたどってください。ビューやページで止めてはいけません。 AppHeader.tsx、DesignView.tsx、ChatPanel.tsx などの親コンポーネントを指定するだけでは不十分です。実際の UI が、その親がインポートする子コンポーネント（HeaderActions、CanvasControls、ChatBubble、質問カードのラッパー）にある場合があるためです。親だけを渡し、子について記憶を頼りに説明すると、子の再現は間違ったものになります。表示される UI を構成するインポート済みコンポーネントをそれぞれ開き、-f で渡すか、実際のソースに基づいて説明してください。mowgli edit --lint は、まさにこの確認を強制するためのものです。プッシュの前に必ず実行し、報告された [missing] をすべて解消してください（セクション 5 のゲートを参照）。これは、オートパイロット状態で送信するのを防ぐための強制措置であり、自分でレンダリングパスを読むことの代わりではありません。
• 「それらしいアイコンを使う」「代表的なボタンをいくつか使う」と曖昧に指示してはいけません。 それは捏造を指示することになります。実際には 7 つのコントロール（クレジット、フィードバック、共有、プレゼンス、MCP 接続、エクスポート、テーマ）があるヘッダーでも、2 つしか名前を挙げなければ、2 つしか描画されません。
• 実際に異なる状態をひとまとめにしてはいけません。 「状態 B：テキストだけ異なる状態 A」と説明すると、渡したソースに異なるレイアウトが示されている場合でも、ほぼ同じ画面が生成されます。構造上、実際に何が異なるかを説明してください。
• サンプルデータを使っても構いませんが、明記してください。 自分で考えた価格、名前、日付、文言は、ライブ API のデータではありません。将来の同期で実データと誤認されないよう、値が代表的なサンプルであることをバージョンメタデータに記録してください。
• 編集はステートレスです。 前回の編集の会話に追加することはできません。編集を拒否された場合や結果が間違っていた場合は、修正済みの指示全文と、新たに必要になったファイルをすべて含めて、新しい呼び出しとして再実行してください。
• 並行実行： プロジェクトで別のアクションがすでに実行中の場合、アクションは失敗します。編集は順番に実行してください。各 edit は現在の HEAD を基に構築されます。
• シェルのクォート（zsh）： zsh ではクォートされていない変数は単語分割されないため、変数でフラグを組み立てると（B="--base-url x"; mowgli $B ...）、1 つの引数として渡されます。フラグはコマンドに直接書くか、引用符で囲むか、配列にしてください。

---

7. 初回同期チェックリスト

ユーザーからコードベースを Mowgli にプッシュするよう依頼された場合：

1. mowgli projects -> プロジェクト ID を特定します（あいまいな場合は確認します）。
2. mowgli -p <id> info -> プロジェクトのメタデータを読み取り、矛盾があればユーザーと確認します。メタデータが欠落または古い場合は、更新または書き込みを行います（コードベース、スタック、コンポーネントライブラリ、パスマップ、テーマトークン->hex テーブル、現在のコミット）。
3. mowgli -p <id> versions -> 最後に同期したコミットの最新バージョン userdata を読み取ります。これを差分の基準点とします。
4. 変更されたソースファイルを、影響を受ける画面 + SPEC.md + frontend.xml に対応付けます。
5. 画面ごとに、まず mowgli edit --lint -f <page file> を実行して、インポートツリーを手早く把握します。ページ（およびルーティング／バックエンド）を読み、その画面の役割、ユーザーがその画面にたどり着く方法、関係するユーザージャーニー／データ、状態の全一覧を理解します。読み取りの目的は動作の理解であり、末端の要素を書き写すことではありません。ページ + UI の末端要素 + テーマを -f で渡します（末端要素は未読のまま名前だけ渡しても構いません）。画面がすでにあるプロジェクトに追加する場合は、変更禁止の参照画面として既存の画面を 1 つ @-メンションします。役割、つながり、ユーザージャーニー、状態を中心とした正確な指示を書き、変更禁止の範囲があれば明記します。mowgli edit --lint -f <all files> を再実行し、すべての [missing] を解決します（追加するか、UI を描画しないことを確認します）。把握されていない missing がある状態で edit を実行してはいけません。その後で初めて edit を実行します。1 回の実行につき、単純な画面なら 2～5 件、複雑な画面なら 1 件をまとめて処理します。
6. edit の統計サマリーを読み、問題がありそうな場合に限り diff／再度 read します（差分がない、予期しないファイル構成または行数、変更禁止ファイルに手が加えられている）。差分がない場合や問題がある場合は、最新の状態で再実行します。
7. mowgli -p <id> version <n> set-meta -> 変更内容、コミットの短縮ハッシュ、および意図的な相違／省略事項を記録します。