codemod

Codemod のベストプラクティス

AI エージェントと LLM 向けに設計された、Codemod（JSSG、ast-grep、ワークフロー）の包括的なベストプラクティスガイドです。11 のカテゴリにわたる 48 のルールを、影響度の高い順に掲載し、自動リファクタリングとコード生成の指針を示します。

適用するタイミング

以下の場合に、このガイドラインを参照してください。

• JSSG または ast-grep を使って新しい codemod を作成するとき
• 移行用のワークフロー設定を設計するとき
• パターンマッチングや AST トラバーサルの問題をデバッグするとき
• パフォーマンスと安全性の観点から codemod のコードをレビューするとき
• 変換を検証するためのテストフィクスチャを設定するとき

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	AST の理解	重大	ast-
2	パターンの効率性	重大	pattern-
3	パース戦略	重大	parse-
4	ノードのトラバーサル	高	traverse-
5	セマンティック分析	高	semantic-
6	編集操作	中〜高	edit-
7	ワークフロー設計	中〜高	workflow-
8	テスト戦略	中	test-
9	状態管理	中	state-
10	セキュリティと機能	低〜中	security-
11	パッケージ構成	低	pkg-

クイックリファレンス

1. AST の理解（重大）

• ast-explore-before-writing - パターンを書く前に AST Explorer を使う
• ast-understand-named-vs-anonymous - 名前付きノードと匿名ノードを理解する
• ast-use-kind-for-precision - 精度を高めるために kind 制約を使う
• ast-field-access-for-structure - 構造的なクエリにはフィールドアクセスを使う
• ast-check-null-before-access - プロパティにアクセスする前に null を確認する

2. パターンの効率性（重大）

• pattern-use-meta-variables - 柔軟なマッチングにはメタ変数を使う
• pattern-avoid-overly-generic - 汎用的すぎるパターンを避ける
• pattern-combine-with-rules - ルール演算子とパターンを組み合わせる
• pattern-use-constraints - 再利用可能なマッチングロジックには制約を使う
• pattern-use-relational-patterns - コンテキストには関係パターンを使う
• pattern-ensure-idempotency - パターンの冪等性を確保する

3. パース戦略（重大）

• parse-select-correct-parser - ファイル形式に適したパーサーを選択する
• parse-handle-embedded-languages - parseAsync で埋め込み言語を処理する
• parse-provide-pattern-context - あいまいなパターンにはコンテキストを指定する
• parse-early-return-non-applicable - 対象外のファイルでは早期に return する

4. ノードのトラバーサル（高）

• traverse-use-find-vs-findall - 単一の一致には find()、複数の一致には findAll() を使う
• traverse-single-pass-collection - 1 回のトラバーサルで複数のパターンを収集する
• traverse-use-stopby-for-depth - stopBy でトラバーサルの深さを制御する
• traverse-use-siblings-efficiently - 効率的に兄弟ノードをたどる
• traverse-cache-repeated-lookups - 繰り返し行うノード検索をキャッシュする

5. セマンティック解析（高）

• semantic-use-file-scope-first - まずファイルスコープのセマンティック解析を使用します
• semantic-check-null-results - セマンティック解析の結果が null の場合に対処します
• semantic-verify-file-ownership - ファイルをまたいで編集する前に、ファイルの所有権を確認します
• semantic-cache-cross-file-results - ファイルをまたぐセマンティック解析の結果をキャッシュします

6. 編集操作（中〜高）

• edit-batch-before-commit - コミット前に編集をまとめます
• edit-preserve-formatting - 編集箇所の周辺の書式を維持します
• edit-handle-overlapping-ranges - 編集範囲の重複に対処します
• edit-use-flatmap-for-conditional - 条件付きの編集には flatMap を使用します
• edit-add-imports-correctly - 適切な位置にインポートを追加します

7. ワークフロー設計（中〜高）

• workflow-order-nodes-by-dependency - 依存関係に基づいてノードの順序を決めます
• workflow-use-matrix-for-parallelism - 並列処理にはマトリックス戦略を使用します
• workflow-use-manual-gates - 重要なステップには手動ゲートを設けます
• workflow-validate-before-run - ワークフローの実行前に検証します
• workflow-use-conditional-steps - 動的なワークフローには条件付きステップを使用します

8. テスト戦略（中）

• test-use-fixture-pairs - 入力と期待値のフィクスチャをペアで使用します
• test-cover-edge-cases - テストフィクスチャでエッジケースを網羅します
• test-use-strictness-levels - 適切なテストの厳格さを選択します
• test-update-fixtures-intentionally - 意図を持ってテストフィクスチャを更新します
• test-run-on-subset-first - 全体を実行する前に、ファイルの一部を対象にテストします

9. 状態管理（中）

• state-use-for-resumability - 再開可能なマイグレーションには状態を使用します
• state-make-transforms-idempotent - 安全に再実行できるよう、変換を冪等にします
• state-log-progress-for-observability - 長時間実行されるマイグレーションの進捗をログに記録します

10. セキュリティと機能（低〜中）

• security-minimize-capabilities - 要求する機能を最小限に抑えます
• security-validate-external-inputs - 外部入力を使用前に検証します
• security-review-before-running-third-party - サードパーティ製 codemod を実行前に確認します

11. パッケージ構成（低）

• pkg-use-semantic-versioning - パッケージにはセマンティックバージョニングを使用します
• pkg-write-descriptive-metadata - パッケージのメタデータを具体的に記述します
• pkg-organize-by-convention - 慣例に従ってパッケージを整理します

使用方法

詳しい説明やコード例については、個々のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

完全版ドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。