clean-code-refactor

Clean Code & Refactor

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Ne Zaman Kullanılır

• Yeni özellik öncesi alan temizleme (Boy Scout Rule)
• Code review'da "sonra refactor" notu birikti
• TDD'nin "refactor" fazı (test yeşilken iç yapı iyileştirme)
• Tech debt sprint
• Performans regresyonu olmadan complexity yüksek
• Yeni geliştiricinin kod tabanına girişi yavaş → kavrama yükü düşür

Workflow

1) Test koruması var mı?

Refactor için yeşil test zorunlu. Yoksa:

• Karakterizasyon testi ekle: mevcut davranışı (bug dahil) yakalayan test. Sonra refactor; sonra bug fix ayrı PR.
• Coverage test-engineer ile koordine; staged scope ≥ %70 hedef.

2) Smell + complexity tara

Stack'e göre tool:

Stack	Tool
Python	ruff, radon cc, radon mi, pylint
JS/TS	eslint --rule sonarjs/cognitive-complexity, complexity-report
Go	gocyclo, gocognit, staticcheck
Java	pmd, checkstyle, spotbugs

Eşik:

• Cyclomatic ≥ 10 — refactor adayı.
• Cognitive ≥ 15 — Sonar referansı.
• Function ≥ 60 sat + CC ≥ 10 — güçlü smell.
• Class ≥ 300 sat — SRP ihlali şüphesi.

3) Smell katalog (rules/clean-code.md)

Tabloyu tara. Her smell için çözüm ve risk belirle.

4) Refactor planı yaz

Sırasız değil. Sıra:

1. Renaming (revert-edilebilir, davranışsız).
2. Extract Method / Variable (small scope).
3. Extract Class / Move Method (daha büyük yapı).
4. Replace Conditional with Polymorphism (kararlar genişliyorsa).
5. Hide Delegate / Demeter (zincir kısaltma).

Her adım:

• Test yeşil öncesi/sonrası.
• Kendi commit'i (refactor(scope): ...).
• Diff küçük (LOC < 100 ideal, < 300 maks).

5) Davranış invarianti doğrula

• Test koşumu (pytest, go test, npm test).
• Snapshot test (UI'da).
• API contract test (REST/GraphQL).
• Performans benchmark (refactor perf hedefli değilse) — sapma %5'i geçmemeli.

6) Review

code-reviewer agent — refactor PR'ı bağımsız ses ile geçmeli.

• Davranış değişikliği var mı?
• Test coverage azaldı mı?
• Public API kırıldı mı?
• Diff fanout ne?

Refactor Pattern Katalogu (Fowler özet)

Composing Methods

Pattern	Tetik
Extract Method	Long method, comment'la anlatılan blok
Inline Method	Method body == method name (gereksiz indirection)
Extract Variable	Karmaşık ifade
Inline Variable	Variable kullanılmıyor / tek yerde, anlamı kayboluyor
Replace Temp with Query	Geçici değişken hesaplama, expression olabilir
Split Temporary Variable	Bir variable iki amaca hizmet ediyor
Remove Assignments to Parameters	Parametre mutate ediliyor

Moving Features

Pattern	Tetik
Move Method	Feature Envy
Move Field	Field başka sınıfa daha çok ait
Extract Class	Large Class / SRP
Inline Class	Lazy Class
Hide Delegate	Demeter chain (a.b.c.d)
Remove Middle Man	Middle Man smell

Simplifying Conditionals

Pattern	Tetik
Decompose Conditional	If branch'leri uzun
Consolidate Conditional Expression	Birden çok if aynı sonuç
Replace Nested Conditional with Guard Clauses	Erken return ile düzleştir
Replace Conditional with Polymorphism	Switch + tip-bazlı dispatch
Introduce Null Object	Null check'ler yayılmış

Making API Calls

Pattern	Tetik
Rename Method	Yanıltıcı isim
Add/Remove Parameter	API üyesi parametre değişimi
Separate Query from Modifier	Bir method hem hesap hem mutate
Parameterize Method	Aynı kod farklı sabitle
Replace Parameter with Method	Caller hesaplayabilir argüman
Introduce Parameter Object	Data Clump (3+ aynı param)
Preserve Whole Object	Param liste yerine whole object

Generalization

Pattern	Tetik
Pull Up Field/Method	Subclass'larda duplikasyon
Push Down Field/Method	Superclass üyesi sadece bir subclass'a ait
Extract Subclass / Superclass	Yeni varyasyon, ortaklık
Replace Inheritance with Delegation	Inheritance abuse, "is-a" zayıf
Replace Delegation with Inheritance	Delegasyon her metoda mekanik
Form Template Method	İki subclass benzer algoritma, ortak parça superclass'a

Checklist

• Mevcut test paketi yeşil
• Karakterizasyon testi var (test yoktu/yetersizse)
• Cyclomatic + cognitive complexity ölçüldü
• Smell tespit + Fowler pattern eşleşti
• Plan küçük adımlara bölündü, her adım kendi commit'i
• Davranış değişikliği yok (test, contract, snapshot, benchmark doğrula)
• Test coverage azalmadı
• Public API kırılmadı (kırıldıysa breaking change discipline)
• Diff < 300 LOC per commit (ideali < 100)
• code-reviewer agent APPROVE (kanıtla)

Antipattern

• "Big bang rewrite" — full file/module overwrite; review imkansız.
• Refactor + feature aynı commit — atomic commit ihlali.
• Refactor + bug fix aynı commit — review odağı dağılır.
• Test'siz refactor — davranış invarianti doğrulanamaz.
• "While you're at it" — scope yayma; dokunulmamış dosyalara müdahale.
• Renaming + extract aynı commit — diff okunamaz.
• Speculative generality — "ileride lazım olabilir" abstraction.
• Format + refactor karışık — gerçek değişiklik kaybolur.
• Refactor sırasında public API kır — versioning ile değil, sessizce.
• Coverage düşür — testleri sil, refactor et.

Örnek Agent Davranışı

User: /refactor services/api/orders/processor.py
Agent (refactor-specialist):
1. Read file: 412 satır, OrderProcessor sınıfı.
2. Test paketi: tests/api/orders/test_processor.py — coverage %62. Kabul.
3. Statik tara:
   - radon cc -s -a → ortalama CC 14, max 38 (process_order fn).
   - radon mi → 41 (D bandı, refactor adayı).
4. Smell tespit:
   - Long Method: process_order 187 sat (CC 38).
   - Switch Statement: order_type için 8-yol if/elif.
   - Feature Envy: order.customer.address.* zinciri 4 yerde.
5. Refactor planı:
   a) RENAME `proc_order` → `process_order` (consistency) [commit 1]
   b) Extract Method: payment validation → `_validate_payment` [commit 2]
   c) Extract Method: shipping calc → `_calc_shipping` [commit 3]
   d) Replace Conditional with Polymorphism: OrderTypeStrategy [commit 4]
   e) Hide Delegate: customer.address.zip → customer.zip_code [commit 5]
6. Her adımda: pytest -q tests/api/orders/ + benchmark sapma kontrol.
7. Code-reviewer agent her commit'i bağımsız review.
8. Output: 5 commit'lik PR (mantıken 5 ayrı PR olabilir).

Çıktı Formatı

# Refactor: <path>

## Mevcut Durum
- LOC, CC, MI, smell listesi
- Test coverage

## Critical / High / Medium / Low (smell başına)
- [ ] ...

## Plan (sıralı)
1. <pattern> — <hedef> — <commit subject>
2. ...

## Doğrulama
- Test paketi
- Benchmark
- Public API contract

## Riskler
- ...