guidelines-advisor

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

目的

コードベースを体系的に分析し、Trail of Bits の開発ガイドラインに基づいて助言します。

1. ドキュメントと仕様を作成する（平易な英語による説明、アーキテクチャ図、コードドキュメント）
2. オンチェーン／オフチェーンのアーキテクチャを最適化する（該当する場合のみ）
3. アップグレード可能性のパターンをレビューする（プロジェクトにアップグレード機能がある場合）
4. delegatecall／プロキシの実装を確認する（存在する場合）
5. 実装品質を評価する（関数、継承、イベント）
6. よくある落とし穴を特定する
7. 依存関係をレビューする
8. テストスイートを評価し、改善案を提案する

フレームワーク：安全なコントラクトの構築 — 開発ガイドライン

---

仕組み

フェーズ 1：調査とコンテキストの把握

コードベースを調査して、次の項目を把握します。

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

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

次の作成を支援します。

• 平易な英語によるシステムの説明
• アーキテクチャ図（Solidity では Slither のプリンターを使用）
• コードドキュメントの推奨事項（Solidity では NatSpec）

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

次の項目を分析します。

• オンチェーンとオフチェーンのコンポーネントの分布（該当する場合）
• アップグレード可能性のアプローチ（該当する場合）
• delegatecall プロキシのパターン（存在する場合）

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

次の項目を評価します。

• 関数の構成と明確さ
• 継承構造
• イベントのロギング方法
• よくある落とし穴の有無
• 依存関係の品質
• テストのカバレッジと手法

フェーズ 5：推奨事項

次の内容を提示します。

• 優先順位を付けた改善案
• ベストプラクティスに関するガイダンス
• 実行可能な次のステップ

---

評価領域

スマートコントラクト開発のあらゆる側面を網羅する、11 の包括的な領域を分析します。詳細な基準、ベストプラクティス、具体的な確認項目については、ASSESSMENT_AREAS.md を参照してください。

クイックリファレンス：

1. ドキュメントと仕様

   • 平易な英語によるシステムの説明
   • アーキテクチャ図
   • NatSpec の網羅性（Solidity）
   • ドキュメントの不足箇所の特定

2. オンチェーンとオフチェーンの計算

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

3. アップグレード可能性

   • 移行とアップグレード可能性のトレードオフ
   • データ分離のパターン
   • アップグレード手順のドキュメント化

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）	N/Aと判断する前に、プロキシパターン、delegatecall、ストレージの衝突を検索する
検証せずに「該当なし」とする	対象範囲を早まって狭めると、脆弱性を見落とします	ガイドラインのセクションを省略する前に、コードベースを明示的に検索して確認する
「アーキテクチャは単純なので、分析は不要」	一見わかりやすいアーキテクチャにも、微妙な信頼境界があります	オンチェーン／オフチェーンの構成、アクセス制御の流れ、外部依存関係を分析する
「よくある落とし穴はこのコードベースには当てはまらない」	どのコードベースにも、よくある落とし穴があります	grep／コード検索を使って、ガイドラインにあるすべての落とし穴を体系的に確認する
「テストが存在するので、テストのガイドラインは満たしている」	テストの存在 ≠ テストの品質	カバレッジ、プロパティベーステスト、統合テスト、失敗ケースを確認する
「一般的なベストプラクティスを提示すればよい」	一般論では具体的な行動につながりません	file:line形式の参照を付けて、プロジェクト固有の調査結果を提示する
「調査結果を見れば、ユーザーは改善点がわかる」	優先順位のない調査結果では、行動計画を立てられません	具体的な次のステップを含む、優先順位付きの改善ロードマップを作成する

注意事項

• 関連するセクションのみを分析します（記載がないアップグレードについて推測で述べることはありません）。
• お使いのプラットフォーム（Solidity、Rust、Cairo など）に合わせて対応します。
• 利用可能なツール（Slither など）を使用しますが、利用できない場合も作業を進めます。
• すべての指摘に、ファイル参照と行番号を記載します。
• コードから判断できない設計上の決定については、質問します。

---

さあ始めましょう

必要なもの：

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

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