AI駆動開発の技術的負債管理

// ai-generated: 2026-03-15
export function processUserData(data: unknown): ProcessedUser {
  const user = data as UserInput;
  const processed = {
    id: crypto.randomUUID(),
    name: user.name?.trim() ?? "",
    email: user.email?.toLowerCase() ?? "",
    score: calculateScore(user),
    metadata: extractMetadata(user),
  };
  return processed;
}

function calculateScore(user: UserInput): number {
  // 謎の重み付け計算
  return (user.activity ?? 0) * 0.6 + (user.tenure ?? 0) * 0.3 + (user.spend ?? 0) * 0.1;
}

/**
 * ユーザースコア計算
 *
 * 設計決定 (2026-03-15, @mine_take):
 * - 重み: activity=60%, tenure=30%, spend=10%
 * - 根拠: 2025Q4 チャーン分析で activity が最大予測因子と判明
 * - 参照: internal/analytics/churn-analysis-2025q4.md
 * - 次回見直し: 2026Q3（スコアモデル再訓練後）
 *
 * @param user - 生ユーザーデータ（バリデーション済み前提）
 */
export function calculateUserScore(user: ValidatedUserInput): number {
  const WEIGHT = {
    activity: 0.6,  // 最大予測因子 (社内データ: churn-analysis-2025q4)
    tenure: 0.3,
    spend: 0.1,
  } as const;

  return (
    (user.activity ?? 0) * WEIGHT.activity +
    (user.tenure ?? 0) * WEIGHT.tenure +
    (user.spend ?? 0) * WEIGHT.spend
  );
}

// AIが「拡張性のため」と生成した構造
abstract class DataProcessorBase<TInput, TOutput> {
  abstract validate(input: TInput): boolean;
  abstract transform(input: TInput): TOutput;
  abstract persist(output: TOutput): Promise<void>;

  async process(input: TInput): Promise<void> {
    if (!this.validate(input)) throw new Error("Invalid input");
    const output = this.transform(input);
    await this.persist(output);
  }
}

class UserDataProcessor extends DataProcessorBase<UserInput, ProcessedUser> {
  // 実際にはここ以外に具体実装がない
  validate(input: UserInput): boolean { return !!input.email; }
  transform(input: UserInput): ProcessedUser { /* ... */ }
  async persist(output: ProcessedUser): Promise<void> { /* ... */ }
}

// 現時点の要件だけを実装
export async function processAndSaveUser(input: UserInput): Promise<void> {
  if (!input.email) throw new Error("email is required");

  const processed = transformUser(input);
  await db.users.save(processed);
}

function transformUser(input: UserInput): ProcessedUser {
  return {
    id: crypto.randomUUID(),
    name: input.name?.trim() ?? "",
    email: input.email.toLowerCase(),
    score: calculateUserScore(input),
  };
}

#!/bin/bash
# scripts/check-coverage.sh
# CI で必ず実行する負債検知スクリプト

THRESHOLD=80

coverage=$(pnpm test --coverage --json 2>/dev/null | \
  jq '.coverageMap | to_entries[].value.s | to_entries | 
      (map(select(.value > 0)) | length) / length * 100' | \
  awk '{sum+=$1; count++} END {print sum/count}')

echo "Coverage: ${coverage}%"

if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
  echo "ERROR: Coverage ${coverage}% is below threshold ${THRESHOLD}%"
  exit 1
fi

# .github/workflows/quality-gate.yml
name: Quality Gate

on: [pull_request]

jobs:
  debt-detection:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Complexity check
        run: |
          # Cyclomatic complexity > 10 を負債として検知
          pnpm exec ts-complexity --threshold 10 --format json src/ | \
          jq 'if .violations | length > 0 then error("Complexity violations found") else . end'

      - name: Test coverage gate
        run: pnpm test --coverage --coverageThreshold='{"global":{"lines":80}}'

      - name: Dead code detection
        run: pnpm exec knip --reporter json | jq 'if .files | length > 0 then error else . end'

      - name: Type safety check
        run: pnpm tsc --noEmit --strict

#!/usr/bin/env python3
# scripts/debt_score.py
"""
AI生成コードの負債スコアを定量評価するスクリプト
出力: 0-100のスコア（低いほど良好）
"""

import subprocess
import json
import sys
from pathlib import Path


def get_complexity_violations(src_dir: str) -> int:
    """循環複雑度10超の関数数を取得"""
    result = subprocess.run(
        ["npx", "ts-complexity", "--threshold", "10", "--format", "json", src_dir],
        capture_output=True,
        text=True,
    )
    try:
        data = json.loads(result.stdout)
        return len(data.get("violations", []))
    except json.JSONDecodeError:
        return 0


def get_coverage_deficit(threshold: float = 80.0) -> float:
    """テストカバレッジの不足率を取得（0〜100）"""
    result = subprocess.run(
        ["pnpm", "test", "--coverage", "--json"],
        capture_output=True,
        text=True,
    )
    try:
        data = json.loads(result.stdout)
        # 簡略実装: 実際はcoverageMapから計算
        actual = data.get("coverageSummary", {}).get("lines", {}).get("pct", 100)
        return max(0, threshold - actual)
    except (json.JSONDecodeError, KeyError):
        return 0


def calculate_debt_score(src_dir: str = "src") -> int:
    """
    負債スコアを計算する（0=負債なし、100=深刻）

    重み (経験則):
    - 循環複雑度違反: 1件あたり5点
    - カバレッジ不足: 1%あたり1点
    """
    complexity_violations = get_complexity_violations(src_dir)
    coverage_deficit = get_coverage_deficit()

    score = (complexity_violations * 5) + int(coverage_deficit)
    return min(score, 100)


if __name__ == "__main__":
    score = calculate_debt_score()
    print(f"Debt Score: {score}/100")
    if score > 30:
        print("WARNING: Debt score exceeds threshold (30)")
        sys.exit(1)

# ADR-{番号}: {決定のタイトル}

## 状態
Accepted / Deprecated / Superseded by ADR-XXX

## コンテキスト
なぜこの決定が必要になったか（問題の背景）

## 決定
どのアーキテクチャ/実装を選んだか

## 根拠
- この選択の理由（定量的な根拠があれば記載）
- 検討した代替案とその却下理由

## 結果
- この決定がもたらすトレードオフ
- 次回見直しのトリガー

## AI生成コンテキスト（AI駆動開発の場合）
- 使用したプロンプトの概要（または参照先）
- AIが提案した代替案
- 人間が上書きした判断とその理由

## 設計制約（AI生成時の遵守事項）

### コード生成ルール
- 循環複雑度10超の関数は禁止。分割すること
- 抽象クラス/インターフェースは2つ以上の具体実装が存在する場合のみ導入
- 外部API呼び出しを含む関数には必ずテストを書く
- 数値リテラルは名前付き定数で定義し、根拠をコメントで記載

### 禁止パターン
- `any` 型の使用（`unknown` + type guard を使う）
- 未使用の関数/変数の残存
- プロミス未処理のエラーハンドリング省略

# git blame を使って「変更頻度が高い」× 「複雑度が高い」コードを特定
git log --format="%H" --since="6 months ago" -- "src/**/*.ts" | \
  xargs git show --stat | \
  grep -E "\.ts\b" | \
  sort | uniq -c | sort -rn | \
  head -20
# 出力例: 頻繁に変更されているファイルTop20
# → これらの循環複雑度を先にチェックする

以下の TypeScript 関数をリファクタリングしてください。

制約:
1. 外部インターフェース（引数・戻り値の型）は変更しない
2. 循環複雑度を10以下に下げる
3. 既存テストがすべてパスすること
4. 変更の根拠を JSDoc に残すこと

対象コード:
[コードを貼り付け]

現在の問題点:
- 循環複雑度が15（checkstyleレポート参照）
- if-else のネストが4段

# .github/workflows/regression-guard.yml
# 返済した負債の再発を防止するゲート
name: Regression Guard

on:
  pull_request:
    paths:
      - "src/**"

jobs:
  complexity-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # ベースブランチとの差分を取得

      - name: Check complexity regression
        run: |
          # 変更されたファイルのみを対象に複雑度チェック
          changed_files=$(git diff --name-only origin/main HEAD | grep "\.ts$")
          if [ -n "$changed_files" ]; then
            echo "$changed_files" | xargs npx ts-complexity --threshold 10
          fi

# .github/workflows/codeql.yml
name: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write

    steps:
      - uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: javascript-typescript

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:javascript-typescript"