AI coding agent は、compile できて、test も通り、一見きちんと完成している code を書けるようになりました。しかし、それは long-term maintenance に向いた code であることを意味しません。Type check や unit test ではすぐ捕まらない問題があります。Self-explanatory な code の上に置かれた narrative comment、空の fallback、例外を握りつぶす catch、とりあえずの as any、消し忘れた console.log、大きすぎる function、重複 helper、TODO stub、hallucinated import。ひとつずつは軽く見えても、積み重なると codebase の読みやすさを削ります。

今日紹介する scanaislop/aislop は、この問題に向けた CLI です。もう一つ LLM を呼び出して code review する tool ではなく、deterministic な static rules で project を score し、機械的に直せる問題は先に auto-fix します。GitHub page では現在およそ 329 stars、13 forks。主な言語は TypeScript、license は MIT。Latest release は v0.10.2 で、2026-06-02 に公開されています。

プロジェクト概要

項目内容
Repositoryscanaislop/aislop
位置づけAI 生成コードの痕跡を検出する static analysis / quality gate CLI
Stars約 329
Forks13
主な言語TypeScript
LicenseMIT
Current versionv0.10.2
Supported languagesTypeScript、JavaScript、Python、Go、Rust、Ruby、PHP

Traditional lint が見ない層を見る

aislop が面白いのは、「AI が書いたが、maintenance code としては少し怪しい」pattern を独立した対象として扱っている点です。Traditional linter は formatting、unused variable、明らかな bug、いくつかの security rule を検出するのが得意です。Type system も interface level の誤用をかなり防ぎます。しかし AI-generated code の問題は、より engineering judgment の残りかすに近いことがあります。明らかな処理を説明するだけの comment、silent failure、type problem を隠す any、今の task を通すためにコピーされた helper、あとで直すつもりの placeholder logic。

これらは CI をすぐ red にしません。短期的には feature を早く通す助けに見えることさえあります。代償は数週間後に出ます。次の developer が、その branch が設計されたものなのか、agent が error を避けるために置いた buffer なのか判断しづらくなる。Reviewer は説明 comment が多すぎて、かえって本当の意図を読み取りにくくなる。as any で type boundary が開くと、後続変更の protection が弱くなります。

aislop は、こうした痕跡を scan 可能、configurable、gate 可能な rule にします。README では narrative comments、trivial comments、dead patterns、unused imports、as any、console leftovers、TODO stubs、generic names などが対象として挙げられています。Human review の代替ではありませんが、「明らかに main branch に混ぜたくない agent residue」を先に止める layer として使えます。

Gate には deterministic なほうが向いている

AI code review tool の多くは model を呼び出して suggestion を出します。Complex design issue には有効です。ただし CI gate の目的なら、deterministic であることの価値が大きいです。Gate には次の性質が必要です。

  1. 同じ code を何度走らせても同じ結果になる。
  2. Failure reason が rule と line に紐づく。
  3. False positive は rule 単位で off、warning、error に調整できる。
  4. Output が GitHub code scanning、CI JSON、PR workflow に入る。

aislop は runtime path で LLM に依存しない設計を明示しています。Regex、AST、language tooling を組み合わせて scan し、project に 0-100 の score を出し、severity に応じて影響を計算します。すべての context を理解するわけではありませんが、「低レベルな bad smell を先に止める」automation layer には向いています。

README には config も用意されています。.aislop/config.yml で rule severity を error、warning、off に変更でき、aislop-ignore-next-line、aislop-ignore-line、aislop-ignore-file のような inline suppression も使えます。必要なら理由も添えられます。Team governance としては、「model が今回そう感じた」より扱いやすい形です。

npx aislop scan から始められる

入口は軽いです。

npx aislop scan

Specific directory、changed files、staged files だけを対象にすることもでき、JSON や SARIF も出せます。

npx aislop scan ./src
npx aislop scan --changes
npx aislop scan --staged
npx aislop scan --json
npx aislop scan --sarif

Default では node_modules、.git、dist、build、coverage などを除外します。Generated code、snapshot、legacy directory を外したい場合は .aislop/config.yml や .aislopignore で調整できます。このあたりは成熟した linter に近い設計です。まず default で動き、team が必要に応じて締めていく。

Unsupported language の扱いもよいです。README では、repository の主体が supported language ではない場合、偶然見つかった少数 file だけを scoring すると misleading になるため、score を withheld すると説明しています。見かけ上 precise な 0-100 点を出すより、coverage が足りないと言うほうが安全です。

Auto-fix と agent handoff を分けている

aislop は report だけではありません。fix command で機械的に直せるものを先に処理できます。

npx aislop fix
npx aislop fix --safe
npx aislop fix -f

--safe は reversible か low-risk な修正に絞ります。Unused import の削除、import merge、narrative comment removal、formatting などです。より aggressive な -f は dependency、unused file などにも踏み込みます。この safety level の分離は大事です。自動修正できそうに見えるものを、全部同じ危険度で扱うべきではありません。

Context が必要な残りの問題には agent handoff があります。

npx aislop fix --codex
npx aislop fix --claude
npx aislop fix --gemini
npx aislop fix --prompt

これは aislop 自体が agent になるという意味ではありません。Diagnostic information を、次の coding agent が扱いやすい context にまとめる機能です。Codex、Claude Code、Gemini CLI、Cursor、OpenCode などにとって、「quality issue を直して」ではなく、「この rule がこの file で発火し、ここは auto-fix 済み、ここは judgment が必要」という具体的な task にできます。

Hook mode は agent-heavy workflow に合う

Coding agent を高頻度で使う team では、PR の最後に scan するだけでは遅いことがあります。aislop は hook install を提供し、agent edit のあとすぐ feedback を返せます。

npx aislop hook install --claude
npx aislop hook install --cursor
npx aislop hook install --gemini
npx aislop hook install --quality-gate

README では hook の対応を二つに分けています。Claude、Cursor、Gemini、pi は runtime adapters として scan と feedback を扱う。Codex、Windsurf、Cline、Kilo Code、Copilot などは rules-only 寄りで、agent が rule を読む形です。この boundary は重要です。Agent ごとに拡張 points が違うため、すべての tool を同じ深さで intercept できるとは限りません。

Quality-gate mode では baseline を保存し、score が regression したときに止めることもできます。これは gradual governance に向いています。Old repository に初日から 100 点を求めるのではなく、まず「今より悪くしない」を約束し、少しずつ historical issues を減らしていく使い方です。

CI と SARIF で普通の workflow に入る

aislop は npx aislop ci を提供し、GitHub Actions での利用例もあります。Config では次のように threshold を設定できます。

ci:
  failBelow: 70

Score が threshold 未満なら CI は exit 1 になります。SARIF 2.1.0 output にも対応しているため、GitHub code scanning に upload できます。Team にとっては、terminal report で終わるより実用的です。既存の security/code scanning view に問題を流し、PR workflow とつなげられます。

最初は低めの threshold や warning mode から始めるのが現実的です。AI-generated code の bad smell は完全な binary ではなく、team style による部分もあります。数回 report を見て false positive の範囲を確認し、高価値な rule から error に上げるほうが長続きします。

普通の linter との関係

aislop は Biome、ruff、golangci-lint、clippy、rubocop、php-cs-fixer の replacement ではありません。README でも、それらを underlying engine や ecosystem capability として扱っています。より正確には、formatter、linter、typecheck、security scan の上に、AI-generated code の痕跡に特化した rule と score を追加する tool です。

そのため、使い方も単独ではなく chain の中に置くのが自然です。

  • Formatter が style consistency を守る。
  • Language linter が ecosystem の common issue を検出する。
  • Typecheck が interface boundary を守る。
  • Tests が behavior を検証する。
  • aislop が agent output に残りやすい maintainability smell を検出する。
  • Human review が design、domain semantics、trade-off を判断する。

aislop が埋めるのは、最後の二つの間にある隙間です。Reviewer が毎回「この comment は情報量がない」「ここで exception を握りつぶさない」「type issue を any で隠さない」と言い続けるのは疲れます。そういう feedback は、まず automatic gate に渡したほうがよいです。

残しておくべき疑い

aislop の方向は実用的ですが、score を神格化すべきではありません。0-100 の数字は communication には便利ですが、code quality を完全に表すことはできません。特に AI residue 系の rule は team style の影響を受けます。Explanation comment を多めに許す team もあれば、TODO を厳しく見る team もあります。Generated code や legacy code が多い repository では、設定も必要です。

特に見たい risk は三つです。

  • False positive cost: narrative comment や generic name rule が敏感すぎると、合理的な code まで score のために変更してしまう。
  • Auto-fix boundary: fix -f のような aggressive mode は large repo で無条件に走らせず、まず --safe から始めたほうがよい。
  • Coverage meaning: Multi-language repository や unsupported language が主体の repository では、score が何を代表しているか coverage を見る必要がある。

つまり、aislop は absolute judge ではなく engineering feedback system として扱うべきです。Rules、threshold、suppression reason を review culture に入れると効果が出やすくなります。

試すのに向いている人

aislop は次のような場面に向いています。

  • Codex、Claude Code、Cursor、Gemini CLI、OpenCode などの coding agent を頻繁に使っている。
  • PR に「動くが、人間が長く保守する code としては怪しい」変更が混ざる。
  • AI-generated code の common bad smell を automatic rules にしたい。
  • Project が TypeScript、JavaScript、Python、Go、Rust、Ruby、PHP を主に使っている。
  • CI に quality score、SARIF、GitHub Actions gate を入れたい。
  • 残った診断を agent に渡し、長い prompt を手書きしたくない。

Team がまだ agent を多用していない場合や、project が非常に小さい場合、効果は限定的かもしれません。しかし AI code が安定して main branch に入るようになったなら、軽い governance entry point として試す価値があります。

まとめ

scanaislop/aislop は、AI coding agent が普及したあとの現実的な問題を捉えています。Code generation は簡単になりましたが、codebase が細かな bad smell で重くならないように保つことは、むしろ難しくなっています。この tool の価値は「AI で AI を review する」ことではなく、認識しやすく、設定でき、繰り返し実行できる問題を deterministic gate にすることです。

Zero-config scan、configurable rules、safe fix、agent handoff、hook、CI、SARIF、baseline gate という設計はよくまとまっています。Team ごとの style に合わせた tuning は必要で、human review の代替にもなりません。それでも agent-heavy な development workflow に置く automatic cleanup filter として、かなり試しやすい tool です。