01
ENGINEERING NOTE
- AI駆動開発
- ハーネスエンジニアリング
AIを使うから実装を任せるへ：FooQoo流ハーネスエンジニアリングの考え方
この記事が参考になったら
はてなブックマークに追加してもらえるとうれしいです。
はてなブックマークに追加現在の章01AIを「使う」から実装を「任せる」へ
01
ENGINEERING NOTE
この記事が参考になったら
はてなブックマークに追加してもらえるとうれしいです。
現在の章01AIを「使う」から実装を「任せる」へ
AIを使っているのに、気づけば実装やバグ修正のことばかり考えていませんか。作りたいもののイメージがあっても、コードを動かすことに意識を取られると、そのイメージを具体化する時間が後回しになります。
この問題を防ぐために、AIに個々の作業を頼むだけでなく、実装工程を任せる進め方を考えました。そうすることで、作り手は「何を作るか」「どこまで作るか」「できあがったものはイメージ通りか」という判断に集中できます。
実際にこのテックブログを作るときも、実装やバグ修正に追われて、作りたいものを考える時間がなくなることは避けたいと考えていました。私が時間を使いたかったのは、機能の優先度や画面の雰囲気を決め、このブログをどんなものにするかを詰めることです。
そのために取り入れたのが、ハーネスエンジニアリングの考え方です。この記事では、このブログの開発を例に、AIが参照する仕様、実装結果を確かめる仕組み、人が判断する境界をどう整えたかを紹介します。
実装を任せるには、AIが何を目指して作業し、どの結果を見て修正し、どこで人の判断を求めるかが明確になっている必要があります。毎回こちらが次の作業を指示していると、実装の進行を自分で追い続けることになります。
ハーネスエンジニアリングは、AIが作業できる環境、参照する情報、検証とフィードバックの仕組みを設計する考え方です。OpenAIの実践でも、意図を明文化し、エージェントが自分で結果を確かめられる環境を整えることが重視されています。
私はこの考え方を、AIが仕様を参照して実装と検証を繰り返し、判断が必要な問題を人に戻せる状態を作ることとして捉えました。このブログで整えたものは、大きく3つあります。
図1は、そのつながりを表したものです。計画で決めたデザインモック、設計文書・実装範囲、受け入れ条件を渡し、AIが実装します。実行結果を確かめ、失敗したら修正します。仕様やデザインの変更が必要になったときは、人が判断して計画を見直します。
図1：仕様をもとに実装し、検証結果をAIの次の作業に返します。仕様やデザインの変更は人が判断します。
仕様を渡すところから、実装中の修正、完成の判断までをつなげておく。この流れを用意することで、実装工程を任せやすくなると考えています。
開発を始める時点で、作りたいものの完成像がはっきりしているとは限りません。私はAIとの対話を通じてイメージを具体化し、採用するものを自分で決めました。その判断を、実装中にも参照できる形にしておきます。
このテックブログの開発で最初にAIと議論した問いは、「今回の作業の目的は何か」でした。今回は、読者が記事を選んで読み、書き手についても知れることを中心に置きました。
ホーム画面は記事一覧を兼ね、記事の詳細ページでは本文と目次を読めるようにします。一方、最初に用意できる記事の数は少ないため、サイト内検索やタグによる絞り込み、人気記事などの機能は見送りました。実際にAIから検索機能を提案されましたが、一覧から選ぶ体験を整えるほうが先だと判断しました。
今回作らない機能も明らかにすると、AIが実装中に機能を広げることを防ぎやすくなります。目的と範囲を一緒に渡しておけば、途中で新しい案が出ても、今回の実装に含めるべきかを確かめる基準になります。
次に必要だったのは、「読みやすいブログ」のような言葉を、画面として判断できる形にすることでした。Codexの画像生成機能で複数のデザイン案を出してもらい、明るい技術誌のような雰囲気、左に記事・右にプロフィールを置く構成、文字の余白感など、気に入った要素を選びました。
選んだ方向性は、デザインツール上でホーム、記事詳細、目次、404画面などの具体的なデザインにします。デザインツールは「Pen」を採用しました。
Pen：AIエージェントと一緒に画面の配置や文言を編集できるデザインツール。作った画面は
.penファイルとしてリポジトリに保存できます。テックブログの開発では、画像案から選んだ方向性をPenで具体化し、実装が守る見た目の基準にしました。
AIが生成した画像は雰囲気を探る助けになりますが、文字の大きさや行間まで判断しきれません。実際に使う書体やスタイルで再現し、画面の配置と文言も含めて、実装が参照する仕様にします。 こうすることでデザインツールが画面仕様のハーネスとして機能します。「読みやすいと思うか」という判断に加えて、決めた文字サイズや配置になっているかを具体的に検証できるようになります。
図2：Penで具体化したホーム画面。記事一覧とプロフィールの配置、文字の余白感を実装時の基準にしました。
画面の見た目に加えて、データや公開の条件も決めます。このブログでは記事をMDXファイルで管理し、タイトル、URLに使うslug、公開日、下書きかどうかなどを記事ごとに持たせました。公開記事はビルド時にページを事前生成し、下書きは開発中だけ確認できるようにします。存在しないURLには404を返します。
これらを設計文書に記し、完成時に確かめる内容を受け入れ条件にしました。例えば「公開記事を選ぶと詳細へ進める」「開発中は下書きを確認できるが、本番の成果物には含めない」といった条件です。画面だけでは伝わらない振る舞いも、実装前に明らかにしておきます。
AIには実装方法を考える余地を残しながら、守るべき画面と動作、完成の判定基準を渡します。途中で迷ったときに参照できる仕様があれば、その都度こちらが意図を説明し直す負担を減らせます。受け入れ条件は、そのまま次に説明する検証の出発点にもなります。
対話で決めたことは、デザインや設計文書としてAIがたどれるフォルダ(./docs等)に残します。画面の見た目はデザイン(Pen)、データや公開の条件は設計文書(ARCHITECTURE.md)、完成の判定は受け入れ条件(PLANS.md)というように、確かめたい内容と参照先を対応させます。作業を分けて任せるときにも、共通の基準を見ながら進められます。
仕様を用意したら、実装結果がそれに沿っているかを確かめる手段も揃えます。AIがテストやビルドを実行し、結果を読んで次の修正に進めるようにすることが、実装を任せるうえで重要だと考えています。
実装にはTDD（Test-Driven Development）を採用しました。期待する動作をテストで先に表し、失敗を確認してから実装し、テストが通るところまで進める方法です。受け入れ条件をもとにテストを用意すると、AIが実装中に確かめる対象が具体的になります。
さらにE2Eテストを導入し、実際のブラウザでホームから記事を開き、目次で章へ移動する、といった読者の操作を通して確かめます。下書きが開発環境だけで見えることや、存在しない記事が404になることも確認対象にしました。
静的解析やビルドチェックも組み合わせます。個々の処理が期待通りでも、ページ全体を生成したときに問題が出る可能性はあります。動作、コードの整合性、公開する成果物をそれぞれ確かめられるようにしておきます。
このブログの開発では、独立して実装・検証できる単位に作業を分けました。記事データを扱う基盤、共通UI、ホーム・記事一覧、記事詳細・目次などです。各作業で何を完成させるかを絞ると、AIに渡す範囲と検証する対象も明確になります。
作業は依存関係に沿って進め、並列に進められるものはまとめて実装しました。図3のように、記事データや共通UIの基盤を作り、それを使う画面を揃えてから、全体を検証する流れです。
図3：作業を独立して検証できる単位に分け、依存関係に沿って進めます。各段階で統合し、機能同士のつながりも確認します。
各段階の統合時には、結合試験として専用スクリプトを用意し、機能同士がつながるかを一度に確認しました。例えば、記事データがホームに表示されることや、ホームから詳細へ進めることです。作業単位のテストに加えて、組み合わせた状態でも条件を満たすかを確かめます。最終段階ではE2Eテストとデザインツールとの画面照合も行いました。
例えば、記事データの処理が単独で動いても、ホーム画面が期待する情報を受け取れなければ、記事一覧は完成しません。分けた作業の受け渡しまで確かめることで、個々の作業の完了と、読者が使える状態になったことを結びつけます。統合時の検証も、任せる作業の一部として用意しておきます。
チェックが失敗したら、その結果をAIの次の作業に返します。AIは失敗した項目と実行結果を読み、仕様を参照して原因を調べ、修正後にもう一度検証します。結果を見ながらこの流れを繰り返せるようにすることで、こちらが一つずつ修正手順を指示する必要を減らせます。
ここで受け入れ条件が、修正の方向を確かめる基準になります。例えば本番に下書きが含まれた場合は、公開対象を選ぶ処理や成果物を調べ、決めた条件を満たすように修正します。テストを通すために公開条件そのものを変えてしまうと、作りたかったものから外れてしまいます。
また、テストで確認できるのは、そこに表した条件です。テストが通っていても確認項目に抜けがあれば、その部分の正しさは分かりません。何を確かめる必要があるかを受け入れ条件と照らし合わせ、実際の操作や画面照合も組み合わせます。
こうして、AIの完了報告に実行結果が伴う流れを作ります。実装、検証、修正をつなげておくことで、開発者も何が確かめられたのかを見て、次の判断に進めます。
実装中に問題が出るたびに人が確認していては、作り手が進行を追い続けることになります。そこで、仕様を変えずに直せる問題はAIが調査・修正し、結果を報告するようにします。例えば、決めた表示条件を満たしていない処理や、機能同士をつないだときに生じる不具合は、その範囲で解消してもらいます。
一方、機能の範囲、デザインモック、受け入れ条件を変える必要が出たら、作業を止めて人が判断します。こうした変更は、何を作るかという判断に関わるためです。実装を進める都合で機能を増減させたり、完成の条件を緩めたりする前に、作り手へ戻す境界を設けます。
例えば、目次を押しても該当する章へ移動しないなら、決めた動作を実現するための修正です。目次そのものを省く、表示する項目を変えるといった案が出たら、読者に届ける体験に関わるため、自分で採否を決めます。問題の大きさだけでなく、仕様を変えるかどうかで判断を分けます。
判断を変えるときには、どの仕様を満たせないのか、なぜ変更が必要なのか、どんな選択肢があるのかが分かると、自分も判断しやすくなります。変更を決めたら、参照する仕様と受け入れ条件も揃え直してから実装を続けます。再開後のAIが、変更後の基準で作業できる状態にするためです。
完成時にも、作り手の判断が必要です。テストやビルドは、決めた動作や公開条件を確かめる助けになります。その上で最後に確かめたいのは、計画で具体化したイメージと、読者が触れる画面が合っているかです。
このブログでは、記事を選び、読み進め、書き手を知る流れを自分で操作し、文字の読みやすさや余白の印象も見ます。仕様通りにできていても、触ってみて初めて気づくことがあります。そこで変えたいと思ったことは、次に作るものとして判断し直します。
AIが進められる範囲と、人が判断する範囲を明確にしておく。実装を任せるためには、その両方を用意しておくことが大切だと考えています。
今回は、このテックブログの開発を例に、FooQoo流のハーネスエンジニアリングの考え方を紹介しました。AIが参照する仕様と作業範囲を揃え、検証結果をAIにフィードバックし、何を作るかに関わる判断は人が確認する。そのつながりを整えることで、実装工程を任せやすくなります。
私が目指すのは、何を作るかを自分で決め、実装をAIに任せ、できあがったものを自分で判断する進め方です。ハーネスを整えることは、作りたいものを考える時間を確保することにつながります。実装やバグ修正に追われていると感じたときは、AIが参照する仕様と、結果を確かめる仕組みから見直してみてはいかがでしょうか。