tidy-code

コードベースを16の tc-* 構造品質カテゴリに照らしてレビューし、後続のエージェントまたは人間が実行できる統合計画を1つ作成します。レビューは読み取り専用です。状態ファイルは再開用の自分専用の作業メモであり、人間によるレビュー用ではありません。ホストの todo ツールにある4つのフェーズに沿って進めてください。

必ず守ること（最初に読む）

• ソースファイルは絶対に変更しないでください。 このスキルが書き込むファイルは、状態ファイルと最終計画のみです。
• 明示的に呼び出された場合のみ実行してください。 /tidy-code を使って実行し、自然言語のリクエストから自動的に起動しないでください。
• すべての指摘を分類してください。 Grep で確認できる特定行の具体的なコード断片を引用する FALSIFIABLE（反証可能）か、証拠が解釈に基づく OPINION（意見）のいずれかに分類します。
• 反証可能な引用は、下書きに追加する前にすべて Grep で検証してください。 一致がない場合、または行番号が異なる場合は、その指摘を削除します。
• 深度1。 敵対的レビューは1回だけ実施します。レビュー担当者はファイルレビューを再実行しません。
• 出力ファイルは1つだけです。 最終計画だけがユーザー向けの成果物です。パスのみを提示してください。

除外するパス

以下では探索もレビューも行わないでください。

• ドットディレクトリ：.git/、.venv/、.agents/、.claude/、IDE／エージェント用の足場
• node_modules/、vendor/、bower_components/、*/third_party/* または */vendor/*
• ビルド出力：dist/、build/、target/、out/、coverage/、__pycache__/、.next/、.cache/
• ソース以外のファイル：設定ファイル（JSON/YAML/TOML）、Markdown、ロックファイル、圧縮済みアセット、画像、フォント
• 生成コード（@generated、DO NOT EDIT など）、マイグレーション、.d.ts ファイル、20行未満のスクリプト
• .gitignore に記載されたもの — その指定を優先してください

状態ファイル

作業状態は .agents/local/state/tidy-code-YYYY-MM-DD.md に保存します（date +%Y-%m-%d から日付を取得）。今日の日付のファイルが存在し、すべて確認済みの場合は、-2、次に -3 を付けてください。これは自分専用の作業メモであり、gitignore 対象で、ユーザーには見せず、コミットもしません。

開始時： .agents/local/state/ がなければ作成し、その後 .agents/local/state/tidy-code-*.md を glob します。最新のファイルに未チェック項目があれば、そのファイルを使って再開します。そうでなければ、新しいファイルを作成します。ファイルを削除すると、最初からやり直せます。

# tidy-code — 2026-07-17

## Batch 1
- [ ] src/auth/session.ts
- [ ] src/auth/token.ts (test)

## Findings draft
- [tc-05] Silent Failure — src/auth/session.ts:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly

各ワーカーの作業が戻ったら、ファイルを [x] にします。ワーカーは状態ファイルに書き込まないでください — 同時書き込みにより内容が破損します。

フェーズ1 — 探索（機械的に実行し、サブエージェントは使わない）

除外条件を守りながら、Glob またはシェルのリスターを使って、ソースファイルをインラインで列挙します。利用できないツールがある場合は、rg --files、次に fd --type f、最後に find . -type f の順で使用してください。各ファイルをアプリまたはテストに分類します（テストは *.test.*、*.spec.*、*_test.*、test_* および各言語の同等のパターンです。/tests/ 内にあるファクトリー、フィクスチャー、ヘルパーなど、テストそのものではないファイルはアプリに分類します）。アプリファイルが残らなければ、ユーザー向けエラーを出して終了します。1000を超える場合は、先にサブディレクトリなどに範囲を絞るようユーザーに依頼してください。

ファイルを1ワーカーあたり8〜12個のバッチに分けます（アプリファイルが20個未満のリポジトリでは、1バッチにまとめます）。チェックリストを状態ファイルに書き込み、ただちにフェーズ2へ進みます — 途中で止まったり、要約したり、質問したりしないでください。

フェーズ 2 — レビュー（バッチ単位で並列実行）

バッチごとにワーカーサブエージェントを 1 つディスパッチします。同時実行は最大 5 つとし、各ウェーブの Agent 呼び出しはすべて 1 つのメッセージにまとめて並列実行します。ワーカー： subagent_type: general-purpose、model: haiku（ホストの低コストモデル用エイリアス。固定バージョンは指定しないでください）。各ワーカーには、ファイル一覧（app/test の区別付き）、以下の指摘行フォーマット、インラインのガードレール 読み取り専用 — ファイルは変更せず、指摘のみを報告すること。 を伝えます。ワーカーはユーザーのプロジェクトルートから実行されるため、ディスパッチする前に、ブリーフに記載する references/… の各パスを、このスキルのディレクトリを基準とした絶対パスに展開します。

各ワーカーは次の手順を実行します。

1. 最初に references/principles-quick-ref.md を読みます。該当 ID の候補が現れた場合にのみ、カテゴリ別のリファレンスを読み込みます。重大度の分類時には references/severity-rubric.md を読み込みます。
2. 並列ツール呼び出しでバッチを読み込み、app ファイルを 16 カテゴリすべてに照らしてレビューします。テストファイルは tc-09、tc-03、tc-13 のみを対象とし、それ以外はスキップします。
3. 独自の Grep 呼び出しで反証可能性ゲートを適用します。FALSIFIABLE の指摘には検証済みのパターンを含めます。検証できない引用は報告せず、除外します。
4. 提案する書き換えが違反を解消し、新たな違反を生じさせないことを検証します。修正は 1 回まで試みます。それでも検証できない場合は、提案する修正を番兵値 [Suggested rewrite could not be verified — manual rewrite required] に置き換えます。
5. 指摘を簡潔な 1 行の箇条書きで返します（OPINION の指摘では grep: を省略します）。

- [tc-05] Silent Failure — src/api/client.py:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly

ワーカーが失敗するか、解析可能な結果を何も返さない場合は、そのバッチを 1 回だけ再ディスパッチします。再度失敗した場合は、そのファイルを未チェックのままにし、完了時にその旨を記載します。

オーケストレーターであるあなたは、各ワーカーの指摘を状態ファイルのドラフトに追記し、対象ファイルにチェックを付けます。追記時に重複を排除します。同一ファイルの同一行に同じカテゴリの指摘がある場合は 1 件だけ残します。1 つの根拠が複数カテゴリを裏付ける場合（tc-04 と tc-09 の両方に該当する UserManager など）は、重大度の高い指摘を残し、他のカテゴリもその行に記載します。

カテゴリ別リファレンス：tc-01 composition-over-inheritance.md · tc-02 dependency-injection.md · tc-03 guard-clauses.md · tc-04 single-responsibility.md · tc-05 fail-fast.md · tc-06 least-surprise.md · tc-07 tell-dont-ask.md · tc-08 immutability.md · tc-09 naming.md · tc-10 functional-core-imperative-shell.md · tc-11 magic-numbers.md · tc-12 duplicate-logic.md · tc-13 comment-debt.md · tc-14 type-escape.md · tc-15 query-in-loop.md · tc-16 unsafe-sink.md（すべて references/ 内）。

フェーズ 3 — 敵対的レビュー（1 ラウンド）

ホストのデフォルトモデルを使用するレビュアーサブエージェントを 1 つディスパッチし、指摘ドラフト全体、リポジトリルート、references/adversarial-review-prompt.md のプロンプトを渡します。レビュアーは引用された grep を自ら再実行し、誤検知、重大度の誇張、実行不能な書き換え案を検証し、欠落している指摘を特定して、KEEP／REVISE／DROP の判定一覧を返します。

判定は自分でドラフトに反映します。DROP は削除し、REVISE は取り込み、grep で検証済みの追加指摘は追記します。深さは 1 です。判定の内訳にかかわらず、2 回目のラウンドは絶対にディスパッチしないでください。

フェーズ 4 — レポート

references/final-plan-format.md を読み込み、レビュー済みの指摘を自己完結型の計画書として作成します。

1. リポジトリルートに docs/ がある場合 → docs/YYYY-MM-DD-tidy-code-plan.md。
2. ない場合 → リポジトリルートに YYYY-MM-DD-tidy-code-plan.md。

番兵値が残っている指摘は <manual_review> に記載します。ユーザーへの返信ではこのパスのみを伝え、状態ファイルや中間情報には一切触れないでください。

避けるべき失敗パターン

• テストファイルにカタログ全体を適用しないでください。対象は tc-09／tc-03／tc-13 のみです。tc-02 と tc-10 は、テストでは通常の副作用を伴うセットアップを検出します。
• /tests/ 内のファクトリー、フィクスチャ、ヘルパーをテストファイルとして扱わないでください。これらはアプリケーションコードであり、カタログ全体が対象です。
• コメントに関する指摘を別のスキルに回さないでください。コメントの有無と TODO／FIXME／HACK／XXX マーカーは、このスキルの対象です（tc-13、許可リスト：ドックブロック、リンターディレクティブ、理由が自明でないもの）。
• ファイルをまたぐ重複ロジックを報告しないでください。対象外です（principles-quick-ref.md § スコープの境界を参照）。
• 影響範囲が 5 ファイルを超えるファイル横断の名前変更を、安全な変更として提示しないでください。指摘に blast radius: N files — confirm before applying と記載してください（tc-09）。
• 信頼度、難易度、リスクのスコアを追加しないでください。このスキルでは指摘を報告しますが、優先順位付けは行いません。
• 十分に見せるために、内容の薄いバッチを水増ししないでください。問題のないファイルで指摘が 0 件でも、正当な結果です。

完了

すべての状態ファイルのチェックボックスにチェックが入り、計画が作成されたら作業完了です。計画のパスと、重要度ごとの指摘件数を一行でまとめて返信してください。コミットやビルド・テストコマンドの実行、状態ファイルの削除は行わないでください。