Generowanie dokumentacji

Dokumentacja to most między genialnym kodem a deweloperami, którzy muszą go zrozumieć, utrzymywać i rozszerzać. Claude Code przekształca dokumentację z przerażającego obowiązku w zautomatyzowany proces, który nadąża za szybko ewoluującą bazą kodu. Ta lekcja eksploruje jak generować wszystko od referencji API po diagramy architektoniczne.

Rewolucja dokumentacji

Scenariusz: Twój startup właśnie osiągnął product-market fit. Baza kodu urosła 10x w sześć miesięcy. Nowi deweloperzy dołączają co tydzień. Wiki jest trzy sprinty za rzeczywistością. Customer support nie może wyjaśnić nowych funkcji bo dokumentacja nie istnieje. Brzmi znajomo? Oto jak Claude Code to rozwiązuje.

Tradycyjne vs wspomagane AI podejście do dokumentacji

Tradycyjne podejście
Podejście Claude Code

Tydzień 1: Plan sprintu dokumentacji
- Przydziel pisarzy do każdego modułu
- Przejrzyj istniejące (przestarzałe) dokumenty
- Przeprowadź wywiady z deweloperami o kontekst

Tydzień 2-3: Pisanie dokumentacji
- Ręczna inspekcja kodu
- Tworzenie diagramów ręcznie
- Pisanie przykładów API
- Liczenie że nic się nie zmieni

Tydzień 4: Przeglądy i aktualizacje
- Przegląd techniczny przez deweloperów
- Napraw niedokładności
- Zaktualizuj o ostatnie zmiany
- Opublikuj na wiki

Rezultat: Przestarzałe zanim zostanie opublikowane

Dzień 1: Automatyczne generowanie
> Wygeneruj kompletną dokumentację API dla naszej usługi
> Uwzględnij przykłady, typy i odpowiedzi błędów

> Stwórz dokumentację architektury z diagramami
> Skup się na przepływie danych i interakcjach usług

> Napisz przewodniki użytkownika dla każdej funkcji
> Kieruj zarówno do deweloperów jak i końcowych użytkowników

Dzień 2: Przegląd i polerowanie
- Szkice wygenerowane przez AI gotowe
- Deweloperzy sprawdzają dokładność
- Ciągłe aktualizacje z kodem

Rezultat: Zawsze aktualne, kompleksowe dokumenty

Konfiguracja infrastruktury dokumentacji

Tworzenie komend dokumentacji

Skonfiguruj szablony dokumentacji Stwórz .claude/commands/generate-docs.md:

Wygeneruj dokumentację dla: $ARGUMENTS

1. Przeanalizuj strukturę kodu i wzorce
2. Wygeneruj odpowiednią dokumentację:
   - Dokumenty API dla endpointów
   - JSDoc/TSDoc dla funkcji
   - Przegląd architektury dla systemów
   - Przewodniki użytkownika dla funkcji
3. Uwzględnij przykłady kodu
4. Dodaj diagramy gdzie pomocne
5. Przestrzegaj naszego przewodnika stylu

Skonfiguruj preferencje dokumentacji W .claude/settings.json:

{
  "documentation": {
    "apiFormat": "openapi",
    "diagramTool": "mermaid",
    "codeExamples": true,
    "versionTracking": true,
    "languages": ["en", "es", "zh"]
  }
}

Stwórz przewodnik stylu

> Stwórz przewodnik stylu dokumentacji który obejmuje:
> - Ton i styl (profesjonalny ale przystępny)
> - Standardy formatowania
> - Szablony przykładów
> - Słownik terminologii

Skonfiguruj hooki auto-generowania

> Stwórz hooka git który przypomina o aktualizacji dokumentów:
> - Przy merge feature branch
> - Gdy endpointy API się zmieniają
> - Po większym refactoringu

Generowanie dokumentacji API

Dokumentacja RESTful API

> Wygeneruj kompleksową dokumentację API dla naszych endpointów REST.
> Uwzględnij:
> - URL endpointów i metody
> - Schematy request/response
> - Wymagania uwierzytelniania
> - Szczegóły limitów częstotliwości
> - Przykładowe requesty i responses
> - Kody błędów i ich znaczenia

Claude generuje strukturalną dokumentację:

Przegląd endpointów

# User API

## Uwierzytelnianie
Wszystkie endpointy wymagają uwierzytelniania Bearer token:

Authorization: Bearer <token>

## Limity częstotliwości
- 1000 requestów na godzinę na użytkownika
- Status 429 gdy przekroczony
- Header X-RateLimit-Remaining

## URL bazowy
Produkcja: https://api.example.com/v2
Staging: https://staging-api.example.com/v2

Szczegóły endpointu

## GET /users/{id}

Pobierz pojedynczego użytkownika po ID.

### Parametry
| Nazwa | Typ | W | Opis |
|------|------|-----|-------------|
| id | string | path | UUID użytkownika |
| include | string | query | Dane powiązane oddzielone przecinkami |

### Response 200
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "name": "Jan Kowalski",
  "created_at": "2024-01-15T09:30:00Z",
  "profile": {
    "avatar_url": "https://...",
    "bio": "Deweloper oprogramowania"
  }
}

Response 404

{
  "error": "USER_NOT_FOUND",
  "message": "Użytkownik o podanym ID nie został znaleziony"
}

</Card>
<Card title="Przykłady kodu">
```javascript
const response = await fetch('https://api.example.com/v2/users/123', {
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});
const user = await response.json();

// Python
import requests

response = requests.get(
  'https://api.example.com/v2/users/123',
  headers={'Authorization': 'Bearer your-token-here'}
)
user = response.json()

// cURL
curl -X GET https://api.example.com/v2/users/123 \
  -H "Authorization: Bearer your-token-here"

Specyfikacja OpenAPI

openapi: 3.0.0
info:
  title: User API
  version: 2.0.0
paths:
  /users/{id}:
    get:
      summary: Pobierz użytkownika po ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Użytkownik znaleziony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Dokumentacja GraphQL

> Wygeneruj dokumentację schematu GraphQL z:
> - Definicjami typów
> - Przykładami query i mutacji
> - Wzorcami subskrypji
> - Obsługą błędów
> - Uwagami o wydajności

Rezultat:

"""
Typ User reprezentujący uwierzytelnionego użytkownika w systemie
"""
type User {
  """Unikalny identyfikator"""
  id: ID!

  """Adres email użytkownika"""
  email: String!

  """Nazwa wyświetlana"""
  name: String!

  """Posty użytkownika z paginacją"""
  posts(
    """Liczba postów do zwrócenia"""
    first: Int = 10

    """Kursor do paginacji"""
    after: String
  ): PostConnection!

  """Data utworzenia konta użytkownika"""
  createdAt: DateTime!
}

"""
Główny typ query
"""
type Query {
  """Pobierz aktualnie uwierzytelnionego użytkownika"""
  me: User

  """Znajdź użytkownika po ID"""
  user(id: ID!): User

  """Szukaj użytkowników po nazwie lub emailu"""
  searchUsers(query: String!): [User!]!
}

Dokumentacja techniczna

Dokumentacja architektury

> Przeanalizuj naszą bazę kodu i stwórz kompleksową dokumentację architektury:
> - Przegląd systemu i komponenty
> - Diagramy przepływu danych
> - Interakcje usług
> - Szczegóły stacku technologicznego
> - Architektura wdrożenia

Claude generuje:

# Architektura systemu

## Przegląd
Nasza platforma następuje architekturę mikroserwisów z tymi głównymi komponentami:

### Frontend
- **Technologia**: Next.js 14 z TypeScript
- **Hosting**: Vercel
- **Zarządzanie stanem**: Zustand + React Query
- **Framework UI**: Tailwind CSS + Radix UI

### Usługi backendowe
1. **API Gateway** (Node.js/Express)
   - Routing requestów
   - Uwierzytelnianie
   - Limity częstotliwości

2. **User Service** (Node.js)
   - Zarządzanie użytkownikami
   - Uwierzytelnianie/autoryzacja
   - Zarządzanie profilami

3. **Product Service** (Python/FastAPI)
   - Katalog produktów
   - Zarządzanie zapasami
   - Funkcjonalność wyszukiwania

4. **Order Service** (Go)
   - Przetwarzanie zamówień
   - Integracja płatności
   - Śledzenie zamówień

### Warstwa danych
- **Główna baza danych**: PostgreSQL 15
- **Cache**: Redis 7
- **Wyszukiwanie**: Elasticsearch 8
- **Kolejka wiadomości**: RabbitMQ

# Architektura wdrożenia Kubernetes

## Klaster produkcyjny (AWS EKS)
- Region: us-east-1 (główny), us-west-2 (failover)
- Grupy węzłów:
  - Ogólne: t3.large (3-10 węzłów)
  - Obliczeniowe: c5.xlarge (2-5 węzłów)
  - Pamięć: r5.large (2-4 węzły)

## Wdrożenia usług
- API Gateway: 3 repliki, HPA (CPU 70%)
- User Service: 2 repliki, HPA (CPU 60%)
- Product Service: 3 repliki, HPA (Memory 70%)
- Order Service: 2 repliki, HPA (CPU 50%)

## Infrastruktura
- Load Balancer: AWS ALB z WAF
- CDN: CloudFront
- Storage: S3 dla assetów
- Baza danych: RDS Multi-AZ PostgreSQL
- Cache: Klaster ElastiCache Redis

Dokumentacja modułów

> Udokumentuj moduł uwierzytelniania:
> - Cel i odpowiedzialności
> - Publiczne API
> - Architektura wewnętrzna
> - Uwagi bezpieczeństwa
> - Przykłady użycia

Wygenerowana dokumentacja:

# Moduł uwierzytelniania

## Przegląd
Moduł uwierzytelniania zapewnia bezpieczne uwierzytelnianie i autoryzację użytkowników dla całej aplikacji. Implementuje uwierzytelnianie oparte na JWT z tokenami odświeżania i obsługuje wielu dostawców uwierzytelniania.

## Funkcje
- Generowanie i walidacja tokenów JWT
- Rotacja tokenów odświeżania
- Integracja OAuth2 (Google, GitHub, Microsoft)
- Kontrola dostępu oparta na rolach (RBAC)
- Zarządzanie sesjami
- Uwierzytelnianie wieloczynnikowe (MFA)

## Architektura

### Komponenty

#### AuthService
Główna klasa serwisu obsługująca logikę uwierzytelniania.

```typescript
class AuthService {
  /**
   * Uwierzytelnij użytkownika emailem i hasłem
   * @returns JWT access token i refresh token
   */
  async login(email: string, password: string): Promise<AuthTokens>

  /**
   * Waliduj i odśwież access token
   */
  async refreshToken(refreshToken: string): Promise<AuthTokens>

  /**
   * Odwołaj wszystkie sesje użytkownika
   */
  async logout(userId: string): Promise<void>
}

TokenManager

Obsługuje operacje tokenów JWT.

PasswordService

Bezpieczne hashowanie i walidacja haseł.

OAuthProvider

Klasa abstrakcyjna dla integracji OAuth.

Uwagi bezpieczeństwa

Przechowywanie haseł: Bcrypt z czynnikiem kosztu 12
Bezpieczeństwo tokenów:
- Access tokeny: 15 minut TTL
- Refresh tokeny: 7 dni TTL, jednorazowe użycie
- Tokeny podpisane RS256
Limity częstotliwości: 5 prób logowania na 15 minut
Bezpieczeństwo sesji: Bezpieczne, httpOnly, sameSite cookies

## Dokumentacja kodu

### Generowanie dokumentacji inline

Dodaj kompleksowe komentarze JSDoc do naszych funkcji narzędziowych:

Opisz cel

Udokumentuj parametry i zwracane wartości

Uwzględnij przykłady użycia

Zanotuj efekty uboczne

Przed:
```javascript
function calculateDiscount(price, discountPercent, maxDiscount) {
  const discount = price * (discountPercent / 100);
  return Math.min(discount, maxDiscount || Infinity);
}

Po:

/**
 * Oblicza kwotę rabatu dla danej ceny i procentu rabatu
 *
 * @param {number} price - Cena oryginalna w groszach
 * @param {number} discountPercent - Procent rabatu (0-100)
 * @param {number} [maxDiscount] - Opcjonalna maksymalna kwota rabatu w groszach
 * @returns {number} Obliczona kwota rabatu w groszach, ograniczona do maxDiscount jeśli podano
 *
 * @example
 * // 20% rabat na 100 zł
 * calculateDiscount(10000, 20) // zwraca 2000
 *
 * @example
 * // 50% rabat na 100 zł, ograniczony do 30 zł
 * calculateDiscount(10000, 50, 3000) // zwraca 3000
 */
function calculateDiscount(price, discountPercent, maxDiscount) {
  const discount = price * (discountPercent / 100);
  return Math.min(discount, maxDiscount || Infinity);
}

Dokumentacja typów

> Wygeneruj dokumentację typów TypeScript dla naszych modeli danych

/**
 * Reprezentuje użytkownika w systemie
 * @interface User
 */
export interface User {
  /** Unikalny identyfikator użytkownika */
  id: string;

  /** Adres email użytkownika - musi być unikalny */
  email: string;

  /** Nazwa wyświetlana użytkownika */
  name: string;

  /** Rola użytkownika określająca uprawnienia dostępu */
  role: 'admin' | 'user' | 'guest';

  /** Znacznik czasu utworzenia konta */
  createdAt: Date;

  /** Znacznik czasu ostatniej aktualizacji */
  updatedAt: Date;

  /** Opcjonalne informacje profilu użytkownika */
  profile?: UserProfile;
}

/**
 * Rozszerzone informacje profilu użytkownika
 * @interface UserProfile
 */
export interface UserProfile {
  /** URL do awatara użytkownika */
  avatarUrl?: string;

  /** Biografia lub opis użytkownika */
  bio?: string;

  /** Lokalizacja użytkownika */
  location?: string;

  /** Linki do mediów społecznościowych */
  socialLinks?: {
    twitter?: string;
    github?: string;
    linkedin?: string;
  };
}

Diagramy i wizualizacje

Diagramy sekwencji

> Stwórz diagram sekwencji dla naszego przepływu przetwarzania zamówień

sequenceDiagram participant U as Użytkownik participant F as Frontend participant G as API Gateway participant O as Order Service participant P as Payment Service participant I as Inventory Service participant N as Notification Service U->>F: Złóż zamówienie F->>G: POST /orders G->>G: Waliduj token auth G->>O: Stwórz zamówienie O->>I: Sprawdź zapasy I-->>O: Zapasy dostępne O->>P: Przetwórz płatność P-->>O: Płatność udana O->>I: Zarezerwuj zapasy O->>N: Wyślij potwierdzenie O-->>G: Zamówienie utworzone G-->>F: Odpowiedź zamówienia F-->>U: Pokaż potwierdzenie Note over N,U: Async email wysłany N-->>U: Email potwierdzenie

Diagramy relacji encji

> Wygeneruj diagram ER dla naszych tabel użytkowników i zamówień

erDiagram USER ||--o{ ORDER : places USER ||--o{ ADDRESS : has ORDER ||--|{ ORDER_ITEM : contains PRODUCT ||--o{ ORDER_ITEM : "ordered in" USER { uuid id PK string email UK string name string password_hash timestamp created_at } ADDRESS { uuid id PK uuid user_id FK string street string city string country string postal_code } ORDER { uuid id PK uuid user_id FK string status decimal total timestamp created_at } ORDER_ITEM { uuid id PK uuid order_id FK uuid product_id FK integer quantity decimal price } PRODUCT { uuid id PK string name string sku UK decimal price integer stock }

Dokumentacja użytkownika

Przewodniki funkcji

> Stwórz dokumentację użytkownika dla naszej funkcji koszyka:
> - Pierwsze kroki
> - Instrukcje krok po kroku
> - Symbole zastępcze dla zrzutów ekranu
> - Rozwiązywanie problemów
> - FAQ

Wygenerowany przewodnik:

# Przewodnik koszyka

## Pierwsze kroki

Koszyk pozwala zbierać przedmioty przed zakupem, zapisywać je na później i zarządzać ilościami.

### Dodawanie przedmiotów do koszyka

1. **Ze strony produktu**
   - Kliknij przycisk "Dodaj do koszyka"
   - Wybierz ilość (opcjonalnie)
   - Wybierz opcje produktu (rozmiar, kolor, itp.)
   - Potwierdź dodanie

   ![Dodawanie do koszyka ze strony produktu](screenshots/add-to-cart.png)

2. **Szybkie dodanie**
   - Najedź na produkt w katalogu
   - Kliknij ikonę koszyka
   - Przedmiot dodany z domyślnymi opcjami

### Zarządzanie koszykiem

#### Przeglądanie zawartości koszyka
- Kliknij ikonę koszyka w nagłówku
- Zobacz mini-koszyk w dropdownie
- Kliknij "Zobacz pełny koszyk" dla szczegółów

#### Aktualizacja ilości
1. Przejdź do strony koszyka
2. Użyj przycisków +/- lub wpisz liczbę
3. Zmiany zapisują się automatycznie

#### Usuwanie przedmiotów
- Kliknij link "Usuń"
- Lub ustaw ilość na 0
- Potwierdź usunięcie w popupie

### Zapisywanie na później

Przenieś przedmioty do listy życzeń:
1. Kliknij "Zapisz na później"
2. Przedmiot przesuwa się do listy życzeń
3. Dostęp z menu konta

### Częste problemy

**Koszyk jest pusty po zalogowaniu**
- Rozwiązanie: Przedmioty koszyka są zapisywane na 30 dni
- Sprawdź czy wcześniej przeglądałeś jako gość

**Nie można zaktualizować ilości**
- Problem: Ograniczone zapasy dostępne
- Rozwiązanie: Sprawdź dostępność produktu

**Ceny się zmieniły**
- Przedmioty pokazują aktualne ceny
- Wyprzedaże mogły się skończyć
- Oryginalna cena pokazana przekreślona

Przewodniki integracji API

> Stwórz przewodnik integracji dla deweloperów używających naszego API

# Przewodnik integracji API

## Szybki start

Uruchom się z naszym API w 5 minut.

### 1. Uzyskaj klucz API
```bash
curl -X POST https://api.example.com/v2/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

2. Wykonaj pierwszy request

const API_KEY = 'your-api-key';
const API_URL = 'https://api.example.com/v2';

// Lista produktów
fetch(`${API_URL}/products`, {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
})
.then(res => res.json())
.then(products => console.log(products));

3. Obsługa odpowiedzi

Wszystkie odpowiedzi następują ten format:

{
  "data": { /* żądane dane */ },
  "meta": {
    "request_id": "req_123",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

Uwierzytelnianie

Uwierzytelnianie kluczem API

Najlepsze dla komunikacji serwer-serwer.

OAuth 2.0

Najlepsze dla aplikacji użytkowników.

Szczegółowy przepływ OAuth →

Częste wzorce

Paginacja

// Pobierz stronę 2 z 50 przedmiotami na stronę
fetch(`${API_URL}/products?page=2&limit=50`)

Filtrowanie

// Filtruj produkty po kategorii i cenie
fetch(`${API_URL}/products?category=electronics&max_price=500`)

Integracja Webhook

Zarejestruj webhooks dla aktualizacji real-time:

fetch(`${API_URL}/webhooks`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhook',
    events: ['order.created', 'order.updated']
  })
})

## Utrzymanie dokumentacji

### Utrzymywanie aktualności dokumentów

Stwórz przepływ aktualizacji dokumentacji:

Hooki git dla przypomnień o dokumentach

Automatyczne kontrole świeżości

Śledzenie wersji

Zawiadomienia o deprecacji

Rezultat:

1. **Hook pre-commit**
   ```bash
   #!/bin/bash
   # Sprawdź czy pliki API się zmieniły
   if git diff --cached --name-only | grep -q "api/"; then
     echo "⚠️  Pliki API się zmieniły. Pamiętaj o aktualizacji dokumentów!"
     echo "Uruchom: claude /generate-api-docs"
   fi

Kontrola świeżości dokumentacji

class DocFreshnessChecker {
  async checkFreshness() {
    const docs = await this.loadDocs();
    const code = await this.loadCode();

    for (const doc of docs) {
      const codeFile = this.findRelatedCode(doc);
      if (codeFile.lastModified > doc.lastModified) {
        console.warn(`📚 ${doc.path} może być przestarzały`);
      }
    }
  }
}

Śledzenie wersji

---
version: 2.3.0
last_updated: 2024-01-15
code_version: commit:abc123
---

# Dokumentacja API

> ⚠️ Ta dokumentacja jest dla v2.3.0.
> Zobacz [historię wersji](./versions) dla innych wersji.

Przepływ deprecacji

/**
 * @deprecated Od v2.1.0. Użyj `newMethod` zamiast tego.
 * Zostanie usunięta w v3.0.0.
 */
function oldMethod() {
  console.warn('oldMethod jest przestarzała. Użyj newMethod zamiast tego.');
  return newMethod();
}

Dokumentacja wielojęzyczna

> Wygeneruj dokumentację w wielu językach:
> - Angielski (główny)
> - Hiszpański
> - Mandaryński
> - Uwzględnij adaptacje kulturowe

Claude generuje zlokalizowane wersje:

<!-- Angielski -->
# Getting Started
Welcome to our API! This guide will help you integrate quickly.

<!-- Hiszpański -->
# Comenzando
¡Bienvenido a nuestra API! Esta guía te ayudará a integrar rápidamente.

<!-- Chiński uproszczony -->
# 快速入门
欢迎使用我们的API！本指南将帮助您快速集成。

Najlepsze praktyki dokumentacji

1. Rozwój documentation-first

> Dla nowych funkcji:
> 1. Najpierw napisz dokumentację
> 2. Uzyskaj zatwierdzenie interesariuszy
> 3. Implementuj zgodnie z dokumentami
> 4. Zaktualizuj dokumenty z doświadczeniami

2. Żywa dokumentacja

> Skonfiguruj ciągłą dokumentację:
> - Auto-generacja z komentarzy kodu
> - Aktualizacja z każdym wdrożeniem
> - Uwzględnienie w pipeline CI/CD
> - Monitorowanie pokrycia dokumentacji

3. Dokumenty kierowane przykładami

> Każdy endpoint API powinien mieć:
> - Wyjaśnienie celu
> - Kompletny przykład requestu
> - Przykład udanej odpowiedzi
> - Przykłady odpowiedzi błędów
> - Częste przypadki użycia
> - Przypadki brzegowe

4. Interaktywna dokumentacja

> Stwórz interaktywną dokumentację API:
> - Wbudowany playground API
> - Żywe przykłady kodu
> - Snippety gotowe do copy-paste
> - Wizualizacja odpowiedzi

Metryki dokumentacji

Śledź jakość dokumentacji:

> Stwórz dashboard dokumentacji pokazujący:
> - Pokrycie (% udokumentowanego kodu)
> - Świeżość (dni od aktualizacji)
> - Kompletność (wymagane sekcje)
> - Użycie (odsłony stron, czas na stronie)
> - Feedback (oceny pomocności)

Powiązane lekcje

Rozwój API Buduj API które warto dokumentować

Strategie testowania Dokumentuj swoje testy i testuj swoją dokumentację

Projektowanie architektury Projektuj systemy które są łatwe do udokumentowania

Następne kroki

Nauczyłeś się jak przekształcić Claude Code w potęgę dokumentacji. Kluczem jest traktowanie dokumentacji jako kodu - zautomatyzowanego, kontrolowanego wersjami i ciągle aktualizowanego. Koniec z przestarzałymi wiki czy brakującymi dokumentami API.

Pamiętaj: Najlepsza dokumentacja to ta która istnieje i pozostaje aktualna. Użyj Claude Code aby tak dramatycznie obniżyć barierę tworzenia dokumentacji, że utrzymywanie aktualnych dokumentów stanie się trywialne. Twoje przyszłe ja (i współpracownicy) będą ci dziękować.