はじめに

前回の【モダンWeb開発シリーズ第6回】では、docs/test-cases.md を基準として、既存テストとの対応確認、不足しているテストの追加、Unit Test、Integration Test、Regression Test、ブラウザでの手動確認まで、一次開発のテスト工程を段階的に進めました。

第6回では、テストに失敗した場合も、人間が結果を確認し、Codexへ原因調査、修正、再テストを順番に指示する形で進めています。

この方法は、各工程を理解しながら進めるうえで分かりやすい一方、テストケースが増えてくると、人間とCodexのやり取りも増えていきます。

人間
 ↓
テスト実行を指示
 ↓
Codex
 ↓
FAIL
 ↓
人間
 ↓
原因調査を指示
 ↓
Codex
 ↓
原因を報告
 ↓
人間
 ↓
修正を指示
 ↓
Codex
 ↓
修正
 ↓
人間
 ↓
再テストを指示

そこで今回は発展編として、Codexのエージェントハーネスを意識した開発ルールを用意し、テスト実行、原因分析、軽微な修正、再テスト、Regression Test、結果記録までを一連の流れとしてCodexへ任せる方法を扱います。

重要なのは、AIへ無制限に修正を許可することではありません。

今回のポイントは、

Codexが自律的に作業してよい範囲と、人間へ判断を戻す範囲を最初に決める

ことです。

第6回で使用した117件のテストケースと確定済みの設計書をそのまま利用し、既存仕様を変更せずにテスト工程を自律化します。

この記事で分かること

エージェントハーネスの考え方
Codexへ複数工程をまとめて任せる方法
AGENTS.md をガードレールとして利用する方法
docs/test-cases.md をテスト契約として扱う方法
テスト失敗を原因別に分類する方法
軽微な不整合をCodex自身で修正する方法
修正後に該当テストと関連テストを再実行する方法
Regression Testまで自動的に進める方法
設計判断が必要な場合だけ人間へ戻す方法
docs/test-results.md へ実行結果を残す方法
自動テストと人間によるブラウザ確認を分ける方法
第6回の進め方とエージェントハーネス方式の違い

今回利用する前提環境

今回も、第2回から使用しているDocker Compose + Dev Container環境を利用します。

Windows 11
    ↓
VS Code
    ↓
Dev Containers
    ↓
Docker Desktop
    ↓
Docker Compose
    ├─ app
    │    ├─ Codex CLI
    │    ├─ Go
    │    ├─ Node.js
    │    └─ React + TypeScript + Vite
    │
    └─ db
         └─ PostgreSQL

DB接続は、第6回と同じ構成です。

.env
 ↓
compose.yml
 ↓
app Container
 ├─ DATABASE_URL
 └─ TEST_DATABASE_URL
      ↓
db:5432

通常のBackendは DATABASE_URL、Repository / Integration Testは TEST_DATABASE_URL を使用します。

エージェントハーネスとは

ここでいうエージェントハーネスは、単にAIへ長い指示を渡すことではありません。

今回の記事では、エージェントハーネスそのものを新しくプログラミングするわけではありません。Codexそのものが持つエージェント実行機能を、AGENTS.md、確定済み設計書、テストケース、停止条件によって制御します。Codexが自律的にテスト、原因分析、軽微な修正、再テストを繰り返せる実行ルールをプロジェクト側に用意する構成です。

つまり、今回用意するのは専用のGoやPythonプログラムではなく、Codexが既存の開発プロセスの中で安全に連続作業するためのルールです。AGENTS.mdでプロジェクト全体のルールを定義し、確定済みdocsとdocs/test-cases.mdを判断基準にして、Codexへ渡す指示で作業範囲と停止条件を明確にします。

AIが複数の作業を連続して実行するときに、

何を基準に判断するか
どこまで変更してよいか
何を変更してはいけないか
テストに失敗したら何をするか
どの条件で作業を継続するか
どの条件で人間へ戻すか
最後に何を報告するか

をあらかじめ決めておく考え方です。

今回の場合は、次の流れをCodexへ任せます。

docs/test-cases.md
        ↓
既存テストを確認
        ↓
不足テストを確認
        ↓
テスト実行
        ↓
      PASS？
     /     \
   Yes      No
    |        |
    |      原因分析
    |        ↓
    |   軽微な不整合？
    |      /      \
    |    Yes       No
    |     |         |
    |   最小修正   人間へ報告
    |     |
    |   再テスト
    |     |
    |   関連テスト
    |     |
    └─────┘
        ↓
Regression Test
        ↓
docs/test-results.md
        ↓
完了条件を確認

第6回との違い

第6回では、テスト工程を理解することを優先し、人間がCodexへ段階的に指示しました。

人間
 ↓
Codexへテスト実行を指示
 ↓
結果確認
 ↓
次の作業を人間が判断
 ↓
Codexへ次の指示

今回の発展編では、この間の判断ルールを先に定義します。

人間
 ↓
テスト工程全体のルールをCodexへ渡す
 ↓
Codex
 ├─ 調査
 ├─ テスト実行
 ├─ 原因分析
 ├─ 許可範囲なら修正
 ├─ 再テスト
 ├─ Regression Test
 └─ 結果記録
       ↓
設計判断が必要な場合だけ停止
       ↓
人間

つまり、人間が判断しなくても既存仕様から一意に決められる作業を、Codex側で連続して進めるのが今回のポイントです。

自律化する範囲を決める

まず、Codexが自律的に処理してよい範囲を決めます。

今回、自律化するのは次の範囲です。

作業	Codexで自律実行
既存テストの確認	○
`docs/test-cases.md` との対応確認	○
不足テストの追加	○
Unit Test実行	○
Handler Test実行	○
Repository / Integration Test実行	○
テスト失敗原因の調査	○
単純な実装不整合の修正	○
テストコードの単純な不整合修正	○
修正したテストの再実行	○
関連テストの再実行	○
Regression Test	○
Race Detector	○
Build確認	○
`docs/test-results.md` 更新	○
主要な設計変更	×
新しいAPI追加	×
DB Schema変更	×
認証・認可方式変更	×
セキュリティ要件変更	×

自律化してはいけない範囲

Codexが自律的に動けるようにしても、設計判断までAIへ任せるわけではありません。

次のような場合は作業を停止し、人間へ戻します。

一次開発の機能追加・削除が必要
新しいAPIが必要
DB Schema変更が必要
認証・認可方式の変更が必要
セキュリティ要件の変更が必要
外部インターフェースの大きな変更が必要
確定済みの主要な業務ルールを変更する必要がある
複数の合理的な設計案がある
既存仕様同士が矛盾している

この境界を決めずに「テストが通るまで直してください」とだけ指示すると、テストを通すために仕様そのものを変えてしまう可能性があります。

今回のエージェントハーネスでは、

テストを通す

ことより、

確定仕様へ適合させた結果としてテストが通る

ことを優先します。

AGENTS.mdをガードレールとして利用する

第4回で作成した AGENTS.md は、今回もCodexの作業ルールとして利用します。

今回のプロジェクトでは、すでに次のようなルールがあります。

Architecture
 ├─ Handler
 ├─ Service
 └─ Repository

Frontend
 ├─ TypeScript必須
 ├─ any原則禁止
 └─ API通信を分離

Backend
 ├─ Go命名規則
 ├─ gofmt
 ├─ context利用
 └─ HTTP Status Codeを適切に扱う

Security
 ├─ Secretsをソースへ書かない
 ├─ Validation
 ├─ SQL Injection対策
 ├─ CORS制限
 └─ CSRF

Validation
 └─ Frontend / Backendで契約をそろえる

このルールに、テスト工程での自律実行ルールを組み合わせます。

docs/test-cases.mdをテスト契約として扱う

今回のテストケースは、第3回で設計し、人間が確認した docs/test-cases.md を使用します。

requirements.md
use-cases.md
screen-design.md
database-design.md
api-design.md
open-questions.md
        ↓
横断レビュー
        ↓
docs/test-cases.md
        ↓
117 Test Cases

重要なのは、Codexがテストに失敗したからといって docs/test-cases.md の期待結果を書き換えないことです。

テストFAIL
   ↓
test-cases.mdをPASSする内容へ変更

ではありません。

正しくは、

テストFAIL
   ↓
確定仕様を確認
   ↓
実装・テスト・環境のどこに差異があるか確認

です。

テスト失敗を分類する

テストに失敗した場合、すぐにコードを修正するのではなく、まず原因を分類します。

今回の分類は次のようにします。

分類	例	基本対応
実装不具合	確定仕様と本番コードが不一致	本番コードを最小修正
テストコード不具合	`int64` と `int` の比較不整合	テストコードを最小修正
テストデータ不具合	Fixture不足、前提データ不足	既存方式の範囲で修正
環境不具合	環境変数未設定、依存取得不可	環境を修正
設計差異	docs同士が矛盾	人間へ報告
新規設計が必要	API追加、Schema変更	人間へ報告

第6回では、実際にテストコード側の型不整合も発生しました。

list.Page.Offset → int64
tc.offset        → int

このようなケースは、既存実装と確定仕様から一意に判断できるため、設計変更として扱う必要はありません。

軽微な差異と設計変更を分ける

Codexが自律修正してよいのは、次をすべて満たす場合です。

一次開発の既存スコープ内
新しい機能を追加しない
新しいAPIを追加しない
DB Schemaを変更しない
認証・認可方式を変更しない
セキュリティ要件を変更しない
外部インターフェースを大きく変更しない
既存の確定仕様から一意に判断できる
複数案から人間が選択する必要がない

この条件を満たす場合は、

差異確認
 ↓
影響範囲確認
 ↓
最小修正
 ↓
該当テスト
 ↓
関連テスト
 ↓
元のテスト工程へ戻る

までCodexへ任せます。

人間へ戻す条件

一方、次の場合はCodexで判断せず停止します。

新しい機能が必要
新しいAPIが必要
DB Schema変更が必要
認証・認可方式変更が必要
セキュリティ要件変更が必要
主要な業務ルール変更が必要
複数の合理的な案がある
確定仕様同士が矛盾している

この場合、Codexには次の情報だけを整理してもらいます。

該当TC-ID
関連設計書
現在の実装
発見した差異
判断が必要な理由
選択肢

人間は、この情報をもとに必要であればWorkで設計を再検討します。

テストデータの隔離方式もハーネスに含める

第6回では、Repository / Integration Testで既存のテストデータ隔離方式を確認しました。

今回もこの方式を変更しません。

TEST_DATABASE_URL
      ↓
db:5432/shop
      ↓
テストごとに
step6_test_<UUID>
      ↓
migration
      ↓
seed
      ↓
テストデータ
      ↓
テスト実行
      ↓
t.Cleanup
      ↓
DROP SCHEMA ... CASCADE

単一接続で十分なテストでは pg_temp も利用します。

PostgreSQL Connection
      ↓
pg_temp
      ↓
migration / seed
      ↓
テスト
      ↓
Connection Close
      ↓
自動破棄

エージェントがテストを自動生成するときも、この既存方式を優先します。

新しいテストDBやFixtureを、テストのたびに勝手に追加しないようにします。

Codexを起動する

Dev Container内のターミナルでCodexを起動します。

cd /workspaces/shopping-site
codex

今回も、プロジェクトルートから起動します。

/workspaces/shopping-site
├─ AGENTS.md
├─ backend
├─ frontend
├─ docs
├─ testdata
├─ compose.yml
└─ .env

人間 → Codex 指示①：エージェントハーネスの前提を確認する

最初に、Codexへ今回の作業ルールを確認させます。

このプロジェクトのテスト工程を、既存の確定仕様を基準として継続してください。

まず次を確認してください。

- AGENTS.md
- docs/requirements.md
- docs/use-cases.md
- docs/screen-design.md
- docs/database-design.md
- docs/api-design.md
- docs/open-questions.md
- docs/test-cases.md
- docs/test-results.md
- backendの既存テスト
- frontendの既存テスト
- testdata
- compose.yml

今回は新しい仕様を設計する作業ではありません。

docs/test-cases.mdをテスト契約として扱い、既存実装と既存テストを確認してください。

確定仕様から一意に判断できる軽微な差異は、後述するルールの範囲でCodex側で解消します。

設計変更が必要な場合だけ停止し、人間へ報告してください。

この段階ではファイルを変更せず、
- 現在のテスト構成
- テストデータ準備方式
- TEST_DATABASE_URLの使用箇所
- Cleanup方式
- 自律修正可能な範囲
- 人間判断が必要になる条件
を整理してください。

人間 → Codex 指示②：自律テスト・デバッグ・再テストを実行する

前提確認ができたら、今回の中心となる指示を渡します。

前回までのテスト実装と実行結果を引き継ぎ、未完了項目からテスト工程を継続してください。

テスト・実装中にdocs、docs/test-cases.md、実装、既存テストの間で仕様差異を発見した場合、すべてを人間やWorkへ差し戻さないでください。

まず影響範囲を確認してください。

次をすべて満たす場合は、既存の確定仕様を基準としてCodexで差異を解消してください。

- 一次開発の既存スコープ内である
- 新しい機能を追加しない
- 新しいAPIを追加しない
- DB Schemaを変更しない
- 認証・認可方式を変更しない
- セキュリティ要件を変更しない
- 外部インターフェースを大きく変更しない
- 既存の確定仕様から合理的かつ一意に判断できる
- 複数の設計案から人間が選択する必要がない

この範囲では必要に応じて、

1. 確定仕様と差異の根拠を確認
2. 実装の単純な不整合を修正
3. 既存テストの期待値など、確定仕様から一意に判断できる不整合を修正
4. 関連テストを実行

まで一貫して行ってください。

docs/test-cases.md のテスト条件・期待結果・Status Codeなど、テスト仕様そのものを独断で変更しないでください。

確定設計から一意に判断できる単純な記載不整合を発見した場合は、対象箇所と判断根拠を報告してください。

設計変更になる場合は人間へ報告してください。

次のいずれかに該当する場合は、独断で仕様を決めず停止してください。

- 一次開発の機能追加・削除が必要
- 新しいAPIが必要
- DB Schema変更が必要
- 認証・認可方式の変更が必要
- セキュリティ要件の変更が必要
- 外部インターフェースの大きな変更が必要
- 確定済みの主要な業務ルールを変更する必要がある
- 複数の合理的な設計案があり、既存仕様から一意に判断できない
- 既存仕様同士が明確に矛盾し、どちらを正とするか判断できない

この場合だけ、

- 該当TC-ID
- 関連設計書
- 現在の実装
- 発見した差異
- 判断が必要な理由
- 選択肢がある場合はその選択肢

を報告してください。

テストがFAILした場合は、原因を次のいずれかに分類してください。

- 実装不具合
- テストコード不具合
- テストデータ不具合
- 環境不具合
- 設計差異
- 新規設計が必要

軽微な差異を修正した場合は、

1. 変更したファイルへ必要なFormatを実行
2. FAILした該当テストを再実行
3. 関連テストを実行
4. 必要な範囲のRegression Testを実行
5. 問題がなければ元のテスト工程へ戻る

の順に進めてください。

軽微な差異を修正するたびにプロジェクト全体を再レビューしないでください。

今回の作業範囲と関係のない改善点、リファクタリング候補、二次開発案を新しいブロッカーとして追加しないでください。

既存のFixture、Helper、Setup / Cleanupを優先して再利用してください。

テスト都合で新しいDBやコンテナを追加しないでください。

Repository / Integration TestではTEST_DATABASE_URLを使用し、既存の専用Schemaまたはpg_tempによる隔離方式を維持してください。

テスト工程の最後に、

- gofmt
- Go Unit / Handler Test
- Repository / Integration Test
- go test ./... -count=1
- Regression Test
- Race Detector
- go build ./...
- Frontend Test
- Frontend lint
- Frontend build

のうち、現在のプロジェクトに存在するものを実行してください。

ブラウザーで人間が操作する必要がある項目は自動テストのPASSとして扱わず、Manualとして残してください。

最後にdocs/test-results.mdを更新してください。

最終報告では、

- 発見した差異
- 原因分類
- 判断根拠
- 確認した関連docs
- docs/test-cases.mdに記載不整合があった場合は対象箇所と判断根拠
- 修正した実装
- 修正・追加したテスト
- 実行したコマンド
- PASS / FAIL / SKIP
- Regression Test結果
- 未完了のManual Test
- Definition of Doneを満たしているか

を報告してください。

この指示が、今回のエージェントハーネスの中心になります。

テスト失敗後の自律ループ

この指示を渡すことで、Codexは軽微な問題について人間の指示を待たずに次の流れを進められます。

Test
 ↓
FAIL
 ↓
原因分類
 ↓
確定仕様を確認
 ↓
Codexで修正可能？
   │
 ┌─┴─────────┐
 Yes          No
 │             │
最小修正      停止
 │             ↓
再テスト      人間へ報告
 │
関連テスト
 │
Regression Test
 │
PASS
 │
元のテスト工程へ戻る

実際に発生したテストコード不具合

第6回では、Repository Testで次のコンパイルエラーが発生しました。

invalid operation: list.Page.Offset != tc.offset
mismatched types int64 and int

本番側の Page.Offset は int64、テスト側の期待値は int でした。

このケースでは、

DB Schema変更なし
API変更なし
業務仕様変更なし
本番コード変更なし
既存型定義から正しい型を一意に判断可能

だったため、Codex側でテストコードだけを最小修正できます。

list.Page.Offset != int64(tc.offset)

このような問題まで毎回人間へ戻す必要はありません。

環境不具合は本番コードを変更しない

第6回では、次のような環境側の問題も発生しました。

TEST_DATABASE_URL is not set

また、Frontendでは dist の一部ファイルが root 所有になり、Build時にPermission deniedが発生しました。

EACCES, Permission denied

このような場合は、テストを通すために本番コードを変更してはいけません。

FAIL
 ↓
原因分類
 ↓
環境不具合
 ↓
環境を修正
 ↓
同じテストを再実行

という流れにします。

TEST_DATABASE_URLを使った結合テスト

今回の環境では、次のように設定しています。

DATABASE_URL
→ 通常のBackend

TEST_DATABASE_URL
→ Repository / Integration Test

Dev Container内からは、

db:5432

へ接続します。

テスト専用Databaseを新しく作るのではなく、既存の開発DB内に隔離Schemaを作成します。

shop
 ├─ public
 │    └─ 通常開発
 │
 ├─ step6_test_xxxxx
 │    └─ Test A
 │
 ├─ step6_test_yyyyy
 │    └─ Test B
 │
 └─ pg_temp
      └─ 単一接続テスト

これにより、通常の開発データを直接書き換えずにIntegration Testを実行できます。

不足しているIntegration Testも自動で補う

既存の docs/test-cases.md にテストケースが存在していても、対応するIntegration Testが不足している場合があります。

この場合は新しいテストケースを勝手に追加するのではなく、既存TCに対応するテストコードを追加します。

今回の実行では、たとえば次のTCについてHTTP Integration Testを追加・拡張しました。

新規実装
TC-088
TC-089
TC-090

既存テストを拡張
TC-071
TC-075
TC-077
TC-078
TC-095
TC-096
TC-097
TC-115

これは、

docs/test-cases.md
117 TC
 ↓
不足している自動テストを確認
 ↓
既存TCに対応するテストコードを追加

という意味です。

docs/test-cases.md に118件目、119件目のテストケースを追加したわけではありません。

デバッグ後は該当テストだけを先に再実行する

不具合を修正したあと、いきなり全117 TCを最初から実行する必要はありません。

まずFAILしたテストを再実行します。

FAIL
 ↓
Fix
 ↓
該当テスト
 ↓
PASS

次に関連テストを実行します。

該当テスト
 ↓
PASS
 ↓
同じService
同じRepository
同じAPI
などの関連テスト
 ↓
PASS

ここまで成功したら、Regression Testへ進みます。

Regression Testを実行する

修正した箇所だけPASSしても、別の機能を壊している可能性があります。

そこで、修正後にRegression Testを実行します。

今回のGo Backendでは、次のような確認ができます。

cd /workspaces/shopping-site/backend
go test ./... -count=1

さらに実行順序への依存やRace Conditionも確認します。

go test ./... -count=1 -shuffle=on -race -timeout=5m

今回のテストでは、このコマンドも成功しました。

通常順序
go test ./... -count=1
        ↓
PASS

順序シャッフル + Race Detector
go test ./... -count=1 -shuffle=on -race -timeout=5m
        ↓
PASS

Buildも確認する

テストだけでなく、BackendのBuildも確認します。

cd /workspaces/shopping-site/backend
go build ./...

Frontendも既存のScriptに合わせて確認します。

cd /workspaces/shopping-site/frontend
npm run test
npm run lint
npm run build

プロジェクトに存在しないScriptを勝手に追加してはいけません。

まず package.json を確認し、既存Scriptだけを利用します。

docs/test-results.mdへ自動記録する

テストが終わったら、結果を docs/test-results.md へ記録します。

最低限、次を残します。

項目	記録内容
TC-ID	対象テストケース
テストコード	ファイル・関数
種別	Unit / Handler / Integration / Manual
実行結果	PASS / FAIL / SKIP / Manual
使用DB	必要な場合
データ準備	Fixture / seed / SQLなど
Cleanup	Schema削除 / pg_temp / Rollbackなど
修正内容	修正した場合
実行コマンド	実際に実行したコマンド
未完了理由	Manual、環境制約など

重要なのは、

Covered = PASS

ではないことです。

Covered
→ テストコードとの対応が存在する

PASS
→ 実際に実行して成功した

として区別します。

自動テストとManual Testを分ける

エージェントハーネスを使っても、すべてを自動化する必要はありません。

今回の117 TCには、ブラウザで人間が確認する項目も含まれています。

たとえば、

画面表示
ローディング表示
ボタン無効化
自動スクロール
ページ再読込
複数タブ
通信失敗時の表示

などです。

これらは、

自動テストがPASS
 ↓
Manual TestもPASSしたことにする

とはしません。

自動テスト
 ↓
PASS

Manual Test
 ↓
未確認

として分けます。

Definition of Doneを決める

エージェントを自律的に動かす場合、終了条件も重要です。

終了条件がなければ、

テスト
 ↓
レビュー
 ↓
改善
 ↓
再レビュー
 ↓
別の改善
 ↓
再レビュー

と作業が広がる可能性があります。

今回の完了条件は、たとえば次のようにします。

□ docs/test-cases.mdの全TCについて確認方法が特定されている
□ 自動対象TCに対応するテストコードが存在する
□ Unit TestがPASS
□ Handler TestがPASS
□ Repository / Integration TestがPASS
□ go test ./... がPASS
□ Regression TestがPASS
□ Race Detectorで問題なし
□ go build ./... がPASS
□ Frontend TestがPASS
□ Frontend lintがPASS
□ Frontend buildがPASS
□ FAILを修正した場合は再テスト済み
□ docs/test-results.mdが更新済み
□ Manual Testの未確認項目が明確
□ 設計変更が必要な未解決事項がない

Manual Testを別工程にする場合は、

自動テスト工程のDefinition of Done

と、

一次開発全体のDefinition of Done

を分けても構いません。

今回の117 TCではどうなったか

今回の第6回では、117件のテストケースを対象に既存テストとの対応を確認しました。

その後、不足していたIntegration Testを追加・拡張し、実PostgreSQLを含むGoテストを実行しました。

全TC
117
 ↓
自動対象
113
 ↓
既存テスト + 不足テスト追加
 ↓
go test ./... -count=1
 ↓
PASS
 ↓
go test ./... -count=1 -shuffle=on -race -timeout=5m
 ↓
PASS
 ↓
go build ./...
 ↓
PASS

さらに、Fixture間のデータ独立性とCleanup後のSchema削除もテストしました。

Test A
step6_test_xxxxx
        ↓
Cleanup
        ↓
DROP SCHEMA

Test B
step6_test_yyyyy
        ↓
Test Aと独立

これにより、単にテストケースがPASSしただけではなく、テスト環境そのものが他のテストへ影響を残さないことも確認できます。

エージェントハーネス導入前後を比較する

最後に、第6回の進め方と今回の方式を比較します。

観点	第6回	エージェントハーネス
テスト実行	人間が段階的に指示	Codexが連続実行
FAIL時の原因分析	人間が次の指示	Codexが分類
軽微な修正	人間が修正指示	条件内ならCodexが修正
再テスト	人間が指示	Codexが自動実行
関連テスト	人間が判断	ルールに従って実行
Regression Test	人間が指示	自動的に実行
設計変更	人間	人間
Manual Test	人間	人間
結果記録	Codexへ個別指示	一連の工程で更新

処理の流れも大きく変わります。

第6回

人間
 ↓
Codex
 ↓
人間
 ↓
Codex
 ↓
人間
 ↓
Codex

エージェントハーネスを利用すると、

人間
 ↓
Codex
 ├─ Test
 ├─ Debug
 ├─ Fix
 ├─ Retest
 ├─ Regression Test
 └─ Report
       ↓
設計判断が必要なときだけ
       ↓
      人間

となります。

エージェントハーネスを使うメリット

今回のようなテスト工程では、特に次のメリットがあります。

人間の確認回数を減らせる
        ↓
軽微なFAILで作業が止まらない
        ↓
修正後の再テスト漏れを防げる
        ↓
Regression Testまで一貫して実行できる
        ↓
結果をdocs/test-results.mdへ残せる

一方で、AIが自律的に作業するほど、ガードレールは重要になります。

自律性を上げる
      ↓
変更可能範囲を明確にする
      ↓
停止条件を明確にする
      ↓
確定仕様を基準にする

この組み合わせが重要です。

まとめ

今回は、第6回で行ったテスト工程をもとに、Codexのエージェントハーネスを意識して、テスト、デバッグ、修正、再テスト、Regression Test、結果記録までを一連の流れとして進める方法を確認しました。

ポイントは、Codexへ「全部任せる」ことではありません。

確定仕様
   ↓
ガードレール
   ↓
Codexが自律実行
   ├─ Test
   ├─ Debug
   ├─ Fix
   ├─ Retest
   └─ Regression Test
          ↓
判断できない場合だけ
          ↓
         人間

という境界を作ることです。

確定仕様から一意に判断できる軽微な不整合まで毎回人間へ戻していると、AIを利用していても人間側の確認作業は減りません。

一方で、新しいAPI、DB Schema変更、認証方式変更、主要な業務ルール変更までAIに独断で決めさせると、テストを通すために仕様そのものが変わる可能性があります。

そのため、

AIが判断できることはAIに任せ、設計判断が必要なところだけ人間へ戻す

という運用が、エージェントハーネスを利用するうえで重要になります。

第6回ではテスト工程そのものを理解し、今回の発展編では、その工程をどこまで自律化できるかを確認しました。

テストケース、確定仕様、AGENTS.md、テストデータの隔離方式、停止条件をそろえておくことで、Codexを単なるコード生成ツールではなく、決められた開発プロセスの中でテスト工程を継続するエージェントとして利用できるようになります。

本連載について

回	タイトル	対応範囲	主な内容
第1回	Docker × VS Code Dev ContainersでGo開発環境を構築する	🐳 Go開発環境	Docker Desktop・VS Code・Dev Containersを使ったGo開発環境の構築
第2回	React + TypeScript + Go + PostgreSQLのフルスタック開発環境を構築する	🛠️ フルスタック開発環境	Docker Desktop・Dev Containers・React・TypeScript・Go・PostgreSQL・Node.js・Vite
第3回	ChatGPT Workでショッピングサイトを設計してみる	📐 システム設計	Project instructions・要件定義・ユースケース・画面設計・ER図・DB設計・REST API設計・テストケース仕様書
第4回	Codex × AGENTS.md × Skillsで実装準備を整える	🤖 AI開発ルール	AGENTS.md・プロジェクトルール・階層化・Skills・実装準備
第5回	Codexで設計書からショッピングサイトを実装する	🛒 ショッピングサイト実装	設計書・AGENTS.md・Skillsを活用した段階的なAI開発・実装・検証
第6回	Codexで実装したショッピングサイトをテスト・動作確認する	🧪 テスト・動作確認	test-cases.md・ユニットテスト・結合テスト・API・ブラウザ・DBによる動作確認
発展編①	Codexのエージェントハーネスでテスト・デバッグ・再テストを自律化する	🤖 エージェントハーネス	AGENTS.md・確定仕様・テストケース・停止条件を利用したテスト・デバッグ・修正・再テスト・Regression Testの自律化
発展編②	Playwrightでブラウザテストを自動化する	🎭 E2Eテスト自動化	Playwright・E2Eテスト・ブラウザ操作・Auto-waiting・Trace Viewer・Seleniumとの違い・Codexとの連携

参考リンク