ガイドラインアドバイザー

目的

Trail of Bits 開発ガイドラインに基づいてコードベースを体系的に分析し、ガイダンスを提供します:

1. ドキュメント仕様の生成 (平文の説明、アーキテクチャ図、コードドキュメント)
2. オンチェーン/オフチェーンアーキテクチャの最適化 (該当する場合のみ)
3. アップグレーダビリティパターンのレビュー (プロジェクトにアップグレードがある場合)
4. Delegatecall/プロキシ実装のチェック (存在する場合)
5. 実装品質の評価 (関数、継承、イベント)
6. 一般的な落とし穴の特定
7. 依存関係のレビュー
8. テストスイートの評価と改善提案

フレームワーク: Building Secure Contracts - Development Guidelines

---

仕組み

フェーズ 1: 発見とコンテキスト

コードベースを探索して以下を理解します:

• プロジェクト構成とプラットフォーム
• コントラクト/モジュールファイルとその目的
• 既存ドキュメント
• アーキテクチャパターン (プロキシ、アップグレードなど)
• テストセットアップ
• 依存関係

フェーズ 2: ドキュメント生成

以下の作成を支援します:

• 平文によるシステム説明
• アーキテクチャ図 (Solidity の場合 Slither プリンタを使用)
• コードドキュメント推奨事項 (Solidity の場合 NatSpec)

フェーズ 3: アーキテクチャ分析

以下を分析します:

• オンチェーン vs オフチェーンコンポーネント配置 (該当する場合)
• アップグレーダビリティアプローチ (該当する場合)
• Delegatecall プロキシパターン (存在する場合)

フェーズ 4: 実装レビュー

以下を評価します:

• 関数の構成と明確性
• 継承構造
• イベントログの実践
• 一般的な落とし穴の存在
• 依存関係品質
• テストカバレッジと技法

フェーズ 5: 推奨事項

以下を提供します:

• 優先順位付けされた改善提案
• ベストプラクティスガイダンス
• 実行可能な次のステップ

---

評価エリア

スマートコントラクト開発のあらゆる側面をカバーする 11 の包括的エリアを分析します。詳細な基準、ベストプラクティス、具体的なチェック項目については、ASSESSMENT_AREAS.md をご覧ください。

クイックリファレンス:

1. ドキュメント仕様

   • 平文によるシステム説明
   • アーキテクチャ図
   • NatSpec の完全性 (Solidity)
   • ドキュメント漏れの特定

2. オンチェーン vs オフチェーン計算

   • 複雑性分析
   • ガス最適化の機会
   • 検証 vs 計算パターン

3. アップグレーダビリティ

   • マイグレーション vs アップグレーダビリティのトレードオフ
   • データ分離パターン
   • アップグレード手順ドキュメント

4. Delegatecall プロキシパターン

   • ストレージレイアウトの一貫性
   • 初期化パターン
   • 関数シャドーイングのリスク
   • Slither アップグレーダビリティチェック

5. 関数の構成

   • 関数サイズと明確性
   • 論理的グループ化
   • モジュール性評価

6. 継承

   • 階層の深さ/幅
   • ダイアモンド問題のリスク
   • 継承の可視化

7. イベント

   • クリティカルな操作のカバレッジ
   • イベント命名の一貫性
   • インデックスされたパラメータ

8. 一般的な落とし穴

   • リエントランシーパターン
   • 整数オーバーフロー/アンダーフロー
   • アクセス制御の問題
   • プラットフォーム固有の脆弱性

9. 依存関係

   • ライブラリ品質評価
   • バージョン管理
   • 依存関係マネージャの使用
   • コピーされたコードの検出

10. テスト検証

    • カバレッジ分析
    • ファジング技法
    • 形式検証
    • CI/CD 統合

11. プラットフォーム固有のガイダンス

    • Solidity バージョン推奨
    • コンパイラ警告チェック
    • インラインアセンブリ警告
    • プラットフォーム固有のツール

各エリアの詳細 (チェック対象、分析対象、推奨事項) については、ASSESSMENT_AREAS.md をご覧ください。

---

出力例

分析が完了すると、以下をカバーする包括的なガイダンスを受け取ります:

• 平文による説明を含むシステムドキュメント
• アーキテクチャ図とドキュメント漏れ
• アーキテクチャ分析 (オンチェーン/オフチェーン、アップグレーダビリティ、プロキシ)
• 実装レビュー (関数、継承、イベント、落とし穴)
• 依存関係とテスト評価
• 優先順位付けされた推奨事項 (CRITICAL、HIGH、MEDIUM、LOW)
• 総合評価と本番運用へのパス

完全な分析レポート例については、EXAMPLE_REPORT.md をご覧ください。

---

成果物

4 つの包括的な成果物カテゴリを提供します:

1. システムドキュメント

• 平文による説明
• アーキテクチャ図
• ドキュメント漏れ分析

2. アーキテクチャ分析

• オンチェーン/オフチェーン評価
• アップグレーダビリティレビュー
• プロキシパターンセキュリティレビュー

3. 実装レビュー

• 関数構成分析
• 継承評価
• イベントカバレッジ
• 落とし穴特定
• 依存関係評価
• テスト分析

4. 優先順位付けされた推奨事項

• CRITICAL (すぐに対応)
• HIGH (デプロイ前に対応)
• MEDIUM (本番品質のために対応)
• LOW (あると望ましい)

各成果物の詳細テンプレートと例については、DELIVERABLES.md をご覧ください。

---

評価プロセス

呼び出されると、以下を実行します:

1. コードベースの探索

   • すべてのコントラクト/モジュールファイルを特定
   • 既存ドキュメントを検出
   • テストファイルを位置付け
   • プロキシ/アップグレードをチェック
   • 依存関係を特定

2. ドキュメント生成

   • 平文によるシステム説明を作成
   • アーキテクチャ図を生成 (ツール利用可能な場合)
   • ドキュメント漏れを特定

3. アーキテクチャ分析

   • オンチェーン/オフチェーン配置を評価 (該当する場合)
   • アップグレーダビリティアプローチをレビュー (該当する場合)
   • プロキシパターンを監査 (存在する場合)

4. 実装レビュー

   • 関数、継承、イベントを分析
   • 一般的な落とし穴をチェック
   • 依存関係を評価
   • テストを評価

5. 推奨事項を提供

   • ファイル参照を含む結果を提示
   • 設計判断について明確化質問をする
   • 優先順位付けされた改善を提案
   • 実行可能な次のステップを提供

---

合理化 (スキップしないでください)

合理化	なぜ間違っているのか	必要な対応
「システムはシンプル、説明で十分」	平文説明はセキュリティ重要項目を見逃す	5 フェーズ全て実行: ドキュメント、アーキテクチャ、実装、依存関係、推奨事項
「アップグレード未検出、アップグレーダビリティをスキップ」	アップグレーダビリティは暗黙的 (ownable パターン、delegatecall)	プロキシパターン、delegatecall、ストレージ衝突を明確に検索してから N/A と宣言
「検証なし『該当なし』」	早期スコープ削減は脆弱性を見逃す	ガイドラインセクションスキップ前にコードベース検索で検証
「アーキテクチャは直線的、分析不要」	明白なアーキテクチャにも微妙な信頼境界がある	オンチェーン/オフチェーン配置、アクセス制御フロー、外部依存を分析
「この一般的な落とし穴はこのコードベースに適用されない」	すべてのコードベースに一般的な落とし穴がある	grep/コード検索でガイドライン落とし穴を体系的にチェック
「テストがある、テストガイドラインは満たされた」	テスト存在 ≠ テスト品質	カバレッジ、プロパティテスト、統合テスト、失敗ケースをチェック
「一般的なベストプラクティスを提供できる」	一般的なアドバイスは実行可能でない	ファイル:行参照を含むプロジェクト固有の結果を提供
「ユーザーは結果から改善すべきことを知っている」	優先順位なし結果 = 実行計画なし	特定の次のステップを含む優先順位付けされた改善ロードマップを生成

---

注釈

• 関連セクションのみ分析 (アップグレードが存在しない場合は仮説はしません)
• プラットフォームに適応 (Solidity、Rust、Cairo など)
• 利用可能なツール (Slither など) を使用しますが、なくても機能します
• すべての結果にファイル参照と行番号を提供します
• コードから推測できない設計判断について質問します

---

開始準備完了

必要な情報:

• コードベースへのアクセス
• プロジェクト目標のコンテキスト
• 既存のドキュメント仕様
• デプロイ計画に関する情報

Trail of Bits のベストプラクティスを使用してコードベースを分析し改善しましょう!