code-archaeology

Code Archaeology & Onboarding

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.

Felsefe

• Onboarding bir invariantdir: yeni gelene 30 dk'da repo'yu kavrayabilmeli; ilk PR'a 2-3 günde, ilk incident'e 2 hafta içinde.
• Tribal knowledge yazılı kalsın: "Ali bilir" — Ali ayrılırsa kayıp. Repo içinde keşfedilebilir doc.
• Code archaeology disiplini: "neden böyle?" sorusu git log + ADR + commit mesajı + linked issue ile cevaplanır. "Ali'ye sor" değil.
• Decision tree > arama: "X yapacağım, hangi dosyaya bakayım" sorusunu dosya gezmeden cevaplayan navigation.

Ne Zaman Kullanılır

• Yeni geliştirici onboarding (full-time / contractor / new AI session)
• Repo "yabancı kalıyor" — uzun çalışan bile "neden burası böyle?" soruyor
• Migration / rewrite öncesi kod tabanı haritası
• M&A entegrasyon (yeni acquired team kod tabanı)
• Documentation as code refresh (stale doc detection)
• Knowledge transfer (Ali ayrılıyor, knowledge handover)
• Tech debt audit (compleksite + age + churn intersect)

Workflow

1) Repo intro (1 paragraf)

[Repo adı] [bir cümlede ne yapar].
[Stack: Python/Node/Go + framework + DB].
[Sahip ekip(ler) + on-call rotasyon].
[Production scale: X RPS / Y kullanıcı / Z servis].
[Critical dependency: A (DB), B (queue), C (3rd party)].
[Public-facing: API / UI / mobile].

Örnek:

payments-platform Python (FastAPI) + Postgres + Redis + Kafka. 4 mikroservis (api-svc, worker, webhook-receiver, admin-tool); 6 mühendisli payments ekibi sahip; PagerDuty rotasyon haftalık. Prod 850 RPS peak / 12k aktif kullanıcı. Stripe (payment provider) + AWS RDS + Datadog + Cloudflare. REST API customer mobile app + admin web tool tarafından tüketilir.

2) Decision tree

"X yapacağım, hangi dosyaya bakayım?" — docs/ARCHITECTURE.md benzeri.

| Hedef | İlk durak |
|---|---|
| Yeni endpoint eklemek | `app/routes/` (FastAPI router) |
| Yeni DB tablosu | `migrations/` (Alembic) + `app/models/` (SQLAlchemy) |
| Background job | `app/tasks/` (Celery) |
| Yeni alert | `monitoring/alerts/` (Prom rule) + runbook |
| API contract change | `openapi.yaml` + `tests/contract/` (schemathesis) |
| Frontend feature | (ayrı repo) `acme/payments-frontend` |
| Bug raporu | GitHub issues + `runbooks/` |
| Üretim incident | `runbooks/incidents/` + `/production-incident` slash |
| Performance regression | `/capacity-plan` + Datadog dashboard |

3) Stack tour

Kategori	Tool	Versiyon	Komut
Build	poetry	1.7+	poetry install
Run (local)	uvicorn	—	make dev veya uvicorn app.main:app --reload
Test	pytest	8.x	make test veya pytest -q
Lint	ruff + mypy	—	make lint
Container	docker	25+	docker compose up
Migration	alembic	1.13+	alembic upgrade head
Deploy	ArgoCD	2.10	git push → auto-sync staging
Logs	Loki / Datadog	—	datadog-cli veya UI link
Trace	Tempo / Datadog APM	—	OTel SDK + Tempo backend
Secret	AWS Secrets Manager + sealed-secrets	—	kubectl get sealedsecret
CI	GitHub Actions	—	.github/workflows/ci.yml

4) Architecture map (C4 model)

Level 1: System Context

[Customer Mobile App] ──→ [Payments Platform API] ──→ [Stripe]
[Admin Web Tool]      ──→                          ──→ [Bank API]
                                                  ←── [Webhook Receiver]
                                                  ↓
                                          [Postgres + Redis + Kafka]

Level 2: Container Diagram

4 container:

• api-svc (FastAPI, port 8080, public via API GW + WAF)
• worker (Celery, no port, consumes Kafka topics)
• webhook-receiver (FastAPI, port 8081, public via dedicated subdomain + signature verify)
• admin-tool (FastAPI + simple HTML, port 8082, internal-only via VPN)

Level 3: Component Diagram

api-svc içinde:

• app/routes/ — HTTP handlers (thin)
• app/services/ — business logic
• app/repositories/ — DB access (SQLAlchemy)
• app/integrations/ — external API client (Stripe, bank)
• app/observability/ — logger + tracer + PII redact

Level 4: Code (drill-down on demand)

Karmaşık dosya/sınıf detayı (sadece refactor / debug için).

5) Glossary (docs/GLOSSARY.md benzeri)

Domain dili + tooling:

Terim	Tanım
Order	Müşterinin satın alma niyeti; lifecycle: created→pending→paid→shipped→delivered
Payment Intent	Stripe terminolojisi; payment'ı initiate eden token
Idempotency Key	Client-generated UUID; same key → same response 24h
Webhook	3rd party (Stripe/bank) event push'u; signature verify zorunlu
PCI scope	DB'de full PAN saklanan resource'lar; minimize tarih
MTTD/MTTR	Mean Time to Detect / Recover (incident metric)
PgBouncer	PostgreSQL connection pooler (transaction mode)
SLO/SLI	Service Level Objective/Indicator (error budget hesabı)

6) Common task playbook

Yeni endpoint ekle

1. app/routes/<resource>.py route handler.
2. app/services/<resource>_service.py business logic.
3. app/schemas/<resource>.py Pydantic input/output.
4. tests/api/test_<resource>.py pytest + httpx.
5. openapi.yaml schema güncelle (auto-gen via FastAPI).
6. CHANGELOG ### Added satır.

Yeni alert ekle

1. monitoring/alerts/<service>.yaml Prom rule.
2. Runbook: runbooks/<alert-name>.md (alert→action→escalation).
3. Dashboard panel: Grafana JSON.
4. PagerDuty service mapping.
5. Test alert: feature flag ile fire et + runbook çalıştır.

Migration (DB)

1. alembic revision --autogenerate -m "<desc>".
2. Review SQL output (autogenerate yetersiz olabilir).
3. Backward compatible ekle (drop sonra ayrı PR).
4. CI'da alembic upgrade head test.
5. Staging'de sun + monitor + prod plan.

(daha fazla playbook task'a göre).

7) Code archaeology — "Neden böyle?"

Sorular ve nasıl cevap bulunur:

Soru	Komut
Bu fonksiyon ne zaman/kim yazdı?	git log --follow -p path/file.py
Bu satırı kim ekledi?	git blame path/file.py veya git log -L start,end:file
Bu sınıf neden var?	linked issue/PR (commit message), ADR (docs/adr/)
Mimari karar gerekçesi?	docs/adr/NNN-*.md
Çıkmış incident var mı?	runbooks/postmortems/ veya git log --grep=incident
Refactor planı var mı?	GitHub issue tech-debt label
Tribal: "Bu değişmesin"	# DO NOT TOUCH comment + git blame ile sahip

8) Tribal knowledge çıkarımı

• Slack scrape (read-only): #engineering #oncall channel son 6 ay archive → "neden X" pattern bul.
• Retro / postmortem doc archive: docs/postmortems/ + docs/retro/.
• ADR: docs/adr/ Markdown decision records.
• Wiki / Notion archive: tribal pages → repo'ya markdown migrate.
• 1:1 with departing engineer: 30 dk session × 5 kişi = "neden X" cevapları yazılı.

9) Onboarding KPI

Metric	Hedef
Repo intro okuma	< 5 dk
İlk environment kurulum	< 1 saat
İlk PR (trivial fix)	< 3 gün
İlk PR (feature)	< 2 hafta
İlk on-call shadow	< 1 ay
İlk on-call solo	< 3 ay
Repo sürpriz oranı ("nereden geldi bu")	< 1 / hafta sonrası

Checklist

• Repo intro 1 paragraf (kullanıcı dilinde, ROI dahil)
• Decision tree (X için hangi dosya)
• Stack tour (tool + versiyon + komut)
• C4 model (Level 1 + 2 minimum; 3-4 on-demand)
• Glossary (domain + tooling)
• Common task playbook (≥ 3 most-frequent)
• Code archaeology rehberi (git log/blame + ADR + postmortem)
• Tribal knowledge çıkarımı (Slack + retro + 1:1)
• Onboarding KPI tracking
• Stale doc detection (≥ 6 ay update yok → review)

Antipattern

• "Ali bilir" — knowledge tek kişide.
• Wiki dışarda (Notion/Confluence) — repo dışı doc kaybolur.
• Stale README — komutlar artık çalışmıyor.
• Decision tree yok — yeni geliştirici dosya gezerek öğrenir.
• C4 model yok — sözel mimari anlatım, çelişkili.
• Glossary yok — "Order" 3 farklı şey demek olabilir.
• Common task playbook yok — herkes farklı yapıyor.
• ADR yok — major karar gerekçesi kayıp.
• Postmortem doc'ları gizli — incident öğrenmesi tekrar.
• Onboarding KPI ignore — yeni gelenin engeli görünmez.
• Tribal knowledge sadece Slack DM — searchable değil.
• Repo "büyük temizlik" ile rewrite — git geçmişi ölü, archaeology imkansız.

Örnek Agent Davranışı

User: /onboard payments-platform
Agent (architecture-cartographer):
1. Repo intro: 1 paragraf (FastAPI + Postgres + ...).
2. Decision tree: 9 madde tablo.
3. Stack tour: 11 tool + versiyon + komut.
4. C4 Level 1+2: ASCII diagram.
5. Glossary: 8 kritik terim.
6. Common task: 3 playbook (endpoint / alert / migration).
7. Code archaeology guide: 7 soru → komut.
8. Tribal: Slack archive 6 ay scrape öner; ADR template ekle.
9. KPI: 7 metric + dashboard önerisi.
10. Output: `docs/ONBOARDING.md` doldurulmuş.
11. Eksik: ADR yok (Critical) + 4 ay'lık stale README (High).
12. Action item: 8 issue (sahip + tarih).

Çıktı Formatı

# Onboarding: <repo>

## Repo Intro

## Decision Tree
| Hedef | İlk durak |

## Stack Tour
| Kategori | Tool | Versiyon | Komut |

## Architecture (C4)

## Glossary

## Common Task Playbook

## Code Archaeology

## Tribal Knowledge Çıkarımı

## Onboarding KPI

## Critical / High / Medium / Low Eksik

## Action Items
| P | Aksiyon | Sahip | Bitiş | Issue |