codebase-conventions

コードベースの規約

コードの記述方法や配置方法に関する、一般的に適用できる規約です。以下の規約をすべて読んでください。これから行おうとしていることに当てはまるものがあれば、適用してください。 これらはユーザーのプロジェクトにおけるデフォルトです。プロジェクトが明らかに別の規約に従っている場合は、そのプロジェクトに合わせ、その旨を伝えてください。

このスキルを参照するタイミング

次の作業を行うときは、いつでも参照してください。

• 新しいファイルを作成するとき、または新しいモジュール（コンポーネント、フック、ユーティリティ、サーバーアクション、型など）の配置先を決めるとき
• ファイル、コンポーネント、エクスポートに名前を付けるとき
• インポートを記述するとき
• プロジェクトのコマンド（インストール、ビルド、テスト、スクリプト）を実行するとき
• コメントを追加するとき

規約

ファイルの配置とコロケーション

各機能／ルートのフォルダーは、あたかもそれ自体が小さなリポジトリであるかのように、自己完結した単位として扱ってください。機能のコードは、利用される場所の近くにあるほど、試行錯誤や理解、将来の移動や削除が容易になります。まずはコロケーションを優先し、実際に幅広く使われる場合にのみグローバルフォルダーへ移してください。

コードの利用機能数に応じて配置を決めてください。

• 単一の機能／ルートで使用 → その機能の専用フォルダー内（例：機能内の components/、hooks/、actions/、lib/ サブフォルダー）に、利用側のすぐ近くに配置します。グローバルフォルダーには移しません。
• 少数の兄弟機能で共有 → 利用側が共通して属する最も近い共通の親フォルダーに移します。トップレベルのグローバルフォルダーに移すのではなく、すべての利用箇所を含む最下層のフォルダーを見つけ、そこに配置します。
• 真にグローバル — 多数の機能で使用 → ルートレベルの共有フォルダー（例：components/、lib/、hooks/、actions/、またはプロジェクト内の同等のフォルダー）が適切です。

追加の指針：

• デザインシステム／UI プリミティブ（components/ui/ フォルダーなどの共有コンポーネントライブラリ）は、利用する機能数にかかわらずグローバルに配置します。
• サードパーティサービスの初期化／設定クライアント（データベースクライアント、メール、ベクトルストア、キュー、分析など）は、グローバルな共有フォルダーに配置します。これらは機能コードではなく、複数領域にまたがるインフラストラクチャです。
• 機能のコンポーネントは、機能外からインポートされていても、その機能内にコロケーションしたままで問題ありません。外部からのインポートだけでは、グローバルフォルダーに移す根拠にはなりません。移動するのは、複数の機能で広く共有されるようになった場合に限ります。

ツールとインポート

• すべてのプロジェクトコマンド（インストール、スクリプトの実行、依存関係の追加／削除）には pnpm を使用します。プロジェクトが明らかに npm／yarn 用に設定されている場合を除き、これらは使用しないでください。
• 長い ../../../ の連鎖ではなく、相対パス以外のインポートにはプロジェクトのパスエイリアス（一般的には @/）を使用します。プロジェクトで既に設定されているエイリアスに合わせてください。

命名

• ファイルには kebab-case を使用します。
• React コンポーネントには PascalCase を使用します。
• 名前付きエクスポートのみを使用し、デフォルトエクスポートは避けます（ルート／ページのエントリーファイルなど、フレームワークで必要な場合を除く）。

コメント

• 自明でない前提、製品固有のロジック、リポジトリ固有の仕組み、または業界標準ではないものを含むコードのそばには、短いインラインコメントを付けます。1文で十分です。
• コードの内容を単に言い換えるだけのコメントは追加しないでください。十分な知識のある読み手がコードだけで理解できる場合、コメントは不要です。

今後追加される規約

このスキルは今後も拡充されます。新しい規約は、上記の規約セクションに、エージェントが機械的に適用できるルールとして追加してください。