template-scaffolding

Template Scaffolding

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 servisin Helm chart'ı, K8s manifest'leri veya Dockerfile'ı sıfırdan oluşturulacak
• Mevcut projede Nginx reverse proxy / PgBouncer / Redis konfigürasyonu eksik
• GitHub Actions reusable build workflow projeye ekleniyor
• Runbook iskeleti üretilecek
• /scaffold komutu çalışıyor

Workflow

1) Bağlam topla

• git rev-parse --show-toplevel → repo kökü
• Mevcut izler: charts/, deploy/, Dockerfile, docker-compose.yml, nginx/, infra/, runbooks/, .github/workflows/
• Stack tespiti: SessionStart hook çıktısı + manuel cat (package.json, pyproject.toml, go.mod, Chart.yaml)

2) Hedef yolu kararlaştır

kind	hedef
helm	charts/<name>/
docker	Dockerfile (root) veya services/<name>/Dockerfile
compose	docker-compose.yml (root)
k8s	deploy/k8s/<name>/
nginx	infra/nginx/reverse-proxy.conf
pgbouncer	infra/pgbouncer/{pgbouncer.ini,userlist.txt.example}
redis	infra/redis/redis.conf
github-actions	.github/workflows/build.yml (caller; reusable: bu plugin)
runbook	runbooks/<name>.md

3) Dry-run sun

Yazıcı operasyon yapmadan kullanıcıya:

• Kopyalanacak dosyalar listesi.
• Düzenlenecek placeholder'lar (Chart.yaml.name, image.repository, vb.).
• Mevcut hedef dosyayla çakışma varsa diff göster — sessiz overwrite yasak.

Onay alınana kadar bekleyiş; otomatik ilerleme yok.

4) Onaylı kopyalama

cp -r "${CLAUDE_PLUGIN_ROOT}/templates/<kind>/..." <hedef>

• templates/ kaynağı read-only — değiştirme.
• Mode + ownership korunsun.

5) Placeholder düzelt

• helm: Chart.yaml.name, Chart.yaml.description, Chart.yaml.appVersion, values.yaml.image.repository.
• docker: Dockerfile base image versiyonu projeye göre, WORKDIR ve user/group.
• github-actions: image-name input → ghcr.io/$ORG/$REPO.
• runbook: REPLACE_* alanları boş bırakma → [TODO: kim/dashboard/escalation] ile flagle.
• Secret/credential'ı gerçek değerle doldurma; ${ENV_VAR} veya secretRef formu öner.

6) Validate

• helm: helm lint <hedef> + helm template ci <hedef> | kubeconform -strict
• k8s: kubeconform -strict <hedef>/*.yaml
• docker: hadolint Dockerfile
• nginx: nginx -t -c <hedef> (varsa)
• github-actions: actionlint .github/workflows/build.yml (varsa)

7) Sonraki adım öner

• helm → values-staging.yaml override + secure-deployment-review skill.
• k8s → /k8s-debug ile dry-run.
• docker → /docker-review.
• nginx → /nginx-check.
• runbook → runbook-author agent ile içerik doldur.

Checklist

• Hedef yol mevcut emsali takip ediyor (charts/, deploy/, infra/)
• Çakışmada onay alındı
• Placeholder'lar düzeltildi (image, name, description, env)
• Secret/credential repo'ya yazılmadı
• Validate adımı (lint/kubeconform/hadolint) yeşil
• Sonraki adım önerisi yazılı

Antipattern

• templates/ içindeki dosyaları değiştirme — kaynak read-only.
• Mevcut charts/<name>/ veya Dockerfile üzerine sessiz overwrite.
• Production image.tag'ı latest veya floating tag — digest pin (@sha256:...) tercih.
• Helm NetworkPolicy namespaceSelector: {} (her ns demek!) override etme — templates/helm/app/values.yaml zaten daraltılmış default veriyor, override ederken bu hataya düşme.
• Runbook'ta REPLACE_* placeholder bırakma — [TODO: ...] ile flagle veya doldur.
• docker-compose.yml template'ini prod'a ölçeklemek için kopyalama — prod için K8s/Helm'e geç (/compose-to-k8s).

Örnek Agent Davranışı

User: /scaffold helm payments-api
Agent (platform-engineer):
1. Bağlam: `charts/` yok, repo Python+FastAPI servis.
2. Hedef: charts/payments-api/. Çakışma yok.
3. Dry-run plan: 9 dosya kopyalanacak; Chart.yaml.name + values.yaml.image.repository düzeltilecek.
4. [Kullanıcı onayı bekleniyor]
5. cp -r → düzelt → helm lint OK → kubeconform 7/7 valid.
6. security-reviewer'a delege: NetworkPolicy egress prod'da `ipBlock` ile sıkılaştır.
7. Sonraki: values-staging.yaml override, /secure-deployment-review.

Çıktı Formatı

# Scaffold: <kind> <name>

## Plan (dry-run)
- Kopyalanacak: ...
- Düzenlenecek: ...
- Çakışma: ...

## Onay sonrası
- Kopyalandı: ...
- Düzeltildi: ...
- Validate: ...

## Sonraki Adım
1. ...