エージェント向けアプリの構築

エージェントが、メンバーが使いたくなる Laze アプリを作る方法。デザインルール、キット、ピン留めと共有、trunk へのプッシュ、自身の作業確認について。

このページは、Laze アプリの作成や変更を依頼された AI エージェント向けです。最初の laze app create の前に読んでください。人は最初の5秒でアプリを判断します。完成して見えるようにし、依頼された場所に置き、準備完了と言う前に自分で確認してください。

ワークフロー#

1. 依頼された会話で作成します:

   laze app create "Insights" --channel <channel>

   アプリは空の状態で始まり、あなた専用のフォルダーがあります。index.html から始め、次に laze app push を使ってゼロから作成します。--channel は、その会話のタブとしてアプリをピン留めします。そこにいる全員とそのエージェントが開いて作業を続けられます（ビルダー）。アプリ名はスラッグではなく、人が読む言葉にします。

   ページからプラットフォームキットとクライアントをリンクします:

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   スライド、デック、トークだけは例外です。これらは唯一のテンプレートである --template slides から始めます。そのファイルがアプリの最初のライブバージョンであり、あなたが変更します。各スライドは slides/ 内の1つのファイルで、slides/deck.json に順番どおりに一覧表示されます。テンプレートの README.md には、スライドの追加、並べ替え、スタイル設定の方法が書かれています。デックにはスライドレール、キーボードナビゲーション、全画面の発表、PDF をエクスポートと HTML をエクスポートのボタンがあります。これらを作り直さないでください。MCP 経由では、template: "slides" を使った create_app が同じことを行い、write_app_files は一度に1枚のスライドを変更します。

   スライドテンプレートは新しいデック専用です。人が送ったファイルがすでにページまたはデックである場合、たとえば HTML エクスポート、index.html を含む zip、静的サイトなどは、そのまま公開します。--template なしでアプリを作成し、先頭に index.html を置いてファイルをフォルダーに展開し、CDN から読み込んでいるスクリプトがあればアプリ内にコピーして、プッシュします。添付ファイル付きで「ここに移動して」や「これをここに置いて」と言われた場合は、そのとおりに行います。意味を聞かないでください。

2. 既存のアプリ は、リンク付きメッセージではなく、ピンとして会話に入れます:

   laze app pin <app> --channel <channel>

   --role editor はメンバーがデータを変更できますがコードは変更できません。--view-only は見ることだけを許可します。laze app pins <channel> はタブを一覧表示します。誰かがピン留めを外したアプリを、再度ピン留めしてはいけません。

3. データの形を決めます。laze.app.json で、ものの種類ごとに1つのコレクションを作り、型付きフィールドと少数のシードレコードを用意します。データはレコードに置き、ページのコードには置きません。数値、行、テキストをハードコードしたページは誤りです。データが変わったら、プッシュしなくてもアプリが変わる必要があります。

4. ページを変更します。その後、ライブにする前にローカルで確認します（自分の作業を確認する を参照）。

5. プッシュします:

   laze app push -m "Added the pipeline board" --seed

   すべてのプッシュは即座にライブアプリになります。下書き、ブランチ、プルリクエストはありません。アプリはトランクベースです。メッセージは、メンバーにとって何が変わったかを普通の文で書きます。--seed は、まだレコードがないコレクションだけに入力します。

6. 戻る。プッシュが誤っていたときは、laze app versions、次に laze app revert <version> -m "<why>" を実行します。これは新しいライブバージョンです。レコードは失われません。アプリ内の git 履歴はこのためだけにあります。

開ける人#

新しいアプリは制限付きです。会話にピン留めされたアプリは、そこにいる全員が開けます。そのため、チームアプリに必要な共有は通常ピンだけです。チャンネルで依頼された場合、依頼した人だけにアプリを共有しないでください。そのチャンネルにピン留めします。公開範囲は、依頼されたときだけ laze app access visibility internal|public で広げます。管理者の承認が必要な場合は、コマンドに表示されます。laze app members は今開ける人を表示します。アプリの準備ができたと伝える前に確認してください。

デザインルール#

レイアウトではなく、アプリの主題から始めます。その主題に関心がある人ならホワイトボードにどう描くかを考え、それを作ります。脅威モデルは攻撃マップ、ロードマップはタイムライン、予算はお金の流れ、プロセスは図です。統計タイルと箇条書きだけのページはレポートのように見えます。それは避けるべきアプリです。

とにかくビジュアルにしてください。できる限りモーショングラフィックスやフローを使い、相手が完全に理解できるよう一歩ずつ案内します。文字の壁は絶対に書かないでください。言葉が必要なところは、簡単で短い文にします。アプリは人が理解するためのものであり、自分の頭の中を吐き出す場所ではありません。

Laze キットはプラットフォームから取得します（/_laze/theme.css、/_laze/kit.css、/_laze/laze.js）。これは埋めるためのレイアウトではなく、道具箱です。トークンと必要なコントロールを使い、その上に自分の CSS を自分のファイルで置きます。キットをアプリにコピーしてはいけません。

• ビジュアルを最初に。 主題の絵をアプリそのものにします。インライン SVG、canvas、地図、タイムライン、図など、人がクリックして探索できるものです。キットのトークンを使い、自分のレイアウトと動きで独自の見た目にします。
• 画面ごとに1つの仕事。 最初の画面は、そのアプリが存在する理由の問いに答えます。2つ目の仕事は最初の下ではなく、タブ（lz-tabs）に置きます。
• 適切な形。 人が行を見比べたり動かしたりするならテーブル（lz-table）またはボード（lz-board）を使います。1つの数値が要点なら統計タイル（lz-stats、lz-stat-value）を使います。時系列の数値にはチャート（lz-chart）、短い手順には番号付きステップ（lz-steps）を使います。3行を超えるテキストはアプリではなくドキュメントに置きます。
• 実データ。 メンバーが気にするレコードを、実際の名前と日付で表示します。「Lorem」、「Item 1」、プレースホルダーのチャートは使いません。ページ上のすべての主張は、レコードまたはリンクから来る必要があります。
• タイプスケール。 ページタイトルは1つ（lz-title）、その下の行は1つ（lz-lede）、セクションタイトル（lz-h2 または lz-card-title）、本文を使います。他のサイズを追加しないでください。
• 余白。 page（lz-page）、card（lz-card lz-card-body）、grid（lz-grid、lz-row）クラスを使います。12〜20 px のリズムを保ちます。カードの中にカードを重ねないでください。
• 両方のテーマ。 色はトークン（var(--color-fg)、var(--color-bg-surface)、var(--color-primary)、var(--color-border) と lz-badge-* のトーン）からだけ使います。16進カラーはダークモードを壊します。
• 狭い幅。 アプリは約 380 px 幅のサイドパネルで開きます。テーブルセルに data-label を指定して行が積み重なるようにし、ヘッダーは1行に収めます。
• 空とエラー状態。 空のリストでは、何が表示される予定か、最初の1つをどう追加するかを説明します。呼び出しに失敗したら Laze.fail(error) を表示します。空白ページにしてはいけません。
• ステータスはバッジで。 状態は色付きテキストではなく、lz-badge とトーン（-success、-warning、-danger、-info、-primary）で表示します。
• フォームは邪魔にならない場所に。 「新しい項目」はボタンの後ろに置きます。リストがメインコンテンツです。

キットリファレンス#

スクリプトはアプリ自身のオリジンからだけ読み込まれます。CDN の <script> は拒否されるため、必要なライブラリはアプリフォルダーにコピーします。claude.ai artifact や別の React ページを移植する場合は、プッシュする前に JSX をコンパイルし（例: npx esbuild app.jsx --bundle --minify --outfile=app.js）、ビルド済みファイルをリンクします。ブラウザー内 Babel も使えますが、開くたびに数 MB を読み込みます。

ページスクリプトでは、Laze.records("<collection>") がレコードの一覧表示、作成、更新、削除を行い、Laze.subscribe が変更時に再読み込みし、Laze.h が要素を作り、Laze.mount がそれらを描画します。

キーボードショートカット#

Laze は、アプリが処理しない限り、Laze 自身のショートカットをアプリから Laze に渡します。そのため、メンバーは先にアプリの外をクリックしなくても、Cmd+K（Windows と Linux では Ctrl+K）を押してアプリから移動できます。渡されるショートカットは、Cmd+K、Cmd+[ と Cmd+]、Cmd+1 から Cmd+9、Cmd+Shift+A、Cmd+Shift+T、Cmd+Shift+M、Cmd+Shift+D、Cmd+.、Cmd+/、さらにテキストフィールド外の Alt+Up と Alt+Down です。それ以外のキーはすべてアプリ内に残ります。

これらの1つをアプリで使いたい場合は、そのキーを処理して event.preventDefault() を呼び出します。すると Laze はそのキーに関与しません:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

自分の作業を確認する#

プッシュする前に、すべての変更を確認します:

laze app serve --port 4173

これは、プラットフォームキットとライブアプリのレコードを使って、http://127.0.0.1:4173/ でフォルダーを読み取り専用で配信します。ライブバージョンが必要なので、最初に一度 laze app push を実行します。ブラウザーツールで開き、両方のテーマとパネル幅でスクリーンショットを撮ります。例:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

各画像を確認します。はみ出すテキスト、収まらない列、ダークモードで消える色、まだ「demo」と表示されているものを修正します。

アプリを投稿する前に:

• 依頼された場所にピン留めされていて、laze app members に開けるべき人が表示されている。
• 最初の画面が、スクロールなしで依頼に答えている。
• ライト、ダーク、390 px のスクリーンショットが完成して見える。
• メッセージにアプリ名と、それが何をするかの1行がある。会話のタブがリンクです。

不明なときは聞く#

間違ったものを作る代わりに、短い質問を1つだけしてください。すでに依頼された手順について「進めて」の返事を待たないでください。このチャンネルでアプリを依頼されたなら、そこで作成し、ピン留めして、伝えます。