anti-koshary

Anti-Koshary

Koshary とは、ご飯とパスタとレンズ豆を一皿に盛った料理です。それぞれは美味しいのですが、一度混ぜてしまうと、もう二度と分けることはできません。Koshary コードも同じ失敗です。健全なスタックの各層が、どの部分も単独では取り出せなくなるまでかき混ぜられてしまった状態です。

このスキルは、そのかき混ぜに対処するためのものです。あなたが探すのは、その症状です:

• コントローラー、コンポーネント、ルートハンドラーの中に住み着いたビジネスロジック
• 同じバリデーションやフォーマット処理が複数のファイルにコピー＆ペーストされている
• 誰も読まなくなったほどに巨大化した関数やファイル
• 元が取れなかった抽象化。分離しておくべき理由しかなかった呼び出し元同士を結合させている

そして、レポートのもっと下の方には、同じ皿に溜まりがちだが、ユーザーがここに来た目的ではない問題もあります:

• 誰も見直さなかった、シークレット、欠落した認証チェック、未検証の入力
• 何年も前にバージョン固定され、静かに CVE を抱えている依存関係

設計上スタンドアロン

このスキルは他の何にも依存しません。相棒のスキルも、設定ファイルも、課題トラッカーも、事前のセットアップ手順も不要です。どんなリポジトリでも、どんなスタックでも、ゼロから実行できます。編集するときもそのままにしておいてください。必要なものはすべて、それ自身のディレクトリの中にあります。

適用される場面

ユーザーが、既存のコードベースのどこに問題があるのかを知りたい、あるいはそれを片付けたいと考えている場合です。新しい機能を構築してほしいと依頼している場合には適用されません。それは前向きな作業であり、機能開発の途中での監査はノイズを増やすだけです。「この関数をリファクタリングして」という依頼にも適用されません。それは作業の実行を求めるものであり、調査を求めるものではありません。

二段階ルール

パス 1 は報告する。パス 2 は修正する。ユーザーが進めと言うまで、パス 2 からは何も起こらない。

たとえ修正が明白で一行であっても、この線は守ってください。レポートこそが、ユーザーが実際に求めている成果物です。見たことのない指摘は、検討したことのない指摘であり、レビュー前に適用された修正は、diff から逆算しなければならない修正です。ユーザーの承認は、どの指摘が本物かをユーザーが決める瞬間でもあります。あなたはそのうちのいくつかについては間違えますが、それを安価に捕まえられるのがパス 1 です。

ステップ 0 — 何かを探す前に全体を把握する

4 つの質問に、ユーザーに向けて数行で声に出して答えます:

1. スタックは何か？ 言語、フレームワーク、パッケージマネージャー（マニフェストだけでなくロックファイルを読んでください。どちらのマネージャーが本当に使われているかが分かります）。
2. どこまでを監査するのか？ リポジトリ全体か、1 つのディレクトリか、直近の diff か。大きな対象では、始める前に境界を合意してください。無制限の網羅は、範囲がだらりと広がるか、あるいは黙ってサンプリングするかのどちらかになり、黙ってサンプリングされた結果は、健全なお墨付きのように読めてしまいます。
3. テストは存在するか、そして通るか？ 実行してください。これが、あなたが後で何を主張してよいかを決めます。
4. 作業ツリーはクリーンか？ git status --porcelain。もし汚れているなら、その旨を伝え、パス 2 の前にユーザーへコミットまたはスタッシュを依頼してください。ユーザーが git reset できることこそが、修正パスを支える唯一の安全網です。

テストがなければ、そのことをはっきり伝え、その結果を監査全体に通してください: いかなる変更も「安全」または「機能的に同等」と表現してはいけません。 テストがなければ、「ビルドはまだ通る」ことは、コードがパースでき、インポートが解決できることを証明するだけであり、振る舞いについては何も証明しません。代わりに、最もリスクの高い変更を 2 つか 3 つ挙げ、それらに触れる前に、1 つの簡単なテストがどこで確信の大部分を取り戻せるかを伝えてください。

パス 1 — 検出と報告

以下の 7 つのセクションをこの順序で進め、それぞれを小さな表として報告してください。すべての検出項目について、それが何か、どこか（ファイル + 行、クリック可能なパスとして）、なぜ重要か、どのような修正を適用するかを示してください。

各検出項目は、それが当てはまる最も早いセクションで一度だけ報告してください。重複したバリデータはセクション 2、4、5 に同時に属しますが、それを 3 回リストするのは、表の衣をまとった水増しです。

見つけやすさではなく、結果の重大さで優先順位をつけてください:

優先度	意味
Critical	生きた認証情報、または今すぐ悪用できる穴。依然として他のすべてを上回る唯一の分類です。
High	複数の場所に実装された 1 つのルールで、いずれ乖離するもの、またはすでに同じロジックを他の場所で書き直さざるを得なくなっている崩壊 — まだ発生していないバグ。および実際の脆弱性。
Medium	変更のたびにメンテナンス時間を要する、またはバグを隠すもの — まさにコシャリそのもの。
Low	整理整頓。すでにそのファイルを触っているついでにやる価値があるもの。

検出項目は、その結果を挙げられる場合にのみ価値を持ちます。「この関数は長い」は検出項目ではありません。「この 400 行のハンドラは認証、バリデーション、DB 書き込みを混在させているため、編集時に 210 行目の認証チェックを見落としやすい」は検出項目です。「つまり…」という文を完成できなければ、それは捨ててください — 水増しされたレポートは、ユーザーに全体をざっと流し読みする癖をつけさせるだけです。

セクション 1〜5 の前に references/structural-decay.md を読んでください。そこには、コストを生む重複と偶然の重複を分けるテストと、崩壊したレイヤーの兆候が書かれています。

1. レイヤーの崩壊 — まさにコシャリ

このスキルの名前の由来となったものです。単一のファイルや関数が、次のうち複数を担っていないか探してください: トランスポート（リクエストの解析、ステータスコード）、ビジネスルール（何が許可され、何が計算されるか）、永続化（クエリ、書き込み、キャッシュ）、プレゼンテーション（レンダリング、フォーマット）。

兆候: React コンポーネントやルートハンドラ内の ORM 呼び出し。純粋なルールであるべき関数にリクエストオブジェクトが到達し、ジョブやテストから呼び出せなくなっている。UI にビジネスルールがあり、UI が禁じているものを API が受け入れてしまう。すべてがインポートし、逆にすべてをインポートし返す utils モジュール。

結果で報告してください: 「価格ルールがチェックアウトコンポーネントに存在するため、モバイルクライアントと管理パネルがそれぞれ再実装している」 は響きます。「これは関心の分離に違反している」 は響きません。

2. 重複したロジック

テストは「これらは似ている」ではありません。次のとおりです: このルールが変わったら、何箇所を同時に変更しなければならず、誰かが 1 つを見落とすか? バリデーション正規表現の 3 つのコピーはバグ生成器です。たまたまどちらも配列をループする 2 つの関数は何でもありません。

定量化してください — 「この正規表現は 4 ファイルに現れる。ルールを変えるには 4 つすべてを編集する必要がある」 — そして偶然か結合しているかの区別についてはリファレンスを参照してください。これはモデルが最も頻繁に間違える判断です。

3. 読まれなくなった関数とファイル

長さは症状であり、検出項目ではありません。探すべきもの: 変更する理由が複数ある。ネストが 3 レベルを超える。動作を切り替える真偽値パラメータ。存在したがっている関数の境界を示すコメント。

リファレンスにはサイズとチャーンのコマンドがあります。まず交差部分を報告してください — 常に変化する大きなファイルこそが痛みの場所であり、2 年間誰も触っていない大きなファイルは通常、リスクを冒す価値がありません。

4. デッドコードと明白なリファクタリング

未使用のインポートとローカル変数、到達不能なコード、誤解を招く名前。削除する前に検証してください: 文字列キーのルックアップ、リフレクション、DI コンテナ、ルートマニフェスト、ライブラリの公開エクスポートは、そうでないコードを未使用に見せかけます。明白な勝利のみ — 検出項目に設計の議論が必要なら、それはここでの修正ではなく、セクション 6 のフラグに属します。

5. 再利用可能な部分 — 明らかな場合のみ

UI やロジックが、1 つのコンポーネント、フック、または関数に切り出すことで明らかに元が取れるほど頻繁に繰り返されている場合。正当化するのに議論が必要なら、省略してください。早すぎる抽象化はそれ自体が一種のコシャリです。それは、一緒に動く理由がなかった呼び出し元を結合してしまいます。

6. 簡単なヘルスチェック

ネットワークや I/O 呼び出しの周辺に欠けているエラーハンドリング。明らかなパフォーマンスの罠 — N+1 クエリ、ページネーションのないリストエンドポイント、ループの外にあるべき処理がループ内にあるもの。次に、気づいた本当に危険なその他の事項を、それぞれ 1 行ずつに収めて。

7. セキュリティと依存関係

最後に、そして意図的にそうしています — しかし、有効な認証情報は依然として Critical であり、Pass 2 は何よりも先にそれを修正します。2 つの半分を別々に報告してください。それらは別々の判断です。

セキュリティ。 まず references/security-checks.md を読んでください。そこには、実行する価値のある grep パターン、素朴なシークレットスキャンを無意味にする誤検知、そしてスタックごとに確認すべきことが記載されています。対象: コード内またはコミットされた設定内のハードコードされたシークレット、ユーザー入力がエスケープされずにインタープリタに到達するインジェクション経路、欠けているか回避可能な認証、ログ、localStorage、または URL 内の機密データ、安全でない実行と wide-open な CORS。作業ツリーだけでなく git 履歴も確認してください — 最後のコミットで削除されたキーは、依然として有効なキーです。

依存関係。 バンドルされたスクリプトを実行してください。これはロックファイルからパッケージマネージャーを検出し、outdated レポートと脆弱性スキャンの両方を実行します:

bash scripts/dep_audit.sh [project-dir]

パスはこのスキル自身のディレクトリ — SKILL.md をロードしたディレクトリであり、監査対象のプロジェクトではありません — からの相対パスです。プロジェクトディレクトリは省略可能な引数で、デフォルトは現在のディレクトリなので、どこからでも実行できます。スタックを認識できない場合は終了コード 2 で終了し、何を探したかを表示し、何も変更しません — そのエコシステム自身の outdated および audit コマンドにフォールバックし、そうしたことをレポートに記載してください。

報告する前に脆弱性の出力をトリアージしてください。スキャナーはアドバイザリを数えるのであって、露出を数えるのではありません。本番環境に出荷されるものと、ビルドまたはテストチェーンでのみ実行されるものを分け、どちらかを明記してください。ランタイム依存関係の CVE は期限のある所見です。ビルドツールチェーンの奥深くにある 12 件のアドバイザリは通常そうではなく、それらを同等に報告することが、本物の 1 件が無視される理由です。マイナーバージョンが 3 つ遅れていることは、セキュリティ上の所見ではまったくありません。

Pass 1 の締めくくり

優先度別の件数を含む短い要約で終え、どのセクションを修正したいかユーザーに尋ねてください。沈黙や曖昧な「良さそう」で進めてはいけません。

パス 2 — 承認後の修正

この順序で修正し、各グループが終わるたびに停止して、プロジェクトが引き続きビルドおよび実行できること(およびテストがあればテストが引き続きパスすること)を確認してください。グループごとに個別にコミットして、問題のある修正を、良い修正を失うことなく破棄できるようにします。 グループがビルドまたはテストを壊した場合は、そのグループを revert し、何が壊れたかを報告して停止してください — ツリーが不明な状態のまま、リストの残りをデバッグしながら進めてはいけません。

1. Critical なものすべて。 有効なクレデンシャルや悪用可能な脆弱性は、レポートのどこに位置していたかに関係なく最優先です。これらは意図的に挙動を変えます — それが目的です — なので、ユーザーが気にする観点で、何がどう変わるのかを正確に述べてください: どのリクエストが失敗し始めるか、どのユーザーがログアウトされるか、何をローテーションする必要があるか。
2. 構造のクリーンアップ。 レイヤーの統合、重複、デッドコード、抽出 — koshary そのもの、そしてユーザーがここにいる理由です。承認されたものだけを行います。これらは挙動を変えてはいけません。それぞれについて before/after を示し、1 つの大きなコミットよりもいくつかの小さなコミットを優先してください。統合されたレイヤーは通常、段階を踏んで分割されます。
3. 依存関係。 パッチとマイナーは自由に上げてください。ロックファイルを更新し、その後ビルドとテストを行います。メジャーバージョンアップグレードは適用しないでください — それぞれを 1 行のマイグレーションノートとともに個別にリストアップし、ユーザーに判断を委ねてください。
4. 残りのセキュリティ修正。 High と Medium のもの。ステップ 1 と同じルールです: それぞれについて挙動がどう変わるかを述べてください。

最後に締めくくりのサマリーを出してください: 何がクリーンアップされたか、どのセキュリティ問題が修正されたか、更新されたパッケージ(旧 → 新)、そしてまだユーザーの判断が必要なもの。

ルール

• 指摘を解決する最小の変更を優先してください。
• 尋ねずにビジネスロジックに触れないでください — コードが何をしているかは見えますが、何をするはずなのかはわかりません。
• 修正が書き直しや破壊的アップグレードを必要とする場合は、推奨事項とともにフラグを立て、そこで停止してください。
• ユーザーが求めていない抽象化、設定、ツールを追加しないでください。目標は、より変更しやすいコードベースであって、より印象的なものではありません。

やってはいけないこと

• パス 1 の間は、どんなに些細でも何も修正しないでください。
• これをセキュリティ監査にしてはいけません。セキュリティがセクション 7 なのは、ユーザーが自分のコードの形について尋ねたからです。本当に必要としていた指摘の前に依存関係のアドバイザリが 1 ページ並ぶのは、より徹底したレポートではなく、より悪いレポートです。
• 徹底して見せるためにレポートを水増ししないでください — 結果を伴わない指摘はノイズであり、本当の指摘から注意を奪います。
• すべてのセクションに当てはまるからといって、同じ指摘を 3 つのセクションで報告しないでください。
• テストがないリポジトリで、変更を「安全」または「機能的に同等」と呼ばないでください。実際に何を検証したかを述べてください。
• スタイル的に気に食わないからといって、動作しているコードを書き直さないでください。
• 単なる偶然の一致にすぎない重複を統合しないでください — それが次の koshary を生み出す方法です。
• 自分の判断でメジャーバージョンの依存関係アップグレードを適用しないでください。
• サマリーでシークレットの値を報告しないでください — ファイルと行を参照し、ユーザーにローテーションするよう伝えてください。

---

Non-Claude-Code バージョン（プレーンなプロンプト）

スキルディスカバリーがないツール向けに、コミット済みのリポジトリでこれを一度貼り付けてください:

変更しにくくなったコードベースをレビューするシニアエンジニアとして振る舞ってください。2 回のパスで監査し、私が承認するまで何も変更しないでください。

まず、スタック（言語、フレームワーク、パッケージマネージャー）、リポジトリのどの範囲を対象にするか、テストが存在するかどうかを教えてください。テストがない場合は、どの変更も「安全」と呼べないので、最もリスクの高いものを挙げ、どこに簡単なテストがあれば役立つかを教えてください。

パス 1 — レポートのみ。 セクションごとに優先順位付きの表を作成し、各指摘は一度だけ記載して、それが何か、ファイルと行、なぜ重要か、そしてあなたの修正案を書いてください: (1) レイヤーの崩壊 — ビジネスルール、クエリ、トランスポート、レンダリングが 1 つのファイルや関数に混ざっている; (2) 重複したロジック — ただし 1 つのルールの変更が複数箇所の同時修正を強制する場合のみ; (3) 誰も読まない関数やファイル — 変更理由が複数ある、深いネスト、ブール値のモードフラグ — どれが頻繁に変更されるかで優先順位付け; (4) デッドコードと明白なリファクタリング — 未使用のインポート、到達不能なコード、誤解を招く名前 — リフレクションと動的ルックアップに対して検証する; (5) 再利用可能な部分 — 明白な場合のみ; (6) ネットワーク/IO 周りのエラーハンドリングの欠如と、N+1 クエリやページングされていないリストのような明白なパフォーマンスの罠; (7) 最後に、セキュリティと依存関係 — ハードコードされたシークレット（git 履歴も確認する）、インジェクション、認証の欠如、ログ/localStorage/URL 内の機密データ、eval/dangerouslySetInnerHTML/オープンな CORS、さらに古いパッケージと私のパッケージマネージャー向けの脆弱性スキャン — ランタイムとビルド専用の勧告を分けて記載する。

結果を明示できないものはすべてスキップしてください。

パス 2 — 私が確認した後。 まず重大なもの — 有効な認証情報や悪用可能な脆弱性 — を修正し、どのような振る舞いが変わるかを伝えてください。次に、私が承認した構造的なクリーンアップ。これは振る舞いを変えてはなりません。次に依存関係（パッチ/マイナーのみ — メジャーアップグレードは移行メモとともに別途リストアップする）。次に残りのセキュリティ修正。各グループの後でアプリがまだビルドおよび実行できることを確認し、それぞれを別々にコミットしてください。グループが何かを壊した場合は、それを元に戻して停止してください。動作する最小の変更を優先し、確認せずにビジネスロジックに触れないでください。書き直しが必要なものは、実行するのではなくフラグを立ててください。