خروجی لینتر را ایجنت می‌خواند، نه آدم

سه ایراد یکسان؛ ۳۱ خط یا ۵ خط

$ ruff check src/api.py
I001 [*] Import block is un-sorted or un-formatted
 --> src/api.py:1:1
  |
1 | / import os
2 | | import json
  | |___________^
help: Organize imports
  |
1 + import json
2 | import os
  - import json
3 |
  |

F401 [*] `os` imported but unused
 --> src/api.py:1:8
  |
1 | import os
  |        ^^
2 | import json
  |
help: Remove unused import: `os`
  |
  - import os
1 | import json
  |

Found 2 errors.
[*] 2 fixable with the `--fix` option.
$ mypy src/api.py
src/api.py:11: error: Incompatible return value type (got "str", expected "int")  [return-value]
Found 1 error in 1 file (checked 1 source file)

$ lintp src/api.py
src/api.py:1   sort the import block
src/api.py:1   remove unused import `os`
src/api.py:11  return int, not str

3 findings, 2 auto-fixable (lintp --fix)

biome خودش JS و TS را هم لینت می‌کند، پس آن ایرادها حذف می‌شوند. صاحب‌شان oxlint است و پرامپت تکراری از هیچ بدتر است.

فلگ‌ها

کانفیگ خودِ پروژه حرف آخر را می‌زند

اگر مخزن .oxlintrc.json داشته باشد، lintp همان را با -c پاس می‌دهد و هیچ فلگ دسته‌ای از خودش اضافه نمی‌کند. دسته‌ای که به‌زور اعمال شود، قاعده‌هایی را برمی‌گرداند که پروژه عمداً خاموش کرده بود، و از همین‌جا است که یک wrapper همان توصیه‌ای را می‌دهد که پروژه قبلاً ردش کرده.

1. لینترهایی که می‌خواهی را نصب کن

   هیچ‌کدام همراه agent-linters نمی‌آیند.

   $ uv tool install ruff && uv tool install mypy
   $ npm install -g oxlint @biomejs/biome

2. مخزن را کلون کن و نصب‌کننده را اجرا کن

   $ git clone https://github.com/cocodedk/agent-linters ~/projects/agent-linters
   $ cd ~/projects/agent-linters && ./install.sh

   پوشه‌های bin/ و shims/ و config/ را به ~/.local و ~/.config سیم‌لینک می‌کند و یک خط source به پروفایل شل اضافه می‌کند. اگر فایل واقعی سرِ راه باشد، اول به <name>.bak منتقل می‌شود.

3. به Claude Code خبر بده

   Claude Code بلوک env خودش را می‌خواند، نه پروفایل شل تو. پس دو متغیر را به ~/.claude/settings.json اضافه کن، یا بگذار ./install.sh --claude با jq این کار را بکند.

   "env": {
     "RUFF_OUTPUT_FORMAT": "concise",
     "RUFF_CACHE_DIR": "/home/YOU/.cache/ruff"
   }

• هیچ‌وقت یک MYPY_CACHE_DIR مشترک نگذار

  دو پروژه که هر کدام یک utils.py دارند، در کش مشترک با هم تصادم می‌کنند و mypy ایراد را به فایلِ آن یکی پروژه نسبت می‌دهد. ایجنتی که به مسیر اعتماد کند، فایلی را در مخزن اشتباه ویرایش می‌کند. شیم به هر پوشهٔ کاری کش خودش را می‌دهد. MYPY_CACHE_DIR ارثی هنوز برنده است، چون تنظیم صریح باید برنده باشد، پس اگر یک‌بار مشترک اکسپورتش کرده‌ای، unset کن.

• ruff هر فایلی را که نام ببری لینت می‌کند

  ruff check app.js یک صفحه خطای سینتکس پایتونِ خیالی برمی‌گرداند. قبل از صدا زدن هر ابزاری، مسیرها را با پسوند فیلتر کن. lintp این کار را در select() می‌کند.

• مسیرهای mypy نسبت به هدف‌اند، نه به مسیر جاری

  یک a.py بدون مسیر در خروجی mypy می‌تواند به فایل هم‌نامِ دیگری در پوشهٔ جاری برسد. اول مسیرهای گزارش‌شده را نسبت به ریشهٔ هدف حساب کن.

• oxlint کانفیگ را فقط از مسیر جاری می‌خواند

  ruff و mypy و biome همه رو به بالا جست‌وجو می‌کنند، oxlint نه. از یک زیرپوشه اجرایش کن و بی‌صدا همهٔ استثناهایی را از دست می‌دهی که کانفیگ مخزن برای همان‌ها نوشته شده. lintp خودش بالا می‌رود و -c را پاس می‌دهد.