--- title: "AI 開発 Skill — zenit Zig UI ドキュメント" description: "Claude Code などの AI Agent 向けの開発マニュアルです。インストールすると、Agent は zenit の UI を書くときにまず既存コンポーネントを選び…" url: https://zenit.z.express/ja/docs/guide/ai-skill language: ja alternate_en: https://zenit.z.express/docs/guide/ai-skill.md alternate_zh: https://zenit.z.express/zh/docs/guide/ai-skill.md alternate_es: https://zenit.z.express/es/docs/guide/ai-skill.md alternate_ko: https://zenit.z.express/ko/docs/guide/ai-skill.md alternate_fr: https://zenit.z.express/fr/docs/guide/ai-skill.md alternate_de: https://zenit.z.express/de/docs/guide/ai-skill.md project: zenit v0.1.0-alpha (Zig 0.15.2, macOS) source: https://github.com/version-next/zenit --- # zenit UI dev Skill Claude Code などの AI Agent 向けの開発マニュアルです。インストールすると、Agent は zenit の UI を書くときにまず既存コンポーネントを選び、token と recipe でスタイルを付け、zenit のライフタイムに沿って状態を管理し、引き渡す前に自らビルドしてスクリーンショットで確認します。 ## ダウンロード アーカイブの中身は標準的な Agent Skill フォルダーです。エントリーの `SKILL.md` は短く、ルールと判断表だけを載せています。詳細は `references/` に分割されており、Agent は必要なときだけ読むのでコンテキストを圧迫しません。 [Skill をダウンロード.zip · 54 KB](https://zenit.z.express/downloads/zenit-ui-dev.zip)[SKILL.md を見る](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md) zenit-ui-dev/ SKILL.md9.6 KB references/ app-architecture.md7.2 KB components.md8.3 KB macos-native.md8.2 KB pencil-design.md7.9 KB performance.md4.1 KB pitfalls.md8.5 KB project-setup.md8.1 KB state-reactivity.md7.8 KB styling.md5.8 KB ui-tree-layout.md6.1 KB verification.md5.7 KB tools/ design\_diff.ts20.6 KB png.ts3.6 KB shot.ts3.7 KB ## インストール 1. **Skill フォルダーに置く** 個人で使うなら `~/.claude/skills/` に置けば全プロジェクトで有効です。チームで共有するならリポジトリの `.claude/skills/` に置いてコミットすれば、クローンした全員が使えます。 2. **Agent のセッションを再起動** Claude Code はセッション開始時に Skill をスキャンします。新しいセッションを開き、`/skills` に `zenit-ui-dev` が表示されればインストール完了です。 3. **いつもどおり依頼する** zenit の UI に関わるタスクでは自動で読み込まれます。「zenit-ui-dev skill を使って」と明示してもかまいません。 ダウンロード後、ユーザーフォルダーに展開します（全プロジェクトで有効）： 展開先 ```zig ~/.claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` または、プロジェクトに展開してコミットします（チームで共有）： 展開先 ```zig .claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` ```sh # Codex and other agents that read AGENTS.md: unpack into the repo and reference it unzip -oq zenit-ui-dev.zip -d .agents/skills echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md ``` > NOTE > > **zenit と一緒に更新します。** zenit は 1.0 までは破壊的変更がありえます。zenit をアップグレードしたら、この Skill を再ダウンロードして古いフォルダーを上書きしてください。Skill には対象の zenit バージョンが記載されており、Agent はプロジェクトの API と食い違いを見つけた場合、ソースコードを正とします。 ## 中身 | ファイル | 内容 | | --- | --- | | `SKILL.md` | エントリーポイント：トリガー条件、ワークフロー、厳守ルール、判断表、どの reference をいつ読むか | | `references/app-architecture.md` | 本番運用のエディターを例にした大規模アプリの階層：状態、ビュー、コマンド、サービス | | `references/components.md` | ui.widgets カタログ、2 種類の mount 形式、「デザイン要素 → コンポーネント」対応表 | | `references/macos-native.md` | メニュー、ショートカット、ファイルダイアログ、クリップボード、ドラッグ＆ドロップ、マルチウィンドウ、IME | | `references/pencil-design.md` | Pencil（pen.dev）デザインの再現：MCP での数値読み取り、フィールド対応表、スクリーンショットの数値比較 | | `references/performance.md` | 仮想リスト、dirty レベル、大きなテキスト、バックグラウンドスレッドとメインスレッドの通信 | | `references/pitfalls.md` | zenit と本番アプリの修正履歴から集めた「症状 → 原因 → 正しい対処」 | | `references/project-setup.md` | 新規プロジェクト、build.zig / build.zig.zon、.app のパッケージング、ビルドオプションの転送 | | `references/state-reactivity.md` | bindState / cx.on、Signal / Memo / Effect、Scope のライフタイムとクリーンアップ | | `references/styling.md` | Token → styles.zig → recipe の 3 層、テーマ、ui.arb による逃げ道 | | `references/ui-tree-layout.md` | ノード、Flex レイアウト、サイズ、ノードの更新、表示 / 非表示、座標 | | `references/verification.md` | Agent の自己検証ループ：ビルド、スクリーンショット、E2E harness、DevTools、ログ | | `tools/design_diff.ts` | デザイン PNG とアプリのスクリーンショットを数値比較し、具体的な修正ヒントを出力 | | `tools/png.ts` | design\_diff が使う依存ゼロの PNG デコーダー | | `tools/shot.ts` | ファイル RPC 経由で任意の zenit アプリをスクリーンショット（Retina） | **手作りより先にコンポーネント** デザインの各要素を ui.widgets の既存コンポーネントに対応付け、Agent が box で Button を作り直すのを防ぎます。 **ライフタイムを正しく** bindState、pub deinit、Scope のクリーンアップ、ページ切り替えのルール。最もよくあるリーク、二重解放、ダングリングポインターに直接効きます。 **引き渡す前に自分で確認** Agent にビルド、実行、スクリーンショット、要件との照合までさせ、「コンパイルが通った」で終わらせません。 **実プロジェクトの落とし穴** 本番アプリの修正履歴から整理した問題リスト。それぞれに原因と正しい対処が付いています。 ## おすすめ：Pencil でデザイン [Pencilpen.dev](https://www.pen.dev/) 推奨ワークフロー · PENCIL + SKILL Pencil と組み合わせて、デザインから AI で実装 [Pencil](https://www.pen.dev/) で画面を描き、この Skill を使って Agent に実装させるのがおすすめです。.pen の Flex レイアウト、間隔、角丸、文字サイズ、lucide アイコンは zenit のモデルとよく似ています。Skill にはフィールド対応表と design\_diff 比較ツールが付属しているので、Agent は感覚ではなく数値で再現できます。 [Pencil について](https://www.pen.dev/) 1. 01.penPencil のデザイン 2. 02MCPAgent が正確な数値を読む 3. 03zigwidgets + token で zenit コード 4. 04diffデザインとの数値比較 1. **Pencil MCP を接続** Agent で Pencil の MCP server を有効にし、.pen ファイルを開きます。Skill は .pen を MCP 経由でしか読みません。MCP はデザイン変数を展開し、解決後の実寸を返します。この 2 つこそ忠実な再現に必要なものです。 2. **画像ではなく数値を読む** Agent はまず `Get(nodeId, { resolveVariables: true })` で gap、padding、角丸、文字サイズ、色を取得し、対応表に従って zenit に書き換えます：`fill_container → .fill()`、`chevron-down → ui.icons.chevron_down`。 3. **一致するまで数値比較** デザインを scale 2 で書き出し、`tools/shot.ts` で実ウィンドウをキャプチャします。`tools/design_diff.ts` がずれ、サイズ差、ヒートマップ、配色のずれを報告し、Agent はそのヒントに沿って修正します。1 ラウンドは約 5 秒です。 ```sh SKILL=~/.claude/skills/zenit-ui-dev bun $SKILL/tools/design_diff.ts --self-test ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png bun $SKILL/tools/design_diff.ts /tmp/design/.png /tmp/actual.png ``` ## 使い方 特別な構文は不要です。欲しい UI や問題を説明するだけです。うまくいく依頼の例をいくつか挙げます： ``` Pencil MCP で開いている .pen の「Settings」フレームを読み取り、zenit で設定ウィンドウとして再現して、design_diff のスコアが 90 を超えたら渡してください。 zenit でこのアプリに設定ウィンドウを追加してください。左にカテゴリ一覧、右にフォーム、変更は即時反映です。 src/views/sidebar.zig に手書きされたスタイルを styles.zig + recipe に移行してください。 ファイルツリーが 5 万ノードになるとスクロールがカクつきます。原因を調べて修正し、修正後のスクリーンショットを見せてください。 ``` > TIP > > **確認方法を伝えます。** 依頼に「修正後にスクリーンショットを見せて」や「E2E で検証して」と書けば、Agent は Skill の自己検証フローに従うので、実際に確認済みの結果が返ってきます。 ## 内容の出典 Skill のルールは 2 つのプロジェクトに由来します。zenit フレームワーク本体（公開 API、サンプル、コンポーネントカタログ、テストツール）と、zenit で開発された本番運用の macOS エディター（大規模アプリの階層化、ネイティブ統合、修正履歴）です。サンプルコードは可能な限りこの 2 つのリポジトリでコンパイルが通るコードから取り、本マニュアルと一致させています。 ソースはサイトリポジトリの `skill/zenit-ui-dev/` にあり、ビルド時に `scripts/pack-skill.mjs` でパッケージされます。[SKILL.md を直接読む](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md)こともできます。