ハーネスエンジニアリング実践編 r001 ― Docker Composeで開発・検証基盤を整える
はじめに
前回の記事「ハーネスエンジニアリングとループエンジニアリングを整理する」では、AIが働く環境と、作業を繰り返して改善する仕組みを整理しました。
今回はその続きとして、実際にハーネスを作ります。最初からAIエージェントにソースコードを自動修正させるのではなく、まず「どこを読んで、何を実行し、何をもって合格と判断するか」を明文化します。この部分が曖昧なままループを組むと、同じ失敗を繰り返しても気づきにくくなります。
今回作るのは、Docker Composeで動く、小さな開発・検証環境です。Pythonの雨量集計処理を題材にして、Ruffによる静的検査、pytestによる検証、実行結果のJSON保存までを実装します。外部AI APIは使用しません。次回、エージェントを接続するための下地を整えることが目的です。
1. 今回の到達点
- 開発手順を
AGENTS.mdに整理します。 - 仕様と受入条件は
docs/に分けます。 - Docker Composeで再現可能な実行環境を作ります。
- テストの成功・失敗・タイムアウトを機械的に判定します。
- 終了コードとログを実行ごとのJSONに保存します。
- GitHub Actionsから同じ検証を呼び出せるようにします。
この段階では「自動修正」「モデルによる判断」「複数回の試行」はまだ実装しません。ハーネスの確認を先に行います。
2. ハーネスの構成
図1は今回の全体像です。ハーネスを単なるDocker環境として考えるのではなく、作業に必要な情報、実行手順、検証、ログ、権限制約の組み合わせとして扱います。
| 要素 | ファイル | 役割 |
|---|---|---|
| 作業規約 | AGENTS.md |
AIに最初に確認してほしい資料と禁止事項 |
| 仕様 | docs/requirements.md |
入力と出力の要件 |
| 受入基準 | docs/acceptance_criteria.md |
何をもって完了とするか |
| 実装 | src/sample_app/ |
検証対象となる雨量集計処理 |
| 制御 | src/harness/runner.py |
各検証ゲートの実行と結果保存 |
| テスト | tests/ |
正常系と異常系を検証 |
| 証跡 | results/run_*.json |
検証の履歴 |
2.1 AGENTS.mdは案内図として使う
作業ルールを大量に記述すると、肝心な情報が見つかりにくくなります。AGENTS.md は短く保ち、仕様、構成、受入条件への入口にします。
今回の例では、変更前に仕様を読むこと、テストを無断で弱めないこと、未検証の変更を合格と報告しないことを明示しています。これは、人間とAIが同じ完了条件を共有するためです。
3. Docker Composeで検証環境を作る
本サンプルは単一サービス harness で動作します。最初の段階からDB、メッセージキュー、Web UIまで追加すると、ハーネス自体の確認が難しくなるためです。
Docker Composeの設定は次のとおりです。
services:
harness:
build:
context: .
dockerfile: Dockerfile
working_dir: /workspace
volumes:
- ./:/workspace
environment:
PYTHONPATH: /workspace/src
PYTHONDONTWRITEBYTECODE: '1'
init: true
network_mode: none
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=64m
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
user: '${LOCAL_UID:-1000}:${LOCAL_GID:-1000}'
command: ["python", "-m", "harness.runner"]
コンテナのネットワークを無効にし、root以外のユーザーで実行しています。ただし、作業ディレクトリは書き込み可能なバインドマウントです。信頼できないコードを完全に隔離する仕組みではありません。AIに実際の変更を許可する段階では、さらに専用の作業領域や承認手順が必要です。
4. 実行手順
参考のために、ZIPファイルを置いておきますので、ダウンロードして活用してください。
ZIPを展開したら、LinuxまたはWSL2上で次のように実行します。
cd harness_engineering_r001
bash scripts/verify.sh
PowerShellでは次のコマンドを使えます。
docker compose run --build --rm harness
初回のDockerイメージ構築ではPythonパッケージを取得するためのネットワーク接続が必要です。一方、完成したコンテナの検証実行はネットワーク接続なしで行います。
ハーネスは ruff check src tests と pytest -q tests を順に実行します。どちらかが失敗すれば、総合判定も不合格です。
5. テストの対象を小さく決める
サンプルアプリは、1時間雨量を日別に合計する処理です。
from sample_app.rainfall import aggregate_daily
rows = [
{"timestamp": "2026-11-01T01:00:00", "mm": 1.0},
{"timestamp": "2026-11-01T02:00:00", "mm": 2.0},
]
print(aggregate_daily(rows))
# {'2026-11-01': 3.0}
正常系だけでなく、負の雨量、NaN、無限大、不正な日時も検査します。さらにハーネス自身について、テスト用コマンドが異常終了した場合やタイムアウトした場合に、合格と誤判定しないか確認します。
単なる文字列比較だけでなく、どの検証手順が実際に実行されたかを記録することが重要です。エージェントを接続する際も、最終回答だけではなく、途中のツール実行や検証の成否を評価する必要があります。
6. 実行結果を残す
実行すると results/run_<実行ID>.json が生成されます。記録するのは、実行ID、UTC日時、検証名、コマンド、終了コード、標準出力、標準エラー、所要時間、合否です。
次はJSONの構造を説明するための例です。実行IDや時間は実際の結果によって変わります。
{
"schema_version": 1,
"run_id": "example123456",
"timestamp_utc": "2026-11-11T00:00:00+00:00",
"gates": [
{"name": "lint", "passed": true, "exit_code": 0},
{"name": "unit_and_acceptance", "passed": true, "exit_code": 0}
],
"passed": true
}
実際のJSONには上記以外にもコマンド、標準出力、標準エラー、実行時間を保存します。
重要なのは、失敗したときに「どのゲートで、なぜ失敗したか」を調べられることです。将来ループを追加した場合、この証跡を次の修正判断に利用できます。
7. CIにも同じ検証を組み込む
.github/workflows/verify.yml を用意しました。GitHub ActionsではDocker Composeを実行し、結果のJSONをArtifactとして保存します。ローカルとCIで異なる検証コマンドを使わないようにします。
検証の結果だけでなく、実行した証拠を残すことが目的です。ただし、検証の成功はソフトウェア全体の正しさを保証しません。今回設定した受入条件を満たした、という範囲の判定です。
8. 次のr002で何を追加するか
今回のr001は、固定された検証手順を繰り返し実行できる段階です。次回は次のように拡張します。
その際は、変更可能なファイルの範囲、最大試行回数、時間・費用の上限、外部アクセスの可否を決めます。検証結果を渡すだけではなく、改善前後で退行していないかを判断する仕組みも必要になります。
9. まとめ
ハーネスの整備は、難しいAIモデルを選ぶことから始める必要はありません。まずは仕様を読めること、同じ環境で動くこと、テストが失敗したら確実に停止すること、結果をあとから確認できることを整えます。
今回の実装は小規模ですが、Python以外の言語でも基本的な考え方は同じです。たとえばFortranでは、コンパイル、単体テスト、基準計算との数値比較、水収支確認などを検証ゲートとして登録できます。ここまで整えておけば、次の段階でAIエージェントを接続しても、作業の合否を一定の基準で判断しやすくなります。



