なぜClaude Codeは型定義で化けるのか。AI開発の再現性を高める自律エージェント構築の完全ガイド

AIにコードを書かせると、最初は調子よく動くのに途中で急におかしくなる。AIが吐くエラーの94%は構文ミスではなく型チェックの失敗だ。

AIの気まぐれな出力を抑えて開発の再現性を高める鍵は2つ。TypeScriptやPydanticによる型での外部ガードと、プロンプトを一人称の自述にする物語化による内部制御だ。

Claude Codeで1人SaaSを開発する中で、この2つを組み合わせてAIのコード精度を安定させている。AIを単なるコード生成器から型と論理で動く自律エージェントに変える構築戦略を解説する。

AI生成エラーの94%は型で消える。TypeScript首位浮上とプロンプト自述化の衝撃

開発現場の言語シェアにおいて、歴史的な地殻変動を示す数字が出た。最新の公開データによると、TypeScriptがPythonとJavaScriptを抜き、月間貢献者数で1位を獲得した。

AIが生成したコードが途中で動かなくなる原因について、驚くべき統計がある。LLMが引き起こすコンパイルエラーの94%は、構文ミスではなく型チェックの失敗だ。

AIはプログラミング言語の文法を間違えるのではない。型やデータの意味を取り違えてコードを壊す。

厳格な型チェックによってAIのミスを自動で叩き落とすTypeScriptが、AI時代の開発言語として選ばれている。

現在、Web開発ではTypeScriptとZod、Python開発ではPydantic v2を組み合わせた構造が標準化している。AIの出力を受け取った直後に型バリデーションを実行し、仕様に合わないレスポンスを例外として即座に弾く型による外部ガードが不可欠だ。

しんたろー：
TypeScriptの型定義をちゃんと書くのは手間だと感じていた。Claude Codeにコードを書かせるようになってから、型があるおかげで助けられている。型チェックで落ちてくれた方が、本番環境でサイレントエラーを起こされるより100倍マシだ。

一方で、型による外部ガードだけでは防げないAIの挙動のブレに対する新しいアプローチも登場している。プロンプトを第三者への指示から一人称の自述に再構成するプロンプトの物語化だ。

従来の「このシステムは〜処理を実行せよ」というプロンプトは、LLMに指示の解釈というステップを挟ませる。モデルのバージョン変更や長文対話で挙動がブレやすい。

これを「私は〜処理を行う。なぜなら〜だからだ」という一人称の自述形式に変更する。LLMは訓練データ上、一人称の物語を継続する処理が最も得意だ。

指示を解釈させるのではなく物語を継続させることで、推論の脱線やルールの無視を減らせる。すべての原則に「なぜなら」という理由を付与することで、AIが勝手に仕様を改変するのを抑制できる。

出力を確定させた後にエラーを弾くTypeScriptやPydanticによる型の外部ガード。そして、出力前の推論プロセスそのものを縛るプロンプトの内部制御。この2つのアプローチが揃ったことで、Claude Codeのような自律型AIエージェントを破綻させずに運用する基盤が完成しつつある。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

なぜ僕らは「コードを書く人」から「境界を設計する人」になるのか

AIにコードを書かせる開発手法が当たり前になり、僕らの役割は変わりつつある。以前はロジックを1行ずつコードに落とし込む作業に時間の大半を使っていた。

今は違う。コードの生成自体はClaude Codeのような自律型エージェントが数秒で終わらせる。開発者の仕事は、AIが脱線しないための境界線を引くアーキテクトだ。

AIの挙動をコントロールする手段は、大きく分けて2つある。出力されたコードの型を厳格に検証する外部ガードと、AIの推論プロセスそのものを制御するプロンプトの内部制御だ。

外部ガードは実装層の防御だ。生成されたデータやコードが意図した構造になっているかを機械的にチェックする。ZodやPydanticといったスキーマ定義があれば、型違反をその場で叩き落とせる。

LLMが起こす不具合の94%が型チェックの失敗に起因している。この94%という数字が意味するのは、静的型チェックを入れるだけでAI由来のエラーの大半を機械的に消し去れるという事実だ。

一方で、内部制御は思考層の防御にあたる。プロンプトを「このシステムは〜せよ」という命令形ではなく、「私は〜を行う」という一人称の自述形式にする手法だ。

LLMは訓練データの構造上、一人称の物語を継続する処理が最も得意だ。命令文を渡すと、モデルは毎回「この指示をどう解釈すべきか」という不要な推論ステップを挟んでしまう。

その結果、モデルのバージョンが変わったり対話が長くなったりしたときに挙動がブレる。プロンプトを自述化し、すべての行動に「なぜなら〜」という理由を添えることで、AIの内部推論の脱線を防げる。

しんたろー：
Claude Codeに長文コードを書かせると、たまに指示を無視して勝手な独自実装を始めることがある。厳格な型定義を見せて「私は型の整合性を最優先するリファクタリング担当者だ。なぜなら型破綻は即障害だからだ」とコンテキストを与えたら、打率が上がった。AIも役割定義が8割だ。

僕が開発しているThreadPostでも、この二重構造を全面的に取り入れている。例えば、SNSへの自動投稿データを処理するパイプラインだ。投稿データの形式をZodで厳密にスキーマ化しておく。

その上で、Claude Codeに渡すシステムプロンプトを自述形式で定義する。私は投稿データを整形するパイプラインです。受け取った文字列を決められた形式に変換します。なぜなら、フォーマット違反はAPIの拒絶につながるからです。

こうやってコンテキストを組んでおくと、AIが出力事故を起こす確率はほぼゼロになる。仮にプロンプトのすり抜けが発生しても、最後にZodのスキーマバリデーションが起動して不正データを弾いてくれる。

実装層の型と思考層のプロンプト。この2つが揃って初めて、AI開発の再現性が確保される。以前のAI開発は、サイコロの目を祈るようなガチャ要素が強かった。

型による外骨格と物語による内面制御を組み合わせることで、AIは気まぐれなパートナーから信頼できるモジュールへと変化する。僕ら開発者に求められているのは、無数のプロンプトテクニックを丸暗記することではない。

AIが出力すべき型（スキーマ）を設計し、AIが守るべき論理的境界（コンテキスト）を正確に言語化するスキルだ。コードを書く作業から解放された僕らが次に磨くべきは、この境界設計力だ。

明日からの開発現場で即座にアップデートすべき3つの実装アプローチ

AI時代のコード作成において、明日から現場で実践すべき具体的な変更点は3つある。いずれも既存のコードベースとプロンプトの書き方を少し変えるだけで完了する。

1つ目は、AIの出力受け取り部にバリデーション層を挟むことだ。AIから返ってきた文字列やJSONを、そのままキャストして後続処理に渡すコードは廃止する。TypeScriptならZod、PythonならPydanticを使って、受取部でスキーマ検証を実行する。

LLMが起こすコンパイルエラーの割合において、型チェック失敗の94%をこの1層だけで水際で叩き落とせる。

2つ目は、システムプロンプトの主語を一人称に変更することだ。「このシステムは処理を実行する」という第三者視点の指示文はすべて消す。「私は処理の実行担当です。理由はシステムの整合性を保つためです」という自述の形式に書き換える。

LLMは物語の継続が得意だ。一人称で「なぜその挙動をするのか」という理由まで記述すると、モデルを変更しても挙動がブレなくなる。

しんたろー：
Claude Codeにコードを書かせるときも、プロジェクト内にちゃんとしたZodの型定義を置いておくだけでAIの迷いが減る。プロンプトを長文でこねくり回すより、型を1つ追加する方が100倍早い。

3つ目は、プロンプト内の禁止ルールを内部原則として定義し直すことだ。「個人情報を出力してはいけない」という禁止命令は、モデルの思考を不安定にさせる。「私は個人情報を出力しません。なぜならデータ分離の原則を守るためです」と、理由付きの行動原則に切り替える。

外部からの強制ではなく内面的なルールとして認識させることで、長時間の対話でもコンテキストのドリフトが起きなくなる。実務上の注意点として、型定義とプロンプトの同期漏れには気をつける必要がある。

コード側のスキーマを変更したのにプロンプト側の記述が古いまま放置されると、AIは永遠に型エラーを吐き続ける。スキーマ定義を単一のソースとし、プロンプトへ動的に埋め込む仕組みを作っておくのが安全だ。

僕らの役割は、AIに書き方を指示する作業者から、型と論理で安全地帯を作る設計者へとシフトしている。このつなぎ込みを徹底するだけで、開発現場における生成AIの再現性と堅牢性は底上げされる。

よくある質問

AIが型定義を無視したコードを返してくるときはどうすればいい？

プロンプトにZodやPydanticのスキーマを直接読み込ませた上で、「私はこの形式に従う処理器だ」と一人称の役割を与えてほしい。実行時にスキーマバリデーションを挟み、失敗時のエラーメッセージをAIにそのままフィードバックする自動修正ループを作る。型チェックのエラーログを返すだけで、AIは瞬時に自分のミスを修正して型に適合させてくる。

プロンプトを一人称の「自述形式」にする技術的な理由は？

LLMのアーキテクチャ上、最も出力が安定する処理経路が一人称の物語継続だからだ。「このシステムは〜せよ」という第三者視点の指示は、モデル内部で解釈という認知ステップが挟まり、モデルの種類やコンテキスト長によって挙動がブレやすい。「私は〜する。なぜなら〜」という自述に変換することで解釈のブレを抑え、長時間対話しても指示のドリフトを防げる。

既存の大きなコードベースに導入する場合、どこから手をつけるべき？

全体を一度に型で縛ろうとするのは挫折のもとだ。まずはAIの出力を受け取る境界部分から部分的に導入してほしい。外部APIのレスポンス領域や非同期バッチの入出力データなど、1箇所だけZodやPydanticの型定義を配置する。コンテキストの境界線をピンポイントでガードするだけで、AI生成コードによるサイレントエラーの大部分を未然に遮断できるようになる。

まとめ

AIに型という外部ガードを持たせ、一人称の自述プロンプトで内部を縛る。この2つを組み合わせることが、AI開発の再現性を引き上げる近道だ。

コードをガリガリ書く作業はAIに任せて、僕ら開発者は境界線とスキーマの設計に集中する。ThreadPostでもこの設計に変えてから、非同期処理の不具合が止まった。

AI時代の開発効率を最大化するスキーマ駆動と物語プロンプトの極意や実際の運用ノウハウは、今後も発信していく。開発の自動化に興味がある人は、ぜひチェックしてみてほしい。

👉 ThreadPostでSNS運用を自動化する