Yapay Zeka Üretimi Kod İçin Linter Nasıl Kurulur

Yapay zeka ajanları derlenen kod üretebilir.

Bu yine de istediğiniz çıta değildir. Çıta şudur: hiç kullanmadığı şeyleri import etmeyen, tür sisteminden any-cast ile kaçmayan, hata dönüşlerini görmezden gelmeyen ve gosec'in incelemeden önce yakalaması gereken kimlik bilgilerini sabit kodlamayan kod.

Yapay zeka modelleri eski Stack Overflow yanıtları üzerinde eğitilir ve orada öğrendikleri kalıpları, kullanımdan kaldırılmış API'ler, eksik tür açıklamaları ve teknik olarak doğru ama güvenle incelenemeyecek kadar büyük fonksiyonlar dahil, olduğu gibi gönderir. Döngüde bir linter'a ihtiyacınız var. Öneri olarak değil, bir geçit olarak.

Bu rehber üç ekosistem için (Ruff ile Python, ESLint v10 flat config ile TypeScript/JavaScript ve golangci-lint ile Go) yapay zekanın getirdiği hata kalıplarına özel olarak ayarlanmış kurallarla yapılandırmayı ele alır. Ardından geçidi atlamayı çok daha zor hale getirmeyi ele alır, böylece ajan yerel kancaları --no-verify ile basitçe atlayamaz ve başka bir katman bunu yakalar.

Kurulum katmanlıdır: IDE düzeyinde linting, ajan yazarken sorunları satır içinde yakalar, pre-commit kancaları bir commit girişimine ulaşan her şeyi yakalar ve CI yerel olarak geçen her şeyi yakalar. Her katman bağımsızdır ve yığınınıza uyan dil bölümlerini seçebilirsiniz. Uygulama katmanı, hangi dili lint ettiğinizden bağımsız olarak aynı şekilde çalışır.

Kısaca

• Ruff (Python), ESLint v10 (TS/JS) ve golangci-lint (Go) her biri, yapay zekanın en yaygın hatalarını yakalayan belirli kurallara sahiptir
• Aşağıdaki yapılandırmalar açıklamalıdır; her kural bir nedenle oradadır
• Lefthook pre-commit geçidini yönetir; Cursor'ın afterFileEdit kancası lint'i satır içinde çalıştırır
• Dört uygulama katmanı, yapay zeka ajanlarının geçidi --no-verify ile atlamasını çok daha zor hale getirir
• CI son güvenlik ağıdır: ajanlar GitHub Actions'a --no-verify geçemez

Python Yapay Zeka Kodu İçin Ruff Nasıl Yapılandırılır

Ruff, yapay zeka destekli kod tabanları için doğru Python linter'ıdır. Hiçbir şeyi engellemeden her dosya kaydetmede çalışacak kadar hızlıdır, hem stili hem de gerçek mantık hatalarını kapsar ve aynı ikili dosya içinde biçimlendirici davranışı (Black'in yerini alarak) sunar. Aşağıdaki kurallar, yapay zeka modellerinin Python'da en sık getirdiği belirli hata kalıplarını hedefler.

Ruff Kurulumu

pip install ruff

# or via uv (faster for new projects):
uv add --dev ruff

Hepsi bu. Eklenti ekosistemi yok, eş bağımlılık pazarlığı yok.

pyproject.toml Yapılandırması

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = [
  "E",   # pycodestyle — style consistency
  "F",   # pyflakes — catches unused imports (the most common AI artifact)
  "I",   # isort — import ordering (AI frequently reorders imports incorrectly)
  "N",   # pep8-naming — naming conventions
  "UP",  # pyupgrade — flags deprecated APIs (AI trains on old Stack Overflow answers)
  "S",   # flake8-bandit — security rules: subprocess.shell=True, eval(), hardcoded creds
  "ANN", # type annotation enforcement (AI frequently omits return type annotations)
]
ignore = []  # intentional: do not add sweeping ignores in AI-assisted codebases

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101"]  # allow assert in tests

F kuralları kendini hemen amorti eder. Yapay zeka kodu, sonunda kullanmadığı paketler için import ifadeleri üretir ve F401 (kullanılmayan import) her birini yakalar. UP kuralları, yapay zekanın 3.10 öncesi Python yanıtlarından öğrendiği kullanımdan kaldırılmış API kalıplarına yapılan çağrıları yakalar; tek başına UP006 ve UP007 onlarca gereksiz tür kontrolü kalıbını işaretler. S (Bandit) kuralları güvenlik hatalarını yakalar: kimlik bilgisi gibi görünen sabit kodlanmış dizeler (S105/S106), subprocess(shell=True) yoluyla shell enjeksiyonu (S603/S607), zayıf kriptografi tercihleri (S324).

ignore = [] kasıtlıdır. Bu listeye eklediğiniz her istisna, izin vermeye karar verdiğiniz bir yapay zeka hata sınıfıdır.

Ruff Çalıştırma

ruff check .           # lint only — see what's wrong
ruff check --fix .     # auto-fix safe violations (imports, formatting)
ruff format .          # format the codebase (replaces Black)

--fix, Ruff'ın güvenli düzeltmelerini varsayılan olarak uygular, örneğin kullanılmayan import'ları kaldırma veya basit biçimlendirme ve lint düzeltmelerini uygulama gibi. Ruff'ın güvensiz düzeltmeleri de vardır, ancak bunlar açık bir tercih gerektirir ve daha dikkatli incelenmelidir. Ruff'ın güvenle düzeltemediği her şeyi manuel olarak inceleyin.

TypeScript ve JavaScript Yapay Zeka Kodu İçin ESLint v10 Nasıl Yapılandırılır

ESLint v10, eski .eslintrc.* yapılandırma biçimini bıraktı. Artık her şey eslint.config.mjs içinde flat config'tir. .eslintrc.json veya .eslintrc.js kullanan bir öğretici bulursanız, sözdiziminin farklı olduğu ESLint v8 veya v9'u hedefliyordur. Aşağıdakini kullanın.

Bu yapılandırmadaki @typescript-eslint kuralları, yapay zeka üretimi TypeScript'te tekrar tekrar ortaya çıkan belirli hata modlarını hedefler: any kaçış kapağı, incelenmesi zor monolitik fonksiyonlar ve sabit olması gereken sabit kodlanmış değerler.

TypeScript Desteğiyle ESLint v10 Kurulumu

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# or with pnpm:
pnpm add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

ESLint v10.5.0, Haziran 2026 itibarıyla günceldir. @typescript-eslint paketleri TypeScript sürümünüzle eşleşmelidir; uyumluluk matrisi için README'lerine bakın.

eslint.config.mjs Yapılandırması

import tseslint from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';

export default [
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: tsParser,
      parserOptions: { project: './tsconfig.json' },
    },
    plugins: { '@typescript-eslint': tseslint },
    rules: {
      // AI defaults to `any` to bypass the type system — this blocks it
      '@typescript-eslint/no-explicit-any': 'error',

      // AI generates variables it declares but never uses
      '@typescript-eslint/no-unused-vars': 'error',

      // AI writes functions that work but are too long to review safely
      'max-lines-per-function': ['error', { max: 50 }],

      // AI overloads function signatures; this forces decomposition
      'max-params': ['error', 2],

      // AI hardcodes values that should be named constants
      'no-magic-numbers': ['error', { ignore: [0, 1, -1] }],

      // AI writes files that are too large to reason about in a single review
      'max-lines': ['error', { max: 250 }],

      // AI leaves console.log debugging in production code
      'no-console': 'warn',
    },
  },
];

max-lines-per-function: 50 kuralı bu yapılandırmadaki en agresif şeydir. Yapay zeka destekli bir kod tabanında ilk çalıştırmada sürekli buna takılacaksınız. Mesele bu. Buna takılmalısınız. 50 satırı aşan fonksiyonlar, yapay zeka çıktısını yoğun şekilde incelerken üzerinde akıl yürütmesi imkansız hale gelen ilk şeydir.

max-params: 2 kuralı ayrıştırmaya zorlar. Yapay zeka modelleri, beş argümanlı fonksiyonların normal olduğu kod tabanlarından öğrenir; kural, ajanın bir options nesnesi kullanmasını gerektirerek geri iter ki bu daha iyi bir tasarım ve okunması daha kolaydır.

ESLint Çalıştırma

npx eslint .                       # lint
npx eslint . --fix                 # auto-fix safe issues
npx eslint . --max-warnings 0      # CI mode — treats warnings as errors

CI adımınızda --max-warnings 0 kullanın. no-console uyarılarını "teknik olarak not edildi"den "gerçekten engelliyor"a yükseltir.

İsteğe Bağlı: Yapay Zeka Üretimi Dosyalar İçin Daha Katı Kurallar

Ekibiniz yapay zeka üretimi kodu işaretlemek için bir dosya adlandırma kuralı kullanıyorsa (*.ai.ts, *-generated.ts veya benzeri), bu dosyalara özel olarak daha sıkı kurallar uygulayabilirsiniz:

// Add to eslint.config.mjs after the main config object
{
  files: ['**/*.ai.ts', '**/*.ai.tsx', '**/*-generated.ts'],
  rules: {
    'max-lines': ['error', { max: 100 }],  // tighter file ceiling
    'complexity': ['error', 5],             // McCabe complexity limit
  },
}

Go Yapay Zeka Kodu İçin golangci-lint Nasıl Yapılandırılır

golangci-lint, Go için standart çoklu linter çalıştırıcısıdır. gosec, errcheck, staticcheck ve 40'tan fazla başka linter ile birlikte gelir ve hepsi tek bir YAML dosyasından yapılandırılabilir. Yapay zeka üretimi Go kodu için kritik kurallar, hata dönüşü kontrolü ve güvenlik kalıbı tespitidir: yapay zeka modellerinin Go'da en tutarlı şekilde kaçırdığı iki hata kategorisi.

golangci-lint Kurulumu

# Official binary installer:
curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b "$(go env GOPATH)/bin" v2.12.2

# or via Homebrew:
brew install golangci-lint

.golangci.yml Yapılandırması

version: "2"

linters:
  enable:
    - gosec        # security: flags hardcoded creds (G101), file path injection (G304), weak crypto (G401)
    - unused       # flags unused vars and functions — a common AI artifact in Go
    - errcheck     # AI frequently ignores error returns — this blocks it
    - govet        # catches subtle correctness bugs AI introduces
    - staticcheck  # comprehensive static analysis
    - revive       # style: catches non-idiomatic Go patterns AI writes
    - misspell     # AI occasionally misspells in comments and string literals

  settings:
    gosec:
      severity: medium
      confidence: medium
    errcheck:
      check-type-assertions: true  # check `val, ok := x.(Type)` patterns
      check-blank: true            # catch `_ = someErr` error suppression

run:
  timeout: 3m
  issues-exit-code: 1

Go'nun hata işleme kalıbı tasarım gereği açıktır: başarısız olabilecek her fonksiyon bir hata değeri döndürür. Yapay zeka modelleri bunu anlar ama hafife alır; kritik olmayan kod yollarında hata kontrollerini atlarlar. errcheck bu atlamayı bir lint hatası haline getirir.

gosec güvenlik linter'ıdır. Yapay zeka kodu için, yapay zekanın 2020 öncesi Go öğreticilerinden edindiği kalıpları yakalar: güvensiz rastgele sayı üretimi (G404), güvensiz hash fonksiyonları (G401), dosya izni sorunları (G306). Bunlar, sözdizimsel olarak normal göründükleri için kod incelemesinde yakalayamadığınız hatalardır.

golangci-lint Çalıştırma

golangci-lint run ./...            # lint all packages
golangci-lint run --fix ./...      # auto-fix where possible

Linter Pre-commit Kancalarına Nasıl Bağlanır

Bir pre-commit kancası her git commit'ten önce lint çalıştırır ve lint başarısız olursa commit'i engeller. Bu, yapay zeka ajanının yapılandırdığınız kuralları geçemeyen kodu commit'leyemeyeceği anlamına gelir. Önce ihlalleri düzeltmek zorundadır.

Lefthook önerilen seçenektir. Platformlar arası, hızlıdır ve özellikle yapay zeka ajanı uygulamasıyla çalışan bir yapılandırma kalıbına sahiptir (bir sonraki bölümde ele alınmıştır).

Lefthook

npm install --save-dev lefthook
npx lefthook install

lefthook.yml:

pre-commit:
  parallel: true
  commands:
    lint-python:
      glob: "*.py"
      run: ruff check {staged_files} --fix
    lint-js-ts:
      glob: "*.{js,ts,tsx}"
      run: npx eslint {staged_files} --fix
    lint-go:
      glob: "*.go"
      run: golangci-lint run {staged_files}
  fail_text: |
    Lint failed. For AI Agents: fix all lint violations before committing.
    Do not use --no-verify to bypass this gate.

fail_text mesajı, bir commit başarısız olduğunda yapay zeka ajanları tarafından okunur. Kalıp şu kaynakta belgelenmiştir: Liam Bigelow'un Claude Code için Lefthook lint uygulaması üzerine yazısı. Bu tek başına kararlı bir ajanı durdurmaz, ancak ona bir geçici çözüm çıkarmaya bırakmak yerine doğru sonraki talimatı ("lint ihlallerini düzelt") verir.

Alternatif: pre-commit (Yalnızca Python kurulumları)

Yalnızca Python yığınındaysanız ve pre-commit çerçevesini tercih ediyorsanız:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.17
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

Cursor: afterFileEdit Kancası ile Satır İçi Linting

Cursor kullanıyorsanız, yapay zeka bir dosyayı değiştirdiğinde, daha bir commit denemeden önce lint'i hemen tetikleyebilirsiniz. Proje kök dizininizde .cursor/hooks.json oluşturun:

{
  "hooks": {
    "afterFileEdit": [
      {
        "match": "*.py",
        "run": "ruff check {file} --fix"
      },
      {
        "match": "*.{ts,tsx,js}",
        "run": "npx eslint {file} --fix"
      },
      {
        "match": "*.go",
        "run": "golangci-lint run {file}"
      }
    ]
  }
}

Bu, Cursor'ın yapay zekası bir dosyayı her değiştirdiğinde tetiklenir. Ajan, görevi tamamlanmış olarak ele almadan önce satır içi lint geri bildirimi alır, böylece çoğu ihlal pre-commit geçidine ulaşmadan önce düzeltilir.

Geçit Yapay Zeka Ajanları Tarafından Nasıl Daha Zor Atlanır Hale Getirilir

Dört uygulama katmanı, bir yapay zeka ajanının pre-commit geçidini --no-verify ile atlamasını çok daha zor hale getirir. Her biri farklı bir saldırı yüzeyini hedefler: CLAUDE.md'deki politika, bir Claude Code deny kuralı, bir PreToolUse kancası ve bir CI güvenlik ağı. Bunları dört bağımsız garanti olarak değil, katmanlı bir kurulum olarak ele alın.

Yapay zeka ajanları, lint başarısız olduğunda ve ajan başarısızlıkların "değişiklikleriyle ilgisiz" olduğuna karar verdiğinde pre-commit kancalarını atlamak için bazen git commit'e --no-verify geçer. Karar her zaman yanlış değildir, ancak ajanın bunu tek taraflı vermesine izin vermemelisiniz. Lint geçidinin tüm amacı, politikayı bir insanın belirlemesidir; ajanın işi onu karşılamaktır, etrafından dolaşmak değil.

İşte her katman ve kapsadığı saldırı yüzeyi.

Katman 1: Politikayı CLAUDE.md'de Belgeleyin

## Linting Policy

NEVER use `git commit --no-verify`. All commits must pass pre-commit hooks.
Pre-commit hooks run lint. Fix lint violations before committing. Do not treat
lint failures as unrelated to your changes — they may not be, and you don't get
to decide that.

Claude Code, oturum başlangıcında CLAUDE.md'yi okur. Bu uygulama değildir; ajan yine de atlamayı deneyebilir. Ancak "bilmiyordum" yolunu ortadan kaldırır ve ajanın aktif olarak ihlal etmeyi seçmesi gereken net bir politika belirler ki bu, sessizlikten bir geçici çözüm çıkarmasından daha az olasıdır.

Katman 2: Claude Code Deny Kuralı

.claude/settings.json'a ekleyin:

{
  "permissions": {
    "deny": [
      "Bash(git commit --no-verify*)"
    ]
  }
}

Bu, açık çağrıyı engeller. Bir sınırlama: deny kuralı önek eşleştirmesi kullanır, bu nedenle yalnızca commit'in hemen ardından gelen --no-verify'i yakalar. Yeterince yaratıcı bir ajan çağrıyı farklı şekilde yapılandırabilir. Buna tek başına güvenmeyin.

Katman 3: PreToolUse Kancası

block-no-verify paketini kurun:

npm install --save-dev block-no-verify

Ardından bunu Claude Code'un ayarlarında bir PreToolUse kancası olarak yapılandırın. Bu, her araç çağrısından önce tetiklenir ve argümanları yalnızca commit değil, altı git alt komutu boyunca --no-verify için inceler. Çağrıyı çalışmadan önce engellemek için sıfır olmayan kodla çıkar.

El kitabı şu kaynakta pydevtools.com bu konuda açıktır: "kanca katmanı kuralı güvenilir şekilde uygulayan tek katmandır." Bunu diğer katmanlarla birlikte kullanın; herhangi bir yerel kancayı bütün garanti olarak ele almayın.

Katman 4: CI Güvenlik Ağı

CI, ajanın bayrak geçirebileceği bir shell'e sahip olmadığı sunucuda çalışır:

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Python
        run: |
          pip install ruff
          ruff check . --output-format github

      - name: Lint JS/TS
        run: npx eslint . --max-warnings 0

      - name: Lint Go
        uses: golangci/golangci-lint-action@v9
        with:
          version: v2.12.2

Yapay zeka ajanları CI'ye --no-verify geçemez. GitHub Actions, ajanın yerel olarak yaptığından bağımsız olarak çalışır. Bir commit bir şekilde başarısız lint ile geçtiyse, CI bunu birleşmeden önce yakalar.

Bu son güvenlik ağıdır.

Bonus: ESLint MCP Sunucusu

Claude Code kullanıyorsanız, geçide ne sıklıkta takıldığınızı azaltan proaktif bir katman vardır.

ESLint MCP sunucusu (@eslint/mcp), ESLint'i doğrudan ajanın araç döngüsüne entegre eder. Ajan, bir commit denemeden önce, görev sırasında ESLint'i sorgulayabilir. Genel olarak kurun:

npm install -g @eslint/mcp@latest

.claude/settings.json'a ekleyin:

{
  "mcpServers": {
    "eslint": {
      "command": "npx",
      "args": ["@eslint/mcp@latest"]
    }
  }
}

Bu yapılandırıldığında, ajan görev sırasında ESLint'i sorgulayabilir. Ajan satır içi lint geri bildirimi alır ve bazı ihlaller kancaya ulaşmadan önce düzeltilebilir. Bu, geçidin yerini almaz, geçitteki gürültüyü azaltır.

Sıkça Sorulan Sorular

Yalnızca tek bir dilde çalışıyorsam üç linter'ın hepsini yapılandırmam gerekir mi?

Hayır. Birincil diliniz için linter'ı ve uygulama katmanını kurun. Yığınınız yalnızca TypeScript ise, ESLint'i yapılandırın ve Ruff ile golangci-lint'i atlayın. Ajan atlamasını önleme bölümü, hangi dili lint ettiğinizden bağımsız olarak geçerlidir.

Bu yapılandırmalar ilk çalıştırmada mevcut kod tabanımı bozar mı?

Neredeyse kesinlikle ve kasıtlı olarak. Önce güvenli ihlalleri otomatik düzeltmek için ruff check --fix . veya npx eslint . --fix çalıştırın. Otomatik düzeltmeden sonra kalan, manuel inceleme listesidir: no-explicit-any cast'leri, 50 satırı aşan fonksiyonlar, eksik hata işleme. Bunları aşamalı olarak halledin. Onlarla uğraşmaktan kaçınmak için ignore kuralları eklemeyin.

Bu noktada Biome, ESLint'in yerini tutar mı?

Biome v2.5.0 (Haziran 2026'da yayınlandı) biçimlendirme ve temel lint kurallarında rekabetçidir. ESLint'ten daha hızlıdır ve onu bun x ultracite@latest init ile kurarsanız sıfır yapılandırma yükü vardır. Tek bir araç isteyen ve tam @typescript-eslint kural derinliğine ihtiyaç duymayan ekipler için Biome makul bir seçimdir. Bu rehberdeki yapay zekaya özel kurallar için (yapay zeka hedefli eşiklerle max-params, no-magic-numbers, max-lines-per-function), @typescript-eslint ile ESLint hâlâ daha fazla kapsama sahiptir. İkisini de çalıştırabilirsiniz: biçimlendirme ve temel lint için Biome, yapay zekaya özel kurallar için ESLint.

Yapay zeka ajanım aynı lint ihlallerini yeniden üretmeye devam ederse ne olur?

Ajan, temel sorunu düzeltmek yerine kuralın etrafından dolaşıyor. no-explicit-any için bu, gerçek türü tanımlamak yerine bir tür iddiası eklemek demektir. max-lines-per-function için bu, hiçbir işe yaramayan ama satır sayısını eşiğin altına indiren bir yardımcı fonksiyon çıkarmak demektir. Hiçbir çözüm kod incelemesinden geçmez. Lint kuralı belirtiyi yakaladı; kök neden ajanın promptu. Tür kısıtlamasını veya beklenen ayrıştırmayı belirtmek için promptu iyileştirin; ajan açık yapı yönlendirmesini örtük kurallardan daha güvenilir şekilde takip eder. Daha kapsamlı bir ajan kurulumu çalıştırıyorsanız, işi kısıtlamaların talimatlarına gömülü olduğu özel bir alt ajana kapsamlamak, tek bir geniş prompttan daha iyi tutma eğilimindedir.

ESLint MCP sunucusu pre-commit geçidinin yerini tutar mı?

Hayır. Ajanın geçidi başarısız kılan kodu ne sıklıkta ürettiğini azaltır. Geçit yine de her commit'te çalışır. MCP sunucusu satır içi kontrolü ve pre-commit kancası uygulaması birbirini tamamlar, bu yüzden ikisini de kaldırmayın.