Basercms5 Claude Workflow Setup

baserCMS5 × Claude Code 開発/移行ワークフロー 環境セットアップ

baserCMS5（CakePHP5）の開発・移行を Claude Code で進めるときの「ベストな進め方の環境」を提案するための入口スキル。技術的な実装・書き換えパターンは別スキル（basercms5-plugin-development / basercms5-theme-development、共通ルールは basercms5-development ほか）に任せ、本スキルはどう進めるか＝設計→パーミッション整理→Auto mode→実装の段取りだけを扱う。

★大前提（このスキルの性格）

• ユーザーに"学習してもらう（教える）"のが主目的: このスキルは作業を代行するためのものではなく、**推奨ワークフロー（brainstorming で設計／permissions-audit で権限整理／Auto mode／spec・plan プレビュー）を、ユーザー自身が今後も使えるように「伝えて学習してもらう」**ためのもの。各ツールは「私（アシスタント）が黙って回す」のでなく、「こういうときはこれを使うとよい」とユーザーに教え、ユーザーが選んで使えるようにする。
• 提案であって強制ではない: ここで示すのは「推奨」。permissions-audit の実行も Auto mode への切替もユーザーが選ぶ（opt-in）。「今回はやらない」も尊重し、そのまま実装に進んでよい。
• 冪等・低摩擦: 技術スキルから毎回最初に呼ばれても繰り返さない。既に整っていれば即スキップ。下記「現状チェック」で整っている項目は飛ばし、足りない項目だけを軽く提案する。
• スキルから自動で環境を変えない: Auto mode の切替や設定の最終適用はユーザー操作。本スキルは案内と、ユーザーが望んだときの作業（permissions-audit の実行等）に留める。

前提: 必要なプラグインの導入（未導入なら案内・ユーザー操作）

このワークフローは2つの Claude Code プラグインを使う。未導入なら導入を提案し（やるかはユーザー判断）、導入コマンドはユーザーが Claude Code 上で実行する（スキルからは導入できない）。

• superpowers（brainstorming / writing-plans / subagent-driven-development 等を提供）
  • 導入: /plugin marketplace add anthropics/claude-plugins-official → /plugin install superpowers@claude-plugins-official
  • （別ソース可: /plugin marketplace add obra/superpowers-marketplace → /plugin install superpowers@superpowers-marketplace）
• permissions-audit（.claude/settings.json の allow/deny を整理）
  • 導入: /plugin marketplace add https://github.com/makikub/claude-code-plugin.git → /plugin install permissions-audit@makikub-plugins
• 導入確認: /plugin（一覧）で superpowers / permissions-audit が有効か。既に有効ならこの節はスキップ。
• ★VSCode（Visual Studio Code の拡張）で作業している場合: プラグイン導入が完了したら、VSCode（または拡張）の再起動を促す。導入直後はプラグイン／スキルが読み込まれないことがあるため、「インストールが完了しました。VSCode を利用中の場合は、一度 VSCode（拡張）を再起動してから続けてください」とユーザーに案内する。
• ※markdown-to-html はプラグインでなくプロジェクトのスキル（.claude/skills/markdown-to-html/）。無いプロジェクトでは代替手段を相談。

前提: 常時ON規則を CLAUDE.md に入れる（提案・opt-in・置き場所はユーザー選択）

本スキルは「設計→計画→spec の順序」「spec/plan の Markdown プレビュー」の詳細手順の正本を持つ（下記セクション）。ただしスキルは呼び出されたときだけ読み込まれるため、これらを全セッションで自動発火（常時ON）——特にプレビューの「毎回言われなくても自動で開く」——にしたい場合は、CLAUDE.md（毎回自動読込）に短いトリガ規則を入れる必要がある。これも環境セットアップの一部として提案する（opt-in・やるかはユーザー判断・既にあればスキップ）。

★追記先はユーザーに選んでもらう（どちらに入れるか必ず確認する）:

• (A) グローバル ~/.claude/CLAUDE.md → 全プロジェクトで常時ON（baserCMS5 を複数プロジェクトで触るなら基本こちら）
• (B) プロジェクトの CLAUDE.md（プロジェクト直下の CLAUDE.md 等） → そのプロジェクトだけ常時ON（このプロジェクトに閉じて効かせたいとき）

選んでもらった側の CLAUDE.md に、次の2ブロックを追記することを提案する（既にあればスキップ）:

> 下記2つは全プロジェクト共通の常時ONルール（要点のみ）。詳細手順は `basercms5-claude-workflow-setup` スキルに集約（あるプロジェクトはそれを正本に参照／無くても下記要点で運用可）。

## spec / plan などの Markdown プレビュー（常時ON・要点）
- spec/plan などレビュー目的の Markdown を作成・更新したら、HTML 化してブラウザで開くまで自動で行う（毎回言われなくても）。`markdown-to-html`（scripts/md_to_html.py、完全HTML文書・--fragment なし）で scratchpad へ出力 → `open` 表示（生成HTMLはコミットしない、更新時は再生成）。スキルが無いPJは代替を相談。

## brainstorming（設計）→ plan プレビュー → spec 書き出し（常時ON・要点）
- superpowers:brainstorming の設計は、いきなり docs/superpowers/specs/ に書き出さず、plan モードで plan ファイル記述 → ExitPlanMode でレビュー → 承認＆反映 → docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 書き出し → 上記プレビュー → writing-plans の順（plan モードでレビューを挟むとき）。通常対話の brainstorming は従来どおり直接 spec でよい。

• ※ プレビューに使う markdown-to-html は各プロジェクトにスキルとして必要（無ければ用意 or 代替を相談）。

使い方（提案フロー）

5系の開発/移行に着手する前に、次を順に提案する。各ステップは「現状チェック→整っていなければ提案→ユーザーが望めば実行」。

1. 現状チェック（まず確認）: 「設計フェーズか実装フェーズか」「.claude/settings.json のパーミッションは整理済みか」「Auto mode を使う意向はあるか」。整っていれば該当ステップは飛ばす。
2. permissions-audit でパーミッション整理（opt-in）: permissions-audit で .claude/settings.json の allow/deny を整理することを提案する。やるか確認し、望めば実行（危険操作は deny、頻用コマンドは allow）。★ユーザーに伝える: パーミッションを整理しておくと Auto mode（自動承認）を安心して使える（危険操作は deny 済みなので、自動承認でも暴走しない）。＝permissions-audit は Auto mode を安全に回すための準備。
3. Auto mode への切替を案内（ユーザー操作）: パーミッション整理が済んだら、Claude Code の Auto mode（自動承認）に切り替えて進めると効率的、と案内する。Auto mode はスキルからは有効化できないので、切替はユーザーが行う。整理前に Auto mode を勧めない（未整理のまま自動承認は危険）。
4. 設計は superpowers /brainstorming を使うことを"ユーザーに推奨として伝える": このスキルが勝手に brainstorming を起動するのではない。「新規開発や大きめの改修など、何かをやりたいときは、いきなり実装せず、プランモードに切り替えて /brainstorming スキルで設計してから進めるのがおすすめです」とユーザーに伝える（提案）。これにより、ユーザーが「brainstorming で設計したい」と判断できるようになる（実際の設計対話は、探索→1問ずつ質問→2〜3案→セクションごと合意 の流れ）。
   • 補足: brainstorming は自動では起動せず、ユーザーがそれで進めたいとき（または「設計から」と依頼したとき）に呼び出される。superpowers 未導入なら前提節の導入案内へ誘導する。
5. 実装フェーズへ: 設計が固まったら下記「設計→計画→spec の順序」に従い、実装は技術スキル（正本は basercms5-plugin-development / basercms5-theme-development、共通ルールは basercms5-development、移行は basercms-plugin-4-to-5-upgrade / basercms-plugin-5x-update）＋テストは basercms-unittest で進める。大規模プラグイン移行の進め方（横断コードチェック→横断構文5系化→テスト&ブラウザ）は basercms-plugin-4-to-5-upgrade「移行の進め方」を参照。

設計→計画→spec の順序（plan モードでレビューを挟む場合）

この手順の正本はこのスキル（~/.claude/CLAUDE.md 側は要点＋本スキルへの参照に集約済み・重複防止）。

superpowers:brainstorming で設計するときは、最終設計をいきなり docs/superpowers/specs/ に書き出さず、plan プレビューでレビューする。

★前提: plan プレビューでのレビューには ExitPlanMode が必要で、これは plan モードでしか使えない。だから、まず plan モードに切り替えてから brainstorming を呼ぶことを推奨する（plan プレビューでユーザーがレビューしやすくなる）。plan モードへの切替はユーザー操作（Shift+Tab で plan モードに）。アシスタントは「先に plan モードへ切り替えて設計しましょう」と案内する。

1. plan モードに切り替える → その中で brainstorming の対話（探索→1問ずつ質問→2〜3案→セクションごと合意）を進める。
2. 合意した最終設計を plan ファイルに記述し、ExitPlanMode で承認（plan プレビュー）に出す（この段階では docs/superpowers/specs/ への書き出し・writing-plans への遷移はまだしない）。
3. ユーザーがプランプレビューでレビューし、指摘を反映（必要なら直して再度 ExitPlanMode）。
4. 承認されたら、レビュー反映後の最終設計を docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に書き出す → 下記プレビューで HTML 化＋表示 → superpowers:writing-plans で実装計画へ。

• まとめ: brainstorming 対話 → plan ファイル → ExitPlanMode（レビュー）→ 承認＆反映 → docs/superpowers/specs/ へ spec 書き出し → writing-plans。
• 補足: plan モードでない通常対話の brainstorming は従来どおり（直接 spec 書き出し）でよい。本順序は「plan モードでレビューを挟みたいとき」のもの。

spec / plan の Markdown プレビュー

spec（設計書）や plan（実装計画）などレビュー目的の Markdown を作成・更新したら、HTML に変換してブラウザで開くまで行う（毎回「プレビューして」と言われなくても自動で）。出力先は scratchpad 等の一時ディレクトリ、open <output.html> で表示（生成 HTML はコミットしない）、Markdown 更新時は再生成。

• 変換手段（優先順・無ければ次へフォールバック）:
  1. markdown-to-html スキル（scripts/md_to_html.py、外部ライブラリ不要の自己完結）で完全な HTML 文書を出力（--fragment なし）。← 推奨。
  2. スキルが無いプロジェクトでは（＝他PJで起きやすい）、次のいずれかにフォールバック:
     • (a) 環境セットアップとして markdown-to-html スキルをそのプロジェクトに用意することを提案（依存なしの python スクリプト1本。opt-in）。
     • (b) pandoc <in>.md -o <out>.html がインストール済みならそれで変換 → open。
     • (c) いずれも無ければ、最小の変換（python の markdown ライブラリ、または簡易変換スクリプトを scratchpad に書いて実行）で HTML 化 → open。
  3. どれも難しい場合は、その旨を伝えてユーザーに選んでもらう（プレビュー無しで進める／変換手段を用意する）。
• 要は「HTML 化してブラウザ表示」という目的が達成できればよく、特定スキルの有無で止めない。

Auto mode の前提と注意

• 前提: Auto mode（自動承認）を使う前に permissions-audit でパーミッションを整理し、危険操作は deny 済みにしておく。未整理のまま自動承認は危険。
• スキルからは有効化できない: Auto mode は Claude Code の CLI 機能。本スキルは「ここで切り替えると効率的」と案内するだけで、切替はユーザーが行う。
• 整理済みなら、設計合意後の反復実装（横断書き換え・テスト・台帳更新等）は Auto mode で効率よく回る。

ユーザーへブラウザ動作確認を依頼する際は対象URLを明示する（常時ON）

• サブエージェントがサンドボックス制約でブラウザ確認できなかった場合や、実装完了後にユーザー自身の目視確認を依頼する場合は、確認してほしいページのURLを必ず明示する（/recruit/採用情報/ のようなパスの言及だけで済ませない）。ローカル開発環境のドメイン（例 https://<project>.localhost/...）まで含め、実際にクリック/コピーしてアクセスできる形で提示する。
• URLはMarkdownリンク付きで提示する。
• 理由: パスだけの言及だと、ユーザーが都度URLを組み立て直す手間が生じる。動作確認依頼は「何を」だけでなく「どこで」をワンアクションで開始できる形にする。
• ★baserCMS5の管理画面URLは、渡す前に必ず疎通確認する（推測で渡さない）。実例（同一セッションで2回発生）: (a) 別プラグインのURLパターンから類推したplugin-a/plugin_bs/indexが404（正しくは対象プラグインのadminNavigation設定に基づく別のダッシュ区切り）、(b) BcBlogの記事編集URLが/edit/{postId}ではなく/edit/{blogContentId}/{postId}が正しい形式（コントローラのbeforeFilterがpass.0をblogContentIdとして要求するため）で、/edit/{postId}だと「コンテンツデータが見つかりません」というBcExceptionになる。
  • 確認手順: ①docker exec <container> sh -c 'cd <v5> && bin/cake routes 2>&1 | grep -i <plugin名またはcontroller名>'で実際のルートパターン（plugin/prefix/controller/action）を確認、②未ログイン状態でcurl -sk -o /dev/null -w '%{http_code}'を打ち、302（ログインへのリダイレクト）なら経路として正しい、404ならルート自体が誤り、500系ならアプリ側の例外（curlの段階でここまで検知できることもある）。
  • このひと手間で「不具合と思ったらURL指定ミスだった」という往復を防げる（basercms-theme-4-to-5-upgrade F-23の「本番実測」姿勢と同じく、推測より実測を優先する）。

関連スキル

• 設計: superpowers:brainstorming / 計画: superpowers:writing-plans
• パーミッション整理: permissions-audit
• 技術パターン（実装）: basercms5-development（5系共通ルールの基底）/ basercms5-plugin-development（プラグイン開発の正本）/ basercms5-theme-development（テーマ開発の正本）/ basercms-plugin-4-to-5-upgrade（プラグイン4→5の書き換え＋「移行の進め方」）/ basercms-plugin-5x-update（5.x 間の更新）/ basercms4-to-5-upgrade（サイト全体の4→5）
• テスト実行: basercms-unittest
• プレビュー変換: markdown-to-html