非エンジニアがAIエージェントに個人開発を任せてみた実測記録

「非エンジニア aiエージェント」で検索する人は、実際にAIエージェントへ個人開発を任せるとどこまで進み、どこで人手が要るのかを知りたいはずだ。この記事では、筆者(非エンジニア)が自社の動画制作パイプライン用に組んだツール群を例に、AIエージェントに任せた部分と、任せなかった・任せられなかった部分を、起きた事実ベースで書く。

3行まとめ

1. 台本の検証やYouTube統計取得を行う約650行のPythonツール（MCPサーバーとしてClaude Codeから呼び出す）を、AIエージェントに実装させて作った。ツール自体は動いている
2. 並列で複数のAIエージェントに作業を分担させると、構造化データを返すはずのエージェントが「何も返さずに終わる」失敗が起きた。役割ごとにエージェントの種類を分けたら解消した
3. 30分かかる動画書き出し処理を自律的なエージェントに監視させると、処理の途中で「監視中です」と報告したまま作業を終えてしまうことがあった。今はエージェントではなく、タイムアウト付きの1本のスクリプトとして実行している

作ったもの: 台本を検証するMCPツール

自社では、AIナレーションで動画を作るパイプラインを運用している。この中で実際に事故が起きたのが、動画で紹介する価格や数値を、調べ直さずに記憶のまま書いて公開してしまったケースだった。この失敗の後、台本のテキストから数値表現を正規表現で抜き出し、「出典を確認したか」を機械的に思い出させるチェック機能を作った。今は次のような検証を、Claude Codeからツール呼び出しの形で実行できる。

• 台本の各スライドの文字数が既定の範囲に収まっているか
• ナレーションの語尾ルールに違反していないか
• 「◯%」「◯倍」「◯人」のような数値表現をスライドごとに抜き出して一覧化する
• 参照している画像ファイルが実際に手元にあるか
• 自社YouTubeチャンネルの直近動画の再生数・コメントを取得する

これらは1つのPythonファイル（約650行）にまとめてあり、Claude Codeからは対応する名前のツールとして呼び出せる。実装自体はAIエージェントに書かせた。正規表現のパターンや、検証関数の骨組みを考えるのはAIの方が速く、非エンジニアの筆者が一からロジックを書くよりも組み上がりが早かった。台本のチェックだけでなく、後から自社YouTubeチャンネルの再生数やコメントを取得する機能を同じファイルに追加したのも、既存の関数の書き方をAIに真似させる形でほぼそのまま任せられた。

このツールはstdio方式のMCPサーバーとしてClaude Codeに接続している。Claude Code公式ドキュメント「Model Context Protocol（MCP）」によれば、Claude Codeはサーバープロセスの環境変数にCLAUDE_PROJECT_DIRを設定しており、Pythonからはos.environ["CLAUDE_PROJECT_DIR"]で読み取ることで、作業ディレクトリに依存せずプロジェクト相対パスを解決できるという。台本ファイルや画像ファイルのパス解決は、この仕組みをそのまま使っている。

同じドキュメントには、stdioサーバーへのツール呼び出しについて次の記述もある。

MCPサーバーへのツール呼び出しで、アイドルウィンドウ中に応答も進捗通知も送信されない場合、ウォールクロック制限を待つ代わりにエラーで中止されます。（中略）アイドルウィンドウはHTTP、SSE、WebSocket、およびclaude.aiコネクタサーバーの場合は5分、stdioサーバーの場合は30分がデフォルトです。

つまり、Claude Code側の仕組みとして、MCPツール呼び出しが応答も進捗通知も返さないまま30分放置されると、Claude Code側がタイムアウトとして打ち切る。これは後述する「失敗2」で筆者が動画書き出し処理そのものに設定した30分のタイムアウトとは別の層の話で、両者を混同しないよう区別しておく。ツール呼び出し自体は応答を返しているため、この節で説明したMCP側のアイドルタイムアウトに引っかかったことはこれまでのところない。

人間が決めたこと・AIに任せたこと

ツールの実装はAIエージェントに任せたが、何を「異常」と判定するかの基準そのものは筆者が決めている。数値表現を検出する関数は、検出した数値を自動で削除したり書き換えたりはしない。一覧を出すだけで、「出典が確認できているか」の判断は人間に戻す設計にした。文字数の許容範囲も、実際に自分の動画で読みにくかった経験から数値を決めており、AIが提案した初期値をそのまま使ってはいない。

つまり、「チェックする仕組みを作る作業」はAIに任せたが、「何をチェック基準にするか」は人間の判断に残した、という線引きになっている。ここを逆にして、AIに基準づくりまで任せていたら、自分の失敗から学んだ具体的な閾値ではなく、一般論としてそれらしい基準に落ち着いていたはずだ。

数値の検出機能を例にすると、抜き出した数値の一覧に対して「出典を確認したか、確認できなければ言い切らない表現に置き換える」という注記を必ず添えるようにしている。この注記の文面自体は、実際に確認を怠って誤った数値を公開してしまった経験をもとに、後から自分で書き足したものだ。AIが最初に組んだ版では、数値を検出するだけで、その先どう扱うべきかの案内までは書かれていなかった。

失敗1: 並列エージェントが構造化データを返さず終わる

複数の記事やツールをまとめて作る際、AIエージェントを何本か並列で走らせて分担させたことがある。この時、「決まった形式のデータ（JSONなど）を返す」役割のエージェントに、ファイルの読み書きを行うツールも一緒に持たせると、指定した形式でデータを返さないまま処理が終わることが複数回起きた。

対策として、役割を分けた。データだけを組み立てて返すエージェントにはファイル操作のツールを持たせず、逆にファイルを読み書きするエージェントには決まった形式でのデータ返却を求めない。この分担に変えてからは、同じ失敗は再発していない。

この現象について、後からClaude Code公式ドキュメント「Subagents」を読み直したところ、関連しそうな記述を見つけた。

フォアグラウンド：レート制限、オーバーロード、またはサーバーエラーが既に出力を生成したサブエージェントを遮断する場合、Agentツールはその部分的な出力を、サブエージェントが遮断され、タスクを完了しなかったというメモ付きで返します。v2.1.200 以降、何も出力しなかったサブエージェント、またはツール呼び出しのみが出力だったサブエージェントは、「Agent terminated early due to an API error」で失敗し、その後にエラーの詳細が続きます。

つまり、レート制限やサーバー過負荷でサブエージェントの処理が途中で遮断されると、「ツール呼び出しだけして、構造化データという最終出力を返さないまま終わる」という状態が起こりうる、という一般的な仕組みが公式ドキュメントに書かれている。エラー一覧のページには、さらに踏み込んだ記述もあった。

このメッセージにはClaude Code v2.1.199以降が必要です。それ以前は、APIエラーテキストがsubagentの結果であるかのようにClaudeに返されていました。

つまり、このエラーメッセージ自体がv2.1.199で新設されたもので、それより前のバージョンでは、APIエラーが起きても「エラーである」というシグナルなしに、エラーテキストそのものがサブエージェントの成果物であるかのように扱われていた、ということになる。筆者が実際に遭遇した現象がこの仕組みそのものによるものだったのか、役割の持たせ方（ファイル操作ツールとデータ返却の同居）による別の問題だったのかは、後から見直しても完全には切り分けられていない。役割を分離してから再発していないという事実と、公式ドキュメントが説明する遮断時の挙動は、矛盾はしないが、同じ現象を指しているという確証もない。

失敗2: 長時間の処理をエージェントに任せると監視だけして終わる

動画の書き出し(レンダリング)は数十分かかる処理だ。これを自律的なAIエージェントに「処理が終わるまで見ていて」と任せたところ、処理の完了を待たずに「監視を続けています」という報告を残して作業自体を終えてしまうことが複数回あった。エージェントが処理を壊したわけではなく、待ち続けるという単純な作業の完了条件が、エージェントにとって曖昧になっていたのだと思う。

これに対応した今のやり方は、長時間かかる処理をエージェントに「見ていてもらう」のをやめ、タイムアウト時間を指定した1本のスクリプトとして実行することだった。今のツールでは、この種の処理にデフォルトで30分のタイムアウトを設定しており、時間内に終わらなければ失敗として扱われる。

Claude Code公式ドキュメントも、サブエージェントは「フォアグラウンド」（完了までメイン会話をブロックする）と「バックグラウンド」（並行して走る）の2通りで動くと説明している。ドキュメントによれば、v2.1.198以降はサブエージェントがデフォルトでバックグラウンド実行になったといい、完了したバックグラウンドサブエージェントは/tasksコマンドの一覧に「完了」として残り続ける仕様になっている（v2.1.208以降）。つまり公式の仕組みとしては、長時間タスクの進捗を/tasksで後から確認する経路が用意されている。ただし、これは「タスクの状態を一覧で確認できる」という機能であって、「タスクが完了するまで自律的に監視し続けて次の行動を取る」という筆者が当時やらせようとしていた振る舞いとは、厳密には別物だ。どちらの形であれ「終わるまで待つだけ」の作業をエージェントに割り当てるのは、少なくとも筆者の環境では相性が良くなかった。なお公式のスラッシュコマンド一覧によると、/tasksは「完了したサブエージェントを含む、現在のセッションのバックグラウンド作業を表示および管理します。/bashes としても利用可能です」と説明されている。今のツールでは書き出し処理をエージェント越しでなく1本のスクリプトとして直接実行しているため、/tasksで状態を確認する場面自体が減っている。

公開のような不可逆な操作は、既定で人間の実行に戻す

もう一つ意識して作ったのが、動画をYouTubeに実際に公開するかどうかの分岐だ。ツール側では、公開までを自動で実行するオプションを用意しているが、既定値は「公開しない」側になっている。公開する場合は、呼び出し時に明示的に指定しなければならない。ビルドや検証のような取り消せる作業はAIに投げても実害が小さいが、外部に公開する・課金が発生するといった取り消せない操作は、たとえツールとして自動化できていても、実行の最終判断だけは残すようにしている。

2つの失敗と対応を整理すると、次のようになる。

当時のバージョン・ログを残しておらず、公式説明との一致は確認できていない

• ここに書いた2つの失敗は、筆者1人が自社の動画制作パイプライン向けに組んだ約650行のツール1本での経験であり、他の非エンジニアが同じツールを同じ手順で作った場合に同じ現象が起きるかは確認していない
• 「失敗1」について公式ドキュメントから見つけた技術的な説明（レート制限・オーバーロード等によるサブエージェントの遮断）は、一般的な仕組みとして存在することを確認したものであり、筆者が実際に遭遇した現象の原因がそれだったと確定させるものではない。当時使っていたClaude Codeのバージョンや、遭遇時の詳細なログは記録として残しておらず、事後的に突き合わせることができなかった
• 「失敗2」についても、当時のバージョンでフォアグラウンド・バックグラウンドのどちらの挙動だったかは記録が残っておらず、公式ドキュメントが示す現在の仕様（v2.1.198以降のデフォルト挙動）がそのまま当時にも当てはまっていたかは確認できない

同じジャンルで、Claude CodeのSkills機能を業務ごとに設定した記録は非エンジニアがClaude CodeのSkills機能を設定した手順に、AIに任せる作業と任せない作業の一般的な線引きは非エンジニアが起業・個人開発でAIに任せる作業と任せない作業の線引きにまとめている。