dev-starter, bütün projelerimin başladığı yer ve ortak hafızası. Bir fikri piyasa taramasından geçirip plana çeviren ajanlar, güncel tech stack ile (Next 16, Tailwind v4, motion) hazır şablonlar, her projede aynı kalan bir marka kimliği, kopyalanabilir bileşenler ve ilk günden canlıya kadar sırayla izlenen rehberler burada. Yaşanmış her hata, karar ve desen kaydediliyor; komutlar ve ajanlar her makinede tek kaynaktan kuruluyor.
# Yeni makine: komutları, ajanları, global kuralları ve skill'leri kurar
git clone https://github.com/ahmetakyapi/dev-starter ~/Desktop/Projects/dev-starter
bash ~/Desktop/Projects/dev-starter/machine/bootstrap.shSonra herhangi bir klasörde Claude Code içinde:
/kickoff ergoterapistler için seans takip uygulaması
strategist ajanı birkaç soru sorar, piyasayı tarar, 2-3 yön önerir, teknolojiyi
seçer ve docs/KICKOFF.md yazar. Onay verdiğinde /new-project şablonu kurar,
paleti uygular ve ilk doğrulamayı koşar.
flowchart LR
A([Fikir]) --> K["/kickoff<br/><sub>strategist</sub>"]
K -->|KICKOFF.md| N["/new-project<br/><sub>şablon + palet</sub>"]
N --> D{{Geliştirme Döngüsü}}
D --> S["/snippet<br/><sub>snippets/ui</sub>"]
D --> R["design-reviewer<br/><sub>ekranı ölçer</sub>"]
D --> E["content-editor<br/><sub>metni düzeltir</sub>"]
S & R & E --> G["/check + gate<br/><sub>kalite kapısı</sub>"]
G --> P["/deploy<br/><sub>Vercel</sub>"]
P --> M["/roadmap<br/><sub>sırada ne var?</sub>"]
M -.-> D
classDef step fill:#0d74c4,stroke:#0a5a9a,color:#fff
classDef soft fill:#e8f1fa,stroke:#3a93d6,color:#101c2b
class K,N,G,P step
class S,R,E,M soft
Her proje aynı mantıkla kurulur: iki katmanlı token, tonla derinlik, tek
hareket eğrisi, aynı bileşen davranışı. Değişen tek şey palet. Varsayılan
signature paleti, Açılış Zili'nin lacivertten maviye uzanan ailesi.
| Her Projede Aynı | Projeye Göre Seçilen |
|---|---|
Rol adlı token'lar (--text-strong, --surface, --primary-ink) |
Vurgu ailesi (--primary ve türevleri) |
| Derinlik gölgeyle değil ton farkıyla; glass yalnızca bilinçli seçimle | Zemin ve metnin hafif renk eğilimi |
| Degrade yalnızca üç yerde: kısa başlık, birincil CTA, marka karosu | Display ve marka degradesi |
| Tek değişken font ailesi, rol adlı punto ölçeği, Title Case | Font eşleşmesi (snippets/fonts) |
Tek eğri, aynı süreler, prefers-reduced-motion |
Varsayılan tema (gündüz aracı açık, gece ürünü koyu) |
Paletler tokens.ts'te tanımlı ve her palet × tema kombinasyonu WCAG AA
kontrastına göre test ediliyor (npm test). Yukarıdaki görseller de aynı
dosyadan üretiliyor; token değişip görsel güncellenmezse CI kırılıyor.
→ guides/00-brand-identity.md
motion/react + LazyMotion (yalnızca kullanılan özellikler iner), tüm geçişler
tek eğriyle, reduced-motion her yerde. LCP başlığı asla görünmez başlamaz; Reveal
SSR'da görünür kalır. → guides/04-motion.md
| Şablon | Ne Zaman | İçinde |
|---|---|---|
nextjs-fullstack |
Ürün, panel, kullanıcılı uygulama | Next 16 · Auth.js v5 + proxy.ts · Neon + Drizzle (tembel bağlantı) · zod env · güvenlik başlıkları · 7 test dosyası · CI |
landing |
Tanıtım sayfası, portfolyo | Aynı sistem katmanı · 7 hero düzeni · içerik tek dosyada (lib/content.ts) · JSON-LD · OG |
agentic-chat |
Yapay zekâ ajanı arayüzü (overlay) | AG-UI + CopilotKit, sabitlenmiş sürümler, senaryo testleri |
docs/ |
Her proje | KICKOFF · PRODUCT · ROUTEMAP · ARCHITECTURE · SCREENS · DESIGN |
İki uygulama şablonu da temiz kurulumdan build, typecheck, lint ve test
ile doğrulanıyor.
Landing şablonunda yedi hero düzeni var; lib/content.ts içinde hero.variant
tek satırla değiştirilir. Görseller GitHub temana göre açık ya da koyu gelir.
 Canlı Veri · live-dataÖlçülebilir bir vaat ve sayıların gerçek kaynağı varsa. Varsayılan. |  Bildiri · statementMesaj tek başına güçlüyse: lansman, manifesto. |
 Editoryal İkiye Bölünmüş · editorial-splitGösterilecek gerçek bir ürün ekranı ya da fotoğraf varsa. |  Ürün Çerçevesi · product-frameSatışı arayüzün kendisi yapıyorsa; çerçeve kaydırdıkça düzleşir. |
 Bento · bentoEşit ağırlıkta 3-5 güçlü yön varsa. |  Kaydırma Sahnesi · scroll-stageHikâye üç adımda anlatılabiliyorsa. |
 Minimal · minimalİçerik ağırlıklı sayfalar: blog, belge, rehber. |
Tüm Sayfa ve Telefon
 |
 |
Kopyala-yapıştır kütüphane: her dosya tek başına projeye girer, yalnızca token
sınıflarına ve cn()'e dayanır, açık/koyu ve dört palette doğru görünür.
/snippet <ad> uyarlayarak kopyalar.
| Grup | Bileşenler |
|---|---|
| Yükleme | spinner · loading-mark · route-progress · skeleton |
| Düğme ve İkon | icon · icon-button (aria-label tipte zorunlu) · button-group · segmented-control · copy-button · kbd |
| Katmanlar | dialog · sheet (yerel <dialog>) · popover · tooltip + InfoTip · dropdown-menu · command-palette (⌘K) |
| Veri | data-table (adreste sıralama, yapışkan sütun, karşılaştırma çubuğu) · tree-view · tree-table · pagination · stat · sparkline |
| Form | switch · checkbox · radio-group · select · combobox (Türkçe süzer) · file-dropzone |
| Gezinme ve Durum | tabs · accordion · breadcrumb · badge · avatar · stepper · timeline · empty-state |
Menü, açılır pencere ve konumlandırma gibi erişilebilirliği zor parçalar
Base UI üzerinde, görünüm tamamen token'la. Ağaç ve
ağaç tablo WAI-ARIA klavye haritasını eksiksiz uygular (oklar, Home/End,
yazarak arama; ı ile I, i ile İ doğru eşleşir).
 |
 |
 | |
snippets/fonts on hazır eşleşme taşır (signature, editorial,
longform, product, playful …); hepsi latin-ext ve ğ, ş, İ, ı için ekranda
denetlendi. Ölçülerek bulunan tuzaklar rehberde: ₺ bazı ailelerde yok,
Schibsted Grotesk'te tabular-nums virgülü açıyor, capitalize Türkçede
Istanbul üretiyor. → guides/09-typography.md
→ guides/10-component-library.md · snippets/ui/README.md
Yeni bir projeye başlarken sırayla okunur; her kuralın yanında "neden" ve hangi projede yaşandığı yazar.
| # | Rehber | Ne Anlatır |
|---|---|---|
| 00 | Marka Kimliği | Değişmezler, proje türüne göre palet ve tema seçimi, yeni paletin ölçülerek türetilmesi |
| 01 | Kickoff | /kickoff'tan ilk deploy'a ilk gün ve ilk hafta listesi |
| 02 | Tasarım Token'ları | İki katman, rol adları, -ink/-wash, punto ve twMerge tuzakları, kontrast |
| 03 | Tema | Çerez + sunucuda data-theme, view transition'lı düğme, zemin katmanları |
| 04 | Hareket | LazyMotion, süre tablosu, Reveal kuralları, kaydırma ve sayfa geçişleri |
| 05 | Bileşenler | Şablon bileşenleri, ekran düzeni sırası, boş/yükleme/hata durumları |
| 06 | Next.js 16 | proxy.ts, async API'ler, önbellek katmanları, soft 404, React 19 formları |
| 07 | Veri, Kimlik, Güvenlik | Neon/Drizzle, migration disiplini, Auth.js sertleştirme, başlıklar |
| 08 | Kalite ve Yayın | Commit kapıları, smoke betiği, CWV, erişilebilirlik, deploy listesi |
| 09 | Tipografi | Font eşleşmeleri, Türkçe glif kontrolü, punto ölçeği |
| 10 | Bileşen Kütüphanesi | Başsız kütüphane kararı, klavye haritaları, a11y listesi |
| 11 | VPS, E-posta, Push | Vercel dışı deploy (Actions → SSH → sürüm dizini), env senkronu, arama motoru açılışı, Resend, Web Push |
flowchart TB
subgraph Önden["Önden Gidenler"]
ST["strategist<br/><sub>pazar · yön · teknoloji · MVP</sub>"]
RS["researcher<br/><sub>benzer çözümler, kaynaklı</sub>"]
BA["business-analyst<br/><sub>kapsam sorgusu · orkestrasyon</sub>"]
end
subgraph Kuranlar["Kuranlar"]
UX["uiux"] --- FE["frontend"] --- BE["backend"] --- AG["agentic-ui"] --- QA["qa"]
end
subgraph Ölçenler["Ölçenler"]
DR["design-reviewer<br/><sub>ekran × tema × genişlik</sub>"]
CE["content-editor<br/><sub>Türkçe ses ve doğruluk</sub>"]
GT["gate<br/><sub>6+1 geçiş, her biri komut</sub>"]
end
DP["deploy"]
ST --> BA --> Kuranlar --> Ölçenler --> DP
classDef lead fill:#0d74c4,stroke:#0a5a9a,color:#fff
class ST,GT lead
| Komut | Ne Yapar |
|---|---|
/kickoff [fikir] |
Fikri pazar taraması, yön seçenekleri, teknoloji kararları ve MVP planına çevirir |
/roadmap [odak] |
Var olan projede sıradaki en değerli 5 işi, fırsatları ve dokunulmayacakları önerir |
/new-project |
Şablon + palet + tema + belgeler + hook doğrulama |
/plan |
Planning fazını yürütür (P1→P6): belgeler + story'ler |
/story [id] |
Story'yi uçtan uca işler: alt ajanlara dağıt → Gate → commit |
/gate [story] |
6+1 pass denetim; sonuç ROUTEMAP'e — commit kapısını açar |
/fix [tarif] |
Bugfix protokolü: triage → failing test → düzeltme → kayıt |
/research [konu] |
Benzer çözümlerin kaynaklı taraması → docs/research/ |
/status |
Kaldığın yer + sıradaki en değerli 3 iş |
/retro |
Dersleri onayla bilgi tabanına işler |
/evolve |
Ekosistemin kendi gelişim turu: sağlık + tazelik + dış tarama |
/theme |
Paleti ve temayı uygular ya da günceller |
/snippet <ad> |
Bileşeni projeye uyarlayarak kopyalar |
/reference <bölüm> |
Gerçek bir sitenin bölümünü (menü, CTA, alt bilgi…) referans alır, yapısını projenin token'larıyla kurar |
/review-ui |
Token, kimlik, iki tema, ekran düzeni, a11y ve hareket incelemesi |
/check |
Build, typecheck, lint, test, token ve güvenlik sağlık kontrolü |
/agentic |
Yapay zekâ arayüzünde aracın nerede, kontrolün hangi seviyede olacağı |
/deploy |
Vercel yayın listesi |
/release |
Sürüm, changelog, etiket |
.claude/agents/ altındaki dokuz ajan (strategist, design-reviewer,
content-editor, gate, deploy, frontend, backend, qa, researcher)
bootstrap ile ~/.claude/agents'a bağlanır ve her projede kullanılabilir.
Ana oturum orkestratördür: işi Görev Zarfı ile dağıtır, sonucu ROUTEMAP'e
işler (agents/AGENT_PROTOCOL.md → Orkestrasyon).
Rol tanımlarının tek kaynağı agents/.
| Dosya | İçerik |
|---|---|
knowledge/mistakes.md |
Yaşanmış hatalar: belirti, sebep, çözüm, hangi projede (sayı yukarıdaki görselde) |
knowledge/patterns.md |
Projelerden toplanmış, test edilmiş desenler |
knowledge/decisions.md |
Ekosistem kararları ve neden değiştikleri |
knowledge/tech-radar.md |
İhtiyaç → teknoloji: benimse / dene / bekle |
knowledge/themes/ |
6 projenin görsel hafızası |
knowledge/live-projects-audit.md |
Canlı projelerin denetimi |
Her push'ta CI şunları koşar; biri kırmızıysa birleştirme yok.
| Kapı | Ne Doğrular |
|---|---|
npm test |
Token sözleşmesi, palet × tema kontrastı (WCAG AA), theme.css ↔ tokens.ts eşitliği |
lint · typecheck · build |
Paketler sıfır uyarıyla |
verify:exports · verify:lock |
Paket giriş noktaları, kilit dosyası tutarlılığı |
verify:readme |
Bu sayfadaki görseller token'larla güncel mi |
verify:agentic |
Agentic snippet'ler sabitlenmiş sürümlerle derleniyor mu |
verify:anatomy |
anatomy figür kiti iki şablonda build, tip, lint ve testten geçiyor mu |
test-hooks.sh |
Commit kancalarının davranışı |
health-check.sh |
Şablonlar yeni tech stack'te mi (Tailwind v4, flat ESLint, proxy.ts, motion) |
machine/bootstrap.sh tekrar çalıştırılması güvenli bir
kurulum betiği: global CLAUDE.md'yi, komutları, ajanları ve depoda taşınan
skill'leri ~/.claude'a bağlar (kopyalamaz; tek kaynak burada kalır),
kullanılan taste-skill parçalarını kurar, üzerine yazdığı her şeyi önce yedekler.
--dry-run ile ne yapacağını önceden gösterir. İzin listesi bilinçli olarak
taşınmaz; claude.ai eklentileri girişle kendiliğinden gelir.
→ machine/README.md
Depo Haritası
dev-starter/
├── guides/ 00-11 · projeye başlarken sırayla okunan rehberler
├── templates/
│ ├── nextjs-fullstack/ Next 16 · Auth.js · Neon/Drizzle · CI
│ ├── landing/ 7 hero düzeni · içerik tek dosyada
│ ├── agentic-chat/ AG-UI overlay
│ └── docs/ KICKOFF · PRODUCT · ROUTEMAP · ARCHITECTURE · SCREENS · DESIGN
├── snippets/
│ ├── ui/ kopyala-yapıştır bileşen kütüphanesi
│ ├── fonts/ Türkçe glif kontrolünden geçmiş font eşleşmeleri
│ └── *.tsx reveal · theme-toggle · rolling-number · modal · toast …
├── packages/@ahmet/
│ ├── theme/ theme.css (sistem + palet) · tokens.ts · index.css
│ └── ui/ Surface · Button · motion varyantları · cn()
├── agents/ 12 rol tanımı + AGENT_PROTOCOL
├── .claude/
│ ├── agents/ strategist · design-reviewer · content-editor · gate · deploy · frontend · backend · qa · researcher
│ └── commands/ 19 komut
├── knowledge/ mistakes · patterns · decisions · tech-radar · design-references · themes
├── rules/ 9 kural
├── phases/ planlama · geliştirme · uçtan uca cila · yayın ve bakım
├── hooks/ gate-guard · quality-scan · routemap-sync · session-brief
├── scripts/ health-check · audit-project · verify-* · build-readme-assets
└── machine/ bootstrap.sh · global CLAUDE.md · taşınan skill'ler
MIT · Ahmet Akyapı · Değişiklik geçmişi: CHANGELOG · Katkı: CONTRIBUTING