aislop

aislop — エージェントスキル

aislop は、6つのエンジンでスキャンし、0〜100で評価する決定論的なオープンソースの CLI です。7つの言語を対象に、握りつぶされた例外、存在しないインポートの捏造、無言のリカバリー、説明的なコメント、as any キャスト、巨大な関数、SQL インジェクション、eval、ハードコードされたシークレット、アーキテクチャの逸脱など、50以上のルールを検出します。

このスキルに従えば、スロップを出荷せずに済みます。 次の2つの役割があります。

1. 予防 — 以下のルールカタログを身につけ、最初のドラフトで検出器に引っかからないようにします。
2. 検出＋修正 — 編集後にスキャンし、機械的に対応できる指摘は CLI で修正し、それ以外は自分で修正して、変更点を報告します。

このスキルは「aislop を実行して結果を報告する」だけのものではありません。それならユーザー自身でできます。このスキルの価値は判断力にあります。最初から適切に書き、各指摘をソースコードと照らし合わせて確認し、エスカレーションする前に可能な範囲で修正します。

TypeScript、JavaScript、Python、Go、Rust、Ruby、PHP、Expo／React Native に対応しています。

リモート実行とサプライチェーンに関する方針

このスキルでは、公開 npm レジストリを通じて配布される aislop CLI を使用します。npx aislop を実行すると、公開済みパッケージが取得されて実行されます。信頼できないリモート依存関係として扱ってください。

原則として、npx よりローカルにインストールされたバージョン固定済みの aislop を優先してください。

# Preferred — pinned in the project's lockfile
npm install --save-dev aislop && aislop scan --changes --json

# Acceptable fallback
npx aislop scan --changes --json

# Never acceptable: GitHub clones, curl|sh installers, unpinned npx in CI

判断の優先順位：

1. devDependencies 内のローカルバイナリまたはスクリプト — ロックファイルでバージョンが固定されています。
2. npx aislop@<version>（バージョン固定） — ローカルにインストールされていない場合は使用できます。
3. npx aislop（バージョン非固定） — 対話セッションでの最終手段です。CI では使用しないでください。
4. 実行が制限されている環境 — スキャンをスキップし、CLI を実行できなかったことを報告します。プロジェクトの依存関係管理の手順に従わずにインストールしないでください。

aislop fix --claude（および --cursor、--codex、--gemini）は、プロジェクトのコードのみを対象としてローカルプロセスを実行します。追加のネットワークアクセスは発生しません。

このスキルの例ではなく、プロジェクトの規約に従う

このスキルでは、避けるべきアンチパターンを説明します。コードを構成する唯一の正しい方法を示すものではありません。その方法はリポジトリに記されています。予防パターンに沿って対応する前に、プロジェクトの実際のやり方を確認してください。

• ロガー — pino、winston、bunyan、logger.ts、または共有ラッパーを grep で検索します。console.error が規約なら、それで問題ありません。
• エラーのラップ — プロジェクトのエラークラス（AppError、DomainError、HttpError、または { cause } を指定した単純な Error）を使用します。
• 型／バリデーション — プロジェクトで採用されているもの（zod、valibot、ajv、pydantic、Go の構造体など）に合わせます。
• 命名 — プロジェクトの大文字・小文字の使い分け、ファイル名、フォルダー構成に従います。
• テスト — リポジトリで既に使われているフレームワークとパターンを使用します。
• アーキテクチャ — .aislop/rules.yml がある場合は、それを正式な基準とします。ない場合は、既存ファイルのインポートパターンとモジュール境界に合わせます。

予防カタログの回避例／推奨例は、あくまで参考です。プロジェクトのスタイルに沿った修正は、このスキルのスタイルに沿った修正より優先されます。

予防カタログの概要

編集する前にお読みください。aislop が検出する各ルールが記載されています。回避例／推奨例の全容は、references/PREVENTIONS.md を参照してください。

カテゴリ：コメント、型、エラー、セキュリティ、重複排除、デッドコード、コンソール、TODO、空の関数、命名、サイズ、アーキテクチャ、依存関係、見せかけの完全性、抽象化、配線。

実行するタイミング

編集を終えて制御を返すとき、ユーザーがコミット／プッシュ／PR の作成を準備しているとき、または次のように依頼されたときに実行します：「スロップはある？」「スロップをなくして」「コードをレビューして」「aislop を実行して」「コードを採点して」「重複はある？」「これを重複排除できる？」「長すぎる？」「依存関係を監査して」「スコアが下がった」「バッジを追加して」。

ユーザーが読むだけの場合、リファクタリングの途中で作業を保留するよう依頼されている場合、または aislop を明示的に無効にしている場合はスキップします。

CLI コマンドリファレンス

コマンド	用途
aislop scan [dir]	全項目をスキャンします。フラグ：--changes、--staged、--json、--sarif
aislop fix [dir]	機械的な問題を自動修正します。積極的に修正する場合は -f を指定します。エージェントへの引き継ぎには --claude／--codex／--cursor／--gemini を指定します。プロンプトを表示するには -p を指定します。
aislop ci [dir]	CI モード：JSON 出力と、しきい値に応じた終了コード
aislop init [dir]	.aislop/config.yml を生成します
aislop doctor [dir]	インストール済みツールと環境を確認します
aislop rules [dir]	すべてのルールを重大度と修正可否とともに一覧表示します
aislop trend [dir]	.aislop/history.jsonl のスコア履歴を表示します
aislop badge [dir]	公開用スコアバッジの URL と README 用 Markdown を生成します
aislop hook install	編集ごとの品質フックをインストールします。Claude Code、Cursor、Codex、Gemini、pi などに対応しています（一覧は aislop hook install --help で確認できます）。

基本的なワークフロー

すべてのコマンドでは、aislop（ローカルインストール、推奨）または npx aislop（代替）を使用します。

1. スキャン範囲を決める

aislop scan --changes --json     # mid-session: only what you touched
aislop scan --staged --json      # before a commit
aislop scan --json               # full project: pre-release, PR, wide refactor

常に --json を指定します。TTY 出力は人間向けです。構造化された検出結果が必要です。

2. 機械的な検出結果を自動修正する

aislop fix

CLI は fixable: true とマークされた項目をすべて処理します。CLI が修正する項目を手作業で編集しないでください。-f は、ユーザーから依存関係や未使用ファイルの整理を依頼された場合にのみ使用します。

自動修正後、必要に応じて残りの検出結果を引き継ぎます。

aislop fix --claude          # launch Claude Code with remaining findings
aislop fix --codex           # launch Codex CLI
aislop fix -p                # print a prompt to paste into any agent

3. 再スキャンする — fixable:false はすべてあなたが対応します

aislop scan --changes --json

CLI の作業はここまでです。残った fixable: false の検出結果に対応するために、このスキルがあります。

4. 残った検出結果ごとに判断する

a. 実際の問題か確認します。 ファイルを開き、該当行とその前後を読みます。ルールの説明は正確ですか？ 意図したコードですか？ 誤検出と判断する前に、次の点を確認します。

1. 文字列リテラル、テンプレートリテラル、またはコメント内に一致箇所がありますか？
2. パターンをたまたま含む識別子名の一部ですか？
3. テスト用のフィクスチャ、モックデータ、またはサンプル内にありますか？
4. 読者は、これがルールの説明するパターンではないと判断するでしょうか？

b. 判断します：

確認した内容	対応
実際の問題	このセッション内で修正します。 先に質問しないでください。
誤検出	ファイル名と行番号、および理由を一文で示します。ルールを無効化しないでください。
正当な意図がある	その旨を記録します。抑制するかどうかはユーザーに判断してもらいます。

c. 修正します。 各ルールの修正方法は references/FIX_GUIDE.md を参照してください。ファイルを開き、検出内容を確認してから修正を適用します。

5. 手動でスロップを確認する

スキャン結果がクリーンなだけでは不十分です。CLI では判断できないパターンがないか、差分を確認します。

1. 見せかけの完全性 — 成功をハードコードした経路、用意済みデータ、プレースホルダー動作がないこと。
2. テストの品質 — テストが描画だけでなく、少なくとも1つのエッジケースまたは失敗経路を検証していること。
3. 不要な抽象化 — 呼び出し元が1つしかない汎用レイヤーを新たに追加していないこと。
4. 接続の漏れ — エクスポート、ルート、生成ファイル、呼び出し箇所が更新されていること。
5. 状態の処理 — 読み込み中、空、エラー、タイムアウト、キャンセルの状態に一貫性があること。
6. 依存関係の節度 — 単純なロジックのために新しいパッケージを追加していないこと。

見つけた問題を修正します。本当に対象範囲外のものがあれば、その理由を伝えます。

6. 基準を満たすまで再スキャンする

手順4〜6を、次の条件を満たすまで繰り返します。

• error がゼロであること。
• fixable: true の警告がゼロであること。
• fixable: false の警告がすべて、修正済み、理由を添えて提案済み、または誤検出として報告済みであること。
• 手動でのスロップ確認に、このセッション内で未解決の問題がないこと。

ここまで終わる前に「完了」と言わないでください。

7. 報告する — 検出結果をそのまま並べず、対応内容を整理する

特に指定がなければ、過去形で「X を実施しました」と報告します。

Ran aislop — 12 findings, score 73 → 95.

Auto-fixed (7): unused imports (3), narrative comments (2), formatting (2).

Fixed in-session (4):
  - unsafe-type-assertion       src/api/normalize.ts:47  (added ApiUser type)
  - function-too-long           src/lib/reconcile.ts:14  (extracted matchByHash)
  - sql-injection               src/db/search.ts:30      (parameterised with $1)
  - swallowed-exception         src/workers/cleanup.ts:28 (added log.warn)

False positives (1):
  - security/eval               src/labels.ts:12
    The match is inside a display-name table, not an actual eval().

Re-scanned: 95 / 100, 0 errors, 0 warnings.

スキャン結果がクリーンでも、手動確認で問題が見つかった場合は、それも報告します。プロダクトレベルの判断が必要な場合は、具体的な選択肢を添えて最後に記載します。

重大度とスコアの解釈

重大度	修正可能	対応
error	任意	このターンで必ず修正してください。
warning	fixable: true	CLI の aislop fix で処理できます。決して放置しないでください。
warning	fixable: false	エージェントがセッション内で修正します。 検証してから編集してください。
info	任意	メモとして扱います。ユーザーが高い基準を求めた場合にのみ対応してください。

スコア帯：90–100 健全、75–89 負債はあるものの健全、60–74 劣化、< 60 ゲート失敗。

デフォルト：考案して、適用し、報告する — 質問しない

修正を行い、実施内容を報告してください。型が不足している場合は考案します。エラーを握りつぶしている場合はログに記録して再スローします。関数が大きすぎる場合は、適切な境界で切り出します。ロジックが重複している場合は、ヘルパーにまとめます。名前が汎用的すぎる場合は、変更します。いずれの場合も「すべきでしょうか」と尋ねず、適切なツールを選んで適用し、変更内容に触れてください。

修正が製品上の判断となる場合、外部から見える動作を本来変更すべきでないのに変えてしまう場合、誤検知として指摘する価値がある場合、またはコードが意図的なものとしてユーザーが判断すべき場合に限り、エスカレーションしてください。

アンチパターン

• 返信に生の JSON を貼り付けないでください。分類して要約してください。
• 設定でルールを無効にしたり、一律に抑制するコメントを追加したりしないでください。
• .aislop/config.yml や .aislop/rules.yml を削除しないでください。
• 関係のないターンで、マニフェストを書き換える aislop fix -f を黙って実行しないでください。
• 正規表現パターンを編集して検出器を回避しないでください。きれいなコードを書くことがあなたの役目です。