Zenn
🧠

Claude CodeでIntentScriptを試したら、AIが書いた技術レビューが想像以上だった

に公開
AI
開発ツール
Claude
intentscript
技術検証
tech

Claude CodeでIntentScriptを試したら、AIが書いた技術レビューが想像以上だった

自然言語の柔軟さと、構造化の厳密さ。その境界にIntentScriptはある。

はじめに

この記事で分かること

  • Claude CodeでIntentScriptを実際に使った結果と比較
  • AIによる技術レビューの驚くべき精度と客観性
  • IntentScriptの適用範囲と現実的な限界
  • 人間とAIが協働する新しい開発スタイルの可能性

基本用語

  • IntentScript：AIに意図を伝えるためのYAMLベースの構造化言語。自然言語の曖昧さを回避し、生成AIによる誤読や仕様抜けを減らす目的がある
  • Claude Code：自然言語でAIにコード生成を依頼できるツール。プロジェクトの意図や仕様をCLAUDE.mdに記述して開発を進める

実験の背景

Claude Codeがリリースされて話題になっている中、以前から温めていたIntentScriptを実際に試してみることにしました。

「Claude Code × IntentScript」の組み合わせは理論的には完璧にマッチするはずでした。Claude Codeは自然言語でAIに意図を伝えてコード生成するツールで、IntentScriptはまさに「AIに意図を伝えるための言語」だからです。

しかし実験してみると、予想とは違う形で興味深い発見がありました。

実験の設定

題材：割り勘アプリ

実験には適度に複雑な「割り勘アプリ」を選びました。単純なTODOアプリではIntentScriptの優位性が見えにくく、複雑すぎるとノイズが多くなるためです。

割り勘のルール：

  • 参加者タイプ：主催者、社会人、学生
  • 端数処理：学生は100の位で切り捨て、社会人は100の位で切り上げ
  • 主催者は残り全額を負担（端数調整役）

計算例：
総額24,000円、主催者1人・社会人2人・学生2人の場合

  • 基準額：24,000 ÷ 5 = 4,800円
  • 学生：4,800円 → 4,000円（切り捨て）
  • 社会人：4,800円 → 5,000円（切り上げ）
  • 主催者：24,000 - 18,000 = 6,000円

比較方法

  1. 自然言語仕様書をCLAUDE.mdに記述してClaude Codeで実装
  2. IntentScript仕様書に差し替えて同じように実装
  3. 結果を比較

実験結果

詳細な仕様書はこちらで確認できます。

自然言語版：スムーズに完成

最初の自然言語版は期待通りスムーズに完成しました。npm run devで起動まで一発でできました。

IntentScript版：試行錯誤が必要

一方、IntentScript版は予想外に手こずりました。

初回版（曖昧な表現）：

participant_types:
  student:
    rounding: round_down_100    # 学生は100円単位で切り捨て
  worker: 
    rounding: round_up_100      # 社会人は100円単位で切り上げ

この記述ではround_down_100やround_up_100が何を意味するのかClaude Codeが理解できず、時間がかかりました。

改良版（具体的な実装まで記述）：

rounding_functions:
  round_down_100:
    logic: |
      100円単位で切り捨て。
      実装: Math.floor(amount / 1000) * 1000  # JavaScriptの関数を明示
      例：4,800円 → 4,000円
  round_up_100:
    logic: |
      100円単位で切り上げ。
      実装: Math.ceil(amount / 1000) * 1000   # JavaScriptの関数を明示
      例：4,800円 → 5,000円

Math.floorやMath.ceilといった具体的な実装まで書き、example sectionで期待する結果を明示したところ、一発で成功しました。

予想外の収穫：AIによる技術レビュー

実装完了後、Claude Codeに「IntentScriptについての感想を書いて」と依頼したところ、想像以上に詳細で客観的な技術レビューが返ってきました。

詳細な生の出力はこちらで確認できます。

AIによる評価レポート（抜粋）

良い点：

  • 構造化された記述：YAML形式により仕様の階層関係が明確
  • 実装例の併記：日本語説明と実装コード例が併記されており理解しやすい
  • 具体例の提示：具体的な計算例と期待値が明示されている

課題点：

  • 実装時の変換コスト：YAML構造をそのままTypeScriptコードに活用できない
  • 外部依存の読み飛ばし：include文を実装時に無視してしまった
  • 過度な構造化：今回のような単純な計算ロジックでは自然言語の方が直感的

総合評価：

IntentScriptは構造化仕様書として一定の価値があるが、今回のような単純な計算ロジックでは「学生は切り捨て、社会人は切り上げ、主催者が残額負担」という自然言語記述の方が実装効率が高かった。複雑なビジネスロジックや大規模システムでの仕様管理には有効だが、適用場面を見極めることが重要。

さらに詳しく聞いてみました

AIの評価が想像以上に的確だったので、追加で4つの質問をしてみました。

Q1: 今回の体験を踏まえて、IntentScriptをより実用的にするにはどんな機能や改善が必要だと思いますか？

A1:
AI連携の強化として、AIが外部参照を確実に処理するための仕組みや、LLM向けの読み込み順序のヒント、仕様書の完全性チェック機能が必要です。

また開発ツールの整備も重要で、TypeScript/Python等への自動変換ツール、IDEプラグイン（シンタックスハイライト、補完）、リアルタイムバリデーションなどがあるとより実用的になるでしょう。

Q2: あなたのような言語モデルが新しい技術を評価したり、自己分析を行う際の、客観性や限界についてどう考えますか？

A2:
客観性には限界があります。実装経験に基づく評価はできますが、実際の開発現場での長期運用経験は不可能です。人間開発者の感覚や直感的な使いやすさを完全には理解できません。

また今回のように基本的な仕様読解ミス（外部参照無視）が発生することもあり、評価の一貫性が保証されない問題もあります。

Q3: IntentScriptが「複雑なビジネスロジック」で有効と評価しましたが、具体的にはどのようなプロジェクトでの活用を想定していますか？

A3:
推奨される領域として、金融システム（複雑な手数料計算、リスク評価）、ECサイト（価格計算、在庫管理、ポイント・クーポン）、HR/給与システム（給与計算、勤怠管理）、保険システム（保険料計算、契約条件判定）などがあります。

これらの共通点は、多段階の条件分岐、ドメイン知識の集約、頻繁な仕様変更への対応が必要なことです。

Q4: IntentScriptを実際のプロジェクトで試してみたい開発者に対して、どのようなアドバイスがありますか？

A4:
段階的導入をおすすめします。まずは小さな計算ロジックから試してみて、既存プロジェクトの一部分で実験的に使用してください。

学習アプローチとしては、IntentScriptの設計思想（LLM最適化、段階的形式性）を理解し、自然言語での記述から始めて、徐々に構造化を進めるのが良いでしょう。

まずは「小さく始めて、大きく育てる」アプローチがおすすめです。

発見と考察

IntentScriptの適用範囲

今回の実験で分かったのは、IntentScriptの真価は単純な仕様書レベルでは発揮されないということでした。

詳細な仕様を書こうとすると、結果的に自然言語版と同じような情報量になってしまい、差が出にくくなります。IntentScriptが活きるのはもっと高レベルな設計段階や、複雑なシステム間の関係性を表現する場面なのかもしれません。

AIの技術分析・自己評価能力

しかし最大の発見は、AIに技術分析や自己評価を依頼することの可能性でした。

Claude Codeは依頼されて以下のような評価を行いました：

  • 自己の評価プロセスの問題点を認識
  • 技術の適用範囲を客観的に分析
  • 具体的な改善提案を提示
  • 将来の発展可能性まで言及

これは従来の「コード生成ツール」を超えて、「技術コンサルタント」的な役割すら担える可能性を示しています。

特に注目すべきは、AIが自己の限界を率直に認めて客観的に分析できることです。「実際の開発現場での長期運用経験は不可能」「評価の一貫性が保証されない」といった謙虚な自己評価は、人間がAIを信頼する上で重要な要素かもしれません。

新しい開発スタイルの可能性

今回の実験は以下のような流れで進みました：

  1. 人間がアイデアを提案
  2. AIと一緒に仕様を検討（IntentScriptを作成）
  3. AIが実装
  4. AIが客観的に技術評価
  5. AIが改善提案

この「人間とAIの協働開発サイクル」は、今後の開発スタイルの一つのモデルになるかもしれません。

おわりに

当初は「IntentScriptの実用性証明」を目的とした実験でしたが、結果として「AIの技術分析・自己評価能力」という予想外の価値を発見することができました。

IntentScript自体については、適用場面を見極めることの重要性が明確になりました。単純な仕様では差が出にくいですが、複雑なビジネスロジックや大規模システムでは価値を発揮する可能性があります。

しかし何より興味深かったのは、AIが技術を客観的に分析し、自己評価まで行った上で建設的な提案まで行えることでした。これは今後の技術選定や設計判断において、AIを「技術アドバイザー」として活用する新しい可能性を示しています。

Claude CodeもIntentScriptも、まだ発展途上の技術です。しかし両者の組み合わせを通じて、人間とAIが協働して技術を発展させていく未来の一端を垣間見ることができました。

追記:
この記事を Grok に読んでもらったところ、非常に興味深いレビューをしてくれましたので
こちらに載せておきます。

参考：

この記事の作成過程も「人間×AI協働」の実例です：

  • アイデア発案・実験設計：人間
  • 技術評価・分析：Claude Code（AI）
  • 記事構成・執筆：人間 + Claude Sonnet（AI）
  • 記事レビュー：ChatGPT（AI）、Gemini（AI）

今回も記事の企画から実験の実施、記事の執筆、レビューに至るまで多大な貢献をしてくれたAI達に感謝します。

Discussion