こんにちは！Yappli の iOS グループでテックリードをしている三宅 (@tsushi130) です。
iOS チームでは日々 AI を活用した開発を行っています。
一方で AI の進化は非常に速く、新しくリリースされる機能のキャッチアップや活用度合いにはメンバーごとの差も生まれやすくなっています。結果として、AI を活用したアウトプットの質やスピードも個人の習熟度に依存しやすく、チーム全体としての再現性をどう高めるかが iOS グループとして重要なテーマになってきました。
Yappli では AI の活用を個人の工夫に閉じず、チームとして底上げしていくための環境整備を進めています。
本記事では、Yappli のアプリプラットフォーム開発を支えるために取り組んでいる Harness Engineering について紹介します。
Harness Engineering とは
Harness Engineering とは、「AI エージェントが継続的に安定したアウトプットを出せるように実行環境そのものを設計すること」と捉えています。
AI 活用初期では Prompt Engineering が中心的なテーマとして議論されてきました。これはモデルに対して「どう指示するか」を工夫する考え方です。
しかし、AI エージェントにある程度まとまったタスクを依頼するようになると、プロンプトそのものだけではなく、「どんな情報」を「いつ」「どれだけ」「どの順序」で見せるかという Context Engineering が重要になってきます。
更にボリュームのあるタスクになってくるとコンテキストの設計だけでも足りず、途中の進捗を記録することで Session を跨いで状態を引き継いだり、一連の手順をワークフロー化するなど、継続して作業できる土台が必要になります。
また重要なのは、AI を活用して得られるアウトプットの質はモデル単体で決まるのではなく、進捗を引き継ぐ仕組みやツール、ドキュメント、計画、テスト、レビュー、権限管理まで含めた実行環境全体で左右される点であり、Harness Engineering では、こうした実行環境全体を harness として捉え設計します。
全体像
Yappli では AI に単に実装を任せるのではなく、計画・実装・評価を分離したワークフローとして構成しています。所々省略していますが、全体像は次の通りです。
大きくは Planner / Generator / Evaluator の三層構成です。 Planner が仕様やデザインをもとに実装計画を整理し、Generator がその計画に沿って実装を進め、Evaluator が成果物を評価します。各層では必要に応じて Skill や Sub-Agent を呼び出し、計画 → 実装 → ビルド → レビュー → 評価 までを段階的に進めます。
計画と評価の基準を先に評価者と擦り合わせることで、期待値のズレが少ないアウトプットを継続的に得ることを目指しています。
開発イテレーションの言語化
まずは Yappli における開発イテレーションの言語化を行いました。
人間が普段どういう手順で開発を進めているのかを整理し、それを AI が辿れるワークフローとして分解しました。
仕様・デザインを確認してタスクを整理する
実際には、プロジェクトへのアサイン後に技術調査や見積もりを経て仕様・デザインが固まっていきます。その上で、必要に応じてコードを調査しながらタスクの分解や最終的な振る舞いを整理します。Swift 製のビルドツール (toolchain) をビルドする
Yappli はアプリプラットフォームであり、1 つのコードベースから 900 以上のアプリを生成しています。アプリごとに異なる構成や依存関係を解決するため、toolchain を使ってビルドを行っています。アプリ全体をビルドする
ビルドした toolchain を実行すると、対象アプリの CMS 設定に応じてプロジェクトファイルやPackage.swiftが適切にアップデートされます。
アップデートされたプロジェクトファイルをもとにアプリ全体のビルドを行い、実装前にクリーンな状態へセットアップします。コードを実装する
ビルドが完了したら実装へ移ります。オプション機能なのかアプリ全体に関わる変更なのかによって、新規モジュールを切るべきかどうかの判断も変わります。API 連携が必要な場合には、モックサーバーを使って疎通確認を行うこともあります。ビルドとテストを実行する
実装後は必要に応じてコードを整理し、Unit テストや Snapshot テストを実行します。問題があれば修正し、再度確認します。期待通り動作するか確認する
Simulator や必要に応じて実機を使って確認します。Yappli では CMS で機能を有効化し、細かいパラメータを切り替えながら複数パターンを検証する必要があります。UI や動作の多くが動的な変数で決まることがあるため、この確認コストは特に高くなりやすいポイントです。commit する
ビルド → テスト → 動作確認まで完了したら commit し、次のタスクに進みます。
このイテレーションを前提に、AI がどこまで自律的に進められるか、どこで評価や制約を挟むべきかを設計していきました。
Claude Code の機能を活用したワークフローの構築
開発イテレーションを言語化できたので、ステップごとに Claude Code の機能を活用しながらワークフローを構築しました。
全ては紹介しきれないですが、以下は実際に活用している Skill / Sub-Agent の抜粋です。
※ 🤖・・・Sub-Agent、🧠・・・知識の Skill、📝・・・ワークフローの Skill を示しています
Sub-Agents
🤖 nocode-app-engineer
ノーコードアプリプラットフォームを開発・運用する汎用エンジニアです。
Sub-Agent の skills frontmatter field に後述の nocode-app-engineering の Skill を指定してコンテキストを注入しています。各 Skill の agent frontmatter field に指定したり、実装や修正の task prompt を渡すことでノーコードアプリプラットフォームのエンジニアとしてタスクを遂行してもらっています。
https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields
🤖 build-verifier
アプリをビルド及びエラーの修復を行う時に利用する Sub-Agent です。
Sub-Agent で実行することで、ログによってメインコンテキストが汚れないようにしています。
またビルドに関連する仕組みのひとつとして、Yappli では動作確認のサイクルを早くするために Hot Reload の仕組みを導入しています。この差分ビルドの仕組みをうまく有効活用できないか検討も進めたいです。
Skills
🧠 nocode-app-engineering
一般的なアプリ開発と異なる点や避けるべき設計、特有の思考や持つべき問いを記述し、AI っぽい無難な実装ではなく Yappli の iOS エンジニアとしてアウトプットを出すための専門知識としての Skill です。
この Skill では、方向性や設計観点を記述することでベクトルを揃えつつ、具体的な手順は縛らないようにして、Yappli の iOS 開発に必要な専門性を前提に自走できるような自由度のレベルで設計しています。
Skill の設計にあたっては、Anthropic の Skill authoring best practices で紹介されているコアコンセプトを踏まえて実装を行いました。
Skill authoring best practices - Claude API Docs
📝 planning
開発イテレーションの 1 に該当するステップを行うためのワークフローとしての Skill です。仕様書やデザインを与えながら AskUserQuestion ツールを通してヒアリングを行い、それらの情報をもとに 🤖 × 3 の Sub-Agent ( planner / analyst / readteam ) が Teammate として連携して実装計画書をまとめます。
必要なタスクは features.json に書き出し、各タスクは完了に応じて passes を true に更新します。
Markdown ではなく JSON で管理しているのは、長めの作業を AI に扱わせるときに、構造化された形式のほうが安定して更新しやすいためです。
この設計は、Anthropic の Effective Harness に関するブログで紹介されていた feature list の考え方を参考にしています。
After some experimentation, we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files.
📝 worker
planning で作成した実装計画をもとに、実際の開発イテレーションを回していく Skill です。開発イテレーションの 3 ~ 7 を繰り返し実行し、完了したタスクから features.json の passes を更新して次へ進んでいきます。
ワークフローで行われる各ステップは Sub-Agent や Skill として再利用できるように実装されており、以下のフローで実行されます。
prebuilder → nocode-app-engineer (実装) → refining-code → build-verifier → test-verifier → evaluator → committing
🧠 building-app
Booted を優先的に使う destination 生成スクリプトや、Unit テストのビルド時に only-testing を使って必要なテストだけを実行する仕組みなど、特に時間がかかりやすいビルドを最適化するための知識としての Skill です。
📝 refining-code
code-reviewer によるコードレビューを行ったり、/simplify を活用しながら冗長さや複雑さを落として実装を整えたりする Skill です。
📝 mock-server
与えられた proto ファイルやその URL をもとに、必要なエンドポイントを動的に構築し、message に沿った stub response をコンテキストを踏まえて自動生成した上で、の mock-server という Swift 製のツールを起動します。
新設 API や API 変更時の検証で活用しており、AI が実装だけでなく確認まで進めやすくするための重要な土台になっています。
ドキュメントや Rules 整備
glob パターンで表現できるものは Rules、それ以外は docs/ 配下に段階開示できるよう構造化して管理しています。 基本的には機能単位でマルチモジュール化されているため、Rules はモジュール単位で定義を行います。記述する内容としては、コードベースから読み解けない仕様や、AI のアウトプットからよく逸れる観点をコンテキストに補完できるように記述します。
コンテキストウィンドウは共有財産でもあるため、Rules や docs の書き方次第では異なるエントリーポイントから注入されたコンテキスト同士が競合することもあります。そのため Context Engineering の観点でも注意が必要です。
計画しているものの、Rules の整備は現時点でそこまで進んでいないため、引き続き拡充していきたいです。
今後の展望
チーム全体への導入は行っていないものの検討や検証中の仕組みもあり、有効性が示すことができれば既存のフローに組み込んでいきたいと考えています。
例えば、lint error をエージェントが理解しやすい形でコンテキスト注入する仕組みの検証や、Yappli においてコストの高い動作確認を自動テストする方法の検討を行っています。
モデルの性能が高くなることで相対的に harness の強度は下がっていく可能性もありますが、周辺ツールを活用した確率的ではない自動化の価値は引き続き高いと考えています。
iOS の AI 活用の取り組みを Android でも来期以降足並み揃えて取り組んでいく予定です。
また余談ですが、plugin として配布することで context: fork や agent の frontmatter field がうまく動作せず、結果としてコンテキストがそのまま inline 展開されてしまい、コンテキストウィンドウの独立性と設計のトレードオフが発生してしまうことから、現時点では plugin では運用していないです。
同じ事象に関連する Issue が立っているようなので、引き続きウォッチしながら plugin 対応を進めていく予定です。
https://github.com/anthropics/claude-code/issues/16803
終わりに
Harness Engineering において、チームの開発プロセスそのものを再現可能な形に落とし込み、それを支える仕組みとして実行環境全体を設計していきました。
本稿がチームで Harness Engineering を進める際のヒントとして少しでも参考になれば幸いです。
Yappli のサービスやシステムなどにご興味をお持ちの方はカジュアル面談も行っていますのでぜひお越しください！
