🤖

1人OSS開発を『詰ませない』ためのAIエージェント設計 - wandas 開発の実践例

に公開

はじめに

こんにちは。普段は会社勤めをしながら、3歳の子どもを育てる父親として、限られた空き時間をやり繰りしてOSS開発をしています。

家族が寝静まった後の短い時間でプロジェクトを前に進めるため、1年前からGitHub Copilotを頼れる「共同開発者」としてフル活用してきました。

しかし、AIエージェントにタスクを丸投げしようとすると、生成されたコードがメンテ不可になったり、コンテキストを無視したコードを生成されたり、関係ないファイルを壊されたりと、かえってレビュー・修正に時間を奪われて、燃え尽きて開発をやめそうになることが多々ありました。

今回は、私が音データ処理ライブラリ「wandas」開発でたどり着いた、1人OSS開発を『詰ませない』ためのAIエージェント設計をご紹介します。

単にデフォルトの Agent モードを使うだけでなく、wandas 開発のために設定した「プロジェクト専用のエージェント」と「AI が働きやすいコード設計」に焦点を当てます。

リポジトリ: https://github.com/kasahart/wandas

なぜ AI エージェント開発を選んだのか

1人OSS 開発において、以下のような課題を感じていました。

  • レビューリソースの不足: メンテナーが 1 人なので、PR を精査する負担が大きく、客観的なレビューもしづらい。
  • 一貫性の維持: コントリビューター(自分と AI)のコードスタイルがばらつく。
  • ドキュメントの遅れ: 実装は進んでも、ドキュメントが追いつかない。

Copilot Agent の登場により、これらの課題に「自動化」というアプローチで向き合いやすくなりました。ただし、そのまま使うだけでは思ったほど安定しない場面もありました。そこで、プロジェクト固有のワークフローに合わせて、エージェントへの指示とリポジトリ構造の両方を整えることを意識しました。

プロジェクト専用 AI エージェントの設計思想

役割分離アプローチ

色々とドキュメントを参照した結果、万能な 1 つの AI に全てを任せるのではなく、役割を分けた 4 つの専用エージェントを定義しています(GitHub Copilot の .github/agents/ を利用しています)。

.github/agents/
├── wandas-planner.agent.md      # 要件分析・影響範囲マッピング
├── wandas-implementer.agent.md  # コード実装
├── wandas-reviewer.agent.md     # コードレビュー
└── wandas-publisher.agent.md    # Git 操作・PR 作成

1 つのエージェントが全てを担当すると、「設計」と「実装」のコンテキストが混在し、不要なファイル編集を試みるといった問題が起きやすくなります。そこで、役割ごとに「できること」と「できないこと」を明確にしました。

エージェント 主要ツール 禁止事項 制限の理由
planner 検索, TODO作成 ファイル編集 未検証の設計混入を防ぐ
implementer ファイル編集, テスト実行 planner の指示から逸脱 スコープ肥大化を防ぐ
reviewer 検索, テスト実行 直接のコード修正 レビューの客観性を保つ
publisher Git コマンド コード変更 誤コミットを防ぐ

Handoff による文脈の引き継ぎ

また、役割を分けると、「エージェント間の引き継ぎ漏れ」という別の課題が生まれます。これを防ぐため、Handoffs(引き継ぎ)で次に呼ぶべきエージェントとプロンプトを定義しています。

---
name: wandas-planner
description: Read-only planner for Wandas; maps requirements to frames, processing, and IO modules.
argument-hint: Describe the feature/bug and paste any relevant issue links.
tools: ['search', 'todo', 'search/usages', 'execute/testFailure', 'web/fetch']
handoffs:
  - label: Start Implementation
    agent: wandas-implementer
    prompt: Use the requirements, impact analysis, and risks above to implement the change.
    send: false # 次のエージェントに自動で引き継ぐ場合は true にする
---

指示システムの階層化

すべてのルールを 1 つのプロンプトに書くと、AI が重要な情報を見落としたり、トークン効率が悪化したりします。そこで、指示を 3 層に分け、段階的に読み込ませる仕組みを採用しました。

  • Level 1: プロジェクト全体の方針(常に参照)
  • Level 2: 役割特化型エージェント定義(エージェント起動時に参照)
  • Level 3: ドメイン特化型プロンプト(タスクに応じて必要時に参照)

これにより、AI の認知負荷を下げやすくなるだけでなく、「フレーム設計のルールを変えたいときは Level 3 のファイルだけ直す」といった人間側のメンテナンス性も上げやすくなりました。

AI エージェントがミスを犯しにくいコード設計

不変性(Immutability)の強制

前回の記事でも触れた通り、wandas は元のデータを変更せず、操作のたびに新しいオブジェクトを返します。

  • AI の推論負荷
    可変設計では「このメソッド呼び出しで他に何が変わるか?」を追跡する必要があります。一方で wandas の不変設計では、「新しいオブジェクトを生成して返す」という定型処理を理解すれば十分です。

  • デバッグ
    可変設計では、どの時点で状態が変わったかを追跡しにくくなります。対して不変設計では、各ステップで新しいオブジェクトが生成されるため、追跡しやすくなります。

不変設計により、AI は「複雑な副作用の推論」から解放されます。新しいメソッドを追加する際も、決まった手続きに沿って実装しやすくなり、安全に変更を進めやすくなります。

フレームと計算ロジックの分離

状態管理やメソッドチェーンを担うフレーム(ChannelFrame など)と、実際の信号処理ロジックを明確に分離しています。

これにより、AI は「メタデータの更新」といった複雑なコンテキストをいったん脇に置き、「入力配列を受け取って、出力配列を返す」という計算ロジックの実装と、そのユニットテストの作成に集中しやすくなります。結果として、AI がプロジェクトのルールから逸脱したコードを書く頻度は減ったように感じています。

自動テストと静的解析を AI の「ガードレール」にする

AI が生成したコードを人間がすべて手動でチェックするのは非現実的です。wandas では、implementer エージェントに pytest(テスト)、mypy(型チェック)、ruff(lint / format)を実行する権限を与え、これらがすべて通るまで自律的にコードを修正させるループを構築しています。

特に mypy による厳格な型チェックは、AI のハルシネーション(もっともらしい誤り)や辻褄の合わない引数渡しを早い段階で検知できる、有効なガードレールになっています。

エージェントが迷わずこの自律修正ループを回せるよう、テストやエラーの設計にも一工夫入れています。

エラーハンドリングの一貫性

AI が生成するエラーメッセージの形式を「WHAT / WHY / HOW」パターンに統一しています。

# copilot-instructions.md の指示例
raise ValueError(
    f"Sampling rate mismatch (WHAT).\n"
    f"Filters require matching rates to prevent phase distortion (WHY).\n"
    f"Resample inputs to the same rate before filtering (HOW)."
)

テストでは、メッセージの先頭行(WHAT)のみをマッチさせるようにしています。これにより、AI が WHY や HOW の文章を自律的に改善しても、テストが壊れて修正ループが回るのを防げます。

実行コマンドの記録

implementer エージェントには、実装時に実行したすべてのコマンドを記録させています。

実行ログの例は以下の通りです。

  1. uv run pytest tests/test_filters.py -v — 既存テストの確認
  2. uv run ruff format wandas/processing/filters.py — フォーマット適用
  3. uv run mypy wandas/processing/filters.py — 型チェック

レビューヤー(人間)は、この Command Log を見ることで「どの品質チェックを通過したか」を確認しやすくなり、負担の軽減につながります。

まとめ

これらの設計を取り入れた結果、エージェントが自律的に修正ループを回し、品質を担保しながら開発を進めやすくなりました。PoC(概念実証)で終わらせず、長期的にメンテナンスしていくライブラリにおいて AI 駆動開発をうまく回すには、「AI の性能」はもちろんですが、「プロジェクトに合わせたカスタマイズ」と「AI が働きやすい土台作り」も重要だと感じています。

ただ、ひと通りの土台ができてくると、今度は別の問題にも直面しました。ローカル環境のエディタ上で AI と対話を繰り返していると、Copilot の高機能モデルを使える「プレミアムリクエスト枠」があっという間に枯渇してしまうのです。実際、私は壁打ちを何度も AI と続けた結果、わずか 1 週間で 1 か月分の枠を使い切り、開発のモチベーションが下がってしまいました(気が付かないうちにClaude Opusを使っていたのも原因の一端ですが...)。

この失敗から、ローカルでのチャット型開発には構造的な限界があると痛感しました。GitHub Copilot Pro+は個人開発としては少々高価です。そこで辿り着いたのが、ローカルでの対話を減らし、クラウド上のエージェントにタスクを大きく移譲して「並行開発」するスタイルです。

次回は、wandas 開発におけるクラウド上のエージェントを活用した並行開発について書けたらと思います。

ご支援

リポジトリ を Star していただけると大変励みになります!
また、フィードバックやコントリビューションも歓迎しています。お気軽に Issue を立ててください。

Discussion