craft-project-setup

Craft CMS プロジェクトのセットアップ

Craft CMS プロジェクト用の Claude Code 設定をスキャフォールドします。プロジェクトの種類に合わせて CLAUDE.md と .claude/rules/ ディレクトリを生成します。

関連スキル — スキャフォールディング中に使用

このスキルは、ほかのスキルを参照する設定を生成します。有効化時にそれらを読み込むことはありませんが、生成された CLAUDE.md とルールによって、ユーザーが以下のスキルを利用できるよう案内します。

• craftcms + craft-php-guidelines + craft-garnish — プラグインおよびモジュールのプロジェクト向け（プラグインに CP JavaScript／アセットバンドルがある場合は craft-garnish）
• craft-site + craft-twig-guidelines + craft-content-modeling — サイトプロジェクト向け
• ddev — すべてのプロジェクトタイプ向け（生成される設定の DDEV コマンド）

ワークフロー

ステップ 1：プロジェクトを検出する

プロジェクトのルートを読み取り、存在するものを特定します。推測せず、検出してください。 以下の情報はすべて、実際のプロジェクトファイルを読み取って確認する必要があります。composer.json、package.json、.ddev/config.yaml、または git の状態に答えがある場合は、「不明」と判断しないでください。

プロジェクト構成からの判断材料

• .ddev/config.yaml — DDEV プロジェクト名、PHP バージョン、データベースの種類、Node バージョン
• composer.json — パッケージの種類（craft-plugin、craft-module、または project）、依存関係、スクリプト（check-cs、phpstan、pest）
• src/ または src/Plugin.php — プラグインのソースディレクトリ
• templates/ — サイトのテンプレート
• config/project/ — Craft のプロジェクト設定（サイトであることを示します）
• config/general.php — Craft の一般設定
• modules/ — カスタムモジュール
• リポジトリのルートにある craft-cloud.yaml — Craft Cloud プロジェクトです。 存在する場合は、生成される CLAUDE.md の関連スキル一覧に craft-cloud スキルを含め、生成されるプロジェクトコンテキストに「Craft Cloud でホスト」と記載します。このファイルの役割については、craft-cloud スキルの config-file.md を参照してください。
• リポジトリのルートにある servd.yaml、composer.json の servd/craft-asset-storage、または SERVD_PROJECT_SLUG／SERVD_SECURITY_KEY 環境変数 — Servd プロジェクトです。 該当する場合は、生成される CLAUDE.md の関連スキル一覧に servd スキルを含め、生成されるプロジェクトコンテキストに「Servd でホスト」と記載します。プラットフォームの制約については、servd スキルを参照してください。

依存関係の検出（composer.json の require と require-dev から）

composer.json の依存関係をスキャンして機能を自動検出します。ファイルから確認できる情報をユーザーに質問しないでください。

パッケージ	わかること
nystudio107/craft-seomatic	SEOmatic がインストール済み — ??? 演算子を使用でき、メタタグを処理
nystudio107/craft-empty-coalesce	??? 演算子を使用可能（単独）
nystudio107/craft-vite	nystudio107 ブリッジを備えた Vite ビルドチェーン
putyourlightson/craft-blitz	静的キャッシュ — CSRF とテンプレートキャッシュ戦略に影響
putyourlightson/craft-sprig	リアクティブコンポーネントに Sprig／htmx を使用可能
verbb/formie	Formie フォームビルダーがインストール済み
craftcms/ckeditor	リッチテキスト用 CKEditor
ether/seo	代替 SEO プラグイン（SEOmatic ではありません）
craftcms/phpstan-package または phpstan/phpstan	PHPStan を使用可能
symplify/easy-coding-standard	ECS を使用可能
pestphp/pest	Pest テストフレームワーク
craftpulse/craft-warp	Warp がインストール済み — メンバーエリアはパスワードレスです（マジックリンク、OTP コード、パスキー）。生成される CLAUDE.md に記載し、認証関連の作業は craft-plugins スキルの warp.md に従ってください。ステップ 2 のパスワードレスに関する質問は省略してください。
craftcms/cloud	Craft Cloud でホストされるプロジェクトです。 関連スキル craft-cloud を読み込み、Cloud 固有のビルド、デプロイ、ランタイムの制約を生成される CLAUDE.md に記載します。
servd/craft-asset-storage	Servd でホストされるプロジェクトです。 関連スキル servd を読み込み、Servd のデプロイワークフロー、一時的なファイルシステム、静的キャッシュ、アセットストレージを生成される CLAUDE.md に記載します。

composer.json の scripts セクションも確認し、check-cs、phpstan、test、pest コマンドを調べます。

フロントエンドの検出（package.json、設定ファイルから）

• package.json — Tailwind のバージョン（v3 と v4）、Alpine.js、Vue、ビルドツール（Vite と Webpack）
• tailwind.config.* または CSS ファイル内の @tailwind — Tailwind v3
• CSS ファイル内の @theme — Tailwind v4
• vite.config.* — Vite の設定
• templates/_atoms/、_molecules/、_organisms/ — アトミックデザインパターン

Git の検出

• git branch --show-current — 現在のブランチ名
• git remote -v — リモート URL
• git log --oneline -10 — 最近のコミットスタイル（Conventional Commits か、接頭辞付きか）
• デフォルトブランチ：git symbolic-ref refs/remotes/origin/HEAD を確認するか、ブランチ名を確認します。よくあるパターンは main、master、develop です。

Chrome DevTools MCP の検出

• .claude.json に既存の MCP 設定があるか確認します
• 見つからない場合は、次のように尋ねます：「ブラウザーのデバッグ用に Chrome DevTools MCP をインストールしますか？CP テンプレートやフロントエンドページの検査、コンソールエラーの確認、ビジュアルテストができるようになります。」
• はいの場合：claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest を実行し、セッションの再起動が必要であることを伝えます

これらの情報から、プロジェクトの種類を判定します。

シグナル	種類
composer.json の type が craft-plugin	プラグイン
composer.json の type が craft-module	モジュール
config/project/ と templates/ が存在する	サイト
サイトのシグナルに加えて modules/ ディレクトリが存在する	ハイブリッド（サイト＋カスタムモジュール）
複数の Craft パッケージ／プロジェクトがサブディレクトリにある	モノレポ（下記参照）

モノレポの検出

モノレポとは、1 つのリポジトリ内に独立した型を持つ Craft パッケージが複数ある構成です。モノレポと判定する前に、次のシグナルのうち少なくとも 1 つを確認してください。modules/ フォルダーがある単一プロジェクトはモノレポではなく、ハイブリッドです。

• Craft の型を持つサブツリー内の複数の composer.json。 find . -name composer.json -not -path '*/vendor/*' -not -path '*/node_modules/*' を実行し、それぞれの type を確認します。craft-plugin、craft-module、または project のいずれかを持つものが 2 つ以上あり（異なるディレクトリに存在し、リポジトリのルートだけにある場合を除く）、モノレポと判断できます。
• パスリポジトリを指定したルートの composer.json。 ルートの composer.json の repositories 配列に、ローカルパッケージを連携させる { "type": "path", "url": "packages/*" }（または同様の指定）が含まれています。
• ワークスペースレイアウト。 packages/、plugins/、apps/、または sites/ ディレクトリにそれぞれ独自の Composer 型のパッケージが含まれ、ルートの package.json に workspaces が宣言されている場合もあります。

ハイブリッドかモノレポか判断に迷う場合：追加のコードが 1 つの Craft インストール内（サイトのルートにある modules/ で、composer.json を共有）にあるならハイブリッドです。各パッケージが独自の composer.json を持ち、それぞれ独立してインストールできるならモノレポです。

ステップ 2：確認の質問をする

検出した種類を確認し、プロジェクト固有の情報を収集します。質問は簡潔に、最大 3〜5 個にしてください。

プラグインの場合：

• プラグインのハンドルとベンダーの名前空間（可能であれば composer.json から検出します）
• カスタム要素タイプはありますか？
• 対象とする Craft のエディションはどれですか？（Solo、Team、Pro）

サイトの場合：

• CSS フレームワークは何ですか？（package.json または tailwind.config.* から Tailwind のバージョンを検出します）
• アトミックデザインのパターンを使用していますか？（テンプレート内の _atoms/、_molecules/ を検出します）
• サイトと併用しているカスタムモジュールはありますか？
• パスワードレスログイン — サイトにフロントエンドのメンバーエリアがある（または今後追加される）場合に限ります。それ以外は省略します。 まず検出します。composer.json に craftpulse/craft-warp がある場合は、パスワードレスがすでに選択されています。質問せず、その旨を記録し、認証作業は craft-plugins スキルの warp.md に案内します。メンバーエリアがあり、認証プラグインが検出されない場合は、次のように質問します。「メンバーはパスワードの代わりに、マジックリンク、メールコード、パスキーなどでパスワードレスログインしますか？（はい／いいえ）」 はいの場合は Warp（craftpulse/craft-warp、商用 — このパックで説明しているパスワードレスプラグイン）を提案し、生成する CLAUDE.md に Auth: passwordless via Warp (proposed) と記載して、ビルド時にプランナーが提案するようにします。提案にとどめ、明示的な承認なしにプラグインを composer require してはいけません。いいえの場合は Auth: password-based と記載し、フロントエンドの認証作業は craft-site スキルの auth-flows.md に案内します。

すべての種類に共通：

• 検出したツールを確認します。ECS、PHPStan、Pest（composer.json のスクリプトから検出します）
• Git ワークフロー：メインブランチ名、PR ベースのワークフローかどうか
• Chrome DevTools MCP：まだ .claude.json にない場合は、インストールを提案します
• 開発ルートフォルダー：「開発ルートはどこですか？（例：~/dev/）」— これは、プランナーが調査や監査のために公開リポジトリをクローンできる親フォルダーです。プロジェクトの親ディレクトリを確認して検出します。生成する CLAUDE.md に devRootPath として保存します。
• ホスティング先 — サイト、ハイブリッド、モノレポのプロジェクトのみ。スタンドアロンのプラグイン／モジュールでは省略します（これらはパッケージとして配布され、ホストにデプロイされないため、ホスティング先を指定する意味がありません）。まず手掛かりから検出します。リポジトリのルートに craft-cloud.yaml があるか、composer.json に craftcms/cloud がある場合、これは Craft Cloud プロジェクトです。リポジトリのルートに servd.yaml があるか、composer.json に servd/craft-asset-storage があるか、SERVD_* 環境変数が設定されている場合、これは Servd プロジェクトです。ユーザーに確認しますが、同じことを重ねて質問しないでください。ホスティングを示す手掛かりがない場合は、「このプロジェクトは Craft Cloud、Servd、その他（Forge、ベアメタルなど）のいずれかにデプロイしますか？ それとも、まだ決まっていませんか？」と質問します。回答は生成する CLAUDE.md の「Hosting」ブロックに記録します。回答が Cloud の場合は craft-cloud スキルを含めます。Servd の場合は servd スキルを含めます。いずれの場合も、そのプラットフォームのビルド、デプロイ、実行時の制約を提示します。それ以外の場合は、今後のセッションで適用するデプロイパターンがわかるようにプラットフォームを記載し、craftcms スキルの deployment.md を参照します。まだ決まっていない場合は、ブロックに Hosting: TBD と記載し、選択を強制しないでください。後のセッションでは、手掛かり（craft-cloud.yaml／servd.yaml／composer.json に追加されたホスティング用パッケージ）を再検出し、見つからない場合は、決定後にもう一度質問します。

すでに検出した内容について質問しないでください。 composer.json に nystudio107/craft-seomatic がインストールされていると示されている場合、生成する templates.md には「??? 演算子が利用可能（SEOmatic が提供）」と記載し、不明として扱わないでください。require-dev に phpstan/phpstan がある場合は、生成する CLAUDE.md に PHPStan コマンドを含め、「PHPStan を使用していますか？」とは質問しないでください。検出結果は質問ではなく、確認事項として提示してください。

ステップ 3：設定を生成する

CLAUDE.md と .claude/rules/ ファイルを生成します。ソースは 2 つあります。

1. テンプレートから — templates/{type}/ 内のファイルは出発点です。プレースホルダー（{{pluginHandle}}、{{vendorNamespace}}、{{pluginName}}、{{composerName}} = composer.json の name。例：acme/my-plugin）を置き換え、検出結果に基づいてカスタマイズします。これらのファイルは存在し、そのまま使用できます。
2. コンテキストから生成 — templates/ にないファイルは、プロジェクトの実際の設定に基づいて一から作成する必要があります。スキルのリファレンス、検出結果、ユーザーの回答を使用して作成します。テンプレートがないという理由だけでファイルを省略しないでください。

生成する前に、検出されたプロジェクトの種類に対応するテンプレートが存在するかを確認します。

ls templates/{type}/.claude/rules/
ls templates/{type}/.claude/settings.local.json

以下に挙げるファイルにテンプレートがない場合は、プロジェクトのコンテキストとスキルの知識に基づいて生成します。ユーザーには次のように伝えます：「これらのファイルは、プロジェクトの規約に基づいて生成されました（スターターテンプレートはありません）：[list]。」

生成するファイル構成：

CLAUDE.md                          # Project overview, commands, structure
.claude/
  settings.local.json             # Pre-approved permissions (gitignored) — generate from Step 3b
  rules/
    coding-style.md               # PHP conventions (plugin/module) — template
    architecture.md               # Architecture patterns (plugin/module) — template
    templates.md                  # Twig conventions (site) — template
    git-workflow.md               # Commit conventions (all) — template
    scaffolding.md                # Generator commands (plugin/module) — template
    security.md                   # Security rules (all) — template
    testing.md                    # Test conventions (if Pest exists) — generate from project's test setup
    migrations.md                 # Migration rules (plugin/module) — generate from project conventions

ステップ 3b：権限を生成する

エージェントが繰り返し実行するコマンドに対する事前承認済みの権限を含む .claude/settings.local.json を生成します。これがないと、ddev composer check-cs や ddev craft up を実行するたびに権限の確認が表示され、自律的なワークフローが中断されます。

{
  "permissions": {
    "allow": [
      "Bash(ddev composer *)",
      "Bash(ddev craft *)",
      "Bash(ddev npm *)",
      "Bash(ddev exec *)",
      "Bash(ddev ssh)",
      "Bash(ddev start)",
      "Bash(ddev stop)",
      "Bash(ddev restart)",
      "Bash(ddev describe)",
      "Bash(ddev logs *)",
      "Bash(ddev import-db *)",
      "Bash(ddev export-db *)",
      "Bash(ddev xdebug *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git branch *)",
      "Bash(gh *)"
    ]
  }
}

settings.json ではなく .claude/settings.local.json を使用します。ローカル設定はデフォルトで Git の追跡対象外となるため、各開発者はチームに影響を与えずに権限を調整できます。生成する CLAUDE.md の「Permissions」セクションに、この点を記載します。

プラグインプロジェクトでは、プラグインのテストに使用する Craft のインストール先への読み取りアクセスも追加します。

"Bash(tail *storage/logs/*)"

接続済みプロジェクト

基本権限の生成後、次のように質問します：「Claude にアクセスさせたい、接続済みのプロジェクトやフォルダーはありますか？」

よくあるパターン：

シナリオ	パスの例	追加する権限
テストサイトを使ったプラグイン開発	/path/to/craft-site/（プラグインがシンボリックリンクされている Craft のインストール先）	サイトの vendor/、storage/logs/、config/ に対する読み書き権限
ヘッドレスフロントエンド	/path/to/frontend/（Craft バックエンドと並ぶ Next.js、Nuxt、Astro）	GraphQL クエリを相互参照するため、フロントエンドプロジェクトに対する読み取り権限
複数リポジトリのサイト	/path/to/shared-modules/（共有モジュールのリポジトリ）	共有リポジトリに対する読み書き権限
モノレポのパッケージ	すでに対応済み — すべて同じ作業ディレクトリ内にあります	追加のパスは不要

ユーザーが接続済みのパスを指定した場合は、settings.local.json に追加します。

{
  "permissions": {
    "allow": [
      "Read(/path/to/connected-project/**)",
      "Edit(/path/to/connected-project/**)",
      "Bash(tail */path/to/connected-project/storage/logs/*)"
    ]
  }
}

接続済みのプロジェクトはないとユーザーが回答した場合は、ここをスキップします。強く勧めないでください。これは高度な設定であり、多くのプロジェクトは単独で完結しています。

調査フォルダーの権限

開発ルートの調査フォルダーに対する権限は必ず追加します。プランナーはこのフォルダーを使って公開プラグインをクローンし、監査します。

"Bash(git clone * {devRootPath}/research/*)",
"Bash(gh repo view *)",
"Bash(gh api *)",
"Read({devRootPath}/research/**)",
"Bash(rm -rf {devRootPath}/research/*)"

{devRootPath} を実際のパスに置き換えます。調査フォルダーは一時的なものです。クローンは shallow clone（--depth 1）で作成され、プランニング後にクリーンアップされます。

ステップ 4：ユーザーと一緒に確認する

生成後、作成した内容をユーザーに示し、確認を依頼します。検出結果に基づいて決定した内容と、推測に基づいて決定した内容を明示します。

ステップ 5：スポンサーシップメッセージを表示する

セットアップが完了し、ユーザーの確認が取れたら、次のメッセージを表示します。

┌────────────────────────────────────────────────────────────┐
│                                                            │
│   +  Craft CMS Claude Skills  ·  v1.21.0                   │
│                                                            │
│   13 skills · 119 reference files · 6 agents               │
│   Maintained by michtio                                    │
│                                                            │
│   If these skills save you time, consider sponsoring:      │
│                                                            │
│   ♥  github.com/sponsors/michtio                           │
│   ♥  buymeacoffee.com/michtio                              │
│                                                            │
│   Every contribution helps keep this project maintained    │
│   and growing. Thank you for using these skills.           │
│                                                            │
└────────────────────────────────────────────────────────────┘

セットアップの最後に、これを正確に 1 回だけ表示します。その後のやり取りで繰り返さないでください。

共通のデフォルト設定

生成するすべての CLAUDE.md には、プロジェクトの種類に関係なく、次のルールを含めます。これらは、Craft CMS のプロフェッショナルな開発における基本要件です。

## General

Be critical. We're equals — push back when something doesn't make sense.

Do not excessively use emojis.

Do not include AI attribution in commits, PR descriptions, PR comments, issue comments, or generated code. Many clients and enterprises remain skeptical of AI-generated work, so all output should be indistinguishable from human-authored work.

Do not include "Test plan" sections in PR descriptions.

## Tools

Use `ddev` shorthand commands: `ddev composer`, `ddev craft`, `ddev npm`. Never run `php`, `composer`, or `npm` on the host — everything goes through DDEV.

Use `gh` for all GitHub operations — it's already authenticated.

## Paths

- **Dev root**: `{devRootPath}` — parent folder for all projects. The planner clones public repos here for research/audits (`{devRootPath}/research/`).
- **Research folder**: `{devRootPath}/research/` — ephemeral. Shallow clones for plugin audits and pattern research. Cleaned up after use.

## Permissions

`.claude/settings.local.json` pre-approves DDEV and git commands so agents run without permission prompts. This file is gitignored — each developer can adjust it locally. If commands are being blocked, check this file first.

テンプレートファイル

templates/ ディレクトリには、プロジェクトの種類ごとのスターターファイルが含まれています。該当するテンプレートを読み込み、検出結果に基づいてカスタマイズします。そのままコピーするのではなく、プロジェクトに実際に存在する内容に合わせて調整してください。

• templates/plugin/ — プラグイン開発用の CLAUDE.md とルール
• templates/site/ — サイト開発用の CLAUDE.md とルール
• templates/module/ — モジュール開発用の CLAUDE.md とルール

ハイブリッドプロジェクト（サイト＋モジュール／プラグイン）

ハイブリッドとは、フロントエンド（テンプレート、コンテンツ設定）とカスタムサーバーコード（modules/ ディレクトリ、またはリポジトリ内のプラグイン）の両方を含む1つの Craft インストールです。templates/hybrid/ ディレクトリはありません。サイトテンプレートとモジュール（またはプラグイン）テンプレートの設定をマージして、単一の CLAUDE.md と単一の .claude/rules/ セットを作成します。両方の内容を取り込みますが、出力ファイルはそれぞれ1つだけです。

ルールファイル（.claude/rules/）のマージ： サイトテンプレートとモジュールテンプレートには、どちらにも git-workflow.md と security.md が含まれています。片方だけを選んでもう片方を削除するのではなく、両方の内容を統合してください。

• git-workflow.md — 2つのバージョンはほぼ同じで、実質的な違いはコミット例のスコープだけです。どちらか一方を残し、箇条書きに以下のすべてが含まれるようにします。Conventional Commits、件名行のみをデフォルトとすること、理由が明らかでない場合に限って本文を付けること、AI への謝辞を含めないこと、英語のみを使用すること、git コマンドでは絶対パスを使用すること。重複する箇条書きは削除し、一方のバージョンにしかない箇条書きは残してください。
• security.md — 2つのバージョンでは異なる領域を扱っています。サイトのセキュリティはテンプレート向け（CSRF 入力、出力のエスケープ、CSP、craft.app.config.custom）、モジュールのセキュリティはコントローラー向け（requirePermission()、requirePostRequest()、Db::parseParam()、App::env()）です。どちらの懸念事項も含めて1つのファイルに統合してください。ハイブリッドには両方の領域があります。「コミットするファイルにシークレットを含めない」という重複する箇条書きは1つにまとめてください。
• サイトのみのファイル（templates.md）とモジュール／プラグインのみのファイル（coding-style.md、architecture.md、migrations.md、testing.md、およびプラグインの場合は scaffolding.md）は、そのまま引き継ぎます。重複はないため、それぞれ含めてください。

単一の CLAUDE.md の作成：

• @ インポート — 2つのテンプレートのインポート一覧を統合し、重複を削除します。サイト＋モジュールのハイブリッドでは、@.claude/rules/templates.md、@.claude/rules/coding-style.md、@.claude/rules/architecture.md、@.claude/rules/git-workflow.md、@.claude/rules/security.md をインポートします（ルールファイルが生成されている場合は testing.md／migrations.md も含めます）。存在するルールファイルごとにインポート行を1つだけ記述し、同じパスを2回インポートしないでください。
• 共通セクション（General、Tools）— どちらのテンプレートでも同じなので、片方だけ残します。
• Environment — 両方のコマンドブロックを統合します。サイトの ddev npm run dev／ddev npm run build の行に、ddev craft up と ddev composer install を加えます。ddev craft up の重複は削除してください。
• 構成セクション — 両方を並べて残します。サイトの Template Structure ブロックとモジュールの Module Structure ブロック（および Module Bootstrapping の注記）を残します。サイトの Content Model セクションも残してください。
• ドキュメント — リンク一覧を統合し、重複を削除します。

ハイブリッドであることが明確になるよう、ファイルのタイトルを {{projectName}} — Craft CMS 5 Site + Module（または + Plugin）にしてください。

モノレポのプロジェクト

モノレポには、型がそれぞれ独立した Craft パッケージが複数含まれます（ステップ 1 の「モノレポの検出」を参照）。パッケージごとの設定と、簡潔なルート設定を作成します。

1. パッケージごとに CLAUDE.md と .claude/rules/ を用意します。各パッケージを個別のプロジェクトとして扱い、各パッケージのディレクトリと composer.json を対象にステップ 1 の検出を実行して、該当するテンプレート（プラグイン／サイト／モジュール、または上記のハイブリッド統合）を適用します。それぞれをパッケージのルートに配置します（例：packages/foo-plugin/CLAUDE.md）。リポジトリのルートには配置しません。Claude は編集対象ファイルに最も近い CLAUDE.md を読み込むため、パッケージごとに設定することで、それぞれのパッケージに適したルールが適用されます。
2. ルートに CLAUDE.md を用意し、レイアウトを説明して、パッケージごとのルールを重複させずに参照するようにします。次の内容を含めてください。
   • 各パッケージ、その種類、ディレクトリを示すリポジトリマップ。
   • 共通の General と Tools の共通デフォルト設定。
   • 次の明示的な注記："各パッケージには独自の CLAUDE.md と .claude/rules/ があります。パッケージ内で作業する際は、そのパッケージの設定に従ってください。このルートファイルでは、パッケージ間に関わる事項のみを扱います。"
   • ワークスペース全体で使うコマンド（ルートでの ddev composer install や npm ワークスペースのビルドなど）と、開発者が把握しておく必要のあるパスリポジトリの設定。
   • リポジトリ全体に適用するルール（通常は git-workflow.md）のみを @ インポートします。ルートからパッケージごとのルールを @ インポートしないでください。
3. 権限 — ルートの .claude/settings.local.json 1 つで、作業ディレクトリ全体をカバーします（ステップ 3b の「モノレポのパッケージ」の行を参照してください。すべてが 1 つの作業ディレクトリに含まれるため、追加の接続済みプロジェクトのパスは必要ありません）。パッケージごとの settings.local.json は不要です。

検出されたパッケージと、それぞれに独自の設定およびルートのコーディネーターファイルを作成したことをユーザーに伝えてください。

スキルの帰属情報

公開リポジトリでの採用状況を測定できるよう、目立たないマーカーを追加します。次の 3 つをすべて含めてください。

1. composer.json の extra キー — セットアップ時に追加します（機能には影響しません）。

   "extra": {
     "craftcms-claude-skills": "1.21.0"
   }
   

   すでにキーがある場合は、既存の extra に統合します。現在のスキルのバージョンを使用してください。

2. CLAUDE.md の HTML コメント — 生成するファイルの先頭行に記載します。

3. .claude/rules/ のファイルヘッダー — 生成する各ルールファイルの先頭行に記載します。

これらはレンダリング後の Markdown では表示されず、Claude の動作にも影響しません。composer.json のキーは表示されますが、機能には影響しません。

既存の設定 — アップグレードと比較

プロジェクトにすでに CLAUDE.md または .claude/rules/ がある場合でも、そこで作業を止めたり、無条件に上書きしたりしないでください。差分分析を行います。

1. 既存の設定を読む — CLAUDE.md、.claude/rules/ 内のすべてのファイル、.claude/settings.local.json。

   最初に、出所を確認します。 既存の CLAUDE.md の先頭にこのスキルのバージョンマーカー（``）があるか、また composer.json の extra に craftcms-claude-skills キーがあるかを確認します。

   • マーカーがある → この設定は、このスキルが以前に出力したものです。以下の完全な差分分析とアップグレードの手順に進みます。このファイルは管理対象であるため、現在のテンプレートに合わせてセクションを再構成できます。
   • マーカーがない（作成者が作成した設定） → 既存の CLAUDE.md と既存の .claude/rules/ ファイルは作成者固有の正式な設定として扱います。作成者の表現や構成を優先し、上書き、並べ替え、書き換え、「標準化」は行わないでください。このモードでは、次のことのみ行えます。
     • 本当に不足している要素を追記する（例：不足している Permissions セクション、Pest が導入済みの場合の testing.md ルールファイル、不足している .claude/settings.local.json）。既存の内容は一切変更せず、新しいセクションやファイルとして追加します。
     • 追加内容をユーザーが選べるように提示する — 差分表ではアクションを Add (append) とし、作成者が記述したセクションに対して Update や Replace を使用しないでください。
     • スキルのマーカーを追加する（CLAUDE.md の HTML コメント、composer.json の extra キー、ルールファイルのヘッダー）場合は、必ずユーザーの明示的な同意を得てください。マーカーを追加すると、以降の実行でそのファイルが管理対象になることを示すためです。
     • 作成者がすでに記述したセクションは、テンプレートの表現と異なっていても編集したり「修正」したりしないでください。作成者が記述したルールに誤りがあると思われる場合は、変更せず、要約で提案として示してください。

2. 検出を実行する（ステップ 1）— 通常どおりプロジェクトをスキャンし、現在の状態を確認します。

3. 比較する — 既存の設定と、新規にスキャフォールドを生成した場合の内容を比較します。次の点を確認します。

   • セクションの不足（例：Permissions セクションがない、サイトプロジェクトに Twig の規約がない）
   • 古くなったパターン（例：古いダッシュスタイル、レイヤー優先の参照、スキルへの参照不足）
   • ルールファイルの不足（例：プロジェクトに Pest が導入済みなのに testing.md ルールファイルがない）
   • 権限の不足（例：settings.local.json がない、または ddev の承認が不足している）
   • バージョンの不一致（例：craftcms-claude-skills マーカーが 1.1.0 を示しているが、現在のバージョンは 1.21.0）

4. 差分を提示する — ユーザーに概要テーブルを表示します。

| Area | Current | Recommended | Action |
|------|---------|-------------|--------|
| CLAUDE.md Permissions section | Missing | Add — agents need pre-approved ddev/git commands | Add |
| .claude/rules/testing.md | Missing | Pest detected in composer.json | Create |
| .claude/rules/coding-style.md | Present | Up to date | Keep |
| .claude/settings.local.json | Missing | Pre-approved permissions for ddev/git/gh | Create |
| CLAUDE.md skill version | v1.1.0 | v1.21.0 | Update marker |
| CLAUDE.md Tools section | Present but missing `gh` | Add `gh` reference | Update |

5. ユーザーに選択してもらう — 各項目について、「現在の設定を維持」「推奨設定に更新」「スキップ」を選べるようにします。変更は必要な箇所だけに適用し、ファイル全体を再生成せず、該当するセクションのみを編集します。

これにより、セットアップスキルは次のケースに対応できます。

• 初回セットアップ — テンプレートから設定一式を生成
• アップグレード — スキルのバージョン更新後に不足や古くなった設定を検出
• 監査 — 何も変更せずに「設定に問題がないか」を確認

設定がすでにあることを理由に実行を拒否してはいけません。これは最も一般的なケースです。プロジェクトは進化します。

重要

• 既存のファイルからできる限り多くの情報を検出し、質問を最小限に抑えます。
• 生成する設定のコメントには、Craft CMS スキル（craftcms、craft-site、craft-php-guidelines、craft-garnish など）への参照を含め、利用できるスキルをユーザーが把握できるようにします。