AI OpenHandsの使い方：セットアップ、プロンプト、実世界のワークフローの実践ガイド
優秀な開発者が24時間365日ペアプログラミングをしてくれることを願ったことがあるなら、AI OpenHandsはそれに非常に近い存在です。これは、リポジトリを読み込み、コードを書き、ターミナルを実行し、ドキュメントを参照し、反復処理を行うことができるオープンソースの「AIエンジニア」です。まるで、すぐに学習し、精力的に働くジュニア開発者のようです。しかし、その力を発揮するには、正しくセットアップし、操作方法を学ぶ必要があります。
このガイドでは、インストールから高度なワークフローまで、AI OpenHandsの使い方をステップバイステップで説明します。自信を持ってより迅速に開発を進めることができるようになります。
- OpenHandsをローカルまたはクラウドモデルで実行する
- プロンプト、リポジトリ、タスクに関するベストプラクティス
- 機能開発、デバッグ、テスト、ドキュメントに関する実績のあるワークフロー
注目すべき点：OpenHandsは、All Handsチームとコミュニティによって積極的に開発されています。公式ドキュメントは、最新の指示とヒントを得るための頼りになる情報源です。また、ローカルおよびVMのセットアップを文書化した実践者によるハンズオンインストールガイドも参照できます。ローカルモデルでの実行については、ドキュメントに具体的なガイダンスが含まれています。
AI OpenHandsとは—そして、なぜ使うのか？
AI OpenHandsを、キーボードを持つAIチームメイトと考えてください。チャットのみのアシスタントとは異なり、OpenHandsは次のことができます。
- ターミナルを使用してコマンド、テスト、リンターを実行する
そのため、機能の実装、バグの修正、テストの作成、ドキュメントの作成、リファクタリング、コードベースの最新化などのタスクに最適です。プロンプトをやりくりしたり、コピー/ペーストしたりする代わりに、OpenHandsに目標を与え、その動きを監督しながら反復させることができます。
クイックスタート：OpenHandsを最も早く使い始める方法
開始するにはいくつかの方法があります。どの方法を選ぶかは、クラウドLLMを使用するか、すべてをローカルで実行するかによって異なります。
オプションA：クラウドLLMを使用する（最も簡単）
- 公式の「Start Building」および「Getting Started」ドキュメントに従って、アプリをインストールして実行します。通常は次の手順を実行します。
- 前提条件（Docker、Node、Python、Git。パスによって異なる）をインストールする
- サポートされているクラウドモデル（例えば、OpenAI、Anthropic、またはプロジェクトがその時点でサポートしているその他のモデル）のAPIキーを提供する
- OpenHandsインターフェースを起動し、リポジトリを接続する
この方法では、最小限の計算オーバーヘッドで迅速に生産性を向上させることができます。
オプションB：ローカルLLMでOpenHandsを実行する
- コードとプロンプトをクラウドに置きたくない場合、またはAPIコストを避けたい場合は、公式ドキュメントのローカルLLMガイドを使用してください。
- 互換性のあるローカルモデルを設定する（Ollamaまたはその時点でサポートされているその他のバックエンド経由）
- モデルのエンドポイントとコンテキスト制限を構成する
- マシンに十分なVRAM/CPUとディスク容量があることを確認する
オプションC：VMにデプロイする
- 専用の環境が必要な場合、実践者はVM上でOpenHandsをスピンアップし、数分でアプリを構築する方法を文書化しています。これは、安定した共有AIエンジニアインスタンスを必要とするチームに役立ちます。
初回実行：プロジェクトのセットアップとタスクのフレーミング
OpenHandsは、コードを見ることができるときに威力を発揮します。まず、次のことを行います。
- プロジェクトを実行またはインデックス化して、OpenHandsが構造をマップできるようにする。
適切なタスクのフレーミングの例：
- "トークンベースのメールリンクを使用して、
authサービスにユーザーパスワードのリセットを追加します。既存のmailerモジュールを使用します。トークン生成と有効期限の単体テストを追加します。ユーザーデータスキーマを変更しないでください。"
これがうまくいく理由：
- コンポーネント、スコープ、依存関係、境界を指定しているためです。明確であればあるほど、OpenHandsはより適切に計画し、実行します。
OpenHandsのための効果的なプロンプトの書き方
プロンプトを簡潔なチケットと考えてください。最適なプロンプトは次のとおりです。
- ファイル、モジュール、またはテストを参照する：「
auth/routes.pyおよびtests/test_auth.pyを参照」
- 制約を記述する：「DBスキーマの変更なし。既存のインターフェースを維持」
- 受け入れ基準を含める：「テストは合格する必要があります：
pytest -k password_reset」
再利用できるテンプレート：
目標：<構築または修正したいもの>
コンテキスト：<関連ファイル、既知の制約、外部サービス>
受け入れ：<合格に見えるもの：テスト、エンドポイント、メトリック>
境界：<変更しないことまたは避けるべきアプローチ>
ツール：<実行できるコマンド、スクリプト、またはデータソース>
コアワークフロー：計画 → 実行 → 検証 → 改善
OpenHandsは通常、複数ステップの計画を提案します。それをガイドする方法は次のとおりです。
- 計画を早めに承認または調整します。最初にテストを実行して、ベースラインの失敗を把握するように指示します。
- 成功を定義するためにテストを作成または更新し、次にコードを実装するように依頼します。
- 行き詰まった場合は、ファイル名、スタックトレース、またはログなどのコンテキストを追加します。
プロのヒント：モノリシックな編集ではなく、PRサイズの小さな変更を推奨します。これにより、レビューとロールバックが容易になります。
コピーできるワークフローの例
1）機能の実装
- プロンプト：「
ordersページにCSVエクスポートを追加します。サーバー側のページネーションを使用し、text/csv経由で結果をストリーミングします。OrdersTable.jsxにExportボタンを追加し、routes/orders.tsにエンドポイントを追加します。ページネーションとヘッダーのテストを含めます。」
- 変更を監督、承認し、グリーンになったらマージします。
2）失敗したビルドのデバッグ
- プロンプト：「CIがNode 20で失敗しています。
build.mjsのESM/CJSインポートエラーを修正します。既存のrollupプラグインを保持します。CIに合格するように構成とコードを更新します。」
- ログを提供するか、CIアーティファクトへのリンクを提供します。
- OpenHandsにローカルで複製（
npm run build）し、最小限の差分を提案するように依頼します。
3）テストカバレッジと強化
- プロンプト：「
payments/service.pyのカバレッジを62％から85％以上に増やします。retry_charge、refund、webhook_signatureの単体テストを追加します。テストでバグが明らかにならない限り、ビジネスロジックを変更しないでください。」
- OpenHandsにテストを生成させ、実行し、改善させます。
4）ドキュメントと開発者エクスペリエンス
- プロンプト：このリポジトリの
CONTRIBUTING.mdとDEVELOPMENT.mdを作成します。環境のセットアップ、スクリプト、テストコマンド、PRガイドラインを含めます。
ガードレール：OpenHandsを役立ち、安全に保つ
- ディレクトリスコープ：他の場所での誤った編集を避けるために、特定のリポジトリまたはディレクトリを指定します。
- ファイル保護：構成ファイルまたは重要なインフラストラクチャを可能な限り読み取り専用としてマークします。
- コマンド監査：破壊的なコマンド（例えば、
rm -rf、データベースのリセット）の承認を要求します。
- シークレットの衛生：APIキーをプロンプトに貼り付けないでください。環境変数とマスクされたログを使用します。
- ネットワークアクセス：ブラウジングが有効になっている場合は、サンドボックス化し、アウトバウンドコールをログに記録します。
ローカルモデルとクラウドモデル：自分に合ったものを選択する
- 長所：強力な推論/コーディング、最小限のセットアップ、迅速な反復
- 短所：ハードウェアの需要、モデルの品質が異なる、より多くの調整が必要
モデルのバックエンドとメモリ制限を構成するには、公式のローカルLLMの説明を参照してください。
チームプレイ：コラボレーションフローでOpenHandsを使用する
- ブランチファーストのワークフロー：OpenHandsに機能ブランチを作成させ、PRレビューのために変更をプッシュさせます。
- コミットの衛生：明確なメッセージと参照Issue番号を使用して、アトミックコミットを生成するように依頼します。
- PRテンプレート：レビュー担当者が何が変更されたか、なぜ変更されたかを把握できるように、PRテンプレートを生成して適用します。
- コードオーナー：CODEOWNERSと組み合わせて、AIが生成したPRを適切なレビュー担当者にルーティングします。
一般的な問題のトラブルシューティング
- 行き詰まったり、ループしたりする場合：スコープを絞り込みます。次のステップを説明するように依頼します。失敗するテストを提供します。
- 乱雑な差分：より小さく、段階的な計画—最初にテスト、次に最小限のコード変更を要求します。
- 間違ったファイルの編集：正確なパスを指定し、境界を思い出させます。
- ローカルでは合格するが、CIで失敗する：CI環境の詳細とログを共有します。コンテナで複製させます。
パフォーマンスのヒントとパワーの活用
- ウォームスタートコンテキスト：最初にキーファイル（
README、package.json、メインサービスファイル）を読ませます。
- スクリプトを提供する：
make testまたはnpm run verifyを提供して、迅速に検証できるようにします。
- ドメインを教える：短いアーキテクチャの概要を説明します。ロジックエラーが少なくなるため、効果があります。
- スタイルを適用する：
.eslintrc、.prettierrc、black/ruff構成を指摘して、正しくフォーマットするようにします。
- チェックポイントを使用する：各マイルストーンの後、概要と次のステップを依頼して、軌道に乗せておきます。
実世界のシナリオ：バグレポートから1時間でパッチを当てる
- 状況：本番環境のバグにより、
orders APIの不正なJSONペイロードで未処理の500が発生します。
- プロンプト：「
orders POSTの不正なJSONで500を再現します。スキーマ検証を追加し、エラーの詳細とともに400を返します。不正なペイロードをカバーするようにテストを更新します。」
節約された時間：OpenHandsがスキャフォールディングを処理している間、影響分析とロールアウトに集中しました。
OpenHandsをスーパーチャージする統合
- テストランナー：pytest、Jest、Vitest、JUnit
- ビルドツール：Vite、Webpack、Rollup、Babel
- パッケージマネージャー：npm、pnpm、yarn、pip/poetry
- リンター/フォーマッター：ESLint、Prettier、black、ruff
- コンテナ：CIとのローカルパリティのためのDocker Compose
これらのツールを標準化することにより、OpenHandsはスタックについてより確実に推論し、開発ループの自動化を強化できます。
ところで：OpenHandsと並行してSider.AIを使用する
関連性スコア：8/10。OpenHandsをAIエンジニアとして使用している場合は、仕様、PRの説明、ドキュメントの作成に役立つ調査および起草コパイロットと組み合わせる価値があります。ところで、Sider.AIは、技術仕様を迅速に作成したり、RFCを要約したり、OpenHandsの実行ログをクリーンな変更ログとリリースノートに変換したりするのに役立ちます。この組み合わせにより、コンテキストスイッチングが削減されます。OpenHandsはコードアクションを処理し、Sider.AIは結果をクリーンなユーザー向けのドキュメントに変換します。
セキュリティ、プライバシー、コンプライアンスのチェックリスト
- シークレットをenv変数に保持します。プロンプトにキーを埋め込まないでください
- ジュニア開発者のPRと同様に、AIが生成したすべての変更を確認します
- 監査のためにコマンドとアクションをログに記録します
- ツールチェーンのバージョンを固定します。ロックファイルでの誤ったアップグレードを避けます
- クラウドLLMを使用している場合は、データ保持ポリシーに合わせます
OpenHandsを使用すべきでない場合
- 強力なテストまたは仕様のスキャフォールディングがない斬新なアルゴリズム設計
- 堅牢なレビュープロセスがない高度に規制されたコードベース
- 手動コーディングの方が高速な1回限りの使い捨てスクリプト
OpenHandsでの最初の60分：ミニプレイブック
- 0〜10分：公式のクイックスタートを使用してインストールして起動します
- 10〜20分：リポジトリを接続します。プロジェクト構造をマッピングするように依頼します
- 20〜35分：小さくてテスト可能な目標を定義します。計画を承認します
- 35〜50分：実装してテストを実行させます。必要に応じて促します
- 50〜60分：差分を確認し、改善し、機能ブランチにマージします
キーリンクと次のステップ
- OpenHandsの公式「Start Building」および使用ドキュメント：ヒント、クイックスタート、およびベストプラクティス。
- ローカルLLMセットアップガイド：OpenHandsを完全にマシン上で構成して実行します。
- VMでのコミュニティ主導のインストールチュートリアル：実際的なインストールの手順と簡単なデモプロジェクト。
重要なポイント
- 明確な受け入れ基準を持つチケットのようにタスクを構築します。
- イテレーションを小さく保ちます。テストを早期かつ頻繁に行います。
- ガードレールを使用し、変更を確認します—ジュニアチームメイトのように扱います。
- 利便性のためにクラウドを選択し、プライバシーのためにローカルモデルを選択します。
- ドキュメントツール（例えば、Sider.AI）と組み合わせて、仕様とリリースノートを加速します。
よくある質問
Q1:AI OpenHandsをインストールしてすぐに使い始めるにはどうすればよいですか？
公式のクイックスタートを使用して、前提条件をインストールし、サポートされているLLM（クラウドまたはローカル）を接続し、UIを起動してリポジトリを接続します。「Start Building」ドキュメントには、セットアップのヒントを含むステップバイステップの手順が記載されています。
Q2:クラウドモデルの代わりにローカルLLMでOpenHandsを実行できますか？
はい。ローカルLLMガイドに従って、ローカルモデルバックエンドを構成し、コンテキスト設定を調整します。これは、プライバシーを重視するプロジェクトやAPIコストの回避に最適です。
Q3:コーディングタスクのためにOpenHandsにプロンプトを出す最適な方法は何ですか？
簡潔なチケットのようにプロンプトを記述します：目標を定義し、特定のファイルを参照し、境界を設定し、受け入れ基準を含めます。進捗状況を検証するために、テストを作成または実行するように依頼します。
Q4:AI OpenHandsは本番環境コードで使用しても安全ですか？
ジュニア開発者のように扱います：ブランチ保護、コードレビュー、およびCIを使用して変更を検証します。コマンドのガードレールを追加し、プロンプトからシークレットを排除します。
Q5:OpenHandsは従来のコードアシスタントとどのように比較されますか？
チャットのみのツールとは異なり、OpenHandsはコマンドを実行し、ファイルを編集し、リポジトリ内で自律的に反復処理できます。機能、デバッグ、テストなどのエンドツーエンドのタスク用に構築されています。
