matlab-define-toolbox-api

matlab-define-toolbox-api — ツールボックスの範囲と仕様の生成

コードのフォルダーを受け取り、ツールボックスに含めるものを判断し、公開 API を特定して、ツールボックスが公開する内容を定義する契約であるインターフェース仕様を作成します。1 つのスキルで、1 つの成果物を作成します。

使用する場面

• コードをツールボックスにしたい場合
• フォルダーを指定して「これをツールボックスにして」または「これをパッケージ化して」と依頼された場合
• スクリプト、関数、テスト、データ、作業用ファイルが混在している場合
• ファイルからパッケージを作成するパイプラインを最初から開始する場合

使用しない場面

• 既存の仕様にファイルを追加する場合 — buildUtilities/toolboxSpecification.m を直接編集します
• 依存関係を分析する場合 — 仕様の承認後に matlab-analyze-dependencies を使用します
• .mltbx パッケージをビルドする場合 — matlab-build-toolbox を使用します
• ツールボックスのドキュメントを作成する場合 — matlab-document-toolbox を使用します

主な関数

関数	目的
dir	インベントリ作成のための再帰的なファイル一覧
which	パス上の関数の場所を解決
exist	名前がファイル、フォルダー、または組み込み関数として解決されるか確認
matlab.codetools.requiredFilesAndProducts	サポートの分類のために呼び出し元と呼び出し先の関係を追跡

入力

入力	必須	説明
path	いいえ	分析するフォルダーまたはファイルの一覧です。指定されていない場合は、ユーザーに尋ねます。
purpose	いいえ	ツールボックスの機能と利用者です。指定されていない場合は、ユーザーに尋ねます。

ワークフロー

ステップ 1 — 入力を収集する

path が指定されていない場合：

ツールボックスとしてパッケージ化するフォルダーまたはファイルを指定してください。

purpose が指定されていない場合：

このツールボックスの機能と利用者を、1、2 文で説明してください。

両方が指定されるまで先に進まないでください。

ステップ 2 — フォルダーのインベントリを作成する

パスを再帰的にスキャンします。各ファイルを分類してください。

カテゴリ	検出ルール
関数	最初の非コメント行に function キーワードがある .m ファイル
クラス	classdef キーワードがある .m ファイル
スクリプト	function／classdef キーワードがない .m ファイル
ライブスクリプト	.mlx ファイル
テスト	tests/／test/ フォルダー内にある、または名前が *Test.m、*_test.m、test_*.m に一致するファイル
データ	.mat、.csv、.xlsx、.json、.xml（設定ファイルを除く）
設定／メタデータ	buildfile.m、projectStartup.m、Contents.m、.prj、resources/
作業用／一時ファイル	scratch/、tmp/ 内にある、または untitled*.m、Copy_of_* のような名前のファイル
その他	README、画像、ライセンスなど

ステップ 3 — 関連性を分類する

purpose を基準に、各ファイルを分類します。

• 含める — ツールボックスの明示された目的に直接役立つ
• サポート — 含めるファイルに必要（内部で呼び出されるヘルパー／ユーティリティ）
• 除外 — 関連性がない（テスト、作業用ファイル、無関係なコード）
• 要確認 — ユーザーへの確認が必要

判断の目安：

手掛かり	扱い
関数名が目的を表すキーワードと一致する	含める
H1 テキストに目的に関する概念が含まれる	含める
含めるファイルから呼び出される	サポート
private/ または +internal フォルダー内にある	サポート
含める関数のテストファイル	除外
目的とのつながりがないスクリプト	除外
含めるコードから参照されるデータファイル	含める
作業用／一時ファイルの命名パターンに一致する	除外

ステップ 4 — 公開 API を特定する

含めるファイルから、公開範囲を判断します。

手掛かり	分類
H1 ヘルプテキストがある	公開の可能性が高い
arguments ブロックまたは入力検証がある	公開の可能性が高い
説明的で動作を示す名前	公開の可能性が高い
public メソッドを持つ classdef	公開
他のファイルから呼び出されるが、単独では使用しない	内部
private/ 内にある、または汎用的なユーティリティ名	内部
スクリプト	例／エントリーポイント

ステップ 5 — レポートを提示して確認を得る

スコープと API をまとめたレポートを表示します。

## Toolbox Scope & API — [Name]

**Purpose:** [user's stated purpose]
**Source:** [path]
**Total files:** N

### Public API (N functions)
| Function | Signature | H1 | Category |
|----------|-----------|-----|----------|

### Internal Support (N files)
| File | Type | Reason |
|------|------|--------|

### Excluded (N files)
| File | Reason |
|------|--------|

### Uncertain — Need Your Input
| File | Why Uncertain |
|------|--------------|

次に、以下を尋ねます。

確認してください：

1. 除外したファイルのうち、含めるべきものはありますか？
2. 含めたファイルのうち、削除すべきものはありますか？
3. 判断が難しいファイルについて、含めますか、除外しますか？
4. 公開 API の範囲は正しいですか？
5. 関数をどのカテゴリに分類しますか？（例：「解析」、「I/O」、「可視化」）

続行する前に、フィードバックを反映します。

ステップ 6 — インターフェース仕様を生成する

構造には scripts/toolboxSpecificationTemplate.m を使用して、toolboxSpecification.m を生成します。classdef エントリには function エントリにない追加フィールド（methods、properties）があるため、spec.entries は構造体配列ではなくセル配列です。フィールドが一致しない構造体を MATLAB で連結することはできません。spec.entries{i} でエントリにアクセスしてください。各エントリには "type" フィールドがあり、値は "function" または "classdef" のいずれかです。両方のタイプで使用するフィールドの詳細については、テンプレートを参照してください。

プロジェクトのルートにある buildUtilities/toolboxSpecification.m に保存します（必要に応じてフォルダーを作成してください）。このフォルダーは toolbox.ignore または package.ignore によりツールボックスパッケージから除外されます。

出力

• 単一の成果物：buildUtilities/toolboxSpecification.m — MATLAB 構造体として実行可能な仕様
• 表示：セッション中にレビュー用として表示される Markdown レポート
• 後続処理：ほかのスキル（matlab-assess-toolbox、matlab-build-toolbox、matlab-analyze-dependencies）が toolboxSpecification.m を使用します

チェックポイント

このスキルは、ステップ 5 で必ずユーザーの承認を得るために一時停止します。 仕様を生成する前に、ユーザーがスコープと公開 API を確認する必要があります。確認が得られるまで、何も書き込まれません。

重要なルール

• 入力が不足している場合は、必ず質問してください。 パスや目的を推測してはいけません。
• すべてのファイルを把握します。 ファイルを黙って除外してはいけません。ファイルは、理由を明記したうえで、含める、除外する、または判断が難しいものとして提示します。
• 分類は目的に基づいて行います。 ユーザーが示した意図を主な基準とします。
• 判断が難しい場合は、そのまま示します。 誤った推測をするより、曖昧さを明示してください。
• 理由の記載は必須です。 含めるか除外するかの判断には、すべて理由を付けます。
• テストは除外しますが、除外したことを明示します。 テストは後で matlab-assess-toolbox によって処理されます。
• スクリプトは例として扱います。 function キーワードのないファイルは、公開 API ではなく、例またはエントリーポイントです。
• 公開範囲はユーザーが決定します。 ヒューリスティックによる提案を、ユーザーが確認します。
• 成果物は 1 つで、ビルド用ユーティリティに保存します。 ソースを整理した状態に保ち、パッケージ化するツールボックスから除外するため、書き込むのは buildUtilities/ に保存する toolboxSpecification.m のみです。

次のステップ

• /matlab-analyze-dependencies — インターフェース仕様で特定された外部依存関係を解決します
• /matlab-create-project — 仕様を参考にして、ファイルを MATLAB プロジェクトに整理します

---

Copyright 2026 The MathWorks, Inc.

---