AIエージェント・ワークフローにおけるレビュー・テスト体制を、Google eng-practices / OWASP / ISTQB の語彙で説明する
本プロジェクトは、AIエージェント(実装・レビュー・テスト設計を担う複数ロール)が人間の承認ゲート(HITL)の下でコード変更を配達するワークフローである。その品質保証層は次の3点で説明できる。
レビュー19観点をGoogle eng-practices・OWASP Top 10(2021)・OWASP LLM Top 10(2025)・CWE・Twelve-FactorへJSON正本上でマッピング。テスト23パターンをISTQB CTFL v4系の標準技法へタグ付け。重大度はblocker〜nitとP0〜P3の対応表1枚で橋渡し。
① 証跡境界規律 — 「何を証明していないか」を出力契約(JSON Schema)で強制。② 観点ID運用 — 観点パックのversion+digestをrun開始イベントに束縛。③ 実run実証 — 2026-07-19の実runで13/19観点の識別的選択とISTQBタグ付きテスト5本を実測。
grader(レビュー品質の自動採点)は採点実績ゼロ。finding受理率などレビュー有効性メトリクスは意図的に未計測。公開ページはJSON正本より古い版を配信中。実run実証はまだn=1。
ワークフローは1チケット=1runで次のロール列を通る。
一般的な組織のPRレビュー+CIに対応させると、reviewerがヒューマンレビューの代替、テストパックとその実行がテスト計画+CI、HITL承認がマージ権限に相当する。相違点は、各段の入出力がスキーマ強制されたJSONとして残り、監査可能な証跡になることである。
観点はJSON正本 config/flow-engine/review-perspective-pack-v1.json で管理される(HTML文書は参照側)。各観点は id(不変ID)・standard_mapping・machine_gate(先行する決定論ツール)・llm_focus(機械で確定できない文脈判断)・trigger_paths(発火する変更パス)を持つ。代表例(全19観点は附録A、既存公開ページはコードレビュー観点一覧を参照):
| 観点 | 標準 |
|---|---|
| P-01 秘密情報ハードコード | CWE-798、secret scanning |
| P-03a 認可・アクセス境界 | OWASP A01:2021 Broken Access Control |
| P-04 LLM固有セキュリティ | OWASP LLM01:2025 Prompt Injection、LLM02:2025 Sensitive Information Disclosure |
| P-05 結合・責務境界 | Google code review: design / complexity |
| P-14 要求適合 | Google code review: functionality |
| P-15 可読性・保守性 | Google code review: naming / comments / style / documentation |
設計上の要点は2つ。機械ゲート先行の原則(ツールで検出できるものはツールに任せ、LLMは文脈判断に集中する、というGoogle流の役割分担を観点ごとに明文化)と、Googleのレビュー観点の網羅(eng-practices "What to look for" の主要カテゴリをP-05/07/11/13/14/15でカバー。P-14とP-15は標準に照らした欠落レビューで後から追加された経緯があり、「標準で自分の穴を見つける」運用が機能した実例)。
テストパターンはJSON正本 config/flow-engine/test-pattern-pack-v1.json で管理され、各パターンが evidence_level・technique_mapping(ISTQB CTFL v4系の標準技法名)・変更クラス別の適用可否と最低テストセットを持つ。登場する技法: 同値分割、境界値分析、状態遷移、デシジョンテーブル、負例、契約テスト、mutation(PIT系)、golden master、フォールトインジェクション、テストダブル、トレーサビリティ確認。パック冒頭にISTQB CTFLシラバスv4.0.1等への参照URLが根拠として残る。既存公開ページのテストパターン一覧も参照できる。
証跡レベル語彙は7種で、テスト結果から主張してよい範囲の上限を表す:
ISTQBのテストレベルがテストの対象範囲の分類であるのに対し、この語彙はその結果から何を主張してよいかの分類である点が特徴。
選定の決定論化: 最少3・最多5、同点時は定義順、変更クラス別のmin_requiredにより、テスト選定がLLMの裁量ではなくパック定義で拘束される。ただし限界が1つ実測されている: 実装は選定数が上限5件に達すると後続の変更クラスを打ち切るため、複数クラスが同時に活性な場合にmin_requiredが無警告で脱落し得る(run 10監査で実測。§5-5参照)。
| 一般語彙 | エンジン重大度 | blocking | 規律 |
|---|---|---|---|
| blocker | P0 / P1 | する | 違反した不変条件と影響する主要経路の明示が必須 |
| major | P1 / P2 | P1のみ | 主要経路/共有runtimeの欠陥を証拠で示せる場合だけP1 |
| minor | P2 | しない | 回復可能な局所不具合・改善 |
| nit | P3 / surface | しない | 文書整合・命名等。自動整形領域はfindingにしない |
blocking判定はreviewer本人の宣言ではなくrunner側のコードで導出される。重大度と根拠の構造(違反不変条件・影響経路)が揃った場合にのみ機械的に止まるため、severityインフレというレビュー運用の一般的な劣化モードへの構造的対策になっている。
reviewerの出力契約は unproven_scope(未証明範囲)、overclaim_findings(過大主張の指摘。証跡レベルの無断昇格 evidence_escalation を分類として持つ)、worker_claimed_evidence_level を必須項目とするJSON Schemaで検証される。test-designerも skipped_tests(理由必須)、carried_unproven_scope、overclaim_risks を必須で持つ。
実測例(run 10): テスト設計出力は「local modeの成功をSnowflake実接続成功の証拠として扱わない」等のoverclaim回避4件、理由付きskip 4件を明示。integrator判断にも「Slack HTTP receiptは送信成立だけを示し、受信者の閲覧・理解は未証明」という境界記述が残る。一般実務でこれに相当するのはテスト計画書の「対象外項目」節や熟練レビュワーの慎重な言い回しだが、属人的文化でありスキーマで強制されない。ここでは過大主張が構造的に書けない。
観点・テストパックはJSONが単一の正本(SSOT)。各runの開始イベントの config_identity.knowledge_packs に、パックのversionとsha256 digestが束縛される(run 10実測: review pack = sha256:10e972d0…、test pack = sha256:b7d9e16e…)。観点の選択は変更パス×trigger_pathsの決定論で行われ、findingは観点IDへ構造帰属する(reviewer契約v3でperspective_idフィールド化)。
レビューチェックリストを持つ組織は多いが、チェックリストのバージョンを個々のレビュー実行に紐付けて追跡する組織は稀。ここでは観点定義の改訂とレビュー結果が同じ証跡チェーンに乗る。
2026-07-19、実チケット(RAIOPS-10: HITL画面警告文言の日本語first化)を対象に観点パック適用後の初runが完走(run ID: phase4b-pilot-raiops-10-20260719-01)。
| 項目 | 実測値 |
|---|---|
| 観点選択 | 19観点中13観点が変更パスから選択(P-01, P-02, P-03a/b, P-04, P-05, P-06, P-08b, P-09b, P-11, P-12a, P-14, P-15)。全部盛りではなく識別的選択が動いた。この選択はマッチャー意味論を独立に再実装した第三者検算で期待集合と完全一致を確認済み(除外6観点も全て正当) |
| レビュー結果 | outcome = no_blocking。P2 finding 1件 — 新設の非sensitive系safe-stop文言分岐に直接テストがない、という指摘。該当パス・行番号・根拠・影響経路・checker候補付き。指摘の実在性は統合後コードとの照合で確認済み(該当文言はapp.py:151にのみ存在し、参照するテストが無い) |
| 未証明範囲 | 4件明示(実ブラウザ表示、credential欠落時の実行時挙動、remote状態 等) |
| テスト設計 | TP-13 / 12 / 15 / 03 / 02 を知識源とする5本(選定上限どおり)。各テストに期待証跡レベル。負例4・境界5・失敗時artifact期待5・skip理由4 |
| 統合 | 人間の一回性承認後、retail main へ統合(commit c6588d4。remoteのfresh cloneで実在確認済み) |
| 終端検証 | terminal_result = success、HMAC署名付きprocess receipt生成 |
findingの中身も象徴的で、「実装は正しいがテストが分岐を1本カバーしていない」という、Google eng-practicesがtests観点で求める典型的な指摘である。
a725ba6)、commit ad7ede0 を既存Cloudflare経路でデプロイ。7ページのsource equivalence PASS+canonical URLの独立フェッチで19観点・23パターン・標準名の表示を確認済み。dropped_min_requiredの実記録・人間approve後の成功終端+署名検証まで一巡を実証。統計的主張にはなお不足で、実run数を積む以外の近道はない。tie_break宣言と実装の走査順の食い違いも併発。→ 2026-07-19に修正済み(engine 02acb52〜9ed2d5e / retail b61ff4d): 走査順はpackキー順へ、脱落はdropped_min_requiredとして記録、パック適用自体もfail-closed化。remote独立検証済み。2026-07-20のRAIOPS-34 live runで脱落記録の非空実記録までE2E実証済み。一言で言えば、「Google eng-practicesの観点分離とOWASP/ISTQBの標準語彙を、AIレビュワーの出力契約として機械可読化し、観点定義のバージョンごとrun証跡に焼き込んだレビュー・テスト体制」である。
| ID | 観点名 | 標準マッピング | 機械ゲート(先行) |
|---|---|---|---|
| P-01 | secret-hardcode-reviewer | CWE-798、secret scanning | secret scanning、credential literal scan |
| P-02 | config-hardcode-reviewer | Twelve-Factor App: Config | config schema validation、env-reference lint |
| P-03a | security-logic/access-control | OWASP A01:2021、Google: functionality | authorization contract tests、input schema validation |
| P-03b | security-logic/sast-sca | OWASP A03:2021、SCA | SAST、SCA、dependency audit、parameterized-query lint |
| P-04 | llm-security-reviewer | OWASP LLM01:2025、LLM02:2025 | prompt injection fixtures、tool allowlist、output validation |
| P-05 | coupling-boundary-reviewer | Google: design / complexity | dependency direction lint、cycle detection |
| P-06 | availability-resilience-reviewer | resilience patterns、fault tolerance | timeout/retry/idempotency tests、failure-artifact contract |
| P-07 | concurrency-race-reviewer | Google: functionality(並行性) | race/idempotency tests、transaction tests |
| P-08a | scale-nfr/requirements | performance engineering、NFR | NFR schema/checklist、benchmark threshold |
| P-08b | scale-nfr/code | performance engineering、Google: complexity | performance smoke、query profile、N+1 scan |
| P-09a | data-kpi-correctness/contracts | data contract testing | schema tests、dbt tests、semantic contract validation |
| P-09b | data-kpi-correctness/evaluation | golden dataset evaluation | golden evaluation、semantic validator |
| P-10 | compatibility-migration-reviewer | backward compatibility、API versioning | contract compatibility tests、migration/rollback tests |
| P-11 | test-gap-reviewer | Google: tests | test execution、coverage、negative/mutation fixtures |
| P-12a | pii-logging/privacy | OWASP LLM02:2025、OWASP A09:2021 | redaction tests、PII/log scan、secret scan |
| P-12b | pii-logging/diagnostics | OWASP A09:2021、observability | trace contract tests、failure artifact parity |
| P-13 | architecture-intent-boundary | Google: design、ADR | contract/schema validation、architecture lint |
| P-14 | requirement-conformance-reviewer | Google: functionality | acceptance criteria readback、brief/config identity validation |
| P-15 | readability-maintainability | Google: naming / comments / style / documentation | formatter、lint、documentation link check |
| ID | パターン名 | 証跡レベル | 技法マッピング |
|---|---|---|---|
| TP-01 | dbt parse / compile --empty | compile-only | static testing、configuration validation |
| TP-02 | runtime failure artifact parity | contract-test | negative testing、状態遷移、contract testing |
| TP-03 | live trace runner boundary | live-integration | integration testing、negative testing、fallback-path |
| TP-04 | RBAC / LLM-safe / cost guardrail contract | contract-test | negative testing、同値分割、contract testing |
| TP-05 | dbt schema / generic / singular / static gate | data-bearing-local | data contract testing、同値分割、invariant testing |
| TP-06 | rate KPI mutation / denominator-zero guard | contract-test | mutation testing、境界値分析、negative testing |
| TP-07 | Backlog / Slack private simulation | fixture-unit | test doubles、negative testing、idempotency |
| TP-08 | diagram quality lint | static-lint | static testing、visual contract testing |
| TP-09 | feedback reflection lint | static-lint | static testing、traceability testing |
| TP-10 | workflow state vocabulary lint | static-lint | 状態遷移テスト、contract testing |
| TP-11 | fixture/unit regression | fixture-unit | 同値分割、境界値分析、unit testing |
| TP-12 | Streamlit component smoke | fixture-unit | component testing、scenario testing |
| TP-13 | Streamlit browser E2E | user-facing-e2e | end-to-end testing、scenario testing、状態遷移 |
| TP-14 | Golden Eval / answer quality | data-bearing-local | golden master testing、regression testing |
| TP-15 | integration evidence freshness | static-lint | traceability testing、consistency checking |
| TP-16 | HTML parse / link / local preview | static-lint | static testing、navigation contract testing |
| TP-17 | SCA / dependency vulnerability scan | static-lint | software composition analysis、static testing |
| TP-18 | reviewer defense fixture / Promptfoo redteam | contract-test | negative testing、adversarial testing、mutation |
| TP-19 | NFR placeholder / performance load smoke | data-bearing-local | performance testing、境界値分析 |
| TP-20 | idempotency key / external API fault injection | contract-test | fault injection、状態遷移、negative testing |
| TP-21 | Golden Eval two-layer / dbt unit tests | data-bearing-local | golden master、unit testing、regression |
| TP-22 | AI_OBSERVABILITY_EVENTS comparison ADR | contract-test | デシジョンテーブル、traceability、contract testing |
| TP-23 | pre-commit formatting layer / review separation | static-lint | static testing、consistency checking |
| テストID | 知識源 | 目的(要約) | 期待証跡レベル |
|---|---|---|---|
| T-01 | TP-13 | 実ブラウザでHuman Review画面の日本語first警告を確認(skip 0) | user-facing-e2e |
| T-02 | TP-12 | 承認待ち/safe-stop fixtureのcomponent renderで警告文言を固定 | fixture-unit |
| T-03 | TP-02 | credential欠落時のsafe-stop契約と失敗artifactの項目整合 | contract-test |
| T-04 | TP-03 | 明示的local mode実行とcredential欠落safe-stopの経路分離(暗黙fallback禁止) | live-integration |
| T-05 | TP-15 | 結果artifactを対象commit・設定・skip数へ対応付け、古い証跡を除外 | static-lint |
付随して負例4件(NC-01〜04)、境界5件(BC-01〜05)、失敗時artifact期待5件、理由付きskip 4件(実Snowflake接続・実外部送信・公開デプロイ・push検証)が設計された。