1300行のコンテキストが崩壊した日：一括コンテキストから細切れ仕様書へ移行したAI駆動開発におけるDocOps（Documentation Operations）改革

---

# PR Semantic Audit Pipeline Specification

## 1. System Topology & Sequence

sequenceDiagram
    autonumber
    actor Dev as 開発者 (人間)
    participant CI as CIワークフロー
    participant API as リポジトリAPI
    participant SC as 連携スクリプト環境
    participant AI as AIモデル (クラウド環境)
    participant Chat as チャットツール

    alt 軽微な修正の場合 (直マージ)
        Dev->>API: メインブランチへ直接マージ・プッシュ
        Note over API, SC: PRを起票しないため、AI意味論監査はスキップ
    else 意味論監査を行う場合 (PR駆動)
        Dev->>API: 特徴量実装・変更の PR作成
(説明文に仕様書名やパス、ヒントを自然言語で記載)
        
        Note over CI: 物理テスト実行 (ユニットテスト & 結合テスト)
        
        alt 物理テスト合格 (success)
            CI->>SC: Webhook送信 (CI合格 + PR番号)
        end

        activate SC
        %% 最初のデータ取得（超軽量）
        SC->>API: PRの説明文(Body)および変更された「ファイルパス一覧」を要求
        API-->>SC: 説明文テキスト & 変更ファイルパスの一覧を返却
        
        %% ステップ1: 仕様書の自律特定
        SC->>AI: 仕様書特定要求 (説明文 + パス一覧)
        activate AI
        Note over AI: 人間の雑な説明文から、監査の物差しにすべき
仕様書(*.proto等)の正確なパスを自律推論
        AI-->>SC: Function Calling発火: fetch_repository_files(spec_path, code_paths)
        deactivate AI

        %% ステップ2: 指示されたファイルの取得（土管化）
        SC->>API: 指定された仕様書および変更コードの「生テキスト丸ごと」を要求
        API-->>SC: 対象ファイルの生テキスト群を返却
        
        %% ステップ3: 本番の意味論監査
        SC->>AI: 監査実行（関数の実行結果として生データを引き渡し）
        activate AI
        Note over AI: 人間が指定した物差し(スキーマ定義等)と
実装コード(ファイル丸ごと)の意味論的矛盾を検知
        AI-->>SC: 報告書返却 (厳格なJSONオブジェクト)
        deactivate AI

        %% 結果のデリバリー
        SC->>Chat: 判定結果(APPROVE/REJECT)をデリバリー
(Markdownでシンタックスハイライト付き着信)
        deactivate SC
    end

---

## 2. SYSTEM RULES (AI監査における制約)

* **仕様書パスの厳格な検証 (厳格なガードレール):**

    * 監査の実行には、PR説明文（Body）内への仕様書パス（例: `schemas/…/*.proto` など）の**完全一致での明記を絶対条件**とする。

    * 説明文に仕様書パスの**記載がない場合**、あるいは指定されたパスが変更ファイルパス一覧等と照らし合わせて**リポジトリ内に実在しない（誤りがある）場合**は、自律推論による補完を一切行わず、即座に「監査エラー（REJECT）」として処理を中断し、その旨を報告すること。

* **物理・論理の完全分離:**

    * Linter、コンパイラ、自動テスト（物理防衛）で機械的に検知できるシンタックスエラーや型エラー、テストの成否に関する指摘は一切行わないこと。

* **意味論の突合:**

    * 取得したソースコード（変更があったファイル丸ごと）と、明示指定された仕様書内の `BUSINESS RULES` 拡張および `Mermaid図` との間に、論理的な矛盾や実装漏れがないかのみを監査すること。

* **アーキテクチャ不壊の監視:**

    * データの計算や純粋なビジネスロジックを担う「コアロジック層（ドメイン共通ライブラリ等）」の変更内に、外部依存の強いWebフレームワーク、非同期ランタイム・非同期コード、および非同期構文（`async/await` 等）が混入していないか厳しくチェックすること。

* **出力フォーマットの厳守:**

    * **仕様書取得フェーズ:** 正しいパスが明記されている場合のみ、関数（Tool Use / Function Calling）を呼び出してファイルを取得すること。

    * **最終監査報告（またはエラー終了）フェーズ:** 判定結果（およびパス不正によるエラー報告）は、人間がチャット上で一目で確認できるよう、 “`json … “` のMarkdownコードブロック形式を用いて、構造化したJSONオブジェクトのみで報告すること（前後の挨拶や余計な解説テキストは一切不要）。

---