ISOソフトウェア品質特性とAI駆動開発：Verifiability（検証可能性）を担保する自動レビュー環境の構築

はじめに

現代のソフトウェア開発において、機能の複雑化とリリースサイクルの短縮化が課題になっています。

この課題への対応策として、開発者それぞれによる単純なコードレビューも依然として重要ではあります。

しかし、レビュアーのスキルへの依存、ミスによる見落とし、そして「品質基準のばらつき」という課題を抱えています。

特に、システムの信頼性を支える「品質」の定義が曖昧なままレビューが行われると、将来的な技術的負債の蓄積を招きます。

ここで有用なのが、国際規格であるISO/IEC 25010に基づいた客観的な評価基準の導入です。

本レポートでは、AI（大規模言語モデル）を開発プロセスに組み込み、ISO品質特性の中でも特に「Verifiability（検証可能性）」に焦点を当てた自動レビュー環境の構築手法を詳説します。 AIにISO基準を学習・適用させることで、属人化を排除し、持続可能で検証可能なコードベースを維持するための実践的アプローチを提案します。

ISO/IEC 25010におけるソフトウェア品質特性とVerifiability（検証可能性）の定義

AIに的確なレビューを行わせるためには、まず人間側が「何を良しとするか」を言語化し、定義する必要があります。 ここでは、ソフトウェア品質の国際規格であるISO/IEC 25010（システム及びソフトウェア製品品質モデル）をベースラインとして採用します。

本レポートで中核に据える「Verifiability（検証可能性）」は、ISO規格内の用語として直接定義されているわけではありませんが、主に保守性（Maintainability）の副特性である以下の2つを統合した概念として定義します。

保守性（Maintainability）と検証可能性

ISO/IEC 25010において、保守性は「製品またはシステムが、意図した保守者によって修正することができる有効性及び効率性の度合い」と定義されています。 検証可能性を担保するためには、以下の副特性が極めて重要です。

• 試験性（Testability）

システムやモジュールが、効率的にテストを行える状態になっている度合いです。AIによる自動生成テストや、CIでの回帰テストが容易に行える構造（疎結合など）であることが求められます。

• 解析性（Analyzability）

不具合が発生した際に、その原因や影響範囲を診断・追跡できる度合いです。ログの適切さや、コードの可読性がここに直結します。

互換性（Compatibility）

また、現代のマイクロサービスアーキテクチャやライブラリ依存の開発においては、互換性（Compatibility）も無視できません。 これは「相互運用性（Interoperability）」を含み、他のシステムや構成要素と情報を交換・連携できる度合いを指します。 AIレビューにおいては、APIの仕様変更が既存の連携を破壊していないか、インターフェースの整合性が保たれているか、といった事項も検証対象となります。

検証可能性を高めるための自動テスト記述指針と開発ルール

AIレビューの効果を最大化するためには、そもそもレビュー対象となるコード自体が「AIにとっても人間にとっても理解しやすく、検証可能である」必要があります。 コード自体の品質が悪い場合は、レビューだけで検証可能性を担保することは困難です。 ここでは、コードを検証しやすい状態に保つための開発ルール（コーディング規約）を挙げていきます。 これをチーム内で合意形成し、AIでコード生成する際のプロンプトにも（例えばCursorで開発する場合であれば）.cursorrulesなどに知識として記述しておくことが重要です。

依存性の注入（Dependency Injection）の徹底

検証可能性（特に試験性）を阻害する最大の要因は、モジュール間の密結合です。 データベース接続や外部API呼び出しを関数内で直接インスタンス化するコードは、テスト時のモック化を困難にします。 AIに対しても、「外部依存は引数として渡す（DIパターン）」ことを強制させます。 これにより、単体テストの自動生成が容易になり、AIがコードの振る舞いを予測する精度が向上します。

純粋関数（Pure Function）の推奨と副作用の分離

解析性を高めるため、ビジネスロジックは可能な限り「純粋関数」として実装します（純粋関数とは、入力が同じなら常に出力が同じであり、DB書き込みやグローバル変数の変更といった副作用がない関数を指します）。 こういったコードは、AIにとっても人間にとっても検証コストが最も低い構造です。 副作用を扱うレイヤーと、ロジックを扱うレイヤーを明確に分離するアーキテクチャを採用します。

コンテキストを含む型定義とドキュメンテーション

AIに渡すコンテキストとして、型情報とドキュメント（Docstring/JSDoc）を付与することも重要です。 動的型付け言語（PythonやJavaScript）であっても、型ヒント（Type Hints）を必須とします。

• Bad: def process(data):

• Good: def process_user_payment(payment_data: PaymentRequest) -> TransactionResult:

このように明示的な型定義を行うことで、AIは「互換性（Compatibility）」の観点から、データの受け渡しに不整合がないかを解析できるようになります。

自動レビューによる品質検証の徹底

開発プロセスにおいて、コードのプルリクエスト（PR）作成時にAIレビューを必須化します。 AIによるレビューそのものも一つの検証であり、ISO基準に基づいたチェックリストを用いたレビューを行うことで、重要なブランチにコードがマージされるたびに必ず検証が走るように担保することが可能です。 こちらの方法論については、次章以降で詳しく述べます。

GitHub ActionsとAIを用いたCI/CD自動レビューパイプラインの構築

さて、ここまでの部分では検証可能性を高めるための理論的背景と開発ルールについて述べてきました。 ここからは、その一つの実践例としてGitHub Actionsを用いてPull Request（PR）作成時に自動でAIレビューを実行するパイプラインを構築していきます。

システム構成概要

1. 開発者がPull Requestを作成または更新する。

2. GitHub Actionsがトリガーされ、変更差分（git diff）を取得する。

3. 取得した差分とISO基準プロンプトをOpenAI API（GPT-5等のモデル）に送信する。

4. AIからのレスポンスを整形し、PRのコメントとして自動投稿する。

ワークフロー実装例 (.github/workflows/ai-review.yml)

以下は、Pythonスクリプトを呼び出してレビューを行うワークフローの定義例です。 既存のコードレビュー系のSaaSを使わず、自社で制御可能な環境を構築する場合の構成です。

name: AI Code Review based on ISO 25010

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  ai_review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 差分取得のために全履歴を取得 ※必要に応じて調整

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install openai PyGithub

      - name: Run AI Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO_NAME: ${{ github.repository }}
        run: python scripts/ai_reviewer.py

この構成により、自社の品質基準に完全にカスタマイズされたレビュー環境が構築可能です。 scripts/ai_reviewer.py内部では、git diff origin/main...HEAD等のコマンドで差分を取得し、後述するプロンプトと組み合わせてAPIを叩くロジックを実装します。

下記はその実装例です。

import os
import sys
import subprocess
from typing import Optional
from github import Github
from openai import OpenAI

# 環境変数から設定を取得
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
REPO_NAME = os.getenv("REPO_NAME")
PR_NUMBER = os.getenv("PR_NUMBER")
BASE_BRANCH = os.getenv("GITHUB_BASE_REF", "main") # PRのターゲットブランチ

# レビュー対象外とするファイルパターン
IGNORE_PATTERNS = [
    "*.lock",
    "*.json",
    "*.md",
    "*.txt",
    "dist/*",
    "build/*",
]

# 最大トークン数節約のための文字数制限
MAX_DIFF_LENGTH = 15000

def get_git_diff() -> str:
    """
    Gitコマンドを使用して、PRの変更差分を取得します。
    マージベースからの差分を取得し、不要なファイルを除外します。
    """
    try:
        # 除外オプションの構築
        exclude_args = []
        for pattern in IGNORE_PATTERNS:
            exclude_args.append(f":(exclude){pattern}")

        # git diff origin/base...HEAD
        # 注意: actions/checkoutで fetch-depth: 0 にしておく必要があります
        cmd = [
            "git", "diff",
            f"origin/{BASE_BRANCH}...HEAD",
            "--"
        ] + exclude_args

        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            check=True
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Error getting git diff: {e.stderr}")
        sys.exit(1)

def generate_review(diff_text: str) -> Optional[str]:
    """
    OpenAI APIを呼び出し、ISO/IEC 25010に基づいたレビューを生成します。
    """
    if not diff_text.strip():
        print("No changes detected in diff.")
        return None

    if len(diff_text) > MAX_DIFF_LENGTH:
        print(f"Diff is too large ({len(diff_text)} chars). Truncating...")
        diff_text = diff_text[:MAX_DIFF_LENGTH] + "\n...(Truncated due to length limit)"

    client = OpenAI(api_key=OPENAI_API_KEY)

    # システムプロンプト：ISO品質特性（検証可能性・保守性）を重視するよう定義
    system_prompt = """
あなたはISO/IEC 25010の専門知識を持つシニアソフトウェア品質保証エンジニアです。
提示されたコードの変更差分（Diff）に対して、特に以下の品質特性基準に基づき厳格なコードレビューを行ってください。

## 評価基準（ISO/IEC 25010重視）
1. 保守性 (Maintainability) - 特に以下の副特性に注意してください:
    - 試験性 (Testability): この変更はテストコードの作成を困難にしていないか？依存関係は注入可能か（DI）？
    - 解析性 (Analyzability): エラー発生時の原因特定は容易か？ログや例外処理は適切か？
    - モジュール性 (Modularity): 変更が他のコンポーネントと疎結合になっているか？
2. 互換性 (Compatibility):
    - 既存のインターフェースやデータ構造との不整合はないか？
3. 機能適合性 (Functional Suitability):
    - 実装が意図された機能を過不足なく満たしているように見えるか？

## 制約事項
- 抽象的な指摘は避け、具体的な修正案やコード例を提示すること。
- 「良いコードです」といった形式的な称賛は不要。改善点とリスクのみを優先的に指摘すること。
- 重大な懸念がない場合は「**ISO基準に基づく重大な指摘事項は見当たりませんでした。**」と出力すること。
- 出力は日本語で行うこと。マークダウン形式で見やすく整形すること。
"""

    try:
        response = client.chat.completions.create(
            model="gpt-5",
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": f"以下のGit Diffをレビューしてください:\n\n{diff_text}"}
            ],
            temperature=0.2, 
        )
        return response.choices[0].message.content
    except Exception as e:
        print(f"OpenAI API Error: {e}")
        return None

def post_comment_to_pr(review_body: str):
    """
    GitHub APIを使用して、PRにコメントを投稿します。
    """
    if not review_body:
        return

    try:
        g = Github(GITHUB_TOKEN)
        repo = g.get_repo(REPO_NAME)
        pr = repo.get_pull(int(PR_NUMBER))

        # コメントのヘッダー装飾
        final_body = f"## 🤖 AI Code Review (ISO/IEC 25010)\n\n{review_body}\n\n---\n*By Verify-Bot based on ISO standards*"
        
        pr.create_issue_comment(final_body)
        print("Comment posted successfully.")

    except Exception as e:
        print(f"GitHub API Error: {e}")
        sys.exit(1)

def main():
    print("Starting AI Code Review...")
    
    # 1. 差分の取得
    diff = get_git_diff()
    print(f"Diff length: {len(diff)} chars")

    # 2. AIによるレビュー生成
    review = generate_review(diff)

    # 3. GitHubへの投稿
    if review:
        post_comment_to_pr(review)
    else:
        print("No review generated.")

if __name__ == "__main__":
    main()

このように実装することで、ISO/IEC 25010に基づいた自動コードレビューが可能になります。 なお、コード内のプロンプトは、プロジェクトごとに特に重要視するISO品質特性に応じてカスタマイズするとよいでしょう。 その際、次の章で述べるポイントを参考にしてください。

ISO基準に基づきAIにコードレビューさせるためのプロンプト設計

AIの出力品質はプロンプトで決まります。 漫然と「コードをレビューして」と依頼するのではなく、ISO/IEC 25010の観点から監査を行うよう役割を与えます。

プロンプト構成案

以下は、先程のサンプルコード内でも用いていた、検証可能性（試験性・解析性）と保守性を重視したシステムプロンプトの例です。

あなたはISO/IEC 25010の専門知識を持つシニアソフトウェア品質保証エンジニアです。
提示されたコードの変更差分（Diff）に対して、以下の品質特性基準に基づき厳格なコードレビューを行ってください。

## 評価基準（ISO/IEC 25010重視）
1. 保守性 (Maintainability) - 特に以下の副特性に注意してください:
    - 試験性 (Testability): この変更はテストコードの作成を困難にしていないか？依存関係は注入可能か？
    - 解析性 (Analyzability): エラー発生時の原因特定は容易か？ログや例外処理は適切か？
    - モジュール性 (Modularity): 変更が他のコンポーネントと疎結合になっているか？
2. 互換性 (Compatibility):
    - 既存のインターフェースやデータ構造との不整合はないか？
3. 機能適合性 (Functional Suitability):
    - 実装が意図された機能を過不足なく満たしているように見えるか？

## 制約事項
- 抽象的な指摘は避け、具体的な修正案やコード例を提示すること。
- 「良いコードです」といった形式的な称賛は不要。改善点とリスクのみを指摘すること。
- 指摘事項がない場合は「No issues found adhering to ISO standards.」と出力すること。
- 出力は日本語で行うこと。

## 入力データ
(ここにgit diffの内容を挿入)

このプロンプトでは、AIに対して「ISO品質特性のどの項目に違反しているか」を意識させています。 これにより、レビュー結果に「なぜ修正が必要なのか」という根拠（Why）が付与され、開発者の納得感が高まります。 もし、PoCレベルの小規模なプロジェクトなどで、特定の品質特性に絞り込みたい場合は、上記の評価基準リストから不要な項目を削除しても構いません。 例えば、保守を考える必要がないのであれば、保守性に関する部分を削除し、機能適合性と互換性のみにフォーカスしたプロンプトに変更するとよいでしょう。

実践：AIによる自動コードレビュー結果とフィードバックの検証

実際に構築したパイプラインを用いて、意図的に品質を下げたコードをレビューさせた結果を紹介します。

ケーススタディ：外部APIに依存する密結合な関数

1. 修正前のコード（検証可能性が低い）

import requests

def get_user_data(user_id):
    # URLがハードコーディングされており、単体テストでモック化しにくい（試験性の欠如）
    response = requests.get(f"https://api.example.com/users/{user_id}")
    if response.status_code == 200:
        return response.json()
    else:
        # エラーの詳細が握りつぶされており、原因追及が困難（解析性の欠如）
        return None

2. AIによる指摘（ISO基準フィードバック）

このような低品質なコードをAIにレビューさせたところ、 AIレビューボットは以下のようなコメントを生成しました。

## ISO品質基準に基づく指摘事項

- 試験性（Testability）の低下: `requests.get` が関数内で直接呼び出されており、外部APIへ直接依存しています。これにより、ネットワーク遮断環境でのテストや、異常系テストの実施困難です。依存性の注入（Dependency Injection）を検討してください。

- 解析性（Analyzability）の不足: エラー時に単に `None` を返していますが、これでは呼び出し元で「ネットワークエラー」なのか「ユーザーが見つからない」のか判別できません。適切な外送出またはログ出力を追加してください。

-    保守性（Maintainability）の懸念: APIのベースURLがハードコーディングされています。環境変数または設定ファイルから読み込む設計に変更すべきです。

これらは、人間の開発者の感覚とも一致する的確な指摘だといえます。

3. AIの指摘を受けて修正したコード

こういった指摘を受け、開発者は例えば次のようにコードを修正することができます。

import logging
from typing import Dict, Any, Optional

# インターフェース依存にして試験性を向上（DIパターンの適用）
def get_user_data(user_id: str, api_client: Any, base_url: str) -> Optional[Dict[str, Any]]:
    try:
        response = api_client.get(f"{base_url}/users/{user_id}")
        response.raise_for_status()
        return response.json()
    except Exception as e:
        # 解析性の向上：エラー内容をログ出力し、文脈を含めて再送出または処理
        logging.error(f"Failed to fetch user data for {user_id}: {str(e)}")
        raise

DIなどが適切に実施され、エラーハンドリングも改善されています。 コードの品質は明確に向上したと言えるでしょう。 このように、AIの指摘に従うことで、テスト容易性が確保され、本番運用時のトラブルシューティングも容易なコードへと改善されました。

まとめ：AIとISO品質特性による開発プロセスの進化

本レポートでは、ISO/IEC 25010、特に「検証可能性（Verifiability）」を軸としたAI自動レビュー環境の構築について解説しました。

AIにISOという「共通言語」を与えることで、以下のメリットが生まれます。

1. レビュー品質の均質化: ベテラン・若手を問わず、一定の品質基準（試験性・解析性など）が常にチェックされる。

2. 教育効果: 「なぜこのコードがダメなのか」がISO用語と共にフィードバックされるため、開発者が自然とアーキテクチャ設計を意識するようになる。

3. 検証可能性の担保: テストしにくいコードがマージされるのを防ぎ、長期的な保守コストを低減する。

AI駆動開発は、単にコードを書かせるだけでなく、品質保証（QA）プロセスそのものを構造化・自動化するフェーズに入っています。 今後は、プロジェクト固有のドメイン知識をRAG（検索拡張生成）でAIに与え、さらに高度な「仕様整合性」のレビューを実現することが次の展望となります。