こんにちは。Ubie の syucream です。最近は組織開発とか生成AI社内活用とかやってます。
前回の記事では、Claude Code と n8n を使って「自然言語でワークフローを自動生成する」体験を紹介しました。
今回は、あの華やかなデモの裏側の話となります。AIに「ワークフロー作って」と頼めばシュッとできる。それは事実。でも、その AI が Slack に100回投稿したり、他のエージェントの作業を消し去ったり、本番のワークフローを壊してしまう──そういうことも普通に起きます。
これに対して自分がこの数ヶ月やっていたのは、振り返ってみるとまさに「ハーネスエンジニアリング」だったなと。AI エージェントが安全に、かつ効果的に開発できる環境を地道に作り続ける作業。今回はその実践を、具体と抽象の両面から紹介します。
ハーネスエンジニアリングとは
AI エージェント（Claude Code 等）が安全かつ効果的に開発できるように、プロンプト・ツール・ガードレールを体系的に設計・改善していく取り組みと言えるでしょう。
Ubie において n8n のバイブコーディングでこれが特に重要になるのは、以下の3つの理由があります。
- n8n の専門知識を持たないメンバーでも vibe coding でワークフローを作りたい
- n8n ワークフローファイルは独自の構造を持ち、AI が正しく生成するにはドメイン知識が必要
- 大量のワークフローを管理しており、誤った apply（デプロイ）は本番に直接影響する
つまり「誰でも使える」ようにしたいけど、「誰がやっても壊れない」ようにもしたい。この二律背反をエンジニアリングで解く、というのが今回のハーネスエンジニアリングの活動の本質です。特に、「エンジニアではない同僚でも効率的に開発できるように」意識する必要があるのはユニークではないでしょうか。
転落したから柵を作った
抽象的な話はここまでにして、まずは実際に起きた「事故」の話をさせてください。ハーネスエンジニアリングがなぜ必要なのか、一番わかりやすいのは現実世界の課題から眺めることでしょう。
事故1: git restore で他のエージェントの作業が消えた
ある AI エージェントが自分の変更を戻そうとして git restore を実行しました。ところが同じブランチで別の AI エージェントが作業中で、未コミットだった5ファイルの変更も一緒に消えてしまいます。未コミットだから復元もできない。
AI は「自分の変更」と「他のエージェントの変更」を区別できません。複数エージェントが協調作業する環境では、破壊的操作に対する明示的な手順が必要だと痛感しました。
事故2: apply したらワークフローが4件重複した
新規ワークフローをローカルで作って仮 ID で apply した。n8n のサーバーは別の ID を割り当てたのですが、ローカルの ID がリモートと不一致のまま再度 apply してしまい、毎回「新規」として4件重複作成。
n8n の ID 採番はサーバー側で行われる。こういうドメイン固有の仕様を AI は知らない。だから明示的に教える必要があるのです。
事故3: アイテムが爆発して224件がAPIに流れ込んだ
これは「n8nのワークフロー開発」でよくある問題ではないでしょうか。あるとき Code ノード（return [{json: ...}] で常に1件返す）を Set ノードに置き換えました。ところが Set は入力アイテムごとに実行される仕様なので、224件がそのまま下流の Notion API に流れ込み、結果として大量のノイズとなるページが作成されてしまいました。
ルールで「注意してね」と書くだけでは防げない。ツールで自動検出できる仕組みが必要です。
事故4: Claude が本番のワークフローを壊した
これは直近の話。AI エージェントがワークフローの修正中に、意図せず他のワークフローにまで影響を及ぼしてしまいました。
CLAUDE.md に「ディレクトリ全体への apply は禁止」と書いてあはありました。でも AI は従わないケースも多々あります。なんなら、 AI を使用する人間が「やっていい」と言ってしまうと例外的に実行してしまうケースもあります。
「お願い」しても無駄なんだと、身をもって学びました。 だったら物理的に止めるしかないわけです。
三階建てのアーキテクチャ
こうした痛い経験を経て、ハーネスは三階建ての構造に進化しました。
| 層 | 強制力 | 役割 | 更新頻度 |
|---|---|---|---|
| Hook | 最強（物理的に止める） | 危険な操作の阻止 | 低（安定後は変更少） |
| **CLAUDE.md・Skills** | 弱（お願い・ガイド） | ドメイン知識・規約 | 高（日常的に追記） |
| n8n-cli | 基盤 | 全操作の土台 | 中（機能追加時） |
Hook──最後の砦
Claude Code の PreToolUse イベントを傍受し、危険なコマンドを実行前にブロックする仕組み。地味なシェルスクリプトだが、こういう愚直なガードレールが転落防止になります。
CLAUDE.md + Skills──ドメイン知識の体系化
CLAUDE.md（約48KB）は AI エージェントへの行動規約。Skills は必要な時に必要な詳細知識をロードする仕組み。現在はワークフロー設計パターン9種、ノードスキーマ25種などを格納しています。
n8n-cli──AI と人間の橋渡し
ワークフローは「人間にはグラフに見える」が「AI にはテキストの羅列に見える」。それゆえ、人間だったら気づけるような誤りにも AI は気づきにくい可能性があります。この認知のギャップを埋めるCLIツール（OSS: ubie-oss/n8n-cli）。lint（11ルール）、trace、apply（dry-run対応）、test などを備えました。
Slack を毎日3回検索する──フィードバックループ
自分がやっていたのは、非常に原始的に「n8n」って Slack 検索する、ということ。1日に3回ぐらいやっていました。
「本当の課題」は「悩んでいる瞬間」を捉えないと観測できない。だからこそ、Slack でのボヤきを拾うのが一番のパスです。ヒアリングをしに行ってももちろん良いです、それはそれで実行すべきだとは思うのですが、「ペインを抱えたその瞬間」を捉えることができるならその価値は絶大であり、また情報収集もしやすいです。
誰かの困りごとが、将来の誰かの作業を効率的・安全にできる。みんなが Claude Code で武装しているからこそ、この理屈がまかり通ります。
おわりに: ハーネスは組織で育つ
前回「技術を組織にインストールする設計が、組織を変える」ことについて触れました。今回はそのインストールを支える舞台装置の話です。ハーネスは組織で運用しているからこそ育つ。誰かの失敗が全員の安全を底上げする。
これは n8n のワークフロー開発を社内で民主化するというお話でしたが、エッセンスは異なるあなたのプロジェクトでも転用できる部分があると思います。
- Step 1: CLAUDE.md から始める（背景「なぜ」を必ず書く）
- Step 2: ハマりポイントを収集して蓄積する
- Step 3: Skills でドメイン知識を構造化する
- Step 4: Hook で最後の砦を作る
徐々に改善する舞台装置が、この時代であれば構築しやすくなっています。
最後にではありますが、 Ubie ではこうした社内の業務生産性を AI を使って向上させるエンジニアを正社員とインターンで募集しております。ご興味ある方はぜひ、まずはカジュアルにお話させていただければ幸いです！
Discussion