Suggest Tidying - AI基盤の安全・持続可能なコード改善ワークフロー

背景と目的

プロジェクトのコードベースが成長するにつれ、可読性の維持と技術的負債の管理がより重要になっています。
しかし、大規模なリファクタリングはスケジュールへの負担が大きくロジック変更のリスクも伴います。

そこで、Kent Beckの「Tidy First?」哲学を取り入れ機能変更を伴わずに構造のみを整える「Tidying（整頓）」文化の導入を提案します。重要なのは「非常に小さく完璧に安全でレビューしやすい」変更を持続することです。

このプロセスを負担なく実行するためにAIエージェントを活用した自動化ワークフローも併せて導入したいと思います。

Tidyingとは？

リファクタリングのサブセットであり機能（動作）は絶対に変更せずコードの配置や見た目だけを綺麗に整える作業

核心となる原則

• 安全第一：ランタイムの動作が変わる可能性が0%であること
• 原子的修正：一度に一つずつ、独立したコミットに分離すること
• 容易なレビュー：diffを見るだけで即座にMerge可能だと判断できるほど単純であること

AI自動化ワークフロー

毎回手動で修正箇所を探すのではなく、直近の作業コミットを分析してTidyingの機会を提案してくれるAIワークフローを構築しました。

AI指示のための事前準備

AIに適切なコンテキストを与えるために、以下の設定をプロジェクトに追加します。

1. ドキュメントの配置

以下の2つのファイルを docs フォルダ（もしくは指定のフォルダ）に保存します。AIはこのルールに従って動作します。

• docs/suggest-tidying.md: Tidyingの判断基準とルール
• • suggest-tydings.md
• docs/workflow-tidying.md: 作業を実行するための手順書
• • tyding-workflow.md

2. package.json の設定

AIが最近のコミットハッシュを取得できるように、以下のスクリプトを追加

{
  "scripts": {
    "tidy-target-commits": "git log --no-merges --pretty=format:'%H' -n"
  }
}

AI自動化ワークフローと実行例

毎回手動で修正箇所を探すのではなく、直近の作業コミットを分析してTidyingの機会を提案してくれるAIワークフローを構築

Claude Code (CLI / Web) での実行例

Claude Codeを使用する場合、作成したドキュメントをコンテキストとして渡して実行

docs/suggest-tidying.md と docs/workflow-tidying.md を読み込んでください。
workflow-tidying.md の手順に従って、現在のブランチの最近の変更に対するTidying案を提示してください。コマンドは yarn を使用してください。

CLAUDE.md の設定（Claude Code用）

ルートディレクトリに CLAUDE.md ファイルを作成し、カスタムコマンドを定義します。これにより /tidy コマンドが使用可能になります。

# Commands
/tidy: docs/suggest-tidying.md と docs/workflow-tidying.md をコンテキストとして読み込み、定義されたワークフローに従ってコードの整頓案を提示する。

Cursor / IDE での実行例

チャットウィンドウまたはComposer機能で以下のように入力

docs/suggest-tidying.md、docs/workflow-tidying.md
上記のドキュメントに基づいてTidyingの提案を行ってください。

.cursorrules の設定（Cursor用）

ルートディレクトリに .cursorrules ファイルを作成（または追記）し、AIにデフォルトの振る舞いを教えます。

# Tidying Rules
ユーザーが「tidy」または「整頓」に関連する要求をした場合、必ず以下の手順に従ってください
1. docs/suggest-tidying.md のガイドラインを厳守する。
2. docs/workflow-tidying.md のワークフローを順守して実行する。
3. コマンド実行時は必ず yarn を使用する。
# Tidying Rules
ユーザーが「tidy」または「整頓」に関連する要求をした場合、必ず以下の手順に従ってください
1. docs/suggest-tidying.md のガイドラインを厳守する。
2. docs/workflow-tidying.md のワークフローを順守して実行する。
3. コマンド実行時は必ず yarn を使用する。

適用するTidying手法

主要な手法は以下の通り

1. Guard Clauses：ネストされたif文を早期リターン（Early Return）で平坦化
2. Dead Code Removal：使用されていないコードや不要なコメントの削除
3. Normalize Symmetries：類似したロジックを類似した形状に統一
4. New Interface, Old Implementation：既存の実装を呼び出す新しいインターフェース（Pass-through）を作成
5. Reading Order：読む順序に合わせて関数や変数の宣言位置を調整
6. Explaining Variables：複雑な式を意味のある変数として抽出
7. Extract Helper：明確な目的を持つ小さなコードブロックをヘルパー関数として抽出
8. Explaining Comments：難解な部分に明確なコメントを追加して可読性を向上
9. Magic Numbers to Constants：100や"error"などのハードコーディングされた値を定数に変更
10. Collapse Hierarchy：不要に深い継承やフォルダ構造の単純化

導入手順まとめ

• docs/suggest-tidying.md (プロンプトガイド) の追加
• docs/workflow-tidying.md (実行手順) の追加
• package.jsonに yarn tidy-target-commits スクリプトを追加
• .cursorrules および CLAUDE.md の設定追加
• チームメンバーによるAIを活用したTidyingの試行とフィードバック共有

期待される効果

• コードレビュー時間の短縮（読みやすいコードへ）
• 機能開発前のウォーミングアップによるコード理解度の向上
• 大規模なリファクタリングなしでの漸進的なコード品質向上

参考資料

Kent Beck, Tidy First?
Claude Code Meetup Seoul の発表資料