本投稿は、2026年5月2日にダバコ団ダオラボバイブコーディングギルドで「ハーネスエンジニアリング」に関する事例紹介として発表された内容です。
Nextainは、SW製品を持つ企業のAXに関する技術を開発・支援する企業で、韓国の教会ポータルであるOnmam.comのシステム運用を移管され、AXに関する作業を進めています。 以前のIDCセンターにあったレガシーシステムの移行を進め、プロジェクトをエージェントベースの開発および運用が可能な環境設定を行い、安定化および機能改善作業を進めています。 古いレガシーシステムであるため試行錯誤があり、これをnaia-business-adkをOnmam.comに適用することで、企業の経験と技術として具現化しています。 この経験として、ハーネスエンジニアリングを説明する事例としてイベントで共有しました。
この記事のワンポイントメッセージ 「AIをうまく使うことよりも、AIがミスをしない環境を作ることの方が重要だ。」
1. まず、私たちのサービス紹介
Onmam.com — 全国13,876の教会が利用する教会管理プラットフォーム
www.onmam.com ← 教会検索、会員ポータル
home.onmam.com ← チャネルアプリ（コンテンツ/決済）
{教会名}.onmam.com ← 個別教会ホームページ
インフラ: 旧型IDCサーバー → 2026年4月 GCP(Google Cloud)への完全移行完了 DB: 13,876の教会データ × Cloud SQL
2. ある出来事から始めましょう
「2026年4月のある日」
午前11時。突然、Onmam.comの全サービスが無応答に。
ユーザーたち: 「サイトが使えないのですが？」
原因を追跡したところ — Board.phpというファイルの掲示板リスト照会コード。
-- 問題となったクエリ（簡略化）
SELECT * FROM boards
JOIN (
SELECT bbs_id, COUNT(*) FROM all_boards GROUP BY bbs_id -- ← これが問題
) AS summary ON boards.id = summary.bbs_id
WHERE church_id = ?
このクエリ一つが、13,876の教会全体のデータを毎回フルスキャンしていた。 トラフィックが集中すると、600～800秒かかるクエリが145個同時実行 → サーバーが完全に麻痺。
これがAIとどう関係するのか？
このコードを最初に作成したのは、おそらく人間の開発者だった。 しかし今日、開発者たちはこのようなコードをAIと共に作成する。
問題は — AIは「このコードが13,876の教会環境でどのように動作するか」を知らないということだ。 AIは要求された機能を実装することに集中し、私たちのサービスの文脈は知らない。
そこで開発者たちが悩み始めたこと: 「AIが私たちのサービスを知らないままコードを作成するのをどう防ぐか？」
3. ハーネスエンジニアリング — 30秒解説
馬を扱う際に手綱と馬具（Harness）が必要なように、
AIエージェントにも制約・ガイド・検証装置が必要だ。
エージェント = モデル + ハーネス
ハーネス = AIが働く環境全体を設計すること
単に「AIに良い質問をする」ことではない。 AIがミスをしたときに、構造的に同じミスをできないようにするシステム設計。
4. Onmam.comで実際に構築されたハーネス
[ハーネス #1] AGENTS.md — AIに与える「私たちのサービスマップ」
alpha-adk/
├── CLAUDE.md ← AIがセッション開始時に必ず読むファイル
├── AGENTS.md ← プロジェクトルールリスト
└── .agents/
└── context/
└── agents-rules.json ← 具体的運用ルール
AIがOnmam.comのコードに触れる前に、必ずこれらのファイルを読み込む。 ここには、このような内容が含まれている:
- 「テストとコード修正はalpha環境でのみ行う」
- 「home.onmam.comはportalではなく別途のchannelアプリである」
- 「Board.phpでのGROUP BY派生テーブルパターンは絶対禁止」
先ほどの障害？今やAIは同じパターンを作成しようとすると、このルールを見て停止する。
[ハーネス #2] Hooks — AIの行動前後に作動する「安全装置」
現在、このワークスペースで実際に動作中のフック:
AIがBashコマンドを実行する直前 →
✓ pr-guard.js : レビューなしのPRマージをブロック
✓ commit-guard.js : ルール違反のコミットをブロック
✓ deploy-guard.js : 運用サーバーへのデプロイを承認なしでブロック
✓ git-push-guard.js : 承認なしのgit pushをブロック
✓ destructive-git-guard.js : git reset --hardなどの破壊的コマンドをブロック
AIがファイルを修正する直前 →
✓ prod-gateway-guard.js : 運用APIキーをdev環境ファイルに書き込むのをブロック
✓ design-doc-guard.js : 設計文書の無断修正をブロック
AIがファイルを修正した直後 →
✓ cascade-check.js : 修正されたファイルに連鎖的に影響を受けるファイルを確認
deploy-guard.js 実際の動作例:
AIが運用デプロイコマンドを実行しようとした場合:
$ gcloud run deploy onmam-web ...
→ [Harness] prodデプロイコマンドをブロック: gcloud run deploy
プロジェクト: onmam-web
prodデプロイには事前の承認が必要です。
承認方法: .claude/deploy/approvals.jsonに承認項目を追加
AIはprodデプロイを直接実行しません。
AIが誤って、あるいはあまりにも積極的に運用サーバーに何かをアップロードしようとしても、物理的にブロックされる。
[ハーネス #3] Alpha環境 — AIが実験する専用の遊び場
運用(Production) : www.onmam.com ← 実際の教会が使用
ステージング(Staging) : staging.onmampick.org ← デプロイ前の最終確認
アルファ(Alpha) : luke-*-alpha.onmampick.org ← AIと共に作業する空間
ルール: AIと共に行うすべての作業はalphaでのみ。
なぜこれが重要なのか — 2026年4月29日に実際に起こったこと:
AIが
home.onmam.comをportalアプリと勘違いし、誤ったvhost設定を作成。 alpha環境であったため → 実際のサービスへの影響なし。 このミスをAGENTS.mdに記録 → AIが同じミスを繰り返さない。
ハーネスの本質がここにある: ミスが発生すれば → ハーネスに記録 → 次回からはそのミスが構造的に不可能になる。
[ハーネス #4] Skills — AIに与える「私たち専用のツール」
skills/
├── email/ ← メール送信（受信者、SMTPルールを含む）
├── sms/ ← SMS送信
├── web-monitoring/ ← サービス状態モニタリング
└── service-management/ ← サービス運用コマンド
AIが「メールを送って」と言うと — このスキルファイルを読み込み、誰に、どのような形式で、どのSMTPで送るべきかを自動的に知る。 毎回「受信者のメールアドレスは何？」と尋ねる必要がない。
5. 開発者たちがこれに注目する理由
「AIなしで開発していた時代の問題」
開発者個人の能力に依存 → シニアが抜けると品質が低下
コードレビューで修正する必要がある → 人が直接確認する必要がある
「AIはあるがハーネスがないチームの問題」
AIが高速にコードを生成するが → 私たちのサービスの文脈を知らない
同じミスを繰り返す → バグはAIが作り、人が修正する
AIが運用サーバーに直接アクセス可能 → いつ事故が起こるか分からない
「AI + ハーネスがあるチーム」
AIが私たちのルールを知ってコードを作成 → コンテキストのある生成
ミス発生時にハーネスに記録 → 同じミスの構造的防止
運用アクセスは人が承認 → 安全な自律性
Tossの表現を借りるなら:
「ハーネスで組織全体の生産性の底上げを図る。 個人の能力に依存せず、すべてのチームメンバーが一定レベル以上の結果を出す。」
6. まとめ — 非開発者に伝えたいこと
AI時代において、「うまくやる」の定義が変わりつつあります。
以前: コードをうまく書く開発者 現在: AIがコードを作成する環境をうまく設計する開発者
その環境設計の核心がハーネスエンジニアリングです。
そして、これは開発者だけの話ではありません。
非開発者でもできるハーネス:
→ 業務ルールを文書で明確に記述すること
→ AIに「これはしても良い、これはしてはいけない」を定義すること
→ AIがミスをしたときに「なぜミスをしたのか」を記録すること
= これ自体がハーネスエンジニアリングの始まり
Onmam.comハーネス構造の概要
alpha-adk/
├── CLAUDE.md ← [Guide] AIセッション開始時に必須で読み込む
├── AGENTS.md ← [Guide] プロジェクトルール (SoT)
├── .agents/context/
│ └── agents-rules.json ← [Guide] 具体的運用ルール
├── .claude/
│ ├── hooks/
│ │ ├── deploy-guard.js ← [Sensor] 運用デプロイをブロック
│ │ ├── prod-gateway-guard.js← [Sensor] 運用APIキーをブロック
│ │ ├── commit-guard.js ← [Sensor] コミットルール検証
│ │ ├── pr-guard.js ← [Sensor] PR承認を強制
│ │ ├── session-inject.js ← [Sensor] 各セッションにコンテキストを注入
│ │ └── cascade-check.js ← [Sensor] 修正後の連鎖的影響を確認
│ └── settings.json ← [Permission] フック実行設定
├── skills/
│ ├── email/ ← [Tool] メール送信スキル
│ ├── web-monitoring/ ← [Tool] サービスモニタリング
│ └── service-management/ ← [Tool] サービス運用コマンド
└── data-private/memory/ ← [Feedback Loop] ミス記録 → 再発防止
├── project_onmam_incidents.md ← Board.php障害パターン記録
├── project_onmam_app_structure.md← home≠portalミス記録
└── feedback_alpha_only.md ← alpha専用ルール記録
ハーネス = これらのファイルの集合 すべてgitリポジトリにコミットされる。チームのすべてのコンテキスト！がコードとして蓄積される。
