name	Workflow Rules
description	開発ガイドライン、コンポーネント細分化ルール、公開後のGit/DB運用（Additive Changes）のルール

Workflow Rules

Development Guidelines

Atomic Design: 機能追加は小さく分割し、1機能1コミットを心がける。
Security First: データベース操作は必ずRLSポリシーを介して行う。クライアント側でのフィルタリングに依存せず、DBレベルでセキュリティを担保する。
Context Awareness: apps/extension/ と apps/app/ は異なる環境であることを意識し、混同しない。
Extension Context:
- 拡張機能内でのデータ再取得（リフェッチ）は、Reactのライフサイクルだけでなく、chrome.tabs.onUpdated や chrome.tabs.onActivated などのブラウザイベントをトリガーにすること。
- バックグラウンドでタブが切り替わった際も正しくコンテキストを追従させる必要がある。
Development Workflow & Package Management:
- ワークスペースの依存関係解決は必ず Bun に一任すること。npm や pnpm が裏で動いてロックファイルが競合しないよう、エディタ側の自動実行コマンド等にも細心の注意を払うこと。
- 検証コマンドの直接実行と型の確認: パッケージごとの package.json に typecheck などのスクリプトが定義されていない場合があるため、bun run -F "*" のようなモノレポ一括実行コマンドを推測で叩かないこと。型チェックを行う際は、必ず対象のディレクトリ（例: apps/app/）に移動するか直接パスを指定して bun x tsc --noEmit を実行すること。また、Biome (biome check) はフォーマットとLintのみを行い型の整合性をチェックしないため、必ず TypeScript (tsc --noEmit) のチェックと併用して開発の安全性を担保すること。
- Next.jsの開発サーバーと検査ツールの競合によるキャッシュ破損:
  - 事実: bun run dev (Next.js / Turbopack) が起動している状態で、フォーマッター（Biome）、テストランナー（Vitest）、型コンパイラ（tsc）などを乱れ打ち（連続・並行実行）すると、ファイル監視プロセスが競合し、Next.jsのビルドキャッシュ（.next ディレクトリ）が完全に破損する事象が確認されている。これにより、依存関係の解決で無限ループに陥り、CPU稼働率が異常に跳ね上がる（フリーズする）原因となる。
  - トラブルシューティング: 開発サーバー起動時や作業中に不可解なCPUスパイクや無限コンパイルが発生した場合は、コードのバグを疑う前に、まずターミナルで rm -rf apps/app/.next を実行してビルドキャッシュを物理削除し、環境をクリーンアップすること。
Release & Post-Release Workflow (公開後の運用ルール):
- ブランチ戦略の維持: 複雑な運用（developブランチ等）は避け、引き続き main ブランチを本番環境（最新状態）とし、機能開発やバグ修正は feature/* や fix/* ブランチで行うシンプルな GitHub Flow を維持する。
- バージョンタグ管理: Chromeウェブストアへの審査提出用ZIPファイルを作成・提出したタイミングで、必ず main ブランチの該当コミットにバージョンタグ（例: v1.0.1）を打つ。これにより、審査中に緊急のバグ修正（hotfix）が発生した際、安全に該当バージョンからブランチを切って対応できるようにする。
- DB/APIの安全な変更 (Additive Changes Only):
  - 審査のタイムラグによる「本番API/DBと公開中拡張機能のバージョン不整合」を防ぐため、DBやAPIの変更は**「追加（Additive）」のみ**とする（Expand & Contract パターン）。
  - 既存の拡張機能を壊さない（後方互換性を保つ）よう、既存カラムの削除（DROP）や名前変更（RENAME）、既存APIのレスポンス構造の破壊的変更は厳禁とする。
  - 新機能の追加時は、新しいカラム（NULL許可またはデフォルト値あり）の追加や、新しいAPIエンドポイントの追加のみで対応する。
Component & Logic Segmentation (コンポーネントの細分化と管理):
- 階層型UIにおけるアクションの制限: 階層型UIにおいて、アクションボタン（新規作成や一括操作など）の表示条件には必ず「最深部のコンテキスト（exact等）」を含めること。途中の階層（ページ一覧など）でのアクション表示は誤操作を招くため禁止とする。
- 1ファイルが150行を超え始めたら、積極的なコンポーネント分割（UIの切り出し）、またはカスタムフックへのロジック抽出（UIとLogicの分離）を検討すること。
- AI自身がコードを生成・修正する際も、1つの巨大なコンポーネントにすべてを詰め込まず、意味のある単位で components/ 配下にファイルを切り出すこと。
- UIコンポーネント変更の対称性確認: グローバルなUI（ナビゲーションやアクション）を変更する際は、必ずDesktop（GlobalSidebar 等）とMobile（AppShell内のFABやMobileBottomNav 等）の両方のコンテキストを同時に確認・修正し、実装の乖離を防ぐこと。
- Hooks抽出の基準: データフェッチ（Supabase等）、認証状態管理、外部API・ブラウザAPI（Chrome Tabs等）との通信などの副作用を伴うロジックは hooks/ 配下に useXXX.ts として分離し、UIコンポーネントを純粋なプレゼンテーション層に保つこと。
- コンテナとプレゼンテーション層の分離: ページのルートコンポーネント（例: サイドパネルのトップ）はフックから状態を受け取り、切り出したUIコンポーネントへPropsとして渡す「薄いコンテナ」に徹すること。
UX & Optimistic Updates (心地よい手触りと楽観的UI):
- ユーザーの思考を妨げない「サクサクとした心地よい手触り」を実現するため、メモの追加・更新・並び替え・削除などのアクションでは、APIのレスポンス完了を待つことによるローディング（スピナー等）や画面のチラつきを極力排除すること。
- データの更新処理では、まずローカルのステートを即時に（楽観的に）更新してUIへ反映させ、バックグラウンドでDB（Supabase等）へリクエストを飛ばす設計（オプティミスティック更新）を基本方針とする。
- 万が一APIリクエストが失敗した場合は、ローカルステートを元の状態にサイレントにロールバックし、トースト等でエラー通知を行う安全設計を徹底すること。
- Ghost Dataの防止と In-Memory State Pattern: 「親レコード（例: 新規ドラフト）がDBに未保存の状態で、子レコード（例: メモ）を作成するUIにおいて、裏側で勝手に親を自動保存（Auto-save）してはならない。必ずブラウザのメモリ上（React State）で一時保持し、ユーザーが明示的に保存ボタンを押したタイミングで、親レコードの生成と子レコードの一括同期（Bulk Insert）を行う設計とすること。」
- データフェッチ戦略: Slim Fetching & Intent-Driven Prefetching:
  - 事象: 初期ロード時に全ノートの content（本文テキスト）まで取得すると、データ量増大時に通信とメモリを圧迫し、ローディングによるUXの悪化を招く。
  - ルール: 大量のリストデータを取得する際は、初期ロード（AppShell等でのグローバルフェッチ）では必ず**メタデータのみ（Slim Fetching）**を取得すること（例: select("id, url_pattern, created_at...") で content を除外）。重いデータ（本文など）は、ユーザーがフォルダを開くなどの「意図（Intent）」を見せた瞬間に裏側で非同期取得する（Intent-Driven Prefetching）、または画面に表示される直前に取得（Lazy Fetching）するよう、責務とタイミングを完全に分離すること。
- サイレント・リフェッチ (Silent Refetching) の徹底:
  - 事象: 拡張機能内でノート編集中に、裏側で chrome.tabs.onUpdated 等が発火してデータが再取得された際、loading === true の判定でリスト全体がアンマウントされ、入力中のテキスト（ローカルステート）が吹き飛ぶ致命的なバグが発生した。
  - ルール: バックグラウンド通信や定期更新でデータを再取得する際、すでにデータが表示されている（notes.length > 0）場合は、絶対にローディングスピナー等でUI全体を置き換えてはならない。既存のUIを維持したまま裏側で静かにデータを更新し、ユーザーの入力フォーカスと状態を保護すること。
- 非同期処理（AI機能等）のエラーハンドリングと通知のUX:
  - 処理が失敗した場合、ネイティブの alert はUXを著しく損ねるため絶対に使用禁止とする。代わりに react-hot-toast 等のトースト通知（視認性を高めるため top-center 配置を標準とする）を用いて、ユーザーに優しいエラーメッセージ（「APIが混み合っています」等）を提示すること。
  - エラー発生時にテキストエリア等を disabled にしてユーザーの入力を妨害してはならない。エラー時は静かにローディング状態のみを解除（ロールバック）し、ユーザーの執筆フローを保護すること。
  - Ghost Textなどのバックグラウンドで高頻度に走る「Lightタスク」が失敗した場合はトーストを出さずサイレントに失敗させる。ショートカットキー等による「明示的な呼び出し（手動トリガー）」の時のみエラー通知を出すよう、出し分けを徹底すること。
- モーダル・イン・モーダルの原則禁止: モバイル対応などでドロワー（Drawer/Sheet）を使用する際、その内部でさらにPopoverやDialogを深くネストする設計はフォーカストラップの競合を招くため原則禁止とする。状態変更はインライン展開（アコーディオン）などの代替UIで解決すること。
Local Development & Ports (ローカル開発環境のネットワーク固定化):
- APIのポート 8787 への厳格な固定、および Next.js 等の実機テスト時の IPv4 (127.0.0.1) のすれ違い防止などを含む具体的なネットワークルールについては、.agent/skills/architecture/SKILL.md に記載の「ローカル開発環境のネットワーク固定化」を参照し、厳守すること。

10. State Management & Caching Strategy (状態管理の完全分離とキャッシュ戦略)

現代のReact開発における「状態管理の責任範囲の切り分け」を究極のベストプラクティスとして厳守すること。ZustandとTanStack Queryの責務を混同すると、キャッシュの不整合や意図しないUIの初期化（リスト消失など）を引き起こす致命的なバグに繋がる。

TanStack Query (サーバー状態・Server State の管理):
- 責務: データベース（Supabase等）から取得したデータ、検索結果、APIのローディング状態（isFetching / isLoading）、キャッシュの有効期限管理。
- 絶対ルール: APIから取得した結果（例: searchResults）を絶対にZustandのStoreに格納してはならない。検索やフィルタリングを行う際は、URLパラメータ（q, tags等）を useSearchParams で取得し、それを直接TanStack Queryの Query Key に含めることで、URLとキャッシュ状態を完全に同期させること。
Zustand (ローカルUI状態・Client State の管理):
- 責務: データベースには保存されない、純粋なブラウザ上のUIステートの管理。
- 具体例: 「現在選択中のノートID（selectedNoteId）」、「編集中テキストの未保存フラグ（isDirty）」など。
Slim Fetching とキャッシュの一括同期 (Cache Normalization):
- 事象: 初期ロード時はメタデータのみを取得（Slim Fetching）し、後から本文（content）を遅延フェッチしてキャッシュを更新する際、queryClient.setQueryData で特定のキー（例: ['notes']）のみを更新すると、派生キー（例: ['notes', 'search', 'keyword']）のキャッシュに本文が同期されず、画面が空振りする問題が発生する。
- 絶対ルール: 遅延フェッチなどで取得した詳細データを既存のキャッシュリストにマージする際は、完全一致の setQueryData ではなく、必ず部分一致（プレフィックス一致）の setQueriesData を使用し、関連するすべての派生キャッシュ（検索結果一覧など）にデータを一斉分配・同期（正規化）すること。
```
// ❌ Bad: 通常のノート一覧しか更新されない
queryClient.setQueryData<Note[]>(['notes'], updater);

// ✅ Good: ['notes'] から始まるすべてのキャッシュ（検索結果等）を透過的に一括更新する
queryClient.setQueriesData<Note[]>({ queryKey: ['notes'] }, updater);
```
Search Trigger Optimization (検索実行の意図的制御とコンテキストの分離):
- 検索UIはその対象データ量（コンテキスト）に応じて、APIリクエストのトリガーを明確に使い分けること。
- グローバル検索（SearchModal等）: アプリ全体の膨大なノートを対象とするため、APIコストとパフォーマンス低下（UIのチラつき等）を防ぐ目的で、入力欄の onChange イベントで都度検索を実行してはならない。必ず「Enterキーの押下」または「検索実行ボタンのクリック」を明示的なトリガーとすること。
- ローカル絞り込み検索（中ペイン等のリスト内）: すでに特定のドメインやフォルダで絞り込まれた限定的なデータを対象とする場合は、逆にUXの快適さを優先し、onChange による自動検索（インクリメンタルサーチ）の実装を許可・推奨する。
URL Params as Single Source of Truth (ドリルダウンとコンテキストの管理):
- フォルダの階層移動（ドリルダウン）や、検索結果からの特定のリストへのジャンプ（コンテキストジャンプ）を行う際、現在の階層状態をZustand等のクライアントステートで管理してはならない。
- 絶対ルール: 階層や表示ビューの切り替えは、すべて URLSearchParams (?domain=..., ?exact=... 等) を唯一の情報源（SSOT）として設計し、どのURLにアクセスしても意図したUI階層が正確に復元される堅牢なルーティングを構築すること。
- 検索結果の二次フィルタリング: 検索実行中（qやtagsが存在）であっても、URLに domain や exact のコンテキストパラメータが存在する場合は、それは『ユーザーが検索結果からさらに特定コンテキストへドリルダウンした結果』であるとみなし、取得した検索結果に対して必ず二次フィルタリングを適用して表示を絞り込むこと。

11. Refactoring & Code Smell Detection (リファクタリングとコードの匂い)

AIが実装や修正を提案する際、以下の「コードの匂い（Code Smell）」を検知した場合は、局所的なパッチ修正（Workaround）に留まらず、アーキテクチャレベルでのリファクタリング（Best Practice）を提案すること。

コードの重複 (Duplicated Code): 複数のコンポーネントに似たような useEffect やイベントリスナー（例: スクロール監視）が存在する場合。-> Centralized Approach への移行を提案する。
不自然なDOM要素 (Unnatural DOM): レイアウトの帳尻合わせのためだけに使われている空の div（スペーサー）や、過剰な absolute 配置がある場合。-> CSSの流れ（Flow）を利用した自然なレイアウトへの移行を提案する。
状態の不一致 (State Inconsistency): URLパラメータの更新とZustandのステート更新が同時に（または片方だけ）行われている場合。-> URLをSSOTとした設計への修正を提案する。

12. Layout & Positioning Robustness (レイアウトとポジショニングの堅牢性)

AppShellのモバイル原則: モバイル環境のAppShellは「3段ボックス構造（Header/Content/Nav）」を基本とし、JSによる動的な高さ変更やスクロール監視を伴う要素の隠蔽ロジック（hide-on-scroll等）はレイアウト崩れとパフォーマンス低下を招くため原則禁止とする。

name	Workflow Rules
description	開発ガイドライン、コンポーネント細分化ルール、公開後のGit/DB運用（Additive Changes）のルール

Workflow Rules

Development Guidelines

Atomic Design: 機能追加は小さく分割し、1機能1コミットを心がける。
Security First: データベース操作は必ずRLSポリシーを介して行う。クライアント側でのフィルタリングに依存せず、DBレベルでセキュリティを担保する。
Context Awareness: apps/extension/ と apps/app/ は異なる環境であることを意識し、混同しない。
Extension Context:
- 拡張機能内でのデータ再取得（リフェッチ）は、Reactのライフサイクルだけでなく、chrome.tabs.onUpdated や chrome.tabs.onActivated などのブラウザイベントをトリガーにすること。
- バックグラウンドでタブが切り替わった際も正しくコンテキストを追従させる必要がある。
Development Workflow & Package Management:
- ワークスペースの依存関係解決は必ず Bun に一任すること。npm や pnpm が裏で動いてロックファイルが競合しないよう、エディタ側の自動実行コマンド等にも細心の注意を払うこと。
- 検証コマンドの直接実行と型の確認: パッケージごとの package.json に typecheck などのスクリプトが定義されていない場合があるため、bun run -F "*" のようなモノレポ一括実行コマンドを推測で叩かないこと。型チェックを行う際は、必ず対象のディレクトリ（例: apps/app/）に移動するか直接パスを指定して bun x tsc --noEmit を実行すること。また、Biome (biome check) はフォーマットとLintのみを行い型の整合性をチェックしないため、必ず TypeScript (tsc --noEmit) のチェックと併用して開発の安全性を担保すること。
- Next.jsの開発サーバーと検査ツールの競合によるキャッシュ破損:
  - 事実: bun run dev (Next.js / Turbopack) が起動している状態で、フォーマッター（Biome）、テストランナー（Vitest）、型コンパイラ（tsc）などを乱れ打ち（連続・並行実行）すると、ファイル監視プロセスが競合し、Next.jsのビルドキャッシュ（.next ディレクトリ）が完全に破損する事象が確認されている。これにより、依存関係の解決で無限ループに陥り、CPU稼働率が異常に跳ね上がる（フリーズする）原因となる。
  - トラブルシューティング: 開発サーバー起動時や作業中に不可解なCPUスパイクや無限コンパイルが発生した場合は、コードのバグを疑う前に、まずターミナルで rm -rf apps/app/.next を実行してビルドキャッシュを物理削除し、環境をクリーンアップすること。
Release & Post-Release Workflow (公開後の運用ルール):
- ブランチ戦略の維持: 複雑な運用（developブランチ等）は避け、引き続き main ブランチを本番環境（最新状態）とし、機能開発やバグ修正は feature/* や fix/* ブランチで行うシンプルな GitHub Flow を維持する。
- バージョンタグ管理: Chromeウェブストアへの審査提出用ZIPファイルを作成・提出したタイミングで、必ず main ブランチの該当コミットにバージョンタグ（例: v1.0.1）を打つ。これにより、審査中に緊急のバグ修正（hotfix）が発生した際、安全に該当バージョンからブランチを切って対応できるようにする。
- DB/APIの安全な変更 (Additive Changes Only):
  - 審査のタイムラグによる「本番API/DBと公開中拡張機能のバージョン不整合」を防ぐため、DBやAPIの変更は**「追加（Additive）」のみ**とする（Expand & Contract パターン）。
  - 既存の拡張機能を壊さない（後方互換性を保つ）よう、既存カラムの削除（DROP）や名前変更（RENAME）、既存APIのレスポンス構造の破壊的変更は厳禁とする。
  - 新機能の追加時は、新しいカラム（NULL許可またはデフォルト値あり）の追加や、新しいAPIエンドポイントの追加のみで対応する。
Component & Logic Segmentation (コンポーネントの細分化と管理):
- 階層型UIにおけるアクションの制限: 階層型UIにおいて、アクションボタン（新規作成や一括操作など）の表示条件には必ず「最深部のコンテキスト（exact等）」を含めること。途中の階層（ページ一覧など）でのアクション表示は誤操作を招くため禁止とする。
- 1ファイルが150行を超え始めたら、積極的なコンポーネント分割（UIの切り出し）、またはカスタムフックへのロジック抽出（UIとLogicの分離）を検討すること。
- AI自身がコードを生成・修正する際も、1つの巨大なコンポーネントにすべてを詰め込まず、意味のある単位で components/ 配下にファイルを切り出すこと。
- UIコンポーネント変更の対称性確認: グローバルなUI（ナビゲーションやアクション）を変更する際は、必ずDesktop（GlobalSidebar 等）とMobile（AppShell内のFABやMobileBottomNav 等）の両方のコンテキストを同時に確認・修正し、実装の乖離を防ぐこと。
- Hooks抽出の基準: データフェッチ（Supabase等）、認証状態管理、外部API・ブラウザAPI（Chrome Tabs等）との通信などの副作用を伴うロジックは hooks/ 配下に useXXX.ts として分離し、UIコンポーネントを純粋なプレゼンテーション層に保つこと。
- コンテナとプレゼンテーション層の分離: ページのルートコンポーネント（例: サイドパネルのトップ）はフックから状態を受け取り、切り出したUIコンポーネントへPropsとして渡す「薄いコンテナ」に徹すること。
UX & Optimistic Updates (心地よい手触りと楽観的UI):
- ユーザーの思考を妨げない「サクサクとした心地よい手触り」を実現するため、メモの追加・更新・並び替え・削除などのアクションでは、APIのレスポンス完了を待つことによるローディング（スピナー等）や画面のチラつきを極力排除すること。
- データの更新処理では、まずローカルのステートを即時に（楽観的に）更新してUIへ反映させ、バックグラウンドでDB（Supabase等）へリクエストを飛ばす設計（オプティミスティック更新）を基本方針とする。
- 万が一APIリクエストが失敗した場合は、ローカルステートを元の状態にサイレントにロールバックし、トースト等でエラー通知を行う安全設計を徹底すること。
- Ghost Dataの防止と In-Memory State Pattern: 「親レコード（例: 新規ドラフト）がDBに未保存の状態で、子レコード（例: メモ）を作成するUIにおいて、裏側で勝手に親を自動保存（Auto-save）してはならない。必ずブラウザのメモリ上（React State）で一時保持し、ユーザーが明示的に保存ボタンを押したタイミングで、親レコードの生成と子レコードの一括同期（Bulk Insert）を行う設計とすること。」
- データフェッチ戦略: Slim Fetching & Intent-Driven Prefetching:
  - 事象: 初期ロード時に全ノートの content（本文テキスト）まで取得すると、データ量増大時に通信とメモリを圧迫し、ローディングによるUXの悪化を招く。
  - ルール: 大量のリストデータを取得する際は、初期ロード（AppShell等でのグローバルフェッチ）では必ず**メタデータのみ（Slim Fetching）**を取得すること（例: select("id, url_pattern, created_at...") で content を除外）。重いデータ（本文など）は、ユーザーがフォルダを開くなどの「意図（Intent）」を見せた瞬間に裏側で非同期取得する（Intent-Driven Prefetching）、または画面に表示される直前に取得（Lazy Fetching）するよう、責務とタイミングを完全に分離すること。
- サイレント・リフェッチ (Silent Refetching) の徹底:
  - 事象: 拡張機能内でノート編集中に、裏側で chrome.tabs.onUpdated 等が発火してデータが再取得された際、loading === true の判定でリスト全体がアンマウントされ、入力中のテキスト（ローカルステート）が吹き飛ぶ致命的なバグが発生した。
  - ルール: バックグラウンド通信や定期更新でデータを再取得する際、すでにデータが表示されている（notes.length > 0）場合は、絶対にローディングスピナー等でUI全体を置き換えてはならない。既存のUIを維持したまま裏側で静かにデータを更新し、ユーザーの入力フォーカスと状態を保護すること。
- 非同期処理（AI機能等）のエラーハンドリングと通知のUX:
  - 処理が失敗した場合、ネイティブの alert はUXを著しく損ねるため絶対に使用禁止とする。代わりに react-hot-toast 等のトースト通知（視認性を高めるため top-center 配置を標準とする）を用いて、ユーザーに優しいエラーメッセージ（「APIが混み合っています」等）を提示すること。
  - エラー発生時にテキストエリア等を disabled にしてユーザーの入力を妨害してはならない。エラー時は静かにローディング状態のみを解除（ロールバック）し、ユーザーの執筆フローを保護すること。
  - Ghost Textなどのバックグラウンドで高頻度に走る「Lightタスク」が失敗した場合はトーストを出さずサイレントに失敗させる。ショートカットキー等による「明示的な呼び出し（手動トリガー）」の時のみエラー通知を出すよう、出し分けを徹底すること。
- モーダル・イン・モーダルの原則禁止: モバイル対応などでドロワー（Drawer/Sheet）を使用する際、その内部でさらにPopoverやDialogを深くネストする設計はフォーカストラップの競合を招くため原則禁止とする。状態変更はインライン展開（アコーディオン）などの代替UIで解決すること。
Local Development & Ports (ローカル開発環境のネットワーク固定化):
- APIのポート 8787 への厳格な固定、および Next.js 等の実機テスト時の IPv4 (127.0.0.1) のすれ違い防止などを含む具体的なネットワークルールについては、.agent/skills/architecture/SKILL.md に記載の「ローカル開発環境のネットワーク固定化」を参照し、厳守すること。

10. State Management & Caching Strategy (状態管理の完全分離とキャッシュ戦略)

TanStack Query (サーバー状態・Server State の管理):
- 責務: データベース（Supabase等）から取得したデータ、検索結果、APIのローディング状態（isFetching / isLoading）、キャッシュの有効期限管理。
- 絶対ルール: APIから取得した結果（例: searchResults）を絶対にZustandのStoreに格納してはならない。検索やフィルタリングを行う際は、URLパラメータ（q, tags等）を useSearchParams で取得し、それを直接TanStack Queryの Query Key に含めることで、URLとキャッシュ状態を完全に同期させること。
Zustand (ローカルUI状態・Client State の管理):
- 責務: データベースには保存されない、純粋なブラウザ上のUIステートの管理。
- 具体例: 「現在選択中のノートID（selectedNoteId）」、「編集中テキストの未保存フラグ（isDirty）」など。
Slim Fetching とキャッシュの一括同期 (Cache Normalization):
- 事象: 初期ロード時はメタデータのみを取得（Slim Fetching）し、後から本文（content）を遅延フェッチしてキャッシュを更新する際、queryClient.setQueryData で特定のキー（例: ['notes']）のみを更新すると、派生キー（例: ['notes', 'search', 'keyword']）のキャッシュに本文が同期されず、画面が空振りする問題が発生する。
- 絶対ルール: 遅延フェッチなどで取得した詳細データを既存のキャッシュリストにマージする際は、完全一致の setQueryData ではなく、必ず部分一致（プレフィックス一致）の setQueriesData を使用し、関連するすべての派生キャッシュ（検索結果一覧など）にデータを一斉分配・同期（正規化）すること。
```
// ❌ Bad: 通常のノート一覧しか更新されない
queryClient.setQueryData<Note[]>(['notes'], updater);

// ✅ Good: ['notes'] から始まるすべてのキャッシュ（検索結果等）を透過的に一括更新する
queryClient.setQueriesData<Note[]>({ queryKey: ['notes'] }, updater);
```
Search Trigger Optimization (検索実行の意図的制御とコンテキストの分離):
- 検索UIはその対象データ量（コンテキスト）に応じて、APIリクエストのトリガーを明確に使い分けること。
- グローバル検索（SearchModal等）: アプリ全体の膨大なノートを対象とするため、APIコストとパフォーマンス低下（UIのチラつき等）を防ぐ目的で、入力欄の onChange イベントで都度検索を実行してはならない。必ず「Enterキーの押下」または「検索実行ボタンのクリック」を明示的なトリガーとすること。
- ローカル絞り込み検索（中ペイン等のリスト内）: すでに特定のドメインやフォルダで絞り込まれた限定的なデータを対象とする場合は、逆にUXの快適さを優先し、onChange による自動検索（インクリメンタルサーチ）の実装を許可・推奨する。
URL Params as Single Source of Truth (ドリルダウンとコンテキストの管理):
- フォルダの階層移動（ドリルダウン）や、検索結果からの特定のリストへのジャンプ（コンテキストジャンプ）を行う際、現在の階層状態をZustand等のクライアントステートで管理してはならない。
- 絶対ルール: 階層や表示ビューの切り替えは、すべて URLSearchParams (?domain=..., ?exact=... 等) を唯一の情報源（SSOT）として設計し、どのURLにアクセスしても意図したUI階層が正確に復元される堅牢なルーティングを構築すること。
- 検索結果の二次フィルタリング: 検索実行中（qやtagsが存在）であっても、URLに domain や exact のコンテキストパラメータが存在する場合は、それは『ユーザーが検索結果からさらに特定コンテキストへドリルダウンした結果』であるとみなし、取得した検索結果に対して必ず二次フィルタリングを適用して表示を絞り込むこと。

11. Refactoring & Code Smell Detection (リファクタリングとコードの匂い)

コードの重複 (Duplicated Code): 複数のコンポーネントに似たような useEffect やイベントリスナー（例: スクロール監視）が存在する場合。-> Centralized Approach への移行を提案する。
不自然なDOM要素 (Unnatural DOM): レイアウトの帳尻合わせのためだけに使われている空の div（スペーサー）や、過剰な absolute 配置がある場合。-> CSSの流れ（Flow）を利用した自然なレイアウトへの移行を提案する。
状態の不一致 (State Inconsistency): URLパラメータの更新とZustandのステート更新が同時に（または片方だけ）行われている場合。-> URLをSSOTとした設計への修正を提案する。

12. Layout & Positioning Robustness (レイアウトとポジショニングの堅牢性)

AppShellのモバイル原則: モバイル環境のAppShellは「3段ボックス構造（Header/Content/Nav）」を基本とし、JSによる動的な高さ変更やスクロール監視を伴う要素の隠蔽ロジック（hide-on-scroll等）はレイアウト崩れとパフォーマンス低下を招くため原則禁止とする。