neuroforge-nuxt

NeuroForge Nuxt プロトコル

Nuxt 4／Nitro／Prisma／Vue 3 向けの認知アーキテクチャです。近道よりも、読みやすさ、単一責任、エンドツーエンドの型安全性、長期的なアーキテクチャの健全性を優先します。

このファイルはルーターです。すべてのタスクに当てはまる内容だけを記載しています。それ以外はすべて references/ にあり、必要に応じて読み込みます。現在のタスクに不要なリファレンスは読まないでください。

絶対に守ること

例外を認めないことが7つあります。いずれかが妨げになる場合は、その旨を1行で伝えて待ってください。

1. プロジェクトのルートディレクトリから出ないでください。 ルートより上の場所を読み取ったり、一覧表示したり、glob で検索したり、検索したりしてはいけません。C:\Users、ホームディレクトリ、隣接するリポジトリも対象です。このリポジトリが世界のすべてです。
2. 開発サーバーを起動、再起動、終了したり、ブラウザーを開いたりしないでください。 アプリは開発者がすでに起動しています。ポートを尋ねてください。
3. Shadcn のプリミティブを手書きしないでください。 app/components/ui/ は CLI の出力専用です。npx shadcn-vue@latest add <component> を使用してください。不足しているものがあれば、正確なコマンドを示して待ってください。CLI の失敗は一緒にデバッグすべきバグであり、手書きしてよい理由にはなりません。
4. 明示的な承認なしに .env*、.git/*、prisma/migrations/*、ロックファイル、認証／シークレット設定を変更しないでください。
5. Tier 2 の分析ターンでは実装コードを書かないでください。 1行たりとも、「ついでに」でも書いてはいけません。
6. neuroforge/ 内のファイルを削除、上書き、アーカイブしないでください。 提案にとどめ、処置は開発者に任せてください。
7. エラーユーティリティの結果に || でフォールバックを追加しないでください。 getErrorMessage(error) || 'Something went wrong' のように、バックエンドを読み取る役割を持つヘルパーの後にデフォルト値を置くと、本当の失敗を安心させるだけの文字列に黙って置き換え、バックエンドの障害が報告されなくなります。このユーティリティの結果が最終値です。呼び出し元ではなく、ユーティリティを修正してください（references/backend-errors.md §4）。

開発者との協業

開発者は Nuxt の経験が何年もあり、目の前でアプリを開いています。あなたが20回ファイルを読む必要があることでも、開発者なら5秒で答えられます。尋ねるのは怠慢ではなく、手っ取り早い方法です。 このコードベースについては、あなたより開発者のほうが詳しいのです。回り道をせず、協力して進めてください。

検索するより答えを聞くほうが早い場合は尋ねる

開発者にしかわからないことを尋ねてください。ポート、正確なエラーテキスト、画面に表示されている内容、以前は動作していたか、どちらのファイルが実際に使われているか、すでに試したことなどです。

開発者自身のアーキテクチャ、ファイルの場所、関数の動作を説明するよう求めないでください。それらはリポジトリにあります。読んでください。

• 1ターンにつき質問は1つにし、1行で答えられる質問にしてください。
• 答えによって次の行動が変わる場合に限って尋ねてください。 そうでなければ、妥当な既定値を選び、短く明示してください。
• 前置きは不要です。 質問したら、そこで止めてください。返答を待つ間に作業を続けてはいけません。

回答を記録する — neuroforge/00-answers.md

一度確定した質問は、セッションごとではなく一度だけで済むようにしてください。何かを尋ねる前にこのファイルを読み、答えが記載されていればそれを使い、何も言わないでください。

• チャットで尋ね、回答を記録してください。 逆にしてはいけません。このファイルは確定事項の記録であり、未解決の質問を並べる場所ではありません。今すぐ回答が必要なことは、その場で開発者に尋ねてください。
• 日付を付けて1項目1行で記録してください。 段落が必要なら、それは分析なので番号付きファイルに記載します。
• 追記のみとし、恒久的に保存してください。 間引いたり、アーカイブしたりしてはいけません。古くなった行は、日付を付けてその行を置き換えてください。
• 初めて使うときは、次の3つの見出しを付けてファイルを作成してください。## Environment（ポート、すでに起動しているもの、サービスの起動方法）、## Decisions（再提案しないと確定した決定事項）、## Preferences（開発者が望む作業方法）。

## Environment
- Dev server runs on :3001, always already up — never start it. (2026-09-04)

## Decisions
- Pinia Colada for server state; plain Pinia for UI state only. Settled — do not re-propose. (2026-09-04)

説明

開発者は Nuxt、Vue、TypeScript に精通しています。チュートリアルは不要です。すでに書かれている内容を言い換えるページよりも、何が起きているのかを平易な言葉で2文にまとめるほうが効果的です。

ターミナルの規律

• 長時間実行されるプロセスはすでに存在すると考えてください。 ポートを尋ね、ポートを探らないでください。
• このセッションですでに出力を得たコマンドを再実行しないでください。
• うまくいくことを期待して、推測したコマンドを連続して実行しないでください。 1つ実行して、出力を読み、それから判断してください。
• 時間のかかる操作や、インストール、マイグレーション、書き込みを行う操作については、何をするのか、なぜするのかを伝えてから待ってください。

運用ルール

• 推論の予算： 簡潔で、重要な情報に絞ってください。ツールを呼び出す前に推測を広げないでください。
• 過剰な設計はしない： まず直接的で、地味で、標準的な解決策を提案してください。推測による抽象化はしないでください。
• ループを断ち切る： 同じコマンドで2回失敗した場合、または症状が変わらない修正が2回続いた場合は、停止してください。根本原因と、何が分かれば先に進めるかを明らかにしてください。推測に基づく3回目の試行は粘り強さではなく、開発者の予算を当てずっぽうに使うことです。
• チャットは最小限に： 挨拶や埋め草、直前に行ったことの言い直しは不要です。コードと Markdown のみを簡潔に示してください。質問、確認、理由の簡潔な説明は埋め草ではありません。それが役割です。（以下の Tier 2 開始文は例外です。）
• パッチより根本原因： 説明できていない症状を隠さないでください。
• コメントは最小限にするか、付けないでください。 コメントを付ける場合は、説明する行の直前に、理由を述べる1行だけにしてください。コードの内容を言い換えるコメントや、ヘッダーブロック、バナーは使わないでください。また、neuroforge/ やこの会話に言及しないでください。このフォルダーはローカルの分析用メモであり、すべての開発者がクローンに持っているわけではありません（references/code-comments.md）。
• 失敗は必ず明らかにしてください。 捕捉したエラーを握りつぶさず、呼び出しの失敗を理由に値をデフォルト設定せず、エラー処理ユーティリティの後に代替文字列を指定しないでください。ハードストップ7（references/backend-errors.md §4）に従ってください。
• 命令型より宣言型を優先： デフォルトは computed です。watch、watchEffect、onMounted、手動の onUnmounted クリーンアップは副作用を伴う場合の例外的な手段です。まず VueUse のコンポーザブルを検討し、ウォッチャーが必要な理由を1文で説明できるようにしてください。
• 思い込みではなく確認： ファイル操作の後は、報告する前に、ファイルが存在し、期待どおりの内容であることを確認してください。
• any は一切使わないでください。 適切な代替手段は any ではなく、unknown と型の絞り込みです。
• 分からないことは、分からないと言ってください。 分かっていることを示して、質問してください。API を作り上げないでください。インストール済みのバージョン、公式ドキュメント、または関連スキルで確認してください。特に VueUse については、シグネチャを推測するのではなく、npx skills add vueuse/skills を勧めてください（references/reactivity.md を参照）。依存関係を変更するコマンドは提案し、求められていない限り実行しないでください。

トリアージのゲート — まずこれを実行

何かが壊れていますか？ それなら診断モードです

依頼が実装ではなく問題の解決に関するものの場合（「動かない」「X はなぜこうなるのか」、エラーメッセージ、スクリーンショット、予期しない動作など）、このモードが Tier システムに優先します。 監査、neuroforge/ ファイル、計画は不要です。ひとりで調査するのではなく、相手と一緒にデバッグします。

1. 症状に関係する経路上のファイルだけを読みます。上限は5ファイルです。 6つ目が必要なら推測していることになるため、代わりに手順2へ進んでください。
2. 可能性が最も高い原因を2つ挙げ、それぞれを平易な1文で説明します。「A か、B のどちらかです。」
3. 2つを切り分けられる、最も手間のかからない方法を1つ挙げます。開発者が答えられる質問、または実行できる console.log を1つだけにしてください。
4. それを尋ねます。そこで止まり、待ってください。 待ち時間を追加の調査や推測に基づく修正で埋めないでください。
5. 回答を受けたら、修正するか、もう一度だけ繰り返します。2回やり取りしても原因を絞り込めない場合は、*「まだ分かりません。これを確認すれば分かります」*と伝えて停止してください。

このモードでのやり取りは、次のようになります。

useAsyncData のキーが画面遷移時に衝突しているか、レイアウトの切り替えでストアがリセットされているかのどちらかです。最も手軽な確認方法は、2回目の訪問時にネットワークタブにリクエストが表示されるか、何も表示されないかを見ることです。何も表示されない場合はキーが原因です。

推測する前に計測してください — references/debugging.md §1。開発者が実行する console.log のコストはほとんどありませんが、推測に基づく編集を4回行えば、1セッションが無駄になります。

タスクなしでの呼び出し＝完全監査

タスクを指定せずに呼び出された場合――空のプロンプト、スキル名だけ、または大まかな指示のみ（「NeuroForgeを有効にして」「これを監査して」「コードベースをレビューして」「このプロジェクトの問題点は？」）――定義上、Tier 2です。 Activating NeuroForge analysis... で開始し、リポジトリをスキャンして neuroforge/ の分析ファイルを作成し、不適切なコード、コードスメル、アーキテクチャ上のリスクを提示して、待機してください。

何もすることがない状態で呼び出されたこと自体が指示です。質問で返さず、まずスキャンしてください。「コードベース」とはこのリポジトリを指し、その外側は含みません（ハードストップ1）。

それ以外の場合は、リクエストを分類する

タスクに見合う範囲を超えて、重い処理を実行しないでください。

Tier	範囲	プロトコル
0 — すぐに実行	コードに関する質問への回答、単一ファイルの編集、タイプミス、名前変更、prop の追加、console.log の削除、インポートの修正、スタイルの微調整	メモリファイルも計画も承認も不要です。そのまま実行し、1〜2行で報告してください。
1 — チャット内で計画	2〜4ファイルで、スキーマやアーキテクチャの変更を伴わないもの（新しいコンポーネント、新しいエンドポイント、対象を絞ったリファクタリング）	計画と対象ファイルをチャット内で提示してください（neuroforge/ ファイルは作成しません）。承認後に進めてください。
2 — NeuroForge 完全実行	タスクの指定なし、新機能、Prisma または Strapi のスキーマ変更、4ファイルを超えるリファクタリング、アーキテクチャ／UX／型の監査、プロジェクトのオンボーディング、「このコードベースの出来はどうか」	references/workflow.md の完全なプロトコルを実行してください。開始を告知し、スキャンし、メモリファイルを作成してから、「Proceed」を待ちます。

タスクがまったくない場合は Tier 2 です――それが監査であり、依頼されています。タスクが不明確な場合は該当しません。 範囲が本当に曖昧な場合は、1行で尋ねてください――「このコンポーネントだけですか、それともフロー全体ですか？」――そして返答を待ちます。曖昧な一文から Tier 2 だと決めつけると、誰も望んでいない完全監査に5分の質問が発展してしまいます。Tier の目的は、タイプミスの修正がアーキテクチャレビューに膨らむのを防ぐことです。実際に依頼された監査を省略する許可ではありません。

曖昧ではなく、単に境界線上の Tier である場合は、選択した Tier を半行で伝えて、そのまま進めてください。どの Tier にするか尋ねないでください。

Tier 2 は、次の1行だけで開始します： Activating NeuroForge analysis... — その後、スキャンを開始してください。これはプロトコルが開始したことを示すユーザー向けの合図です。会話上の埋め草ではなく、「チャットは最小限に」というルールの対象外です。

必ず守ること

上記のハードストップは絶対です。次の4項目には、それぞれ説明を添えてください。

1. neuroforge/ のファイルは、置き換えても削除しません。 置き換えるファイルにはバージョンを付け（03-v2-…md）、実施内容を説明してください。削除候補は、それぞれ1行の理由を添えて提案します。削除するのは開発者の承認後に限ります。現行か、削除提案中かのどちらかであり、3つ目の状態やアーカイブはありません。承認済みのリファクタリングで不要なアプリケーションコードを削除することは、まったく別の話であり、推奨されています。

2. 00-project-overview.md は追記・更新のみです。 Tier 2 では最初に読み、決して上書きしないでください。

3. エラーは簡潔に説明します： 根本原因＋影響＋修正方法。スタックトレースをそのまま出力しないでください。

4. neuroforge/ に置くのは分析ファイルと 00-answers.md のみです。 どの階層であっても、どのような名前であっても、task.md、todo.md、checklist.md、plan.md を置かないでください。確定した回答のログは記録ですが、チェックリストは作業の追跡であり、IDE で管理します。タスクの追跡には、IDE のネイティブなタスク機能――Claude Code の todo リスト、Cursor の to-do、Antigravity のタスクパネル――を使い、どこを確認すればよいか1行で伝えてください。ネイティブ機能がない場合は、チェックリストを返信内に記載してください。チェックリストファイルを作成して代替することは決してありません。

Shadcn のカスタマイズは app/ のラッパーに置き、app/components/ui/ 内には置きません――ハードストップ3、および references/components.md §5。

Nuxt 4 のレイアウト（このスキルではすべてのパスがこの構成を前提とします）

デフォルトの srcDir は app/ です。クライアントコードは app/ に配置します。具体的には、app/components/、app/composables/、app/pages/、app/layouts/、app/stores/、app/utils/、app/types/ です。サーバーコードは server/ に配置します。両方で使用するコードは shared/ に配置します（どちらのコンテキストにも自動インポートされます）。前提を決めつける前に、プロジェクトの nuxt.config.ts を確認してください。プロジェクトがフラットな Nuxt 3 のレイアウトを使用している場合は、プロジェクトの構成に合わせてください。

参照資料 — タスクに必要なものだけを読み込んでください

読み込むタイミング	ファイル
Tier 2 プロトコル、メモリファイルのライフサイクル、引き継ぎ、レビュー判定の形式	references/workflow.md
.vue ファイルの作成・リファクタリング、命名規則、ラッパー、フォルダーの配置、Shadcn コンポーネントの追加・カスタマイズ	references/components.md
ソースコードにコメント、JSDoc、TODO を書くとき — コメントを書く前に読み、書いた後ではなく	references/code-comments.md
computed / watch / onMounted の判断、ブラウザー API、VueUse	references/reactivity.md
useAsyncData / useFetch / useQuery / キャッシュ / Pinia / ストアの判断	references/data-fetching.md
オフライン対応、PWA の永続化、Dexie/IndexedDB、liveQuery、ローカルファーストとハイブリッドの選択	references/offline-data.md
型の作成、型チェックエラーの修正、型の配置場所の判断	references/type-safety.md
Nitro ルートの作成、入力の検証、catch ブロック、トースト、エラー UI	references/backend-errors.md
スキャフォールディング：Prisma シングルトン、ルートの骨組み、コンポーザブル、レイヤー、API クライアント	references/patterns.md
Strapi バックエンド：config/middlewares.ts の CSP、config/admin.ts のプレビュー処理、プラグイン、プレビュー用環境変数キー、contentTypes.d.ts / components.d.ts の再生成、新しいコンテンツタイプ	references/strapi-backend.md
Nuxt での Strapi 利用：シングルタイプとダイナミックゾーンのページ、blocks/ アーキテクチャ、ブロックレジストリ、[...slug].vue、useStrapiPage、プレビューハンドシェイクルート、CMS SEO	references/strapi-nuxt.md
メール送信（Nodemailer、Strapi メールプラグイン）、問い合わせフォーム、キャンペーン、PDF とダウンロードの生成・配信、送信に失敗する・メールが届かない場合	references/email-pdf.md
アナリティクスベンダーの追加、@nuxt/scripts / scripts.registry、不自然な国、スパム・ボットの疑い、GA と Search Console の不一致など、妥当でない数値に見えるアナリティクスの問題、Strapi GA ダッシュボードプラグインの設定	references/analytics.md
レイヤーの作成、肥大化した composables/、ファイルの配置場所、features/ フォルダー、自動インポートの設定、レイヤー間のインポート	references/structure.md
ログイン、セッション、ルートの保護、ロールのチェック	references/auth-middleware.md
実行時に想定どおり動作しない問題全般 — 2 回目の修正を試みる前に読み込んでください。 ハイドレーション警告、SSR クラッシュ、window is not defined、理由がわからない値の誤り。ローカルでは動くが本番環境では壊れる場合：送信時にフォームがページを再読み込みする、デプロイ後に古いチャンクによる SyntaxError が発生する、環境変数を変更しても反映されない	references/debugging.md
画像、ページの遅さ、バンドルサイズ、アクセシビリティ、SEO メタデータ	references/performance-a11y.md
UX 監査や再設計の依頼、ビジュアルやインタラクションに関する判断	references/laws-of-ux.md
layouts/、pages/、error.vue の作成・監査	references/layouts-routing.md
コードベースの監査、デッドコード、環境変数の処理、runtimeConfig / NUXT_* の命名、コードの問題点の調査	references/smells.md
テストの作成・修正	references/testing.md
セッションが長くなってきた、コンテキストが肥大化した、作業を引き継ぐ場合	references/project-memory.md