code-quality-rules

takemo101's avatarfrom takemo101

実装時に遵守すべきコード品質ルール（500行ルール、固定アーキテクチャ、SOLID原則、命名規則、テストカバレッジ要件）を定義

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026⬇️4downloads
[Code Review]

When & Why to Use This Skill

This Claude skill establishes a comprehensive framework for maintaining high-quality codebases by enforcing rigorous implementation rules. It automates the application of the 500-line file limit, SOLID principles, and adaptive architecture strategies, ensuring that code remains maintainable, scalable, and consistent. By defining clear standards for naming conventions, testing coverage, and prohibited practices, it serves as an essential quality gate for professional software development.

Use Cases

  • Automated Code Refactoring: Automatically identifying and splitting files that exceed the 500-line limit into smaller, single-responsibility modules to reduce complexity.
  • Architectural Governance: Utilizing a decision tree to select the most appropriate architecture (e.g., Onion Architecture, Layered, or Framework-standard) based on project scale and requirements.
  • Strict Quality Assurance: Enforcing a minimum of 80% test coverage and preventing the use of anti-patterns like 'any' types, empty catch blocks, or hardcoded secrets.
  • Cross-Language Standardization: Applying consistent naming conventions and linting configurations across multi-language projects (TypeScript, Python, Go, etc.) to ensure team-wide readability.
namecode-quality-rules
description実装時に遵守すべきコード品質ルール（500行ルール、固定アーキテクチャ、SOLID原則、命名規則、テストカバレッジ要件）を定義

コード品質ルール

本ドキュメントは、実装時に遵守すべきコード品質ルールを定義します。 すべてのエージェントはこのルールに従って実装を行います。

1. 500行ルール

1.1 ルール定義

1ファイルあたり500行を上限とします。 これはクリーンアーキテクチャ/オニオンアーキテクチャの単一責任の原則に基づきます。

条件 対応
500行以下 OK
500行超過 自動分割を実行

1.2 500行を超えた場合の対応

  1. 実装時にエージェントが自動で分割を実行
  2. 分割後に品質チェックを再実行
  3. すべて500行以下になるまで繰り返し
  4. 分割が技術的に困難な場合のみ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）

実装エージェントは以下の優先順位で採用するアーキテクチャを決定します。

  1. Project Definition (最優先)
    • docs/architecture.md または設計書（基本・詳細）に明記されたアーキテクチャ。
  2. Framework Convention (フレームワーク標準)
    • Next.js (App Router), NestJS, Rails, Django 等、フレームワークが構造を規定している場合はそれに従う。
    • 禁止: フレームワークの流儀に逆らって無理にオニオンアーキテクチャ等を適用すること。
  3. 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 コミット前チェック

以下のチェックをコミット前に実行：

  1. Lint（エラー0件）
  2. Format（差分0件）
  3. Type Check（エラー0件）
  4. 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からの取り込み）