コード品質

コーディングとリファクタリング時の品質制約、コードの保守性、テスト容易性、適切な拡張性を確保します。

言語

• 中国語と英語の両方の質問を受け付けます
• 常に中国語で回答します

トリガー条件

• ユーザーが新しいコードを書いている
• ユーザーが既存のコードをリファクタリングする必要がある
• ユーザーが Code Review チェックリストを必要としている
• ユーザーが MTE 原則、コード品質、過剰設計の回避について言及している

核心原則：MTE

すべてのコードは MTE 原則 に従う必要があります。

Part 1: コーディング制約

モジュール設計

単一責任

✅ 正しい：一个类/函数只做一件事 (クラス/関数は 1 つのことだけを行う)
- UserService: 用户业务逻辑 (ユーザービジネスロジック)
- UserRepository: 用户数据访问 (ユーザーデータアクセス)
- UserValidator: 用户数据校验 (ユーザーデータ検証)

❌ 错误：一个类做多件事 (クラスが複数のことを行う)
- UserManager: 业务逻辑 + 数据访问 + 校验 + 发送邮件 (ビジネスロジック + データアクセス + 検証 + メール送信)

依存方向

┌─────────────────────────────────────┐
│           Interface Layer           │  ← 薄层，无业务逻辑 (薄い層、ビジネスロジックなし)
├─────────────────────────────────────┤
│           Service Layer             │  ← 业务逻辑（核心）(ビジネスロジック（コア）)
├─────────────────────────────────────┤
│           Domain Layer              │  ← 领域模型 (ドメインモデル)
├─────────────────────────────────────┤
│         Infrastructure Layer        │  ← 可替换 (置換可能)
└─────────────────────────────────────┘

依赖规则：(依存ルール)
- 外层依赖内层 ✅ (外側の層は内側の層に依存する ✅)
- 内层依赖外层 ❌ (内側の層は外側の層に依存する ❌)
- 依赖接口，不依赖实现 ✅ (インターフェースに依存し、実装に依存しない ✅)

関数設計

関数長

• 推奨：単一の関数は 30 行を超えない
• 最大：50 行を超えない
• 超過時：複数の小さな関数に分割する

引数数

• 推奨：3 つ以下の引数
• 最大：5 つ以下の引数
• 超過時：引数オブジェクトを使用する

// ❌ 参数过多 (引数が多すぎる)
function createUser(name, email, age, role, department, manager) {}

// ✅ 使用参数对象 (引数オブジェクトを使用する)
function createUser(params: CreateUserParams) {}

ネスト深度

• 推奨：2 層以下のネスト
• 最大：3 層以下のネスト
• 超過時：関数を抽出するか、早期リターンを使用する

// ❌ 嵌套过深 (ネストが深すぎる)
if (a) {
  if (b) {
    if (c) {
      // ...
    }
  }
}

// ✅ 早返回 (早期リターン)
if (!a) return;
if (!b) return;
if (!c) return;
// ...

テスト容易性設計

詳細なテスト作成仕様については、/testing-guide を参照してください

核心原則

可测试代码的三个要素: (テスト可能なコードの 3 つの要素:)
1. 依赖可注入 - 外部依赖通过参数传入 (依存性の注入可能 - 外部依存関係は引数として渡される)
2. 纯函数优先 - 业务逻辑无副作用 (純粋関数優先 - ビジネスロジックに副作用がない)
3. 边界分离 - 业务逻辑与 IO 分离 (境界分離 - ビジネスロジックと IO を分離する)

依存性注入

// ❌ 硬编码依赖 (ハードコードされた依存関係)
class UserService {
  private db = new Database();
  private mailer = new EmailService();
}

// ✅ 依赖注入 (依存性注入)
class UserService {
  constructor(
    private db: IDatabase,
    private mailer: IEmailService
  ) {}
}

純粋関数優先

// ❌ 有副作用，难测试 (副作用があり、テストが難しい)
function calculateTotal(items) {
  const total = items.reduce((sum, item) => sum + item.price, 0);
  console.log(`Total: ${total}`);  // 副作用
  analytics.track('calculate');     // 副作用
  return total;
}

// ✅ 纯函数，易测试 (純粋関数、テストしやすい)
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

境界分離

// ❌ 业务逻辑混合 IO (ビジネスロジックと IO が混在)
async function processOrder(orderId) {
  const order = await db.findOrder(orderId);  // IO
  if (order.total > 1000) {                   // 业务逻辑 (ビジネスロジック)
    order.discount = 0.1;
  }
  await db.save(order);                       // IO
  await email.send(order.user, 'confirmed');  // IO
}

// ✅ 分离业务逻辑 (ビジネスロジックを分離)
function applyDiscount(order) {  // 纯业务逻辑，可测试 (純粋なビジネスロジック、テスト可能)
  if (order.total > 1000) {
    return { ...order, discount: 0.1 };
  }
  return order;
}

async function processOrder(orderId) {
  const order = await db.findOrder(orderId);
  const updated = applyDiscount(order);  // 调用纯函数 (純粋関数を呼び出す)
  await db.save(updated);
  await email.send(order.user, 'confirmed');
}

テスト作成時：アサーションの品質、Mock 戦略、変異テストなどの詳細なガイダンスについては、/testing-guide を参照してください

過剰設計の回避

YAGNI 原則

You Aren't Gonna Need It - あなたはそれを必要としないでしょう

// ❌ 过度设计：为假设需求添加配置 (過剰設計：仮定の要件のために構成を追加する)
const config = {
  maxRetries: 3,
  retryDelay: 1000,
  enableCache: true,
  cacheExpiry: 3600,
  enableRateLimit: false,  // 从未使用 (未使用)
  rateLimitWindow: 60000,  // 从未使用 (未使用)
  enableMetrics: false,    // 从未使用 (未使用)
  metricsEndpoint: '',     // 从未使用 (未使用)
};

// ✅ 只添加当前需要的配置 (現在必要な構成のみを追加する)
const config = {
  maxRetries: 3,
  retryDelay: 1000,
  cacheExpiry: 3600,
};

抽象化のタイミング

❌ 过早抽象：(早期の抽象化:)
- 只有一个实现就创建接口 (実装が 1 つしかないのにインターフェースを作成する)
- 只有一处使用就提取函数 (1 か所しか使用しないのに関数を抽出する)
- 只有两个相似场景就创建基类 (2 つの類似したシナリオしかないのに基底クラスを作成する)

✅ 适时抽象（Rule of Three）：(適切なタイミングでの抽象化 (Rule of Three):)
- 3 个以上实现时考虑接口 (3 つ以上の実装がある場合はインターフェースを検討する)
- 3 处以上重复时考虑提取 (3 か所以上の繰り返しがある場合は抽出を検討する)
- 3 个以上相似场景时考虑基类 (3 つ以上の類似したシナリオがある場合は基底クラスを検討する)

シンプルな解決策を優先

// ❌ 过度设计：简单场景用复杂模式 (過剰設計：単純なシナリオで複雑なパターンを使用する)
class UserFactory {
  createAdmin() { return new AdminUser(); }
  createMember() { return new MemberUser(); }
  createGuest() { return new GuestUser(); }
}

// ✅ 简单场景用简单方案 (単純なシナリオで単純な解決策を使用する)
function createUser(role: 'admin' | 'member' | 'guest') {
  return { role, permissions: getPermissions(role) };
}

デザインパターンの使用

使用原則

• 必要时才用：解决实际问题，不为炫技 (必要なときにのみ使用する：実際の問題を解決するため、技術を誇示するためではない)
• 说明理由：为什么选择这个模式 (理由を説明する：なぜこのパターンを選択したのか)
• 保持一致：相同问题用相同模式 (一貫性を保つ：同じ問題には同じパターンを使用する)

推薦シーン

Part 2: リファクタリング指導

リファクタリングトリガー条件

コードに以下の Code Smells が見られる場合は、リファクタリングを検討してください。

必須リファクタリング

提案リファクタリング

リファクタリングフロー

1. 确保测试覆盖 (テストカバレッジを確保する)
   │
   ├── 有测试 → 继续 (テストがある → 続行)
   └── 无测试 → 先补充测试 (テストがない → まずテストを追加する)
   │
   ▼
2. 小步重构 (小さなステップでリファクタリングする)
   │
   ├── 每次只改一件事 (毎回 1 つのことだけを変更する)
   ├── 每步都能运行 (すべてのステップが実行可能)
   └── 每步都运行测试 (すべてのステップでテストを実行する)
   │
   ▼
3. 验证行为不变 (動作が変わらないことを検証する)
   │
   ├── 测试全部通过 (すべてのテストに合格する)
   └── 手动验证关键路径 (手動でクリティカルパスを検証する)
   │
   ▼
4. 提交代码 (コードをコミットする)

リファクタリング制約

安全制約

• [ ] 重构前必须有测试覆盖 (リファクタリング前にテストカバレッジが必須)
• [ ] 每步重构后运行测试 (すべてのリファクタリングステップの後にテストを実行する)
• [ ] 不在重构中添加新功能 (リファクタリング中に新しい機能を追加しない)
• [ ] 不在添加功能时重构 (機能を追加するときにリファクタリングしない)

範囲制約

• [ ] 单次重构只改一类问题 (1 回のリファクタリングで 1 種類の問題のみを変更する)
• [ ] 单次 PR 只包含一个重构主题 (1 回の PR には 1 つのリファクタリングテーマのみを含める)
• [ ] 大范围重构需要分阶段进行 (大規模なリファクタリングは段階的に行う必要がある)

リスク評価

Part 3: Code Review チェックリスト

Review 前置検査

• [ ] PR 描述清晰说明改动内容和原因 (PR の説明で変更内容と理由を明確に説明する)
• [ ] CI 通过（测试、lint、build）(CI が合格 (テスト、lint、build))
• [ ] 改动范围合理（单一主题）(変更範囲が合理的 (単一テーマ))

コード品質検査

MTE 原則

• [ ] M - 可维护性 (M - 保守性)

  • [ ] 函数职责单一 (関数の責任が単一)
  • [ ] 命名清晰准确 (命名が明確かつ正確)
  • [ ] 依赖关系清晰 (依存関係が明確)

• [ ] T - 可测试性 (T - テスト容易性)

  • [ ] 核心逻辑有测试 (コアロジックにテストがある)
  • [ ] 依赖可以 Mock (依存関係を Mock 可能)
  • [ ] 边界条件覆盖 (境界条件を網羅)

• [ ] E - 可扩展性 (E - 拡張性)

  • [ ] 预留合理扩展点 (合理的な拡張ポイントの予約)
  • [ ] 不为假设需求设计 (仮定の要件のために設計しない)
  • [ ] 配置合理 (構成が合理的)

コード規範

• [ ] 函数长度 < 50 行 (関数長 < 50 行)
• [ ] 参数数量 < 5 个 (引数の数 < 5 個)
• [ ] 嵌套深度 < 3 层 (ネスト深度 < 3 層)
• [ ] 无重复代码 (重複コードなし)
• [ ] 无硬编码敏感信息 (ハードコードされた機密情報なし)

エラー処理

• [ ] 边界条件处理 (境界条件の処理)
• [ ] 错误信息有意义 (エラーメッセージが意味を持つ)
• [ ] 不吞掉异常 (例外を握りつぶさない)

安全検査

• [ ] 无 SQL 注入风险 (SQL インジェクションのリスクなし)
• [ ] 无 XSS 风险 (XSS のリスクなし)
• [ ] 敏感数据加密/脱敏 (機密データの暗号化/マスキング)
• [ ] 权限控制正确 (権限制御が正しい)

Review フィードバックレベル