コード品質ルール
本ドキュメントは、実装時に遵守すべきコード品質ルールを定義します。
すべてのエージェントはこのルールに従って実装を行います。
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からの取り込み） |