moai-foundation-claude

Claude Code 作成キット

Claude Code のスキル、サブエージェント、プラグイン、スラッシュコマンド、フック、メモリ、設定、サンドボックス化、ヘッドレスモード、高度なエージェントパターンを網羅したリファレンスです。

ドキュメント一覧

主要機能：

• reference/claude-code-skills-official.md - エージェントスキルの作成と管理
• reference/claude-code-sub-agents-official.md - サブエージェントの開発と委任
• reference/claude-code-plugins-official.md - プラグインのアーキテクチャと配布
• reference/claude-code-custom-slash-commands-official.md - コマンドの作成とオーケストレーション

設定：

• reference/claude-code-settings-official.md - 設定の階層と管理
• reference/claude-code-memory-official.md - コンテキストと知識の永続化
• reference/claude-code-hooks-official.md - イベント駆動型の自動化
• reference/claude-code-iam-official.md - アクセス制御とセキュリティ

高度な機能：

• reference/claude-code-sandboxing-official.md - セキュリティ分離
• reference/claude-code-headless-official.md - プログラムおよび CI/CD での利用
• reference/claude-code-devcontainers-official.md - コンテナ化された環境
• reference/claude-code-cli-reference-official.md - コマンドラインインターフェース
• reference/claude-code-statusline-official.md - カスタムステータス表示
• reference/advanced-agent-patterns.md - エンジニアリングのベストプラクティス

クイックリファレンス

スキル：~/.claude/skills/（個人用）または .claude/skills/（プロジェクト用）に配置する、モデルから呼び出される拡張機能です。3 段階の段階的開示に対応しています。最大 500 行です。

サブエージェント：Agent(subagent_type="...") を介して呼び出す、特化型アシスタントです。独自の 200K コンテキストを持ちます。サブエージェントを起動することはできません。/agents コマンドを使用します。

プラグイン：.claude-plugin/plugin.json に配置する再利用可能なバンドルです。コマンド、エージェント、スキル、フック、MCP サーバーを含められます。

コマンド：/command を介してユーザーが呼び出します。パラメーター：$ARGUMENTS、$1、$2。ファイル参照：@file。

フック：settings.json で定義するイベントです。PreToolUse、PostToolUse、SessionStart、SessionEnd、PreCompact、Notification。

メモリ：CLAUDE.md ファイルと .claude/rules/*.md。Enterprise、Project、User の階層構造です。@import 構文を使用します。

設定：6 段階の階層構造です。Managed、file-managed、CLI、local、shared、user の順です。

サンドボックス化：OS レベルの分離です。ファイルシステムとネットワークを制限します。安全な操作は自動的に許可されます。

ヘッドレス：非対話型で使用するには -p フラグを指定します。自動化では --allowedTools、--json-schema、--agents を使用します。

スキルの作成

段階的開示のアーキテクチャ

レベル 1（メタデータ）：名前と説明が起動時に読み込まれます。スキルあたり約 100 トークンです。

レベル 2（指示）：呼び出されたときに SKILL.md の本文が読み込まれます。5K トークン未満を推奨します。

レベル 3（リソース）：追加ファイルは必要に応じて読み込まれます。実質的に無制限です。

必須の形式

名前を kebab-case で記述し、スキルの機能と使用するタイミングを三人称で説明する YAML フロントマターを含む SKILL.md ファイルを作成します。説明は最大 1024 文字です。フロントマターの後にスキル名の見出しを追加し、簡潔な手順を記載したクイックスタートセクションと、詳細情報として REFERENCE.md を参照する詳細セクションを含めます。

ベストプラクティス

• 説明は三人称で記述します（「私は〜する」としません）。
• ユーザーが言及するトリガー語句を含めます。
• 500 行未満にします。
• 参照の階層は 1 段階にします。
• Haiku、Sonnet、Opus でテストします。

サブエージェントの作成

/agents コマンドを使用する

/agents と入力し、「Create New Agent」を選択して目的とツールを定義し、e キーを押してプロンプトを編集します。

ファイル形式

名前、呼び出すタイミングを説明する記述（自動委任には PROACTIVELY を使用）、カンマ区切りのツール一覧（Read、Write、Bash）、モデル指定（sonnet）を含む YAML フロントマターを持つ Markdown ファイルを作成します。フロントマターの後にシステムプロンプトを記述します。

重要なルール

• 他のサブエージェントを起動することはできません。
• AskUserQuestion を効果的に使用することはできません。
• 委任する前に、ユーザーとのやり取りをすべて済ませます。
• 各サブエージェントは独自の 200K コンテキストを持ちます。

プラグインの作成

ディレクトリ構成

.claude-plugin/plugin.json、commands ディレクトリ、agents ディレクトリ、skills ディレクトリ、hooks/hooks.json、.mcp.json ファイルを含む my-plugin ディレクトリを作成します。

マニフェスト（plugin.json）

name、プラグインの目的を説明する description、1.0.0 とする version、name フィールドを含む author オブジェクトを含む JSON オブジェクトを作成します。

コマンド

GitHub からインストールするには、/plugin install owner/repo を使用します。 現在のディレクトリを検証するには、/plugin validate . を使用します。 プラグインを有効にするには、/plugin enable plugin-name を使用します。

高度なエージェントパターン

長時間タスク向けの2エージェントパターン

初期化エージェント：環境、機能レジストリ、進捗ドキュメントを設定します

実行エージェント：個々の機能に取り組み、レジストリを更新し、進捗を管理します

詳細は reference/advanced-agent-patterns.md を参照してください。

オーケストレーター／ワーカーアーキテクチャ

リードエージェント：タスクを分解し、ワーカーを起動して、結果を統合します

ワーカーエージェント：焦点を絞ったタスクを実行し、簡潔な要約を返します

コンテキストエンジニアリングの原則

• 信号対雑音比の高いトークンを最小限に絞ります
• 事前読み込みよりもジャストインタイムでの取得を優先します
• 長時間のセッションではコンテキストを圧縮します
• 外部メモリファイルはウィンドウ外に保持されます

ツール設計のベストプラクティス

• 関連する機能を単一のツールに統合します
• 信号対雑音比が高く、コンテキストを考慮した応答を返します
• パラメーター名は明確にします（user ではなく user_id）
• 例を含む、指示が明確なエラーメッセージを用意します

Explore／検索のパフォーマンス最適化

Explore エージェントまたは直接的な探索ツール（Grep、Glob、Read）を使用する場合は、GLM モデルのパフォーマンスボトルネックを防ぐため、次の最適化を適用してください。

AST-Grep の優先

• テキストベースの検索（Grep）より先に構造検索（ast-grep）を使用します
• 複雑なパターンマッチングには moai-tool-ast-grep スキルを読み込みます
• 例：sg -p 'class $X extends Service' --lang python は grep -r "class.*extends.*Service" より高速です

検索範囲の制限

• 検索範囲を限定するため、必ず path パラメーターを使用します
• 例：Grep(pattern="func ", path="internal/core/") を使用し、Grep(pattern="async def") は使用しません

ファイルパターンの具体化

• ワイルドカードではなく、具体的な Glob パターンを使用します
• 例：Glob(pattern="internal/core/*.go") を使用し、Glob(pattern="src/**/*.py") は使用しません

並列処理

• 独立した検索は並列で実行します（1つのメッセージで複数のツール呼び出し）
• コンテキストの断片化を防ぐため、並列検索は最大5件までにします

ワークフロー：探索・計画・コーディング・コミット

フェーズ1 探索：ファイルを読み、構造を理解し、依存関係を把握します

フェーズ2 計画：思考プロンプトを使用し、アプローチの概要をまとめ、基準を定めます

フェーズ3 コーディング：段階的に実装し、各ステップを検証して、境界ケースに対処します

フェーズ4 コミット：説明的なメッセージ、論理的なグループ化、整理された履歴を心がけます

MoAI-ADK との統合

コアスキル

• moai-foundation-claude：このオーサリングキット
• moai-foundation-core：SPEC システムとワークフロー
• moai-foundation-philosopher：戦略的思考

必須のサブエージェント

• spec-builder：EARS 仕様
• manager-ddd：DDD の実行
• expert-security：セキュリティ分析
• expert-backend：API 開発
• expert-frontend：UI 実装

セキュリティ機能

サンドボックス化

• ファイルシステム：書き込み先を cwd に制限します
• ネットワーク：プロキシ経由でドメインの許可リストを設定します
• OS レベル：bubblewrap（Linux）、Seatbelt（macOS）

Dev Containers

• ファイアウォールでセキュリティを強化します
• 許可リストにある送信通信のみを許可します
• --dangerously-skip-permissions は信頼できる場合にのみ使用します

ヘッドレス実行の安全性

• CI/CD では必ず --allowedTools を使用します
• Claude に渡す前に入力を検証します
• 終了コードを使用してエラーを処理します

リソース

詳しいパターンと実用例については、reference ディレクトリを参照してください。

バージョン履歴：

• v5.0.0 (2026-01-11)：CLAUDE.md のドキュメント標準に従い、ナラティブ形式に変換
• v4.0.0 (2026-01-06)：プラグイン、サンドボックス化、ヘッドレス実行、ステータスライン、開発コンテナー、CLI リファレンス、高度なパターンを追加
• v3.0.0 (2025-12-06)：段階的開示、サブエージェントの詳細、統合パターンを追加
• v2.0.0 (2025-11-26)：初の包括的リリース