@hd-agent-kit/cli 1.3.0 → 1.4.0

package/templates/skills/analyze/SKILL.md

@@ -24,6 +24,41 @@ description: Analyze the project structure, tech stack, and conventions to gener
 - İşlem öncesi kontrol sırasında `project-rules.md` bulunamadıysa → Kullanıcıya "Analiz yapayım mı?" sor.
 - **Önemli:** Kullanıcı `/analyze` yazmamışsa ve `project-rules.md` mevcutsa → Bu süreci ATLAMA.
 
+### Sıfırdan Proje Başlatma Modu
+
+Kullanıcı yeni bir proje başlatacağını bildirirse (package.json yok, kaynak kod boş, "sıfırdan X yapmak istiyorum" gibi ifadeler varsa):
+
+**1. Analiz değil, tasarım moduna geç** — Mevcut kod taramak yerine mimari kararları netleştir.
+
+**2. Şu soruları tek mesajda sor:**
+
+```
+Projeyi başlatmadan önce birkaç şeyi netleştirelim:
+
+1. Proje tipi? (Frontend SPA / Fullstack / Standalone API / CLI / Kütüphane)
+2. Framework? (Next.js, Vite+React, Express, Hono, Electron, vs.)
+3. TypeScript kullanılacak mı?
+4. Kimlik doğrulama (auth) gerekiyor mu?
+5. Stil: Tailwind, CSS Modules, styled-components, başka?
+6. UI kit: shadcn/ui, MUI, Radix, özel tasarım sistemi mi?
+7. Test: Vitest, Jest, Playwright, Cypress, yoksa test yok mu?
+8. Monorepo mu, tek repo mu?
+9. Deployment target? (Vercel, Railway, VPS, npm publish)
+```
+
+**3. Cevaplar alındıktan sonra:**
+
+- `project-rules.md` dosyasını **mevcut kodu analiz etmeden, belirlenen stack ile proaktif olarak oluştur**
+- Önerilen proje iskeletini listele: hangi klasörler oluşturulmalı, hangi config dosyaları kurulmalı, hangi paketler kurulmalı
+- Kullanıcı onayladıktan sonra kuruluma başla
+
+**4. İskeleti kurarken mimari prensipleri uygula:**
+
+- Feature-based klasör yapısı öner (type-based değil)
+- Atomic Design hiyerarşisine uygun component klasörleri kur (`components/ui/`, `components/`, `features/`)
+- Smart/Dumb ayrımını gözetecek klasör yapısı oluştur
+- Backend için katmanlı yapı: `routes/` → `controllers/` → `services/`
+
 ---
 
 ## Analiz Adımları
@@ -70,9 +105,26 @@ package.json + config dosyalarından tespit et:
 └── Diğer: Monorepo tooling, deployment config, analytics
 ```
 
-### Adım 3: Kod Stili & Pattern Analizi
+### Adım 3: Proje Tipi Tespiti & Kod Stili Analizi
+
+Mevcut kaynak kodunu **en az 10-15 dosya** üzerinden örnekleyerek analiz et.
+
+**Önce Proje Tipini Tespit Et:**
 
-Mevcut kaynak kodunu **en az 10-15 dosya** üzerinden örnekleyerek analiz et:
+```
+Proje tipleri ve tespiti:
+├── Frontend SPA     → React/Vue/Svelte, src/components, src/pages, no server
+├── Fullstack        → Next.js/Remix/Nuxt, hem UI hem API/server katmanı
+├── Standalone API   → Express/Fastify/Hono, routes/, controllers/, no UI
+├── CLI Araç         → bin/ klasörü veya package.json#bin, terminal çıktısı
+└── NPM Kütüphanesi  → package.json#main|module|exports, src/, dist/, no bin
+```
+
+**Tespit edilen proje tipine göre aşağıdaki uygun alt bölümleri uygula:**
+
+---
+
+#### Frontend / Fullstack UI Analizi *(SPA, Next.js, Remix vs. için)*
 
 **Component Yapısı:**
 - Arrow function mı, function declaration mı?
@@ -91,26 +143,68 @@ Mevcut kaynak kodunu **en az 10-15 dosya** üzerinden örnekleyerek analiz et:
 - CSS Modules ise: Adlandırma convention'ı ne?
 - Theme/token sistemi var mı?
 
+**Hata Yönetimi (UI):**
+- Error boundary kullanılıyor mu?
+- API hataları nasıl handle ediliyor?
+- Toast/notification sistemi var mı?
+
+---
+
+#### Backend / API Analizi *(Standalone API, Next.js API Routes, fullstack backend için)*
+
+**Route & Controller Yapısı:**
+- Route yapısı nasıl? (Express Router, Next.js App Router, Fastify plugin vs.)
+- Controller ve service ayrımı var mı?
+- Middleware zinciri nasıl kurulmuş? (auth, validation, logging sırası)
+
+**Validation & Error Handling:**
+- Validation nerede yapılıyor? (middleware, handler içinde, Zod schema)
+- Hata response formatı tutarlı mı? (`code`, `message`, `details` yapısı)
+- Global hata middleware'i var mı?
+
+**Auth & Güvenlik:**
+- Auth middleware var mı? Nasıl uygulanıyor? (JWT, session, API key)
+- Rate limiting uygulanmış mı?
+- Input sanitization yapılıyor mu?
+
+**Veri Erişimi:**
+- DB query'leri nerede yazılıyor? (service layer, doğrudan handler'da, repository pattern)
+- ORM/query builder nasıl kullanılıyor? (Prisma, Drizzle, Knex)
+- Transaction kullanım pattern'ı nasıl?
+
+---
+
+#### CLI Araç Analizi *(bin/ olan projeler için)*
+
+- Argüman ayrıştırma nasıl yapılıyor? (manuel `process.argv`, commander, yargs)
+- Komut/sub-komut yapısı nasıl?
+- Kullanıcı geri bildirim formatı nasıl? (log prefix'leri, renkler, emoji'ler)
+- `--force` / `--dry-run` / `--verbose` gibi ortak flag'ler var mı?
+- Cross-platform uyum nasıl sağlanmış?
+
+---
+
+#### Library / NPM Paket Analizi *(package.json#exports olan projeler için)*
+
+- Public API nerede tanımlı? (`index.ts`, `src/index.ts`)
+- Internal vs. public export ayrımı var mı?
+- CJS ve ESM dual çıktı üretiliyor mu?
+- `d.ts` tip tanımları üretiliyor mu?
+- Semver politikası ve changelog tutma convention'ı nasıl?
+
+---
+
+**Tüm Proje Tipleri için Ortak Analiz:**
+
 **Import Sıralaması:**
-- Mevcut koddaki import sıralamasını tespit et (React, 3rd party, internal, styles, types vs.)
-- Absolute import path alias var mı? (`@/`, `~/`, `#/`)
+- Mevcut koddaki import sıralamasını tespit et (stdlib, 3rd party, internal, types vs.)
+- Absolute import path alias var mı? (`@/`, `~/`, `#/`, `src/`)
 
 **Tip Tanımları:**
-- Type'lar nerede tanımlanıyor? (Component yanında, ayrı `types/` klasöründe, global `types.d.ts`?)
+- Type'lar nerede tanımlanıyor? (kaynak dosyanın yanında, ayrı `types/` klasörü, global `types.d.ts`?)
 - `interface` mi `type` mı daha yaygın?
 - Zod/Valibot schema'dan tip türetme var mı?
 
-**Hata Yönetimi:**
-- Error boundary kullanılıyor mu?
-- API hataları nasıl handle ediliyor?
-- Toast/notification sistemi var mı?
-
-**Backend/API Katmanı (varsa):**
-- API route yapısı nasıl? (Next.js App Router, Pages Router, Express router vs.)
-- Validation nerede yapılıyor? (Middleware, handler içinde, Zod schema)
-- Auth middleware var mı? Nasıl uygulanıyor?
-- DB query'leri nerede yazılıyor? (Service layer, doğrudan handler'da)
-
 ### Adım 4: Konfigürasyon Analizi
 
 ```
@@ -206,15 +300,16 @@ Analiz tamamlandıktan sonra aşağıdaki formatta `project-rules.md` oluştur:
 
 ```markdown
 # [Proje Adı] — Proje Kuralları
-# Bu dosya otomatik analiz ile oluşturulmuştur.
-# Son analiz tarihi: [TARİH]
-# Analiz tetikleyicisi: [/analyze komutu / Otomatik tespit]
+<!-- Bu dosya otomatik analiz ile oluşturulmuştur. -->
+<!-- Son analiz tarihi: [TARİH] -->
+<!-- Analiz tetikleyicisi: [/analyze komutu / Otomatik tespit] -->
 
 ## Proje Özeti
+- **Tür:** [Frontend SPA / Fullstack / Standalone API / CLI Araç / NPM Kütüphanesi]
 - **Framework:** [tespit edilen]
 - **Dil:** [TypeScript/JavaScript] | Strict: [Evet/Hayır]
-- **Styling:** [tespit edilen]
-- **State Yönetimi:** [tespit edilen]
+- **Styling:** [tespit edilen veya "Yok"]
+- **State Yönetimi:** [tespit edilen veya "Yok"]
 - **Test:** [tespit edilen]
 - **Build Tool:** [tespit edilen]
 - **Monorepo:** [Evet/Hayır]
@@ -267,6 +362,65 @@ Analiz tamamlandıktan sonra aşağıdaki formatta `project-rules.md` oluştur:
 ## Git Kuralları
 [Commit format, branch naming — projeden tespit edilen]
 
+## Temel Dosya Haritası
+
+> AI asistanın yeni kod yazarken direkt başvuracağı dosya konumları.
+> Analiz sırasında tespit edilen kritik dosyaları domain'e göre listele.
+
+```
+[domain]      : [dosya yolu]
+HTTP Client   : src/lib/api.ts
+Auth Service  : src/services/auth.ts
+Tipler        : src/types/index.ts
+Env Config    : src/config/env.ts
+Router        : src/router/index.ts
+Store/State   : src/store/index.ts
+Theme/Tokens  : tailwind.config.ts / src/styles/tokens.ts
+Test Utility  : src/test/utils.tsx
+```
+
+*Yalnızca projede gerçekten var olan dosyaları ekle. Olmayan alan için satırı dahil etme.*
+
+## Kod Örüntü Örnekleri
+
+> Bu projedeki gerçek kod pattern'larından alınan 3-5 kısa snippet.
+> AI asistanın yeni kod yazarken birebir taklit edeceği referans örnekler.
+
+### [Örnek: Component]
+```typescript
+// Buraya projeden alınmış gerçek bir component örneği
+```
+
+### [Örnek: API İsteği / Data Fetching]
+```typescript
+// Buraya projeden alınmış gerçek bir data fetching örneği
+```
+
+### [Örnek: Tip Tanımı]
+```typescript
+// Buraya projeden alınmış gerçek bir type/interface örneği
+```
+
+*Her snippet ~10-20 satır olmalı — pattern'ı gösterecek kadar, fazla değil.*
+
+## Varsayılan Tercihler
+
+> AI asistanın her prompt için otomatik başvuracağı hızlı referans tablosu.
+> Projede aktif kullanılan tercihler yazılır; kullanılmayan alan için "Yok" yaz.
+
+| Alan | Bu Projede Kullanılan |
+| --- | --- |
+| Form | [React Hook Form + Zod / Formik / Yup / Yok] |
+| HTTP İstek | [TanStack Query / SWR / axios / fetch / Yok] |
+| Bildirim/Toast | [sonner / react-hot-toast / shadcn/Toaster / Yok] |
+| Modal/Dialog | [shadcn/Dialog / Radix / Headless UI / Yok] |
+| Tablo/Liste | [TanStack Table / shadcn/Table / Yok] |
+| İkon Seti | [lucide-react / heroicons / react-icons / Yok] |
+| Tarih Formatlama | [date-fns / dayjs / Intl API / Yok] |
+| Validation Şeması | [Zod / Yup / Valibot / Yok] |
+| Ortam Değişkeni | [NEXT_PUBLIC_ / VITE_ / process.env / Yok] |
+| Test Utility | [Testing Library / supertest / Yok] |
+
 ## Proje-Spesifik Notlar
 [Projeye özel convention'lar, dikkat edilmesi gereken noktalar, bilinen teknik borçlar]
 ```
@@ -278,6 +432,8 @@ Yukarıdaki bölümlerin hepsi her projede geçerli olmayabilir. Analiz sonucund
 - Sadece frontend → "Backend/Server Kuralları" eklenmez.
 - i18n yoksa → "i18n Kuralları" eklenmez.
 
+**"Varsayılan Tercihler" tablosu her projede zorunludur** — frontend ya da backend, her tür proje için ilgili satırlar doldurulur. Kullanılmayan alanlar için "Yok" değerini yaz.
+
 Sadece projede aktif olarak kullanılan teknolojilere ve pattern'lara dair bölümleri yaz.
 
 ---

package/templates/skills/api-design/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: api-design
+description: Design REST/GraphQL API endpoints, define request/response schemas, and generate OpenAPI documentation
+---
+
+# /api-design — API Tasarım Skill'i
+
+> **Tetikleyici:** `/api-design [kaynak/modül]`
+> **Amaç:** REST veya GraphQL API endpoint'lerini tasarlamak, request/response şemalarını tanımlamak ve OpenAPI/Swagger belgesi oluşturmak.
+> **Çıktı:** Endpoint tasarımı + Zod/TypeScript şemaları + OpenAPI YAML/JSON taslağı
+
+---
+
+## Kullanım Formatları
+
+```
+/api-design users                    ← users kaynağı için tam CRUD API tasarımı
+/api-design orders checkout          ← checkout akışı endpoint tasarımı
+/api-design --graphql products       ← GraphQL schema tasarımı
+/api-design --openapi                ← Mevcut route'lardan OpenAPI belgesi oluştur
+/api-design auth                     ← Auth endpoint'leri (login, logout, refresh)
+```
+
+---
+
+## Uygulama Adımları
+
+### Adım 1: Bağlam Analizi
+
+Mevcut projeyi incele ve şunları tespit et:
+
+```
+📋 Proje Bağlamı:
+├── API tipi: [REST / GraphQL / tRPC / mixed]
+├── Framework: [Express, Fastify, Hono, Next.js, Nest.js]
+├── Auth yöntemi: [JWT, session, API key, OAuth2]
+├── Validation: [Zod, Yup, Joi, class-validator]
+├── DB/ORM: [Prisma, Drizzle, Mongoose, TypeORM]
+├── Mevcut API convention'ı: [versiyonlama, prefix, naming]
+└── Mevcut endpoint örnekleri: [varsa örnek route'lar]
+```
+
+### Adım 2: Kaynak & Endpoint Tasarımı
+
+Belirtilen kaynak için RESTful endpoint seti tasarla:
+
+---
+
+## REST API Tasarım Kuralları
+
+### URL Yapısı
+
+```
+Kaynak adları: çoğul isim, kebab-case
+  ✅ /api/users
+  ✅ /api/blog-posts
+  ❌ /api/getUser
+  ❌ /api/user_list
+
+Hiyerarşik ilişkiler: iç içe kaynak
+  /api/users/:userId/orders          ← Kullanıcının siparişleri
+  /api/orders/:orderId/items         ← Sipariş kalemleri
+
+Versiyon prefix'i (gerekirse):
+  /api/v1/users
+  /api/v2/users
+
+Filtre/sayfalama: query parameter
+  /api/users?page=2&limit=20&sort=createdAt:desc&status=active
+```
+
+### HTTP Method Eşleşmesi
+
+```
+GET    /api/resources          → Liste (sayfalı)
+GET    /api/resources/:id      → Tekil kaynak
+POST   /api/resources          → Yeni oluştur
+PUT    /api/resources/:id      → Tamamını güncelle (tüm alanlar)
+PATCH  /api/resources/:id      → Kısmen güncelle (değişen alanlar)
+DELETE /api/resources/:id      → Sil
+
+Özel aksiyonlar (action endpoint):
+POST   /api/orders/:id/cancel  → İptal et (fiil + kaynak kombinasyonu)
+POST   /api/users/:id/verify   → Doğrula
+POST   /api/auth/refresh       → Token yenile
+```
+
+### Standart CRUD Tasarım Şablonu
+
+```
+📋 [Kaynak] API Endpoint'leri:
+
+┌─────────────────────────────────┬────────┬──────────────────────────────────┐
+│ Endpoint                        │ Method │ Açıklama                         │
+├─────────────────────────────────┼────────┼──────────────────────────────────┤
+│ /api/[resources]                │ GET    │ Liste (filtreleme + sayfalama)    │
+│ /api/[resources]/:id            │ GET    │ Tekil kaynak                     │
+│ /api/[resources]                │ POST   │ Yeni oluştur                     │
+│ /api/[resources]/:id            │ PATCH  │ Kısmi güncelleme                 │
+│ /api/[resources]/:id            │ DELETE │ Sil (soft veya hard)             │
+└─────────────────────────────────┴────────┴──────────────────────────────────┘
+```
+
+---
+
+## Request/Response Şema Tasarımı
+
+### Zod Şema Örüntüsü
+
+```typescript
+import { z } from 'zod';
+
+// ── Base schema (DB'den dönen tam nesne) ──────────────────
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user', 'guest']),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+// ── Create request (id ve timestamp'ler yok) ─────────────
+export const CreateUserSchema = UserSchema.omit({
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+});
+
+// ── Update request (tüm alanlar opsiyonel) ────────────────
+export const UpdateUserSchema = CreateUserSchema.partial();
+
+// ── List query parameters ─────────────────────────────────
+export const UserListQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  sort: z.enum(['createdAt', 'name', 'email']).default('createdAt'),
+  order: z.enum(['asc', 'desc']).default('desc'),
+  search: z.string().optional(),
+  role: z.enum(['admin', 'user', 'guest']).optional(),
+});
+
+// ── TypeScript tipleri (şemadan türetme) ──────────────────
+export type User = z.infer<typeof UserSchema>;
+export type CreateUserDto = z.infer<typeof CreateUserSchema>;
+export type UpdateUserDto = z.infer<typeof UpdateUserSchema>;
+export type UserListQuery = z.infer<typeof UserListQuerySchema>;
+```
+
+### Tutarlı Response Formatı
+
+```typescript
+// ✅ Tekil kaynak response
+type SingleResponse<T> = {
+  data: T;
+};
+
+// ✅ Liste response (sayfalama meta verisi ile)
+type ListResponse<T> = {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  };
+};
+
+// ✅ Hata response
+type ErrorResponse = {
+  code: string;          // "VALIDATION_ERROR", "NOT_FOUND", "UNAUTHORIZED"
+  message: string;       // Kullanıcıya gösterilebilir mesaj
+  details?: unknown;     // Validation hataları (sadece dev/staging)
+  requestId?: string;    // Correlation ID (production'da önemli)
+};
+```
+
+### HTTP Status Code Kılavuzu
+
+```
+200 OK              → Başarılı GET, PATCH, PUT
+201 Created         → Başarılı POST (Location header ekle)
+204 No Content      → Başarılı DELETE (body yok)
+400 Bad Request     → Validation hatası
+401 Unauthorized    → Token yok veya geçersiz
+403 Forbidden       → Token geçerli ama yetki yetersiz
+404 Not Found       → Kaynak bulunamadı
+409 Conflict        → Duplicate kayıt, eşzamanlılık çakışması
+422 Unprocessable   → Semantik validasyon hatası (formatı doğru ama mantıksal hata)
+429 Too Many Req.   → Rate limit aşıldı (Retry-After header ekle)
+500 Internal Error  → Beklenmeyen sunucu hatası (detayı logla, kullanıcıya gösterme)
+503 Unavailable     → Servis geçici olarak kullanılamıyor
+```
+
+---
+
+## Sayfalama & Filtreleme Tasarımı
+
+### Sayfalama Stratejileri
+
+```typescript
+// ── Offset tabanlı (basit, küçük-orta veri setleri) ───────
+GET /api/users?page=2&limit=20
+// → { data: [...], meta: { total: 150, page: 2, limit: 20, totalPages: 8 } }
+
+// ── Cursor tabanlı (büyük veri setleri, real-time feed) ───
+GET /api/posts?cursor=eyJpZCI6IjEyMyJ9&limit=20
+// → { data: [...], nextCursor: "eyJpZCI6IjE0MyJ9" | null }
+
+// Tercih kuralı:
+// Küçük-orta, sıralı liste → offset
+// Büyük veri, sosyal feed, real-time → cursor
+```
+
+### Filtreleme & Sıralama Convention'ı
+
+```
+Filtreleme: query param = alan adı
+  /api/users?status=active&role=admin
+
+Çoklu değer: virgülle ayrılmış
+  /api/users?role=admin,moderator
+
+Aralık filtreleri: _gte / _lte suffix
+  /api/orders?createdAt_gte=2024-01-01&createdAt_lte=2024-12-31
+  /api/products?price_gte=100&price_lte=500
+
+Arama: q veya search parametresi
+  /api/products?q=laptop
+
+Sıralama: sort=alan:yön
+  /api/users?sort=createdAt:desc,name:asc
+```
+
+---
+
+## Auth Endpoint Tasarımı
+
+### Standart Auth Akışı
+
+```
+POST /api/auth/register       → Kayıt ol
+  body: { name, email, password }
+  response 201: { user: {...}, accessToken, refreshToken }
+
+POST /api/auth/login          → Giriş yap
+  body: { email, password }
+  response 200: { user: {...}, accessToken, refreshToken }
+
+POST /api/auth/refresh        → Access token yenile
+  body: { refreshToken }
+  response 200: { accessToken, refreshToken }
+
+POST /api/auth/logout         → Çıkış yap (token iptal)
+  headers: Authorization: Bearer <token>
+  response 204
+
+GET  /api/auth/me             → Mevcut kullanıcı bilgisi
+  headers: Authorization: Bearer <token>
+  response 200: { user: {...} }
+```
+
+### Token Güvenlik Kuralları
+
+```
+Access token:  kısa ömürlü (15dk - 1sa), stateless JWT
+Refresh token: uzun ömürlü (7-30gün), DB'de sakla (iptal için)
+Storage:       httpOnly cookie (XSS koruması) veya memory (localStorage değil)
+Rotation:      Refresh token her kullanımda yenile
+```
+
+---
+
+## GraphQL Şema Tasarımı *(GraphQL projeler için)*
+
+```graphql
+# Tip tanımları
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  role: UserRole!
+  createdAt: DateTime!
+  orders: [Order!]!         # İlişki — lazy load
+}
+
+enum UserRole {
+  ADMIN
+  USER
+  GUEST
+}
+
+# Query'ler
+type Query {
+  user(id: ID!): User
+  users(
+    page: Int = 1
+    limit: Int = 20
+    filter: UserFilter
+  ): UserConnection!
+  me: User                  # Auth gerektiren
+}
+
+# Mutation'lar
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+# Input tipleri
+input CreateUserInput {
+  name: String!
+  email: String!
+  password: String!
+}
+
+# Cursor-based pagination
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+```
+
+---
+
+## OpenAPI / Swagger Dokümantasyonu
+
+### Temel Yapı (YAML)
+
+```yaml
+openapi: 3.1.0
+info:
+  title: [Proje Adı] API
+  version: 1.0.0
+  description: |
+    [API açıklaması]
+
+servers:
+  - url: http://localhost:3000/api
+    description: Development
+  - url: https://api.example.com
+    description: Production
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  schemas:
+    User:
+      type: object
+      required: [id, name, email, role]
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        email:
+          type: string
+          format: email
+        role:
+          type: string
+          enum: [admin, user, guest]
+
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: object
+
+paths:
+  /users:
+    get:
+      summary: Kullanıcı listesi
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: page
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Başarılı
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  meta:
+                    $ref: '#/components/schemas/PaginationMeta'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+```
+
+---
+
+## API Versiyonlama Stratejisi
+
+```
+Versiyonlama yöntemleri:
+
+1. URL prefix (önerilen — en açık)
+   /api/v1/users
+   /api/v2/users
+
+2. Header (temiz URL, karmaşık routing)
+   Accept: application/vnd.api+json;version=2
+
+3. Query parameter (öneri değil — cache sorunları)
+   /api/users?version=2
+
+Kural:
+- Breaking change → yeni major versiyon (v2)
+- Geri uyumlu ekleme → aynı versiyonda
+- Eski versiyon → deprecation uyarısı + sunset tarihi
+- En az iki major versiyon paralel desteklenmeli
+```
+
+---
+
+## Çıktı Formatı
+
+1. **Endpoint tablosu** — Method, path, açıklama, auth gereksinimleri
+2. **Request/Response şemaları** — Zod veya TypeScript tiplemesiyle
+3. **HTTP status code haritası** — Her endpoint için beklenen response'lar
+4. **OpenAPI taslağı** — YAML formatında (isteğe bağlı)
+5. **Örnek istekler** — curl veya fetch ile test edilebilir örnekler
+6. **Tasarım kararları** — Neden bu yapı seçildi, alternatifleri neydi