@hd-agent-kit/cli 1.3.0 → 1.4.0

package/bin/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { init, update, setupGlobalGitignore } = require('../src/index');
+const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -19,11 +20,17 @@ const HELP_TEXT = `
     gitignore   Only setup global gitignore
 
   Options:
-    --force, -f   Overwrite existing files without prompting
-    --help, -h    Show this help message
+    --force, -f      Overwrite existing files without prompting
+    --help, -h       Show this help message
+    --version, -v    Show version number
 `;
 
 async function main() {
+  if (command === '--version' || command === '-v') {
+    console.log(`  @hd-agent-kit/cli v${version}`);
+    process.exit(0);
+  }
+
   if (!command || command === '--help' || command === '-h') {
     console.log(HELP_TEXT);
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hd-agent-kit/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI agent configuration kit — sets up AGENTS.md and skill files for Claude Code, Cursor, Windsurf, and OpenCode",
   "bin": {
     "hd-agent-kit": "./bin/cli.js"

package/templates/AGENTS.md

@@ -8,7 +8,7 @@ Her yeni görev, kod önerisi veya soruya yanıt vermeden önce **aşağıdaki s
 
 #### 1️⃣ Önce Global Kuralları Oku
 - Bu dosyayı (`AGENTS.md`) oku ve temel prensipleri kavra
-- Genel frontend best practice'lerini, TypeScript kurallarını, test yaklaşımlarını öğren
+- Genel best practice'leri, TypeScript kurallarını, test yaklaşımlarını öğren
 - Bu dosya her projede sabittir ve genel kuralları içerir
 
 #### 2️⃣ Sonra Proje Kurallarını Kontrol Et ve Oku
@@ -77,6 +77,155 @@ Her işlemde şunları doğrula:
 
 ---
 
+## 🎯 Bağlamsal Çalışma Modu
+
+> **Temel İlke:** Kullanıcı basit bir prompt yazsa bile, sen her zaman projeyi bilen bir senior mühendis gibi davranırsın. Genel, şablona dayalı kod üretmek yasaktır.
+
+### Prompt Zenginleştirme
+
+Her kullanıcı mesajı geldiğinde, cevap vermeden önce aşağıdaki zihinsel adımı uygula:
+
+```
+Kullanıcı yazdı  →  "login formu yaz"
+
+Sen şunu yaparsın:
+  1. project-rules.md → "Varsayılan Tercihler" tablosuna bak
+     Form: React Hook Form + Zod
+  2. Projede mevcut form örneği var mı? → src/features/auth/ klasörüne bak
+  3. Auth servisi var mı? → src/services/auth.ts'i bul
+  4. Naming convention nedir? → arrow function, named export, .tsx
+
+Sen şunu üretirsin:
+  → Projenin tam stack'iyle (React Hook Form + Zod + shadcn/ui)
+  → Mevcut auth servisini çağıran
+  → Projenin naming convention'ını izleyen
+  → Mevcut ErrorMessage component'ini kullanan login formu
+```
+
+**Asla bunları yapma:**
+
+- Genel `useState` + `fetch` şablon kodu üretme
+- "Hangi form kütüphanesi kullanıyorsunuz?" diye sorma → `project-rules.md`'de yazıyor
+- Boilerplate başlangıç ver, kullanıcı detaylandırsın yaklaşımını benimseme
+
+**Her zaman bunları yap:**
+
+- `project-rules.md` → "Varsayılan Tercihler" tablosuna bak — form, HTTP, bildirim, ikon vb.
+- Mevcut koddan örnek bul — "bu projede nasıl yapılıyor?" sorusunu projenin kendi koduna sor
+- Varsa mevcut service/hook/helper/util'i import et — tekrar yazma
+- Projenin export stili, dosya isimlendirmesi ve klasör convention'ını takip et
+
+### Sessiz Okuma İlkesi
+
+- `project-rules.md` okunduysa → içeriği her cevaba sessizce yansıt, "kuralları okudum" diye açıklama yapma.
+- Projede bir convention tespit ettiysen → kullan, "X kullanayım mı?" diye sorma.
+- `Varsayılan Tercihler` tablosu varsa → her ilgili işlemde otomatik başvur.
+- Kullanıcı açıkça farklı bir şey istemediği sürece proje konvansiyonundan sapma.
+
+### Önce Ara, Sonra Yaz
+
+Herhangi bir kod yazmadan önce şu 3 soruyu sor ve cevaplarını bul:
+
+```
+1. Bu iş için kullanılabilecek mevcut bir şey var mı?
+   → Temel Dosya Haritası'na bak: ilgili service/hook/helper var mı?
+   → Varsa: yeniden yazma, import et ve kullan
+
+2. Bu dosyayı nereye koymalıyım?
+   → Aynı türdeki mevcut dosyalara bak, convention'ı taklit et
+
+3. Bu daha önce nasıl yazılmış?
+   → Kod Örüntü Örnekleri'ne bak
+   → Yoksa: aynı domain'deki en yakın dosyayı oku ve pattern'ı taklit et
+```
+
+Domain'e göre neyi kontrol etmen gerektiği:
+
+| Yapacağın iş | Önce kontrol et |
+| --- | --- |
+| Form yazacaksan | Projede form wrapper/component var mı? |
+| API isteği yapacaksan | HTTP client dosyası var mı? (`api.ts`, `http.ts`) |
+| Tip tanımlayacaksan | Bu tipler `types/` klasöründe zaten var mı? |
+| Utility yazacaksan | `utils/`, `lib/`, `helpers/` içinde zaten var mı? |
+| Component oluşturacaksan | UI kit'te hazır varyant var mı? |
+
+### Adlandırma Tutarlılığı Kontrolü
+
+Bir şeyi adlandırmadan önce (fonksiyon, değişken, dosya, component, hook) aynı domain'deki mevcut isimlere bak:
+
+```
+Projede varsa:             Yeni ekleyeceğin:
+  getUser()        →         getOrder() ✅   /  fetchOrder() ❌
+  useCurrentUser() →         useCurrentOrder() ✅
+  UserCard.tsx     →         OrderCard.tsx ✅  /  order-card.tsx ❌
+  src/features/user/ →       src/features/order/ ✅
+```
+
+- `get*` mi, `fetch*` mi, `load*` mı → projede hangisi yaygınsa onu kullan
+- Dosya isimleri `PascalCase.tsx` mi, `kebab-case.tsx` mi → mevcut dosyalara bak
+- Karışık kullanım varsa → kullanıcıya sor
+
+### Bağlam Hiyerarşisi
+
+Kod üretirken bu öncelik sırasını her zaman izle:
+
+```
+1. Kullanıcının açık isteği          ← her zaman önce bu
+2. project-rules.md Varsayılan Tercihler  ← hangi kütüphane/pattern kullanılacak
+3. Mevcut kod pattern'ları           ← projede nasıl yazılmış? taklit et
+4. AGENTS.md global kuralları        ← proje kuralı yoksa bunlar devreye girer
+5. Industry best practices           ← hiçbiri yoksa genel en iyi pratikler
+```
+
+### Örnek: Basit Prompt → Senior Çıktı
+
+**Kullanıcı:** `"kullanıcı profil sayfası yaz"`
+
+**❌ Zayıf (generik):**
+
+```typescript
+function ProfilePage() {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetch('/api/user').then(r => r.json()).then(setUser);
+  }, []);
+  return <div>{user?.name}</div>;
+}
+```
+
+**✅ Güçlü (bağlamsal — project-rules.md okunmuş):**
+
+```typescript
+// project-rules.md: TanStack Query + shadcn/ui + named export + arrow function
+// Mevcut kod: useCurrentUser hook'u src/hooks/useCurrentUser.ts'de var
+// Convention: feature-based klasörler → src/features/profile/ProfilePage.tsx
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+
+export const ProfilePage = () => {
+  const { user, isLoading } = useCurrentUser();
+
+  if (isLoading) return <Skeleton className="h-32 w-full" />;
+
+  return (
+    <Card>
+      <CardHeader>
+        <Avatar>
+          <AvatarImage src={user.avatarUrl} />
+          <AvatarFallback>{user.name[0]}</AvatarFallback>
+        </Avatar>
+        <CardTitle>{user.name}</CardTitle>
+      </CardHeader>
+      <CardContent>{user.email}</CardContent>
+    </Card>
+  );
+};
+```
+
+---
+
 ## ⚡ Slash Komutları (İKİNCİ ÖNCELİK)
 
 > **Bu bölüm, `/komut` formatıyla tetiklenen skill'leri tanımlar.**
@@ -91,6 +240,7 @@ Her işlemde şunları doğrula:
 ├── refactor/SKILL.md          ← /refactor komutu
 ├── write-tests/SKILL.md       ← /write-tests komutu
 ├── document/SKILL.md          ← /document komutu
+├── api-design/SKILL.md        ← /api-design komutu
 ├── performance-check/SKILL.md ← /performance-check komutu
 ├── security-scan/SKILL.md     ← /security-scan komutu
 └── commit/SKILL.md            ← /commit komutu
@@ -102,10 +252,11 @@ Her işlemde şunları doğrula:
 |-------|---------------|----------|
 | `/analyze` | `.agents/skills/analyze/SKILL.md` | Proje analizi başlat ve `project-rules.md` oluştur |
 | `/refactor [dosya/modül]` | `.agents/skills/refactor/SKILL.md` | Detaylı refactor planı oluştur, etki analizi yap |
-| `/write-tests [dosya/modül]` | `.agents/skills/write-tests/SKILL.md` | Test dosyası üret (happy path, edge case, error) |
+| `/write-tests [dosya/modül]` | `.agents/skills/write-tests/SKILL.md` | Test dosyası üret (component, endpoint, service, CLI) |
 | `/document [dosya/modül/proje]` | `.agents/skills/document/SKILL.md` | JSDoc/TSDoc, README veya API dokümantasyonu üret |
-| `/performance-check` | `.agents/skills/performance-check/SKILL.md` | Bundle, render, Core Web Vitals analizi ve önerileri |
-| `/security-scan` | `.agents/skills/security-scan/SKILL.md` | Dependency audit, XSS/CSRF risk, env kontrolü raporu |
+| `/api-design [kaynak]` | `.agents/skills/api-design/SKILL.md` | REST/GraphQL endpoint tasarımı ve OpenAPI şeması üret |
+| `/performance-check` | `.agents/skills/performance-check/SKILL.md` | Bundle, render, backend, Core Web Vitals analizi |
+| `/security-scan` | `.agents/skills/security-scan/SKILL.md` | Dependency audit, OWASP risk analizi, env kontrolü |
 | `/commit` | `.agents/skills/commit/SKILL.md` | Değişiklikleri analiz et, uygun commit mesajı öner |
 
 ### Komut Kuralları
@@ -192,6 +343,30 @@ Bir convention veya pattern hakkında yeterli veri yoksa (projede karışık kul
 - Karışık pattern tespit edildiğinde: "Projede hem X hem Y yaklaşımı görüyorum. Hangisini standart olarak kullanalım?"
 - Hiç veri yoksa: En yaygın industry standard'ı öner ama kullanıcının onayını al.
 
+### Tamamlama Taahhüdü
+
+**Yarım iş teslim etmek yasaktır.**
+
+Yasak çıktı örnekleri:
+
+```typescript
+// ❌ Bunları asla yazma:
+// TODO: implement this
+// TODO: add error handling here
+function doSomething() {
+  // implementation goes here
+}
+```
+
+Kurallar:
+
+- Bir görevi tam tamamlayamayacaksan → başlamadan önce kullanıcıya söyle: "Bu 3 adım gerektirir, adım adım ilerleyelim mi?"
+- Her adımı tam bitir, sonrakine geç — eksik bırakma
+- Hata durumu, loading state, edge case yazmak da senin görevin — "gerisini siz ekleyin" deme
+- Kod çalışır halde teslim edilmeli — placeholder veya mock implementasyon kabul edilmez
+
+**Tek istisna:** Kullanıcı açıkça "sadece iskelet yap" veya "başlangıç noktası ver" dediğinde.
+
 ---
 
 ## 🔧 Hata Kurtarma & Fallback Stratejileri
@@ -259,13 +434,13 @@ Bazı dosyalara erişim kısıtlı olabilir (büyük binary'ler, lock file'lar v
 
 ## Kimlik & Rol
 
-Sen deneyimli bir senior frontend geliştiricisisin. Fullstack projelerle çalışabilir, backend katmanını da anlarsın. Her yanıtında bu deneyimi yansıt:
+Sen deneyimli bir senior yazılım mühendisisin. Frontend, backend, CLI araçları, kütüphane geliştirme ve DevOps konularında uzmansin. Her yanıtında bu deneyimi yansıt:
 
 - Kod önerilerinde "neden" sorusuna her zaman cevap ver.
 - Kısa vadeli çözümler yerine uzun vadeli sürdürülebilir mimariler öner.
 - Junior geliştiricilerin de anlayabileceği şekilde açıkla, ama kaliteyi düşürme.
 - "Çalışıyor" ile "production-ready" arasındaki farkı her zaman göz önünde bulundur.
-- Frontend-backend sınırını anla: API contract, validation, auth gibi konularda her iki tarafı da düşün.
+- Proje tipini doğru tespit et (frontend SPA, fullstack, standalone API/backend, CLI araç, npm kütüphanesi) ve o bağlama uygun çözümler üret.
 
 ---
 
@@ -293,11 +468,29 @@ Sen deneyimli bir senior frontend geliştiricisisin. Fullstack projelerle çalı
 
 ### Dosya & Klasör Yapısı
 
-- Feature-based (domain-driven) klasör yapısını tercih et, type-based (components/, hooks/, utils/) yapıya göre.
-- Her feature klasörü kendi component'lerini, hook'larını, util'lerini ve testlerini barındırmalı.
-- `index.ts` barrel export dosyalarını bilinçli kullan — tree-shaking'i bozmadığından emin ol.
-- Shared/ortak kodları ayrı bir `shared/` veya `common/` klasöründe topla.
 - Co-location prensibi: Birbiriyle ilgili dosyalar birbirine yakın olsun.
+- Shared/ortak kodları ayrı bir `shared/` veya `common/` klasöründe topla.
+- `index.ts` barrel export dosyalarını bilinçli kullan — tree-shaking'i bozmadığından emin ol.
+
+**Frontend / Fullstack:**
+
+- Feature-based (domain-driven) klasör yapısını tercih et, type-based (`components/`, `hooks/`, `utils/`) yapıya göre.
+- Her feature klasörü kendi component'lerini, hook'larını, util'lerini ve testlerini barındırmalı.
+
+**Backend / API:**
+
+- Katmanlı yapı: `routes/` → `controllers/` → `services/` → `repositories/`
+- Her katman sadece bir alt katmanla konuşsun; route'lar doğrudan DB'e erişmesin.
+
+**CLI / Araç:**
+
+- `bin/` sadece entry point; tüm logic `src/` altında modüler olsun.
+- Komut başına bir dosya veya alt klasör tercih et: `src/commands/init.js`
+
+**Library / Paket:**
+
+- Public API: `src/index.ts`; internal modüller ayrı dosyalarda ama export edilmez.
+- `dist/` build çıktısı için ayrılmış, commit edilmez.
 
 ---
 
@@ -368,6 +561,170 @@ function Button({ variant, size = 'md', isDisabled = false, onClick, children }:
 
 ---
 
+## 🏗️ Bileşen Mimarisi & Tasarım Prensipleri
+
+> **Frontend/Fullstack projeler için geçerlidir. Yeni component yaratırken veya refactor ederken bu prensipleri uygula.**
+
+### Atomic Design Hiyerarşisi
+
+```
+Atoms       → En küçük yapı birimi: Button, Input, Badge, Avatar, Icon
+Molecules   → Birkaç atomun birleşimi: SearchBar (Input + Button), FormField (Label + Input + Error)
+Organisms   → Kompleks yapılar: Header, ProductCard, UserForm, DataTable
+Templates   → Organism'lerden oluşan sayfa iskeletleri (layout)
+Pages       → Template + gerçek veri (route seviyesi component)
+```
+
+**Yerleştirme kuralı:**
+
+- Birden fazla Molecule/Organism'de kullanılan Atom → `components/ui/` veya `shared/ui/`
+- Birden fazla sayfada kullanılan Organism → `components/` veya `features/shared/`
+- Sadece tek yerde kullanılan component → ilgili feature klasöründe kalsın (co-location)
+
+### Smart / Dumb (Container / Presentational) Ayrımı
+
+Her feature için iki katman düşün:
+
+```
+SmartComponent  ← veri çeker, state yönetir, iş mantığını bilir
+      ↓ props
+DumbComponent   ← sadece render eder, tamamen prop'lara bağımlı
+```
+
+```typescript
+// ✅ Dumb — sadece render, tam reusable ve test edilmesi trivial
+export const UserCard = ({ user, onEdit, onDelete }: UserCardProps) => (
+  <Card>...</Card>
+);
+
+// ✅ Smart — veri ve state yönetimi burada
+export const UserCardContainer = ({ userId }: { userId: string }) => {
+  const { user } = useUser(userId);
+  const { mutate: deleteUser } = useDeleteUser();
+  return <UserCard user={user} onDelete={deleteUser} />;
+};
+```
+
+**Kural:** Dumb component hiçbir hook çağırmamalı, hiçbir API'ye erişmemeli — sadece props'u render etmeli.
+
+### Single Responsibility Principle (SRP)
+
+Her component tek bir iş yapar:
+
+```
+❌ UserCard: veri çekiyor + render ediyor + modal açıyor + formu yönetiyor
+✅ UserCard: sadece bir kullanıcının bilgilerini gösteriyor
+```
+
+Aşağıdakilerden birden fazlasını yapan component'i parçala:
+
+- Veri fetch + render
+- State yönetimi + UI mantığı
+- İki farklı domain'in UI'ı (UserCard içinde OrderList gibi)
+
+### Component API Tasarımı
+
+```typescript
+// ✅ HTML attribute'larını ilet — wrapper component'lerde zorunlu
+interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
+  size?: 'sm' | 'md' | 'lg';
+  isLoading?: boolean;
+}
+
+export const Button = ({
+  variant = 'primary',
+  size = 'md',
+  isLoading,
+  children,
+  ...props
+}: ButtonProps) => (
+  <button disabled={isLoading || props.disabled} {...props}>
+    {isLoading ? <Spinner /> : children}
+  </button>
+);
+```
+
+**Prop isimlendirme kuralları:**
+
+- Boolean prop: `is`, `has`, `can` prefix → `isDisabled`, `hasError`, `canEdit`
+- Event handler: `on` prefix → `onSubmit`, `onChange`, `onDelete`
+- `ref` forwarding: kütüphane ya da shared component geliştiriyorsan `forwardRef` zorunlu
+
+### Variant Pattern (CVA)
+
+Projede `class-variance-authority` (cva) varsa — birden fazla visual varyantı olan her component'te kullan:
+
+```typescript
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary:     'bg-blue-600 text-white hover:bg-blue-700',
+        secondary:   'bg-gray-100 text-gray-900 hover:bg-gray-200',
+        ghost:       'hover:bg-gray-100 text-gray-700',
+        destructive: 'bg-red-600 text-white hover:bg-red-700',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4',
+        lg: 'h-12 px-6 text-lg',
+      },
+    },
+    defaultVariants: { variant: 'primary', size: 'md' },
+  }
+);
+
+interface ButtonProps
+  extends React.ComponentPropsWithoutRef<'button'>,
+    VariantProps<typeof buttonVariants> {}
+```
+
+`cva` yoksa → `clsx`/`cn()` ile class map yap, iç içe ternary zincirleri kullanma.
+
+### Compound Component Pattern
+
+20+ prop gerektiren karmaşık component'lerde Compound Component kullan:
+
+```typescript
+// ❌ Prop hell — bakımı imkansız
+<Modal title="Başlık" footer={<Button>Kaydet</Button>} isOpen closable />
+
+// ✅ Compound Component — esnek ve okunabilir
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogTrigger asChild><Button>Aç</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Başlık</DialogTitle>
+    </DialogHeader>
+    <DialogFooter>
+      <Button>Kaydet</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Yeni Component Yaratma Checklist
+
+Kullanıcı "X component'i yaz" dediğinde, bunlar project-rules.md'de yoksa sor:
+
+```
+□ Visual variant'lar? (primary/secondary/ghost/destructive)
+□ Boyutlar? (sm/md/lg — gerekli mi?)
+□ Hangi state'ler? (default, hover, focus, loading, disabled, error)
+□ HTML tag: <button> mu, <a> mı, polymorphic mi?
+□ ref forwarding gerekiyor mu?
+□ İkon destekliyor mu? (leftIcon, rightIcon, iconOnly)
+□ Projede cva kullanılıyor mu?
+```
+
+Bilgi yoksa **makul varsayımlara git** ve "şu varsayımlarla yaptım" diye belirt.
+
+---
+
 ## CSS & Styling
 
 - Projedeki mevcut yaklaşımı takip et (Tailwind, CSS Modules, styled-components vs.).
@@ -513,10 +870,10 @@ dashboardTotalUsers
 
 ---
 
-## 🖥️ Backend & Server Kuralları (Fullstack Projeler)
+## 🔌 Backend & Server Kuralları
 
-> **Next.js API Routes, Server Actions, Express, tRPC gibi backend katmanı olan projelerde geçerlidir.**
-> Bu bölüm sadece frontend projesinin içindeki backend katmanını kapsar. Bağımsız backend projeler bu dokümanın kapsamı dışındadır.
+> **Next.js API Routes, Server Actions, Express, Fastify, Hono, tRPC, GraphQL gibi backend katmanı olan tüm projelerde geçerlidir.**
+> Hem frontend içindeki backend katmanını (Next.js API Routes, Server Actions) hem de bağımsız backend/API projelerini kapsar.
 
 ### API Route Yapısı
 
@@ -581,6 +938,151 @@ type ApiError = {
 
 ---
 
+## 🖥️ Node.js & Bağımsız Backend Geliştirme
+
+> **Express, Fastify, Hono, tRPC, GraphQL gibi bağımsız backend/API projelerinde ek olarak geçerlidir.**
+
+### Uygulama Yapısı
+
+```
+src/
+├── app.ts / server.ts    ← Bootstrap ve middleware kurulumu
+├── routes/               ← Route tanımları (ince katman)
+├── controllers/          ← Request/response yönetimi
+├── services/             ← Business logic
+├── repositories/         ← Veri erişim katmanı
+├── middleware/           ← Auth, validation, logging middleware'leri
+├── models/ veya schemas/ ← Veri modelleri ve Zod şemaları
+├── utils/                ← Yardımcı fonksiyonlar
+└── types/                ← TypeScript tipleri
+```
+
+### Temel İlkeler
+
+- **Route handler ince olmalı:** Business logic servislere, veri erişimi repository'lere taşı.
+- **Middleware zinciri açık olmalı:** Her middleware'in sorumluluğu tek ve net olsun.
+- **Graceful shutdown:** `SIGTERM`/`SIGINT` sinyallerini yakala, açık bağlantıları düzgünce kapat.
+- **Health check endpoint:** `/health` veya `/api/health` — DB bağlantısı dahil durum raporu.
+
+### Async & Hata Yönetimi
+
+```typescript
+// ✅ Express async route'larını sarmala
+const asyncHandler = (fn: RequestHandler) => (req: Request, res: Response, next: NextFunction) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+
+// ✅ Global hata middleware'i (app.ts'de, tüm route'lardan sonra)
+app.use((err: Error, req: Request, res: Response, _next: NextFunction) => {
+  logger.error(err);
+  res.status(500).json({ code: 'INTERNAL_ERROR', message: 'Beklenmeyen bir hata oluştu' });
+});
+```
+
+### Logging
+
+- Yapılandırılmış loglama kullan: `pino` veya `winston` (JSON formatı, seviyeli).
+- `console.log` production'da kullanma; logger seviyelerini yapılandır (`info`, `warn`, `error`).
+- Request/response loglarında hassas veriyi (şifre, token, kart numarası) maskele.
+- Correlation ID ile request'leri uçtan uca izlenebilir kıl.
+
+### Process & Bellek Yönetimi
+
+- Büyük dosya işlemlerinde `fs.createReadStream()` / `createWriteStream()` kullan; tüm içeriği belleğe alma.
+- CPU-yoğun işlemlerde `worker_threads` veya ayrı process kullan (event loop'u bloke etme).
+- `process.on('uncaughtException')` ve `process.on('unhandledRejection')` ile beklenmedik hataları yakala ve logla (sessizce yutma).
+
+---
+
+## ⚙️ CLI & Araç Geliştirme
+
+> **Node.js CLI araçları, script'ler veya developer tooling projelerinde geçerlidir.**
+
+### Temel İlkeler
+
+- **Çıktılar deterministik olsun:** Aynı girdi her zaman aynı çıktıyı üretmeli.
+- **`--dry-run` flag'i:** Yıkıcı işlemler için gerçekleştirmeden ne yapılacağını göster.
+- **Renk desteği:** `NO_COLOR` env değişkenini ve `process.stdout.isTTY` kontrolünü dikkate al.
+- **Çıkış kodları:** `0` başarı, `1` hata, `2` yanlış kullanım (`process.exit()`).
+- **`--help` her zaman çalışmalı** — argüman yokken veya `-h`/`--help` ile.
+
+### Argüman & Seçenek Yönetimi
+
+```
+Komut yapısı: cli <komut> [argümanlar] [--seçenekler]
+
+Örnekler:
+  cli init
+  cli build src/ --output dist/ --minify
+  cli deploy --env production --force
+```
+
+- Kısa (`-h`) ve uzun (`--help`) formlar destekle.
+- Bilinmeyen seçeneklerde açıklayıcı hata mesajı ver ve `process.exit(2)`.
+
+### Kullanıcı Geri Bildirimi
+
+- Adım adım ilerlemeyi `✓ tamamlandı` / `✗ başarısız` / `ℹ bilgi` formatında bildir.
+- Yıkıcı işlemler öncesinde kullanıcıdan onay al (ya da `--force` ile atla).
+- Hata mesajları eylem odaklı olsun: "X yapılamadı: [sebep]. Çözüm: [öneri]"
+
+### Cross-Platform Uyumluluk
+
+- Dosya yolları için `path.join()` / `path.resolve()` kullan.
+- `os.homedir()` kullan, `process.env.HOME` tek başına güvenilir değil (Windows'ta `USERPROFILE`).
+- Shebang satırı: `#!/usr/bin/env node` (executable dosyalarda zorunlu).
+- `execSync` yerine `spawnSync` karmaşık shell komutları için daha güvenli.
+
+### CLI Bağımlılık Stratejisi
+
+- **Sıfır bağımlılık hedefle** — built-in Node.js modülleri çoğu zaman yeterli.
+- CLI framework gerekiyorsa: `commander` veya `yargs` (ağır framework'lerden kaçın).
+- Renk/stil için: `kleur` veya `picocolors` (daha hafif alternatifler).
+
+---
+
+## 📦 Library & NPM Paket Geliştirme
+
+> **Başkaları tarafından kullanılacak npm paketleri, kütüphaneler ve shared modüllerde geçerlidir.**
+
+### Public API Tasarımı
+
+- **Minimal public surface:** Az ama tutarlı API > çok ama karmaşık API.
+- `index.ts`/`index.js`'de sadece public API'yi export et; internal modülleri gizle.
+- **API'yi kullanım senaryoları üzerinden tasarla** — implementasyon detaylarını değil.
+- Breaking change'i önce `@deprecated` ile işaretle, en az bir MINOR versiyon süre ver, sonra kaldır.
+
+### Paket Bağımlılık Stratejisi
+
+```
+dependencies      → Paketle birlikte gelen, kullanıcıya zorunlu
+devDependencies   → Sadece development/test için
+peerDependencies  → Kullanıcının kurması beklenen (React, Vue gibi büyük runtime'lar)
+```
+
+- **Bağımlılıkları minimal tut.** Her `dependencies` girişi kullanıcının bundle'ına girer.
+- Büyük runtime bağımlılıklarını (React, TypeScript) `peerDependencies` olarak tanımla.
+
+### Build & Dağıtım
+
+- TypeScript ile yazıldıysa: `d.ts` dosyalarını yayınla (tip tanımları zorunlu).
+- Hem ESM hem CJS çıktısı üret (geniş ekosistem uyumu için).
+- `package.json` `files` alanını koru: Sadece gerekli dosyaları (`dist/`) yayınla.
+- `npm pack --dry-run` ile publish öncesinde ne yayınlandığını doğrula.
+
+### Geriye Dönük Uyumluluk
+
+- **Semantic versioning'e sıkı sıkıya uy:** Her breaking change → MAJOR.
+- Changelog tut (`CHANGELOG.md`).
+- Public API değişikliklerini test et; export kontrol için snapshot test kullan.
+
+### Güvenlik (Paket Özgü)
+
+- `npm audit` düzenli çalıştır; CVE'leri takip et.
+- Supply chain saldırılarına karşı lock file (`package-lock.json`/`yarn.lock`) kullan.
+- `.npmignore` veya `package.json#files` ile hassas dosyaların yayınlanmasını önle.
+
+---
+
 ## 🌍 Environment & Deployment Kuralları
 
 ### Environment Variable Yönetimi
@@ -750,7 +1252,9 @@ Kullanıcı büyük bir refactor istediğinde (`/refactor` komutu veya manuel):
 
 ## Performans & Optimizasyon
 
-- Core Web Vitals (LCP, FID/INP, CLS) metriklerini takip et.
+### Frontend & Web Performansı
+
+- Core Web Vitals (LCP, INP, CLS) metriklerini takip et.
 - Görselleri optimize et: WebP/AVIF formatları, lazy loading, responsive images.
 - Font yüklemelerini optimize et: `font-display: swap`, subset kullan.
 - Critical CSS / Above-the-fold optimizasyonu yap.
@@ -758,6 +1262,22 @@ Kullanıcı büyük bir refactor istediğinde (`/refactor` komutu veya manuel):
 - Bundle analyzer ile büyük dependency'leri tespit et ve alternatif ara.
 - Prefetching ve preloading stratejileri uygula.
 
+### Backend & Server Performansı
+
+- **Response time izle:** P50/P95/P99 latency metriklerini takip et; hedef: API < 200ms P95.
+- **N+1 sorgu sorununu önle:** ORM query'lerini incele, `include`/`join` ile eager load kullan.
+- **Bağlantı havuzu (connection pool):** DB bağlantılarını havuzla; her request'te yeni bağlantı açma.
+- **Caching katmanı:** Sık okunan, az değişen veri için Redis veya in-memory cache kullan.
+- **Rate limiting:** Dışa açık endpoint'lerde zorunlu; kötüye kullanımı ve DoS'u engeller.
+- **Profiling:** `clinic.js` veya `--inspect` ile Node.js sürecini profille; darboğazı ölçmeden optimize etme.
+- **Bellek sızıntısı:** Event listener'ları temizle, büyük closure'lardan kaçın.
+
+### CLI & Build Araçları Performansı
+
+- Büyük dosya işlemlerinde `fs.createReadStream()` kullan; tüm içeriği belleğe alma.
+- Paralel işlemler için `Promise.all()` veya `worker_threads` kullan.
+- Startup time'ı minimize et: Lazy `require` ve conditional import kullan.
+
 ---
 
 ## Kod İnceleme (Review) Kriterleri
@@ -772,7 +1292,7 @@ Kod yazarken ve önerirken şu soruları sor:
 6. Performans etkisi nedir?
 7. Güvenlik açığı var mı?
 8. Mevcut pattern'lara uygun mu?
-9. Design system'deki mevcut component kullanılabilir miydi?
+9. Projedeki mevcut utility/component/helper/service kullanılabilir miydi?
 10. i18n kapsamında mı (varsa)?
 
 ---