ALPS AIガイド

AIとALPS設計

ALPS設計におけるAIの力

ALPS設計には、明確な状態定義、意味のある遷移、一貫した命名、標準語彙との整合性など、複数の要素のバランスが求められます。AIアシスタントはこのような多次元的な思考に優れています。

深いコンテキスト理解

AIはドメイン要件を分析し、本質的な状態と遷移を特定できます。「ショッピングカート付きのECシステム」と説明すると、AIは暗黙のフロー（閲覧 → カート → 決済 → 確認）を理解し、適切な状態名と遷移ラベルを提案します。

セマンティックな命名

命名には規約以上のもの—意図の理解が必要です。Linterはgo*やdo*のパターンを強制できますが、AIは何を意味するかとなぜ重要かを理解します。

「ユーザーが後で見るためにアイテムを保存できるようにする」と説明すると、AIはこれをウィッシュリストのパターンとして認識し、汎用的なdoSaveではなくSchema.orgのWantActionに沿ったdoAddToWishlistを提案します。author（創作的帰属）とcreator（技術的起源）を区別し、外部システムと意味的に接続できる語彙を確保します。

標準への準拠

AIは自動的にディスクリプタを確立された語彙と整合させます：

統合方法

Claude Codeをお使いならSkillが最も簡単です。Claude DesktopなどMCP対応クライアントをお使いならMCPサーバーを、その他のLLMをお使いならllms.txtを参照してください。

Note: Skillは必要な時だけ読み込まれコンテキストを効率的に使います。Claude Codeなどコンソールで動作するAIエージェントはBashでasdコマンドを実行できるのでSkillだけで十分です。Claude DesktopやCursorなどGUIクライアントはBashが使えないため、MCPツールが必要です。

Skill (Claude Code)

Claude Codeユーザー向けの推奨方法です。Skillはセッション全体でAIの動作をガイドする永続的なコンテキストを提供します。

alps-skills

alps-skillsはALPS関連のスキルを集めたパッケージです。

スキル 説明
alps ALPSプロファイルの生成、検証、改善
alps-to-openapi ALPSからOpenAPI仕様を生成
alps-to-graphql ALPSからGraphQLスキーマを生成
alps-to-jsonschema ALPSからJSON Schemaを生成
alps-to-sql ALPSからSQL DDLを生成（PostgreSQL, MySQL, SQLite）

セットアップ

/plugin marketplace add alps-asd/alps-skills
/plugin install alps

または/pluginでDiscoverタブから選択してインストールできます。

確認

質問: 「利用可能なスキルは何ですか？」

レスポンスに「alps」スキルが含まれているはずです。

使用方法

  • 「ブログシステムのALPSプロファイルを作成して」
  • 「alps.xmlを検証して問題を修正して」

入力はテキスト、Figmaデザイン、OpenAPI仕様、ホワイトボード写真、WebサイトURL、その他データベーススキーマ、既存コード、GraphQLスキーマ、Postmanコレクション、Swaggerドキュメント、シーケンス図、ユーザーストーリー、ER図、JSONレスポンス、ルート定義、議事録、Slackスレッド、ナプキンスケッチ…が可能です。

Tip: コンソールでCtrl+Vを押すとクリップボードから画像を貼り付けられます。

MCPサーバー

Model Context ProtocolをサポートするAIクライアント向けです。MCPは検証とダイアグラム生成のためのリアルタイムツールアクセスを提供します。

1. Node.jsバージョンの確認

node --version  # v18.0.0以上が必要

v18未満の場合はアップグレードしてください。nvmを使用している場合はnvm use 18を実行します。

2. 設定ファイルの作成

お使いのクライアントに以下の設定を追加します：

Claude Code: プロジェクトに.mcp.jsonを作成

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.jsonを編集

Cursor: Settings → MCP → Add Server

{
  "mcpServers": {
    "alps": {
      "command": "npx",
      "args": ["@alps-asd/mcp"]
    }
  }
}

3. 接続の確認

MCPサーバーのリストに「alps」が表示されることを確認します。Claude Codeの場合は/mcpを実行します。

4. 試してみる

「todoアプリのALPSプロファイルを作成して」と指示してみましょう。ダイアグラムを含んだASDドキュメントが生成されます。

5. 注意とおすすめ

MCPの接続はセッション中に切断されることがあります。/mcpを実行して再接続してください。

頻繁に使う場合は、グローバルインストールすると起動が速くなります：

npm install -g @alps-asd/mcp

利用可能なツール

ツール 説明
validate_alps ALPSプロファイルを検証し詳細なフィードバックを取得
alps2svg SVG状態ダイアグラムを生成
alps2mermaid Mermaidダイアグラムを生成
alps_guide ALPSベストプラクティスを取得

llms.txt (その他のLLM)

SkillやMCPをサポートしないLLM向けです。llms.txt標準は、どのアシスタントでも利用できるAIフレンドリーなドキュメントを提供します。

リソース

リソース 説明
llms.txt ALPS仕様インデックス
llms-full.txt 完全なALPS仕様
ALPS作成ガイド 設計原則と例

システムプロンプト

システムプロンプトまたはAGENTS.mdに追加：

ALPSプロファイルの作成については、次を参照してください: https://www.app-state-diagram.com/alps-skills/skills/alps/SKILL.md

手動コピー

会話の最初に貼り付けるか、ファイルとしてアップロードしてください。

OpenAI GPTs

ALPSアシスタントは、ALPSに関する質問に特化してトレーニングされたカスタムGPTです。

注意: OpenAI Plusアカウントが必要です。

Google NotebookLM

ALPS Guide Notebookは、AIアシスタントと共にALPSの概念を探求できるインタラクティブなノートブックです。

参考リンク