Claude Code氏によるAIファースト統合エンジニアリング：実践的なデバッグセッション

「AIがコードを書いた」という話のほとんどは、きれいなプロンプトときれいな結果を示すデモです。しかし、これは違います。これは、実際のAPIANT統合製品を使った実際のセッションであり、実際のプロンプト、誤った方向転換、修正、そして人間の記憶が機械を凌駕した瞬間までを網羅しています。

重要なのは、AIが素晴らしいということではありません。重要なのは、実際に腰を据えて作業に取り組んだときに、コラボレーションがどのような形になるかということです。

セットアップ

この製品は、当社のCRMConnect統合製品の一つです。 MindbodyからHubSpotへある顧客から、複数の支払い方法で支払われた売上が正しく同期されていないとの報告がありました。8,400ドルの売上を3つの支払い方法で分割した場合、HubSpot上では400ドルの単一の取引として表示され、残りの8,000ドルはパイプラインから消えていました。

エンジニアリング作業はGitHub Issuesで管理しています。顧客とのやり取りはHubSpot Service Hubで記録されます。セッションは、開発者がAIに作業内容を伝えることから始まりました。

プロンプト： 「支払い問題を見てください」

AIはリポジトリのGitHubイシューを検索し、未解決のインシデントを見つけ、全文を読み上げて、マルチペイメント販売のバグであり、証拠として2つの本番実行IDが挙げられていることを伝えた。手取り足取りの説明は一切不要だった。そして、推測するのではなく、分かりやすい言葉で次のステップを尋ねた。

プロンプト： 「そのロジックは何をするのか、そしてどの自動化／アクションを実行するのか？」

AIはプラットフォームから関連する自動化処理を読み込み、その構造を段階的に実行して、失敗の原因を正確に説明しました。この自動化処理は、HubSpotの各取引ごとに重複排除キーを作成します。複数支払い方式の売上の場合、Mindbodyは支払い方法ごとに1行を返し、すべて同じキーを共有するため、2行目と3行目が1行目で作成された取引と競合し、それらの金額は黙って削除されました。

役に立つ情報だ。しかし、建設業者の方が既に優位に立っていた。

すべてを方向転換させたヒント

プロンプト： 「この取引固有の識別子を、crmconnect-mindbody-zohoプロジェクトで私たちが採用している方法と比較してください。あのプロジェクトでは解決済みだと思っていたのですが。徹底的に比較してください。」

このたった一文が、作品の様相を一変させた。設計者は解決策を説明するのではなく、関連製品を指さし、「それを読んでください」と事実上言ったのだ。

そこでAIは、 MindbodyからZohoへ 統合機能は、完全に独立した製品として、過去の売上を処理する自動化機能を特定し、それを読み込みました。次に、支払い記録を書き込むサブルーチンを見つけて読み込みました。要約ではなく、実際の自動化ロジックを段階的に読み込みました。

結果は、焦点を絞った比較だった。Zohoとの連携によって確かにこの問題は解決されていたが、アーキテクチャが異なっていた。

• HubSpotの製品は、Mindbodyの旧型の販売エンドポイントを使用して、販売明細ごとに1つの固定取引を作成します。このエンドポイントは、分割済みの支払い行を返します。
• Zoho製品は、親となる購入記録に加えて、明細項目と支払いに関する個別の子記録を作成します。この際、Mindbodyの新しいエンドポイントを使用し、各支払いには固有の実際の支払いIDが付与されます。

AIの分析によると、Zohoの方がアーキテクチャ的に洗練されており、当初は3つのオブジェクトからなるモデル全体をHubSpotに移植することを提案した。

建設業者は範囲を縮小する

人間が物事を地に足の着いた状態に保っていたのは、まさにこの場所だった。

プロンプト： 「まだV4.0の準備が整っていません。後回しにして、今は顧客から報告された取引情報の欠落に関する問題を修正する必要があります。」

AIは満足のいくアーキテクチャの書き換えへと向かっていた。しかし、開発者は問題を本質的な問題に絞り込んだ。顧客が必要としているのは新しいデータモデルではなく、正確な取引金額である。AIはこれに同意し、書き換え案を将来の課題としてクローズし、既存の取引自動化機能に対する的確な修正に焦点を絞った。

その訂正は重要です。AIは洗練された一般的な解決策を見つけるのが得意ですが、その洗練された解決策が状況にそぐわないかどうかを判断するのが得意とは限りません。この開発者は、その判断をたった一文で示しました。

AIは、Zohoの設計原理をそのまま踏襲しつつも、その構造を模倣することなく、販売明細ごとに1件の取引を処理し、Mindbodyのより豊富なエンドポイントからデータを取得し、最初の支払いが残りの支払いを上書きしないように、複数の支払い方法にわたって金額を正しく集計するという仕組みを採用した。プラットフォームは違えど、実行方法は異なり、根底にある考え方は同じだ。

予感

重複排除キーを再設計する際、AIはその構成要素の一つである日付に着目しました。その判断は明確でした。販売IDと販売明細IDによって既にキーは一意に構成されているため、日付は不要です。そこで、キーを簡素化し、2つの自動化処理間の脆弱性を排除するために、日付を削除することを推奨しました。

建築業者は反論するための建築基準書を持っていなかった。彼には記憶があった。

プロンプト： 「確か、日付を追加したのは必要だったからだと思う（同じ取引で2回支払いがあったとか、何か変なことがあったとか）？」

どちらも現在の自動化システムからはそれを証明できなかった。そこでAIは自動化システムのバージョン履歴を調べた。自動化システムには2021年まで遡る93のバージョンが保存されていた。AIは関連する変更内容が見つかるまで、変更内容の説明を読み込んだ。

2022年1月から：

「同じ商品に対して複数回の支払いが行われた場合でも一意性を保つため、取引IDをデータベースに保存する際にEPOCH MILLISを追加しました」

2022年2月より：

「カスタム物件による取引検索に販売日を追加し、過去の販売に関する支払いを処理できるようにしました」

建設業者自身の言葉によれば、それは4年前のことだった。顧客が以前の販売に対して後日支払いを行うと、Mindbodyはその販売を新しい日付で再発行する。キーに日付が含まれていないと、後日の支払いは元の取引と競合し、独自の記録を取得できない。日付は冗長なものではなく、分割払いと自動支払いを処理するために意図的に追加された、重要な情報だった。

AIは即座に推奨を撤回し、その旨をはっきりと伝えた。

「その記憶を信じてください。意図的に日付を追加したのなら、それは重要なデータなので、削除することはできません。バージョン履歴で確認しました。」

さらに、事態は進展しました。日付は変更できないため、2つの自動化処理では全く同じ日付値を生成する必要がありました。そうでなければキーが一致せず、重複した取引が発生してしまうからです。元の自動化処理は、特定のMindbodyフィールドから日付を生成していました。AIは、新しい自動化処理が、同じAPI呼び出し、同じタイムゾーン変換を使用して、その同一のフィールドを読み取るように再設定しました。入力も出力も同じで、キーの一致が保証されます。

分割払い処理をひっそりと破綻させる可能性があった回帰バグは、結局発生しなかった。AIが慎重だったからではなく、人間が直感を覚えていて、AIがそれを4年分の履歴と照らし合わせて数秒で検証できたからだ。

地味な部分：構築、実行、トレースの読み取り、修正

設計が確定すると、反復的なエンジニアリングへと移行した。開発環境で変更をビルドし、実行し、実行トレースを読み取り、次の問題を見つけ、修正し、再実行する。実際のバグはごくありふれたものだった。

• 取引成立のステップは16件で失敗に終わった。 PROPERTY_DOESNT_EXIST フィールドバインディングにHubSpotの内部プロパティ名が使用されていなかったため、エラーが発生しました。AIはトレースを読み取り、コネクタのフィールドスキーマを取得し、すべてのフィールドを正しいIDで再バインドしました。
• プラットフォームがソースデータ内の最長の配列に基づいて反復回数をカウントしていたため、本来1回で済むはずのループが2回実行されていました。支払い配列は明細項目配列よりも長かったためです。AIは明示的な反復制御を挿入し、ループが明細項目のみをカウントするようにしました。
• 「取引を探す」ステップでは、取引がまだ存在しない場合、デフォルトのエラーモードで「見つかりません」を致命的なエラーとして扱うため、処理全体が停止してしまいます。AIはエラー発生時に処理を続行するモードに変更し、作成ブランチが実行できるようにしました。これは、既に兄弟プロセスで同様の処理が行われていた方法と一致しています。

どれも華やかなものではありません。これこそが、統合作業の実際の姿です。変わったのは、ループの速度です。AIはステップごとの実行トレース全体を読み取り、失敗しているステップを即座に特定できるため、修正サイクルは数分で完了します。開発テストに合格するまで、顧客には何も出荷されません。

これは建設業者にとって何を意味するのか

物語的な要素を取り除いて、実際に機能するモデルを以下に示します。

• AIの強みは読解力だ。 同社は兄弟システム全体の統合を調査し、既に解決済みの問題を相互参照し、2つの異なるプラットフォーム間でアーキテクチャを適応させ、90バージョンもの履歴を掘り下げて1つの設計上の決定を検証した。人間が半日でこれをこなせるはずがない。
• 人間の強みは記憶力と判断力である。 「あれを追加したのには理由があると思う」という記述はどのファイルにも見当たらない。「まだV4.0に対応できていない」という記述もどのファイルにも見当たらない。どちらも製品を実際に使ってみた経験から生まれたものだ。そして、それぞれが結果を変えた。
• スピードはループから生まれる。 トレースを読み取り、ステップを修正し、再実行する。通常デバッグを遅らせる、何が起こったのかを再構築する手間がなくなる。

AIファーストの統合エンジニアリングとは、AIが単独で作業することでも、人間が作業速度を上げることでもありません。人間には時間がないような情報の読み取りをAIが行い、コードベースに記録されていないコンテキストを人間が補うというものです。これらを組み合わせることで、4年間も再発していたバグを、たった1回の作業セッションで理解、修正、検証することが可能になります。

それこそが、目指すべきワークフローだ。