clarity-check

Clarity チェック スキル

Clarity スマートコントラクトのデプロイ前検証ゲートです。構文エラー、非推奨キーワード、送信者チェックの誤り、エラー伝播の問題、テストの不足に対して自動チェックを実行します。デプロイ操作には、既存の contract スキルと組み合わせて使用します。

使用方法

これはドキュメントのみのスキルです。エージェントはこのファイルを読み、利用可能なチェックを把握して、スキルフレームワークを通じて実行します。以下の CLI インターフェースは、予定されている実装を説明しています。

bun run clarity-check/clarity-check.ts <subcommand> [options]

サブコマンド

validate

Clarity コントラクトファイルに対して、すべての自動チェックを実行します。

bun run clarity-check/clarity-check.ts validate --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

オプション：

• --source（必須）— 検証する .clar ソースファイルのパス
• --project-dir（任意）— clarinet check との連携に使用する Clarinet プロジェクトディレクトリ。省略した場合は、ソースパスから自動検出されます

出力：

{
  "file": "contracts/my-contract.clar",
  "passed": false,
  "checks": [
    {
      "name": "syntax",
      "status": "pass",
      "description": "clarinet check passes"
    },
    {
      "name": "deprecated-keywords",
      "status": "fail",
      "description": "Deprecated keywords found",
      "findings": [
        {
          "line": 15,
          "keyword": "block-height",
          "replacement": "stacks-block-height",
          "severity": "warning"
        }
      ]
    },
    {
      "name": "sender-checks",
      "status": "warn",
      "description": "Sender check analysis",
      "findings": [
        {
          "line": 22,
          "issue": "Token transfer uses contract-caller instead of tx-sender",
          "recommendation": "Use tx-sender for token operations to preserve human identity through proxies",
          "severity": "warning"
        }
      ]
    }
  ],
  "summary": {
    "total": 7,
    "pass": 5,
    "fail": 1,
    "warn": 1
  }
}

checklist

コントラクトのデプロイ前チェックリストを、人が読みやすい形式で生成します。自動チェックと手動確認項目を組み合わせます。

bun run clarity-check/clarity-check.ts checklist --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

オプション：

• --source（必須）— Clarity ソースファイルのパス
• --project-dir（任意）— Clarinet プロジェクトディレクトリ

出力：

{
  "file": "contracts/my-contract.clar",
  "automated": [
    {"check": "clarinet check passes", "status": "pass"},
    {"check": "No deprecated keywords", "status": "fail", "details": "Found: block-height on line 15"},
    {"check": "Correct sender checks", "status": "warn", "details": "1 finding"},
    {"check": "Error propagation uses try!", "status": "pass"},
    {"check": "No dead code or unused features", "status": "pass"},
    {"check": "Events follow structured format", "status": "pass"},
    {"check": "Error codes are unique", "status": "pass"}
  ],
  "manual": [
    "Verify tests exist and pass (npm test)",
    "Check execution costs in clarinet console (::get_costs)",
    "Review post-conditions for all token operations",
    "Verify trait whitelisting if external contracts are called",
    "Test on testnet before mainnet deployment",
    "Document contract address after deployment"
  ]
}

実行するチェック

自動チェック

チェック	検出する内容
構文	clarinet check のエラーと警告
非推奨キーワード	block-height（stacks-block-height を使用）、その他の旧式キーワード
送信者チェック	トークン操作における tx-sender と contract-caller の誤用
エラー伝播	復旧可能なエラーに対して、より適切な try! ではなく unwrap! を使用している箇所
デッドコード	未使用のプライベート関数、到達不能な分岐
イベント形式	notification／payload 構造が欠けているイベント
エラーコードの一意性	重複するエラーコード定数
パブリック関数の戻り値	(response ok err) 戻り値の型が欠けている関数

手動チェック（チェックリストのみ）

チェック	重要な理由
テストが存在し、合格すること	動作が検証されていることを保証します
実行コスト	ブロック制限の超過を防ぎます
ポストコンディション	予期しないトークン移転からユーザーを保護します
トレイトのホワイトリスト登録	許可されていないコントラクトとのやり取りを防ぎます
テストネットへのデプロイ	メインネット公開前に問題を発見します

注意事項

• 構文チェックには、ローカルに clarinet CLI をインストールする必要があります
• clarinet が見つからない場合、構文チェックは警告とともにスキップされます
• 静的解析のみを行います。コントラクトの実行やテストの実行は行いません
• テストを生成するには clarity-test-scaffold を使用し、その後、詳細なレビューには clarity-audit を使用してください
• コンパイラーでは強制されない、Clarity 固有のベストプラクティスチェックを追加することで、clarinet check を補完します