| name | code-quality-rules |
| description | 実装時に遵守すべきコード品質ルール（500行ルール、固定アーキテクチャ、SOLID原則、命名規則、テストカバレッジ要件）を定義 |
コード品質ルール
本ドキュメントは、実装時に遵守すべきコード品質ルールを定義します。
すべてのエージェントはこのルールに従って実装を行います。
1. 500行ルール
1.1 ルール定義
1ファイルあたり500行を上限とします。
これはクリーンアーキテクチャ/オニオンアーキテクチャの単一責任の原則に基づきます。
| 条件 | 対応 |
|---|
| 500行以下 | OK |
| 500行超過 | 自動分割を実行 |
1.2 500行を超えた場合の対応
- 実装時にエージェントが自動で分割を実行
- 分割後に品質チェックを再実行
- すべて500行以下になるまで繰り返し
- 分割が技術的に困難な場合のみTODOに記録
1.3 分割の指針
| レイヤー | 分割方針 |
|---|
| Domain | Entity → Value Object抽出、Domain Service分離 |
| Application | UseCase分割、Query/Command分離（CQRS） |
| Infrastructure | Repository実装分割、外部サービスAdapter分離 |
| Presentation | Controller分割、DTO/Transformer分離 |
| Frontend | コンポーネント分割、カスタムHook抽出 |
1.4 例外
以下の場合は500行超過を許容：
- 自動生成ファイル（マイグレーション、型定義等）
- 設定ファイル
- テストファイル（ただし1000行を上限とする）
2. アーキテクチャ選定戦略
Adaptive Strategy: プロジェクトの特性やフレームワークに合わせて最適なアーキテクチャを選択する。
一律の「固定アーキテクチャ」強制は廃止。
2.1 優先順位（Decision Tree）
実装エージェントは以下の優先順位で採用するアーキテクチャを決定します。
- Project Definition (最優先)
docs/architecture.md または設計書（基本・詳細）に明記されたアーキテクチャ。
- Framework Convention (フレームワーク標準)
- Next.js (App Router), NestJS, Rails, Django 等、フレームワークが構造を規定している場合はそれに従う。
- 禁止: フレームワークの流儀に逆らって無理にオニオンアーキテクチャ等を適用すること。
- Recommended Patterns (デフォルト)
- 上記に該当しない場合、以下の標準パターンを採用する。
2.2 推奨パターン（Default Fallback）
プロジェクト固有の定義がない場合の標準セットです。
| 領域/規模 | 推奨パターン | プロンプト指定 | 備考 |
|---|
| Backend (Simple) | Layered (Controller-Service-Repository) | Layered Architecture | 一般的なWeb API |
| Backend (Complex) | Onion Architecture + DDD | Onion Architecture | ビジネスロジックが複雑な場合 |
| Frontend (App) | Framework Standard (e.g. Next.js App Router) | Next.js App Router | フレームワーク推奨に従う |
| Frontend (Component) | Atomic Design | Atomic Design | 大規模なUIコンポーネント設計時 |
| Script/Tool | Single File / Module based | Modular | 過剰なレイヤー化は禁止 |
2.3 プロンプト最適化ガイド（LLM事前学習活用）
選択されたアーキテクチャ名をプロンプトに含めるだけで、詳細説明は省略可能です（80-90%トークン削減）。
✅ 正しい指示の例
// Next.jsの場合
"Next.js App Router標準構成。Server ComponentsとClient Componentsを適切に分離。"
// 複雑なドメインの場合
"オニオンアーキテクチャ + TDD。Domain層の依存を排除。"
// 小規模ツールの場合
"シンプルなモジュール構成。過剰な抽象化は避けること。"
3. 設計原則
3.1 SOLID原則
| 原則 | 説明 | チェック項目 |
|---|
| Single Responsibility | 単一責任 | 各クラス・関数は1つの責務のみ |
| Open/Closed | 開放閉鎖 | 拡張に開き、修正に閉じている |
| Liskov Substitution | リスコフ置換 | サブタイプは親を代替可能 |
| Interface Segregation | インターフェース分離 | 必要なインターフェースのみ実装 |
| Dependency Inversion | 依存性逆転 | 抽象に依存、具象に依存しない |
3.2 その他の原則
| 原則 | 説明 |
|---|
| DRY | Don't Repeat Yourself（重複を避ける） |
| YAGNI | You Aren't Gonna Need It（必要になるまで作らない） |
| KISS | Keep It Simple, Stupid（シンプルに保つ） |
4. 命名規則
4.1 共通
| 対象 | 規則 | 例 |
|---|
| ファイル名 | kebab-case | user-repository.ts |
| ディレクトリ名 | kebab-case | use-cases/ |
| 定数 | UPPER_SNAKE_CASE | MAX_RETRY_COUNT |
4.2 バックエンド
| 対象 | 規則 | 例 |
|---|
| クラス名 | PascalCase | UserRepository |
| メソッド名 | camelCase | findById() |
| 変数名 | camelCase | userName |
| テーブル名 | snake_case, 複数形 | users |
| カラム名 | snake_case | created_at |
4.3 フロントエンド
| 対象 | 規則 | 例 |
|---|
| コンポーネント | PascalCase | UserCard.tsx |
| カスタムHook | camelCase, use接頭辞 | useAuth() |
| 変数名 | camelCase | isLoading |
| イベントハンドラ | handle接頭辞 | handleClick |
5. テストカバレッジ要件
5.1 カバレッジ閾値
| 対象 | 閾値 |
|---|
| 新規コード | 80%以上 |
| 全体 | 70%以上（推奨） |
5.2 テストの種類
| 種類 | 対象 | 優先度 |
|---|
| Unit Test | ドメインロジック、ユーティリティ | 高 |
| Integration Test | API、DB連携 | 高 |
| E2E Test | ユーザーシナリオ | 中 |
6. コードフォーマット
6.1 必須ツール
| 言語/フレームワーク | Linter | Formatter |
|---|
| TypeScript | ESLint | Prettier |
| JavaScript | ESLint | Prettier |
| PHP | PHP_CodeSniffer | PHP-CS-Fixer |
| Python | Ruff / Flake8 | Black |
| Go | golangci-lint | gofmt |
6.2 コミット前チェック
以下のチェックをコミット前に実行：
- Lint（エラー0件）
- Format（差分0件）
- Type Check（エラー0件）
- Unit Test（全件パス）
7. 禁止事項
7.1 絶対禁止
| 禁止事項 | 理由 |
|---|
any 型の使用（TypeScript） | 型安全性の破壊 |
@ts-ignore / @ts-expect-error | 型エラーの隠蔽 |
空のcatchブロック catch(e) {} | エラーの握りつぶし |
| 機密情報のハードコード | セキュリティリスク |
console.log の本番コード残存 | デバッグコードの漏洩 |
| テスト削除による「修正」 | 品質の低下 |
todo!, unimplemented! の残存 | 実装漏れ（リリースビルドでパニックする） |
7.2 原則禁止（例外要申請）
| 禁止事項 | 例外条件 |
|---|
| 新規依存パッケージの追加 | 既存で代替不可の場合のみ |
| グローバル状態の使用 | 明確な理由がある場合のみ |
| 直接DOM操作（React/Vue） | パフォーマンス上必要な場合のみ |
変更履歴
| 日付 | バージョン | 変更内容 |
|---|
| 2026-01-02 | 1.0.0 | 初版作成（ai-frameworkからの取り込み） |
