コンテンツにスキップ

第5章 AI駆動開発のワークフローと統制#

本章は、AI コーディングエージェントを使った開発の「規律」を定める章です。ツールの使い方紹介ではありません。金融資産を扱うプロジェクトとして、生産性と統制(検証・責任・監査対応)を両立させる進め方を示します。

最初に、本章が置く前提を明確にします。AI を使えば専門知識が不要になる、ということはありません。 本書の以降の章(実装・テスト・セキュリティ)は、AI に生成させた場合でも、読者が出力の正否を自分で判定できる知識を提供するものです。AI は出力を速く出しますが、その出力が正しいかを保証しません。正否の判定は、最後まで人間の側にあります。

5.1 AI駆動開発の全体像#

5.1.1 任せる領域と握る領域#

AI エージェントに任せてよい領域と、人間が必ず握る領域を、あらかじめ区分します。境界は「間違えたときに、後から機械的に検知・是正できるか」で引きます。

領域 主担当 理由
ボイラープレート生成、雛形の作成 AI(人間がレビュー) 誤りはビルド・テストで機械的に検知できる
テストコードの作成、テストケースの洗い出し AI(人間が妥当性を確認) 網羅の抜けは人間が要件(第3章)と突合する
エラー診断、原因の切り分け AI(人間が最終判断) 仮説出しは速い。採否は検証で決める
権限設計、鍵管理の方針 人間 誤ると不可逆。機械的な事後検知が効きにくい
デプロイの承認、mainnet 反映の判断 人間 影響が資産に及ぶ。承認は責任を伴う判断
依存パッケージの採否 人間(AI は候補提示のみ) サプライチェーンの入口。発行元確認は人間が行う(5.5.2)

この表は、以降の統制ルールの土台です。AI に任せる領域ほど、機械的なゲート(5.7)で守ります。人間が握る領域は、承認と記録で守ります。

5.1.2 金融資産ゆえの前提#

一般的なアプリ開発なら、多少の試行錯誤は後から直せます。しかし本書が扱うのは、移転制限・凍結・強制回収を伴う資産トークンです。鍵の漏えい、権限設計の誤り、誤ったデプロイは、取り返しがつきにくいという前提を置きます。

そのため本章の統制は、「AI が優秀かどうか」に依存しません。AI が正しい出力を返すことを期待するのではなく、誤った出力が混じっても機械的に止まる仕組みを作ることを主眼とします。

5.2 公式Agent Skillsの導入#

5.2.1 Agent Skills とは何か#

Agent Skills は、コーディングエージェントに現行仕様に沿った作業手順・参照情報を与える仕組みです。エージェントは学習データに基づいて回答します。そのため、ツールチェーンの変化が速い領域では古い知識に基づくコードを生成することがあります(本書の地雷リストにある Anchor 0.3x 時代の手順の混入が典型です)。Skill を導入すると、エージェントが現行仕様の参照情報を手元に持って作業しやすくなります。

5.2.2 公式スキルの導入手順#

Solana Foundation は、公式の Agent Skill を提供しています。本書の執筆時点(確認日 2026年7月27日)で確認した内容は次のとおりです。

  • 配布リポジトリ: github.com/solana-foundation/solana-dev-skill
  • organization は solana-foundation(公式)。フォークではありません。ライセンスは MIT です。
  • 導入される Skill の名称は solana-dev(作成者表記:Solana Foundation)です。
  • 導入経路は2通りを確認しました。いずれも同じリポジトリを導入します。

Anchor CLI 経由で、ワークスペース作成と同時に導入する方法です。第4章で紹介した anchor init のオプションです。

# Anchor ワークスペースの作成と同時に公式スキルを導入する
$ anchor init <ワークスペース名> --install-agent-skills

すでにあるプロジェクトへ後から追加する場合は、スキルインストーラを直接使います。

# 既存プロジェクトのルートで公式スキルを導入する
$ npx skills add solana-foundation/solana-dev-skill

導入が完了すると、スキル本体がプロジェクト配下に配置されます。執筆時点の確認では .agents/skills/solana-dev に配置され、Claude Code 等の各エージェント用ディレクトリへリンクされました。このスキルが提供する参照情報のカテゴリとして、次のようなものが確認できました(確認日 2026年7月27日)。

  • 共通エラーと対処(common-errors)、バージョン互換表(compatibility-matrix)
  • テスト戦略(testing。LiteSVM / Mollusk 等)、セキュリティ確認(security)
  • Token-2022 の Confidential Transfer(confidential-transfers)
  • クライアント SDK(kit 系)、IDL からのクライアント生成(idl-codegen)、旧 web3.js との移行(kit-web3-interop)

補足:導入時に表示される警告に従ってください。 スキルインストーラは、導入の最後に「利用前にスキルの内容を確認すること。スキルはエージェントの全権限で動作する」旨の警告を表示します(執筆時点の確認)。Skill はエージェントへの指示書であり、その内容がそのまま作業に影響します。公式スキルであっても、導入したら中身に目を通す習慣をつけてください。第三者製スキルの審査は 5.6 で扱います。

5.2.3 導入したスキルを記録する#

スキル・MCP のエコシステムは変化が速い領域です。本書が示す具体名・カテゴリは、上記の確認日時点のものです。読者が実際に導入する時点では、リポジトリ名・スキル構成・導入コマンドが変わっている可能性があります。導入前に公式ソース(solana.com/skills、公式 GitHub)で最新の状態を確認してください。

そのうえで、プロジェクト側では導入したスキルの名称・入手元・確認日を記録する運用を推奨します。導入経路のうち npx skills add を用いた場合は、ロックファイルが自動生成されました(執筆時点の確認では skills-lock.json)。これは導入元(source)とハッシュ(computedHash)を記録します。こうした記録は、後から「どのスキルを、どの版で使ったか」を第三者に説明する材料になります(監査対応。5.8)。

5.3 Solana MCPサーバの活用#

MCP(Model Context Protocol)サーバは、エージェントが外部の情報源へ問い合わせるための接続口です。学習データの陳腐化への対策として、AI エージェントが最新の公式ドキュメントを検索しながら実装する構成を取れます。

Solana Foundation は、公式ドキュメント検索用の MCP サーバを提供しています。本書の執筆時点(確認日 2026年7月27日)で確認した内容は次のとおりです。

  • リポジトリ: github.com/solana-foundation/solana-mcp-official(organization は solana-foundation。フォークではありません)。
  • 接続先(production エンドポイント): https://mcp.solana.com。
  • 提供ツール(ドキュメント検索系): Solana_Documentation_Search、Solana_Expert__Ask_For_Help、list_sections、get_documentation、program_autofixer。

このサーバは、公式ドキュメントを横断的に検索し、エージェントへ返すことを目的としています。実装中に仕様の裏取りが必要な場面で、エージェントがブログ記事ではなく公式情報を参照しやすくなる点が利点です。ただし、MCP が返した情報であっても、本書の検証規則(実行検証・一次情報照合)を免れるものではありません。返答は根拠であって結論ではなく、コマンド・コードは実行して確かめます。

なお、MCP のリポジトリ名・エンドポイント・ツール構成も、上記の確認日時点のものです。導入時に公式 GitHub で最新の接続方法を確認してください。

5.4 プロジェクトルールの整備(CLAUDE.md)#

5.4.1 記載すべき内容#

エージェントの設定ファイル(Claude Code の場合は CLAUDE.md)には、プロジェクト固有の前提と禁止事項を書きます。これは、エージェントが会話ごとに前提を忘れる、あるいは古い知識で埋めてしまうことへの対策です。RWA 実装プロジェクトで最低限記載すべき項目は次のとおりです。

  • 採用バージョン: 第1章のバージョン表と一致させる(本文と設定ファイルで版を二重管理しない)。
  • 使用 SDK: クライアントは @solana/kit 系を基準とする、といった SDK の明示(旧 web3.js v1 との混同を防ぐ)。
  • 禁止事項: 秘密鍵・シード・本番 RPC キーをコンテキストへ渡さない、未検証のコマンド・コードを断定で書かない、など。
  • コーディング規約: コメントは日本語、コードは検証済みのもののみ、など。

5.4.2 リファレンス実装向け CLAUDE.md 例#

本書のリファレンス実装(第1〜4章の技術スタックを前提とする)向けに、CLAUDE.md の例を示します。実際のプロジェクトでは、バージョンを第1章のバージョン表の値に置き換えて使ってください。

# CLAUDE.md — RWA(私募債トークン)リファレンス実装

あなたは、Solana 上で RWA(私募債)トークンを実装するプロジェクトの
開発支援を行うエージェントです。以下の前提と規則に従ってください。

## 技術スタック(第1章バージョン表と一致させること)

- チェーン: Solana devnet / mainnet-beta(バリデータ: Agave)
- プログラム: Rust + Anchor v1.x(0.3x 系の手順を混入させない)
- トークン規格: Token-2022(Token Extensions)
  - 使用拡張: Transfer Hook / Permanent Delegate /
    Default Account State(frozen 既定)/ Metadata Pointer + Token Metadata
- クライアント SDK: @solana/kit 系(旧 web3.js v1 の API を混ぜない)
- テスト: LiteSVM(Rust 単体)/ TypeScript 統合 / Surfpool / devnet
- ※ 具体的なバージョン番号は第1章バージョン表を唯一の正とする。
  本ファイルに「latest」「最新版」と書かない。

## 実装の前提(この設計を崩さないこと)

- 移転可否は Transfer Hook が判定する。Hook を迂回する例外経路を作らない。
- 送信者・受信者の双方が許可済み(Approved)であることを検証する。
- 強制回収は Permanent Delegate 経由でのみ行い、その判定はミントの
  拡張値に一本化する(独自フラグを新設しない)。
- ミント側の拡張はミント作成時に確定する(後から追加できない)。
  拡張の初期化はミント初期化より前に行う。

## 禁止事項

- 秘密鍵・シードフレーズ・本番 RPC キーをコンテキストに渡さない。
  鍵はローカル生成のテスト用のみ。参照は環境変数経由とする。
- 実行検証または公式一次情報での確認なしに、コマンド・コード・仕様を
  断定しない。未確認の事項はコードに書かず、確認すべき旨を明示する。
- 新規依存を追加する提案をする場合は、crates.io / npm の発行元・
  リポジトリを併記する。発行元未確認の依存を既定で採用しない。

## 検証規則

- 生成したコードは、コミット前に必ずビルド・テスト・レビューを通す。
- 依存の帰属を書くときは organization 名まで確認する
  (公式: solana-foundation / anza-xyz / solana-program 等。
   Anchor 本体は otter-sec/anchor へ移管済み)。

5.4.3 例の妥当性の自己確認#

上記の例は、本書の第1〜4章の技術スタックおよびリファレンス実装の設計決定と突き合わせて作成しました。確認した点は次のとおりです。使用拡張の4種と「拡張はミント初期化前に初期化する」制約は、第6章の実装と整合します。Hook を迂回させない・双方 Approved 検証・強制回収は Permanent Delegate 経由という設計は、第7章の実装と整合します。@solana/kit を基準とする点と禁止事項(鍵の非共有、未検証事項を断定しない、依存の発行元確認)は、本書全体の方針と一致します。なお、この例は本書の執筆用 CLAUDE.md とは別物です。執筆用のものは手順書を書くための指示であり、実装プロジェクトへは転用していません。

5.5 AI生成コードの検証規律(本章の核)#

ここが本章の中心です。AI をどう使うかにかかわらず、生成物は同じ関門を通します。

5.5.1 無検証でコミットしない#

生成されたコードは、必ずビルド・テスト・レビューを通してからコミットします。AI の出力を、動作を確かめずにそのまま取り込むことを禁じます。この規律は、生成物が正しく見えるほど重要になります。見た目の妥当さは、正しさの保証ではありません。

5.5.2 依存パッケージの実在・正当性を確認する#

AI は、実在しない crate / npm パッケージや、正規品に似せた名前のパッケージを提示することがあります。これはサプライチェーン攻撃の入口になり得ます。新規依存を採用する前に、crates.io / npm の公式ページで発行元・ダウンロード数・リポジトリを確認してください。確認は人間が行い、結果を記録します(5.1.1 の区分表のとおり、依存の採否は人間が握る領域です)。

コラム:本プロジェクトでの依存の発行元確認 本書のリファレンス実装でも、この確認を実践しました。Transfer Hook 実装で使う SPL 系の crate(spl-transfer-hook-interface ほか)は、crates.io の owner が anza-team、発行 organization が solana-program であることを確認してから採用しています。TypeScript 側の @solana/kit は organization が anza-xyz、@solana-program/* は solana-program org であることを、npm view で maintainer とリポジトリまで確認しました(本プロジェクトのセッション記録より)。似た名前の別物を掴まないために、名前ではなく発行元まで見る、という運用です。

5.5.3 鍵をエージェントのコンテキストに渡さない#

秘密鍵・シードフレーズ・本番 RPC キーを、AI ツールのコンテキストへ渡してはいけません。鍵はローカル生成のテスト用のみとし、コードからは環境変数経由で参照します。本書のミント作成スクリプトも、鍵を環境変数(PAYER_KEYPAIR)で受け取る形にしており、本番鍵・シードは一切扱いません(第6章)。

5.5.4 「動くが危険な」パターンに注意する#

AI は、動作はするが安全でないコードを提案することがあります。金融資産を扱うプログラムで特に警戒すべき典型は次のとおりです。

  • 署名者検証の省略: 命令を呼べる主体を絞る検証(署名の要求)が抜けていると、権限のない呼び出しを許してしまいます。
  • 権限チェックの緩い実装: 「署名者であること」だけを見て「その署名者が権限保持者本人であること」を検証しない、といった緩さです。

これらは、動作テスト(正常系)だけでは見逃されがちです。本書のリファレンス実装では、署名の要求と権限の一致検証(has_one constraint)を両方揃えることで権限昇格を防いでいます(第7章 7.2.2)。渡された PDA のすり替え(account confusion)対策も、シード検証で行っています(同 7.2.2)。レビュー観点と対策の詳細は第7章、脆弱性の体系的な整理は第10章で扱います。

5.6 サードパーティ スキル・MCPの導入審査#

コミュニティ製のスキルや MCP サーバは、便利な反面、注意が必要です。スキルは、それ自体が AI への指示書です。導入すれば、その内容がエージェントの作業に影響します。悪意ある指示が紛れ込む経路にもなり得ます(前掲のとおり、公式インストーラ自身も「スキルはエージェントの全権限で動作する。利用前に内容を確認せよ」と警告します)。

そこで、第三者製のスキル・MCP は、導入前に次の三点で審査することを推奨します。

  1. 公式性: 提供元の organization を確認する。公式(solana-foundation / anza-xyz / solana-program 等)か、第三者かを名前だけで判断せず、リポジトリの帰属まで見ます。
  2. 実績: 利用状況・保守状況(更新の有無)を確認します。
  3. 内容確認: 導入するスキル・設定ファイルの中身を実際に読みます。何を参照し、何を指示するかを把握してから使います。

例:名前が似ていても別物のことがある 本プロジェクトのテスト章(第9章)の作業でも、この注意が効きました。ファジングツールとして名前の挙がる avm は、crates.io 上では Anchor とは無関係の別パッケージ(schultyy/avm)であり、CI で cargo install avm を使ってはならない、という判断をしています。また外部のファジングフレームワーク Trident は、Ackee Blockchain 社製であり Solana 公式 org ではない、という配布元を明記したうえで扱っています。第三者製ツールは、便利さの前に「誰が出しているか」を確認する、という運用です。

5.7 CIによる機械的ゲート#

ここまでの規律を、人の注意力に頼らず担保する仕組みが CI(継続的インテグレーション)です。AI が生成したかどうかにかかわらず、すべてのコードが同じ関門を通る設計にします。関門に含める代表的なゲートは次のとおりです。

  • ビルド(プログラムのビルドが通ること)
  • 全テスト(単体・統合・攻撃系がすべて成功すること)
  • lint(静的解析の警告をエラー扱いにする)
  • 依存監査(既知脆弱性・不審な依存の検査)

本書のリファレンス実装では、これらを GitHub Actions のワークフローとして実装し、実機で全ゲートが通る状態を確認しています(第9章 9.7)。CI の意義は、レビュアーの調子や集中力に品質を依存させない点にあります。AI 生成コードが増えるほど、この「機械的で、逃げ場のない関門」の価値は上がります。

5.8 監査・コンプライアンス対応#

第三者監査や社内のコンプライアンス確認で、AI の利用について問われることがあります。そのとき示すべきなのは、「AI が書いたかどうか」ではなく、「どう検証したか」です。誰がいつ何を検証し、承認の責任が誰にあるかを説明できる状態を、あらかじめ作っておきます。

そのための具体的な材料は、これまでの節で作ってきたものです。CI のログ(5.7)、依存の発行元確認の記録(5.5.2)、導入スキルの記録(5.2.3)が、そのまま説明材料になります。加えて、作業の状態を継続的に記録しておくことが有効です。

コラム:状態の引き継ぎと詰まりの記録 本書の制作自体が、この統制を実践しています。エージェントは会話ごとに記憶を持たない前提のため、本プロジェクトでは各作業セッションの終わりに「変更したファイル・実行したコマンドと結果・固定したバージョン・追加した依存と確認結果・未解決事項」をセッションログに記録し、次のセッションの冒頭で読み直す運用を取っています。この記録は、後から作業の経緯を第三者へ説明する材料にもなります。

記録の価値は、うまくいった手順だけでなく、詰まった事象にもあります。例えば本書の環境構築の再現作業では、配布された Anchor バイナリが GLIBC 2.39 以上を要求し、古いディストリビューション(GLIBC 2.36)ではビルドが止まる、という事象に実際に遭遇しました。この詰まりと回避方法(GLIBC 2.39 以上の環境を使う)を記録に残したことで、第4章のトラブルシューティングは想像上のエラーではなく、実際に起きた事象として書けています(第4章 4.9)。検証の記録は、成功と失敗の両方を残してこそ、監査の場で説明力を持ちます。

「どう検証したか」を説明できる状態は、一度に作るものではなく、日々の作業を記録する習慣から積み上がります。第10章では、この統制が守られているかを監査観点から再確認します。

5.9 本章の自己チェック表#

観点 結果
スタイル規則違反 なし(です・ます調、一文概ね80字以内、コードブロックに言語指定とファイルパス/用途を付与、相互参照は番号、価格・投資リターン・マーケティング語彙・法的判断示唆なし。特定 AI ベンダーの宣伝を避け、原則をツール非依存で記述し具体例として Claude Code 等を挙げる形に統一)
[要検証] の残数 0件(5.2 の導入コマンドは使い捨てディレクトリで実際に実行し成功出力を確認。本章は転記元リポジトリがない分、掲載コマンドの実行検証を照合の代わりとした。MCP の具体名・エンドポイントは公式 GitHub で確認)
バージョン表との不一致 なし(本章は具体的なバージョン番号を本文で断定していない。CLAUDE.md 例の中でも「バージョンは第1章バージョン表を唯一の正とする」「latest / 最新版と書かない」と明記)
具体名の確認日 スキル(solana-foundation/solana-dev-skill、solana-dev)・MCP(solana-foundation/solana-mcp-official、mcp.solana.com、5ツール)はいずれも確認日 2026年7月27日を付し、エコシステムの変化が速い前提で「導入時に公式ソースで再確認」と明記
「専門知識不要」表現 なし(冒頭 5.0 導入および 5.4.3 で、AI 利用でも読者が出力の正否を判定できる知識が必要である旨を明示。「AI を使えば専門知識が不要」と読める記述を置いていない)
実践例コラムの出所 すべて本プロジェクトのセッション記録から引用(依存の発行元 org 確認=セッション1-B / 状態引き継ぎと GLIBC 2.39 問題=セッション2-D)。session-log と一致