2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

ハーネスエンジニアリング実践編 r001 ― Docker Composeで開発・検証基盤を整える

2
Posted at

ハーネスエンジニアリング実践編 r001 ― Docker Composeで開発・検証基盤を整える

はじめに

前回の記事「ハーネスエンジニアリングとループエンジニアリングを整理する」では、AIが働く環境と、作業を繰り返して改善する仕組みを整理しました。

今回はその続きとして、実際にハーネスを作ります。最初からAIエージェントにソースコードを自動修正させるのではなく、まず「どこを読んで、何を実行し、何をもって合格と判断するか」を明文化します。この部分が曖昧なままループを組むと、同じ失敗を繰り返しても気づきにくくなります。

今回作るのは、Docker Composeで動く、小さな開発・検証環境です。Pythonの雨量集計処理を題材にして、Ruffによる静的検査、pytestによる検証、実行結果のJSON保存までを実装します。外部AI APIは使用しません。次回、エージェントを接続するための下地を整えることが目的です。

1. 今回の到達点

  • 開発手順を AGENTS.md に整理します。
  • 仕様と受入条件は docs/ に分けます。
  • Docker Composeで再現可能な実行環境を作ります。
  • テストの成功・失敗・タイムアウトを機械的に判定します。
  • 終了コードとログを実行ごとのJSONに保存します。
  • GitHub Actionsから同じ検証を呼び出せるようにします。

この段階では「自動修正」「モデルによる判断」「複数回の試行」はまだ実装しません。ハーネスの確認を先に行います。

2. ハーネスの構成

図1 ハーネスの構成

図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で検証環境を作る

図2 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. 実行結果を残す

図3 検証と改善の流れ

実行すると 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は、固定された検証手順を繰り返し実行できる段階です。次回は次のように拡張します。

図4 nest step

その際は、変更可能なファイルの範囲、最大試行回数、時間・費用の上限、外部アクセスの可否を決めます。検証結果を渡すだけではなく、改善前後で退行していないかを判断する仕組みも必要になります。

9. まとめ

ハーネスの整備は、難しいAIモデルを選ぶことから始める必要はありません。まずは仕様を読めること、同じ環境で動くこと、テストが失敗したら確実に停止すること、結果をあとから確認できることを整えます。

今回の実装は小規模ですが、Python以外の言語でも基本的な考え方は同じです。たとえばFortranでは、コンパイル、単体テスト、基準計算との数値比較、水収支確認などを検証ゲートとして登録できます。ここまで整えておけば、次の段階でAIエージェントを接続しても、作業の合否を一定の基準で判断しやすくなります。

参考リンク集

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?