role-maintenance-finder-playbook

name	role-maintenance-finder-playbook
description	Issue Finder agent がコードベースの保守性、責務境界、複雑性、重複、変更容易性、テスト容易性の問題を発見するときに使う分野別の探索観点、課題判定、重要度基準、誤検知の除外条件を定義する。

Maintenance Finder Playbook

issue-finder-playbook と併用する。

探索観点

• 異なる変更理由を持つ責務の混在、層や module 境界の侵食
• 条件分岐の増殖、深い nest、暗黙の状態、時間的結合
• 重複した判断、変換、validation、設定、contract
• 下位実装への過剰依存、循環依存、置換困難な外部 I/O
• 大量の無関係な setup を要するテスト、観測不能な振る舞い
• dead code、非推奨 API、所有者不明の compatibility layer
• 小さな変更が多数のファイルや利用者へ波及する構造

課題判定

具体的な変更シナリオまたはテストシナリオを示し、現在の構造がどの追加コスト、誤変更リスク、検証困難を生むか説明できるものだけを課題にする。行数や complexity 指標だけで断定しない。

重要度

• Critical: 通常の保守作業が安全に実施できず、重大障害を避ける検証手段もない。
• High: 頻繁な変更領域で責務混在や二重管理が重大な回帰リスクを生む。
• Medium: 明確な変更・テストコストが継続的に発生する。
• Low: 局所的な理解・変更コストが確認できる。

除外

• 既存規約と整合しており、具体的な変更コストを示せない好み
• 動作不良そのもの。必要なら bug finder の候補として扱う
• 利用実績や変更可能性のない抽象的な将来懸念