sample-module-setup

モジュールのセットアップ

概要

BMad モジュールをプロジェクトにインストールして設定します。モジュールの識別情報（名前、コード、バージョン）は ./assets/module.yaml から取得します。ユーザーの設定を収集し、次の 3 つのファイルに書き込みます。

• {project-root}/_bmad/config.yaml — プロジェクト共通の設定です。ルートにはコア設定（例：output_folder、document_output_language）が入り、各モジュールのセクションにはメタデータとモジュール固有の値が入ります。ユーザー専用のキー（user_name、communication_language）は、ここには書き込まれません。
• {project-root}/_bmad/config.user.yaml — Git で無視することを想定した個人設定ファイルです。user_name、communication_language、および ./assets/module.yaml で user_setting: true と指定されたモジュール変数が入ります。これらの値は、このファイルのみに保存されます。
• {project-root}/_bmad/module-help.csv — ヘルプシステムにモジュールの機能を登録します。

どちらの設定スクリプトもアンチゾンビパターンを使用します。書き込み前に、このモジュールの既存エントリを削除するため、古い値が残ることはありません。

{project-root} は設定ファイル内の_値_（上記のファイルに書き込まれるデータ）における文字どおりのトークンであり、そこでは置き換えないでください。これは、値がスキルのルートではなくプロジェクトのルートを基準にしていることを、設定を使用する LLM に伝えます。ただし、以下のスクリプトに渡すファイルシステムパスの_引数_（--*-path、--*-dir、--target 引数）には適用されません。これらは実際のパスであるため、実行前に {project-root} を実際のプロジェクトルートに解決する必要があります。そうしないと、スクリプトはスキルフォルダー内に文字どおりの {project-root}/ ディレクトリを作成して書き込みます。スクリプトは、トークンが未解決の場合にエラーを返します。

アクティベーション時

1. モジュールのメタデータと変数の定義を確認するため、./assets/module.yaml を読み取ります（code フィールドがモジュール識別子です）。
2. {project-root}/_bmad/config.yaml が存在するか確認します。モジュールのコードに一致するセクションがすでにある場合、更新であることをユーザーに伝えます。
3. {project-root}/_bmad/sam/config.yaml と {project-root}/_bmad/core/config.yaml にモジュールごとの設定があるか確認します。いずれかのファイルが存在する場合：
   • {project-root}/_bmad/config.yaml にこのモジュールのセクションがまだない場合、これは新規インストールです。インストーラーの設定が検出され、新しい形式に値が統合されることをユーザーに伝えます。
   • {project-root}/_bmad/config.yaml にこのモジュールのセクションがすでにある場合、これはレガシー移行です。既存の設定とともにレガシー形式のモジュール別設定が見つかり、レガシーの値がフォールバックのデフォルトとして使用されることをユーザーに伝えます。
   • どちらの場合も、セットアップ後にモジュール別の設定ファイルとディレクトリをクリーンアップします。

ユーザーが引数（例：accept all defaults、--headless、user name is BMad, I speak Swahili のようなインライン値）を指定した場合、指定された値を設定キーに割り当て、残りにはデフォルト値を使用して、対話形式のプロンプトを省略します。最後に、確認内容の全体を引き続き表示します。

設定の収集

ユーザーに値を尋ねます。デフォルト値は角括弧で示します。すべての値をまとめて提示し、変更したい値だけを一度に回答できるようにします（例：「言語をスワヒリ語に変更し、ほかはそのままで」）。チャットインターフェースでは回答するために何か入力する必要があるため、「Enter キーを押す」や「空欄のままにする」とは決して伝えないでください。

デフォルト値の優先順位（高いものが優先）：既存の新しい設定値 > レガシー設定値 > ./assets/module.yaml のデフォルト値。レガシー設定がある場合は、それを読み込み、module.yaml のデフォルト値の代わりに、対応する値をデフォルトとして使用します。現在のスキーマに一致するキーのみ引き継がれます。変更または削除されたキーは無視されます。

コア設定（コアキーがまだ存在しない場合のみ）：user_name（デフォルト：BMad）、communication_language と document_output_language（デフォルト：英語。単一の言語に関する質問として尋ね、両方のキーに同じ回答を設定）、output_folder（デフォルト：{project-root}/_bmad-output）。このうち、user_name と communication_language は config.user.yaml のみに書き込みます。残りはルートの config.yaml に書き込み、すべてのモジュールで共有します。

モジュール設定：./assets/module.yaml 内で prompt フィールドを持つ各変数を読み込みます。そのプロンプトを使い、デフォルト値（または利用可能な場合はレガシー値）とともに尋ねます。

ファイルの書き込み

収集した回答を {"core": {...}, "module": {...}} の形式で構造化した一時 JSON ファイルに書き込みます（コア設定がすでに存在する場合は core を省略します）。この JSON 内の値では、{project-root} トークンをそのまま維持します。その後、両方のスクリプトを実行します。異なるファイルに書き込むため、並行して実行できます。

以下のコマンドでは、実行前にパス引数内の {project-root} をすべて実際のプロジェクトルート（例：/home/me/myapp）に置き換えてください。これらは設定値ではなく、ファイルシステムのパスです。

uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code sam

両方のスクリプトは、結果を JSON として標準出力に出力します。どちらかがゼロ以外の終了コードを返した場合は、エラーを提示して停止します。スクリプトはレガシー設定値をフォールバックのデフォルト値として自動的に読み込み、マージが成功した後にレガシーファイルを削除します。出力の legacy_configs_deleted と legacy_csvs_deleted を確認し、クリーンアップが完了したことを確かめます。

詳しい使い方は、./scripts/merge-config.py --help または ./scripts/merge-help-csv.py --help を実行してください。

出力ディレクトリの作成

設定を書き込んだ後、設定された出力ディレクトリを作成します。ファイルシステム操作（ディレクトリの作成など）に限り、{project-root} トークンを実際のプロジェクトルートに解決し、まだ存在しない config.yaml 内のパス型の値をそれぞれ作成します。これには output_folder と、値が {project-root}/ で始まるモジュール変数が含まれます。設定ファイルに保存されるパスでは、{project-root} トークンをそのまま維持してください。解決済みパスを使用するのは、ディスク上のディレクトリだけです。mkdir -p または同等の方法で、パス全体を作成してください。

レガシーディレクトリのクリーンアップ

両方のマージスクリプトが正常に完了した後、インストーラーのパッケージディレクトリを削除します。これらのディレクトリにあるスキルとエージェントは、すでに .claude/skills/ にインストールされています。_bmad/ ディレクトリには設定ファイルのみを残してください。

マージスクリプトと同様に、実行前に --bmad-dir と --skills-dir のパス引数内の {project-root} を実際のプロジェクトルートに置き換えてください。

uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code sam --also-remove _config --skills-dir "{project-root}/.claude/skills"

スクリプトは、レガシーディレクトリ内のすべてのスキルが .claude/skills/ に存在することを確認してから、何かを削除します。スキルを含まないディレクトリ（_config/ など）は直接削除されます。スクリプトがゼロ以外の終了コードを返した場合は、エラーを提示して停止します。存在しないディレクトリ（以前の実行ですでにクリーンアップ済みのもの）はエラーになりません。スクリプトは冪等です。

確認のため、JSON 出力の directories_removed と files_removed_count を確認してください。詳しい使い方は、./scripts/cleanup-legacy.py --help を実行してください。

確認

スクリプトの JSON 出力を使って、書き込まれた内容を表示します。設定値（コアの設定はルートの config.yaml に、モジュールの設定値はモジュールのセクションに書き込まれています）、config.user.yaml に書き込まれたユーザー設定（結果の user_keys）、追加されたヘルプ項目、新規インストールか更新かを表示します。レガシーファイルが削除されている場合は、移行について言及します。レガシーディレクトリが削除されている場合は、削除したファイルの数と一覧を報告します（例：「sam/、core/、\_config/ からインストーラーパッケージファイルを 106 個削除しました — スキルは .claude/skills/ にインストールされます。」）。次に、./assets/module.yaml の module_greeting をユーザーに表示します。

結果

ユーザーの user_name と communication_language が判明したら（収集した入力、引数、または既存の設定から）、セッションの残りの間は一貫して使用します。設定された名前でユーザーに呼びかけ、設定された communication_language でコミュニケーションを取ります。