0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Astryx入門 — Meta製「AIエージェント可読」デザインシステムをCLIで動かす

0
Posted at

はじめに

AIエージェントにUIコードを書かせると、存在しないpropsを渡してくることがある。variant="danger" のような、いかにもありそうで実際には定義されていない値を平然と使ってくる。Reactのデザインシステムを何十個も読み込んだ学習データから「らしい」名前を予測しているだけなので、個々のプロジェクトが実際に何を定義しているかまでは知らない。

Metaがこの問題に対して出した答えが、2026年6月に公開したAstryxだ。単なるコンポーネント集ではなく、CLIに manifest --json という「自分の全機能を機械可読な形で吐き出す」コマンドを持たせている。エージェントが推測するのではなく、CLIに直接問い合わせて仕様を取得できる設計になっているらしい。

実際にどこまで機械可読なのか、Node.jsが動く環境でnpxから叩いて確かめた。

この記事で学べること

  • Astryxの manifest --json が実際に何を返すか（コマンド数・構造）
  • component --list を素のCLIだけで叩くと何が起きるか
  • doctor コマンドが検出する設定不備の実例

対象読者

  • Reactのデザインシステムを自作・選定している方
  • AIエージェント（Claude Code・Cursor等）にUI実装を任せる機会が多い方

前提環境

  • Node.js: v22.22.2（astryx doctor が要求する最小バージョンは >=22.13.0）
  • npm: 10.9.7
  • @astryxdesign/cli: 0.1.6（2026-07-17時点の最新）

TL;DR

  • npx @astryxdesign/cli manifest --json は15コマンド分の引数・フラグ・型・デフォルト値を1回のJSONで返す。エージェントはヘルプテキストを読まずにCLI全体の仕様を取得できる
  • ただし component --list のような実データを返すコマンドは、CLI単体では動かない。@astryxdesign/core を先にインストールしないと ERR_CORE_NOT_FOUND で失敗する
  • astryx doctor はNode.jsバージョン・パッケージ整合性・テーマ設定・エージェント向けドキュメントの有無までチェックしてくれる

背景・課題

Astryxは、Meta社内で8年かけて育ち13,000以上のアプリで使われてきたデザインシステムを一般公開したものだ1。Reactとコンパイル時CSSエンジンのStyleXの上に構築されており、MITライセンスで配布されている。GitHubリポジトリは公開から3週間ほどで9,000スターを超えた2。

Astryxの売りは「AI fluent」を掲げている点にある。CLIとエージェント向けドキュメント生成機能を最初から組み込み、「システムが挙動・アクセシビリティ・品質を制御し、テーマが見た目を制御する」という役割分担を明確にすることで、企業固有ブランドの強制と開発者の自由度のジレンマを解決すると謳っている1。

この設計思想が実際のCLI操作にどう落ちているのかを、--help から順に確かめていく。

やったこと

ステップ1: CLIをインストールせずに叩いてみる

@astryxdesign/cli はプロジェクトへの追加インストールなしでも npx から直接呼び出せる。

npx --yes @astryxdesign/cli@latest --help

実行すると、次のようにトップレベルの15コマンドが一覧表示された。

Commands:
  init [options]                    Initialize the design system in your project
  component [options] [name]        List components or print component docs
  docs [topic] [section]            Print reference docs
  swizzle [options] [component]     Copy component source for customization
  template [options] [name] [path]  Inject a page or block template
  layout                            Generate XDS layouts from compressed expressions (XLE/XLO)
  upgrade [options]                 Run codemods to migrate between versions
  theme                             Theme tools — build, export, and manage themes
  hook [options] [name]             List hooks or print hook docs
  discover [options] [query]        Discover external packages and components
  search [options] <query>          Search components, hooks, docs, and templates in one ranked list
  build [options] [query]           Build a page: composition kit for an idea, or the workflow playbook
  doctor                            Diagnose your XDS setup and report problems with fixes
  validate-integration [package]    Validate an Astryx integration package (manifest + contributions)
  manifest                          Print the full CLI capability manifest (use with --json)

--dense（トークン節約用の圧縮出力）や --lang zh（中国語簡体字ドキュメント出力）といったオプションも用意されており、CLI自体がLLMのコンテキスト消費量を意識した作りになっている。

ステップ2: manifest --json で仕様全体を取得する

本題の manifest --json を実行する。

npx --yes @astryxdesign/cli@latest manifest --json > manifest.json

出力されたJSONをパースすると、コマンド数と各コマンドの引数・オプション・型が構造化されて取得できた。

import json
d = json.load(open("manifest.json"))["data"]
print(d["name"], d["version"])       # astryx 0.1.6
print(len(d["commands"]))            # 15

component コマンドのエントリだけ抜粋すると、こうなっている。

{
  "name": "component",
  "description": "List components or print component docs",
  "arguments": [{ "name": "name", "required": false }],
  "options": [
    { "flag": "--list", "description": "List all components grouped by category", "type": "boolean" },
    { "flag": "--category <category>", "description": "List components in a specific category", "type": "string" },
    { "flag": "--props", "description": "Print only the props table", "type": "boolean" }
  ]
}

フラグ名・型・説明がすべて構造化されているため、エージェントはこのJSONを1回読み込むだけで「component --props は真偽値フラグでpropsテーブルだけを返す」という仕様を正確に把握できる。ヘルプテキストを自然言語として解釈して推測する必要がない。

ステップ3: component --list はCLI単体では失敗する

ここでハマった。manifest はCLI単体で完結していたので、component --list --json も同じ感覚で叩いた。

npx --yes @astryxdesign/cli@latest component --list --json

返ってきたのはコンポーネント一覧ではなくエラーだった。

{
  "apiVersion": 1,
  "error": "Could not find @astryxdesign/core package",
  "code": "ERR_CORE_NOT_FOUND"
}

manifest はCLIパッケージが自分自身の定義を返すだけなので依存先が要らない。一方 component --list は実際のコンポーネント定義を @astryxdesign/core から読み取る必要があり、プロジェクトにインストールされていないと動かない。CLIとコアパッケージが分離されている以上は当然の挙動だが、「エージェント向けにワンコマンドで仕様を取得できる」という触れ込みだけを見ていると見落としやすい落とし穴だ。

@astryxdesign/core と @astryxdesign/theme-neutral を追加インストールしてから再実行すると、今度は成功した。

npm install @astryxdesign/core @astryxdesign/theme-neutral
npx --yes @astryxdesign/cli@latest component --list --json

# 前のstep 2と同じPythonセッションの続き（import jsonは実行済み）
d = json.load(open("component-list.json"))["data"]
print(len(d))                              # 72 カテゴリ
print(sum(len(v) for v in d.values()))     # 149 コンポーネント（バリアント込み）

72カテゴリ・149コンポーネント（AvatarGroup のようなバリアント違いを含む）が返ってきた。公式サイトが謳う「150以上のアクセシブルコンポーネント」1とほぼ一致する数字だ。

ステップ4: doctor で設定不備を洗い出す

最後に astryx doctor を実行し、環境診断機能を確認した。

npx --yes @astryxdesign/cli@latest doctor

astryx doctor — diagnosing your setup

  ✓ Node.js version
      Node v22.22.2 meets the minimum (>=22.13.0).
  ✓ @astryxdesign/core installed
      @astryxdesign/core resolved (v0.1.6).
  ✓ @astryxdesign/core <-> @astryxdesign/cli alignment
      @astryxdesign/core v0.1.6 is in step with @astryxdesign/cli v0.1.6.
  ⚠ Theme packages
      Theme package(s) installed (@astryxdesign/theme-neutral) but no theme appears wired.
      → fix: Wire a theme via the `astryx.theme` field in package.json, ...
  ℹ AI agent docs
      No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
      → fix: Generate agent docs with `astryx init --features agents`.

Summary: 4 passed, 1 warning, 0 failures, 3 info

テーマを wire していない点をきちんと警告し、さらに「CLAUDE.md / AGENTS.mdが無い」ことまでチェック項目に含めている。ビルドが通るかどうかだけでなく、「このプロジェクトはエージェントから見て自己記述的か」まで診断対象にしているのが、他の一般的なCLIの doctor コマンドとは毛色が違う点だ。

著者視点の発見ポイント

「AIエージェント向け」を謳うCLIツールを検証する際は、--help や manifest のような自己完結コマンドが動くことだけで「エージェント対応済み」と判断しないほうがいい。Astryxの場合、CLIパッケージ自体の仕様は npx だけで即座に取得できるが、実際に価値を生む「今のプロジェクトに何のコンポーネントがあるか」という情報は、対象プロジェクトへの依存パッケージインストールが前提になっていた。エージェントに manifest --json だけ読ませて「これでコンポーネント一覧も分かるはずだ」と判断させると、ERR_CORE_NOT_FOUND で止まる。CLIの自己記述能力と、プロジェクト実データへのアクセス可否は別レイヤーの話として切り分けて検証する必要がある。

まとめ

  • manifest --json はCLIの引数・型・デフォルト値を構造化して返し、ヘルプテキストの自然言語解釈をエージェントに強いない設計だった
  • component --list など実データを扱うコマンドは @astryxdesign/core のインストールが前提で、CLI単体のnpx実行では ERR_CORE_NOT_FOUND になる
  • doctor はNode.jsバージョンからエージェント向けドキュメントの有無まで診断し、実測では72カテゴリ・149コンポーネントが確認できた

「エージェント可読」を謳うツールを自分のプロジェクトに導入する前に、まず manifest --json を叩いて何が返るかを見てから、実際にコアパッケージを入れて doctor を通す、という2段階の確認手順は他のCLIツールを検証するときにも流用できるはずだ。

参考リンク

  1. Introducing Astryx by Meta（2026-06-18時点） ↩ ↩2 ↩3

  2. Meta's Astryx Returns to GitHub Trending（2026-07-16時点の記事内スター数） ↩

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?