busirocket-core-conventions

コア規約

コードベースを拡張しやすく保ち、AI エージェントが容易に操作できるようにする、再利用可能でプロジェクトに依存しない規約です。

使用するタイミング

次のような場合に、このスキルを使用します。

• 新機能に着手し、コードの配置場所を決めるとき
• 保守性を高めるためにリファクタリングするとき
• 「1 ファイルにつき 1 つ」の規律を徹底するとき
• 命名規約、レイアウト規約、境界ルールを定めるとき

必須事項（MUST）

• 小さく、目的を絞ったファイルを数多く用意し、境界を明確にします。
• 独自モジュール（コンポーネント／フック／関数／型）は、1 ファイルにつきエクスポートするシンボルを 1 つにします。
• 依存関係を隠すバレルファイル／インデックスファイル（例：index.ts）は作成しません。
• types/ 以外にインライン型を定義しません。
• コンポーネントやフック内にヘルパー関数を定義しません。utils/ に切り出します。
• 明示的に承認されていない限り、単純なヘルパーのために新たな依存関係を追加しません。

配置場所／境界

• ルート／ページ：app/**
• 再利用可能な UI：components/<area>/...
• オーケストレーション（状態／副作用）：hooks/<area>/useXxx.ts
• 純粋なロジック：utils/<area>/xxx.ts
• 外部との境界（ネットワーク／DB／認証／ストレージ）：services/<area>/xxx.ts
• 共有するデータ構造：types/<area>/Xxx.ts

ルール

コア原則

• core-agent-defaults - エージェントのデフォルト動作（小さな変更、質問する、依存関係を避ける）
• core-code-style - コードスタイルのガイドライン（英語のみ、純粋関数、ネストを避ける）
• core-repo-hygiene - リポジトリの衛生管理（バレルファイルを作らない、責務を 1 つにする、ハンドラーを薄く保つ）

境界と配置

• core-boundaries-decision-tree - コードの配置場所を決めるための判断ツリー（app、components、hooks、utils、services、types）
• core-boundaries-hard-rules - 境界に関する厳格なルール（エクスポートは 1 つ、インライン型を使わない、コンポーネント内にヘルパーを置かない）

命名とレイアウト

• core-naming-folder-layout - フォルダー構造の規約
• core-naming-file-naming - ファイル命名規約（PascalCase、camelCase、kebab-case）
• core-naming-exports - エクスポートの規約（default と named、Next.js の例外）
• core-naming-imports - インポートの規約（バレルファイルを使わない、相対パスとエイリアス）

Services と Utils

• core-services-vs-utils-contract - services/ と utils/ の使い分け
• core-services-vs-utils-api - services と utils の API ガイダンス
• core-services-vs-utils-route-handlers - ルートハンドラーの要件

アンチパターン

• core-anti-patterns-file-structure - ファイル構造のアンチパターン（複数のエクスポート、バレルファイル、雑多なモジュール）
• core-anti-patterns-types - 型のアンチパターン（インライン型、巨大な型ファイル）
• core-anti-patterns-react - React のアンチパターン（コンポーネント内でのフェッチ、コンポーネント内のヘルパー）
• core-anti-patterns-app-router - App Router のアンチパターン（肥大化したハンドラー、未検証の入力）
• core-anti-patterns-dependencies - 依存関係のアンチパターン（単純なヘルパー）
• core-anti-patterns-vite-browser - Vite／ブラウザーランタイムのアンチパターン（process.env、Node のグローバル変数）

関連スキル

• busirocket-typescript-standards - TypeScript 固有の標準
• busirocket-react - React のコンポーネント、フック、状態（Zustand）のパターン
• busirocket-refactor-workflow - リファクタリングのワークフロー

使用方法

詳細な説明とコード例については、各ルールファイルをお読みください。

rules/core-agent-defaults.md
rules/core-boundaries-decision-tree.md
rules/core-naming-folder-layout.md

各ルールファイルには、次の内容が含まれています。

• 重要な理由についての簡単な説明
• コード例（正しいパターンと誤ったパターン）
• 補足情報とベストプラクティス