Playbook konwersji projektu

Playbook konwersji projektu

Przekształć swoje istniejące projekty w repozytoria kodu gotowe na AI, które maksymalizują efektywność Cursor i Claude Code.

Stopniowe ulepszanie

Nie musisz konwertować wszystkiego na raz. Zacznij od dokumentacji i zasad, a następnie stopniowo ulepszaj strukturę projektu podczas pracy z narzędziami AI.

Struktura projektu gotowego na AI

Projekt zoptymalizowany pod AI to nie tylko kod—to dostarczenie kontekstu, zasad i struktury, które AI może zrozumieć i skutecznie wykorzystać.

Kluczowe komponenty projektu gotowego na AI

Komponent	Cel	Priorytet
CLAUDE.md	Kontekst projektu dla Claude Code	Niezbędny
.cursor/rules/	Standardy kodowania dla Cursor	Niezbędny
docs/PRD.md	Wymagania produktowe	Wysoki
docs/ARCHITECTURE.md	Decyzje projektowe systemu	Wysoki
docs/API.md	Dokumentacja interfejsów	Średni
tests/	Kompleksowy zestaw testów	Wysoki
.ai-templates/	Szablony promptów	Średni
.github/ai-review.yml	Konfiguracja przeglądu AI	Niski

Proces konwersji według typu projektu

Aplikacja webowa

Konwersja projektu React/Next.js

1. Utwórz CLAUDE.md w katalogu głównym projektu

# Przegląd projektu
To jest aplikacja e-commerce Next.js używająca:
- Next.js 14 z App Router
- TypeScript dla bezpieczeństwa typów
- Tailwind CSS do stylizacji
- Prisma ORM z PostgreSQL
- Stripe do płatności
- NextAuth do uwierzytelniania

## Kluczowe konwencje
- Domyślnie używaj komponentów serwerowych
- Komponenty klienckie tylko gdy konieczne
- Wszystkie trasy API w app/api/
- Współdzielone komponenty w components/ui/
- Logika biznesowa w lib/

## Przepływ pracy nad rozwojem
- Uruchom `npm run dev` do developmentu
- Testy z `npm test`
- Migracje bazy danych: `npx prisma migrate dev`

## Aktualny fokus
Praca nad optymalizacją procesu checkout

2. Skonfiguruj .cursor/rules/

   mkdir -p .cursor/rules

   Utwórz .cursor/rules/react.md:

   # Zasady rozwoju React
   
   - Preferuj komponenty funkcyjne z hookami
   - Używaj interfejsów TypeScript zamiast typów
   - Wydzielaj niestandardowe hooki dla logiki wielokrotnego użytku
   - Trzymaj komponenty poniżej 150 linii
   - Kolokuj testy z komponentami

3. Udokumentuj istniejącą architekturę

   docs/ARCHITECTURE.md

   ## Architektura frontendu
   - Strony używają Next.js App Router
   - Stan globalny z Zustand
   - Wywołania API przez niestandardowe hooki
   - Optymistyczne aktualizacje UI
   
   ## Architektura backendu
   - Projekt API RESTful
   - Middleware do uwierzytelniania/logowania
   - Wzorzec warstwy usług
   - Wzorzec repozytorium dla danych

4. Utwórz strukturę testów przyjazną AI

   __tests__/checkout.test.tsx

   describe('Przepływ checkout', () => {
     it('powinien poprawnie obliczać podatek', () => {
       // AI może to zrozumieć i rozszerzyć
     });
   });

API backendu

Konwersja API Node.js/Express

1. Utwórz kompleksowy CLAUDE.md

# Przegląd usługi API

RESTful API zbudowane z:
- Framework Express.js
- Baza danych PostgreSQL
- Uwierzytelnianie JWT
- Redis do cachowania

## Struktura API
/api/v1/
  /auth    - Endpointy uwierzytelniania
  /users   - Zarządzanie użytkownikami
  /orders  - Przetwarzanie zamówień
  /products - Katalog produktów

## Kluczowe wzorce
- Middleware do uwierzytelniania/walidacji
- Obsługa błędów z niestandardowymi klasami
- Helpery formatowania odpowiedzi
- Transakcje bazodanowe dla spójności

2. Udokumentuj endpointy API

   docs/API.md

   ## Uwierzytelnianie
   POST /api/v1/auth/login
   POST /api/v1/auth/logout
   POST /api/v1/auth/refresh
   
   ## Użytkownicy
   GET    /api/v1/users
   POST   /api/v1/users
   GET    /api/v1/users/:id
   PUT    /api/v1/users/:id
   DELETE /api/v1/users/:id

3. Dodaj standardy kodowania

   .cursor/rules/api.md

   ## Zasady rozwoju API
   - Zawsze waliduj dane wejściowe z Joi
   - Używaj try-catch z async/await
   - Zwracaj spójny format błędów
   - Loguj wszystkie błędy z kontekstem
   - Używaj transakcji bazodanowych

Aplikacja mobilna

Konwersja projektu React Native

1. CLAUDE.md specyficzny dla mobile

# Przegląd aplikacji mobilnej

Aplikacja React Native wspierająca:
- iOS 14+ i Android 10+
- TypeScript w całości
- React Navigation v6
- Redux Toolkit do stanu
- React Query do API

## Struktura projektu
/src
  /screens   - Komponenty ekranów
  /components - Współdzielone komponenty
  /navigation - Konfiguracja nawigacji
  /store     - Store Redux
  /api       - Klient API
  /utils     - Helpery

2. Zasady specyficzne dla platformy

   .cursor/rules/mobile.md

   - Zawsze testuj na obu platformach
   - Używaj Platform.select dla różnic OS
   - Preferuj styled-components
   - Optymalizuj obrazy i zasoby
   - Obsługuj scenariusze offline

Szablony podstawowej dokumentacji

1. Szablon CLAUDE.md

Kompleksowa struktura CLAUDE.md

# [Nazwa projektu]

## Przegląd
Krótki opis tego co robi projekt i jego główny cel.

## Stos technologiczny
- Język: [np. TypeScript 5.0]
- Framework: [np. Next.js 14]
- Baza danych: [np. PostgreSQL 15]
- Kluczowe biblioteki: [Lista głównych zależności]

## Struktura projektu

/src /components - Komponenty React /pages - Strony Next.js /api - Trasy API /lib - Funkcje narzędziowe /styles - Pliki CSS/Sass

## Konfiguracja rozwoju
1. Zainstaluj zależności: `npm install`
2. Skonfiguruj środowisko: `cp .env.example .env.local`
3. Uruchom bazę danych: `docker-compose up -d`
4. Uruchom serwer dev: `npm run dev`

## Konwencje kodowania
- Tryb strict TypeScript włączony
- ESLint + Prettier do formatowania
- Conventional commits
- Cel 100% pokrycia testów

## Bieżące zadania
- [ ] Implementacja dashboardu użytkownika
- [ ] Optymalizacja zapytań bazodanowych
- [ ] Dodawanie powiadomień w czasie rzeczywistym

## Znane problemy
- Wąskie gardło wydajności w wyszukiwaniu
- Wyciek pamięci w handlerze WebSocket

## Decyzje architektoniczne
- Używanie Server Components dla SEO
- Wybór PostgreSQL dla wsparcia JSONB
- Implementacja architektury napędzanej zdarzeniami

2. Szablon zasad Cursor

Struktura .cursor/rules/

.cursor/rules/
├── general.md      # Ogólne standardy kodowania
├── typescript.md   # Zasady specyficzne dla TypeScript
├── react.md        # Wzorce React
├── testing.md      # Wymagania testowe
├── security.md     # Wytyczne bezpieczeństwa
└── performance.md  # Zasady wydajności

Przykład general.md:

# Ogólne standardy kodowania

## Jakość kodu
- Trzymaj funkcje poniżej 50 linii
- Maksymalnie 3 parametry na funkcję
- Opisowe nazwy zmiennych
- Komentarze tylko dla złożonej logiki

## Obsługa błędów
- Nigdy nie ignoruj błędów po cichu
- Loguj błędy z kontekstem
- Przyjazne dla użytkownika komunikaty błędów
- Graceful degradation

## Przepływ pracy Git
- Branche feature z develop
- Squash commitów przed merge
- Konwencjonalne wiadomości commitów
- PR wymaga 2 zatwierdzeń

3. Szablon PRD

Dokument wymagań produktowych

# Feature: [Nazwa funkcji]

## Przegląd
Krótki opis funkcji i jej propozycji wartości.

## Historie użytkowników
- Jako [typ użytkownika], chcę [akcja] aby [korzyść]
- Jako [typ użytkownika], chcę [akcja] aby [korzyść]

## Kryteria akceptacji
- [ ] Użytkownik może wykonać X
- [ ] System waliduje Y
- [ ] Obsługa błędów dla Z

## Wymagania techniczne
- Musi działać na urządzeniach mobilnych
- Czas odpowiedzi < 200ms
- Wsparcie 1000 równoczesnych użytkowników
- Dostępność (WCAG 2.1 AA)

## Wymagania niefunkcjonalne
- Bezpieczeństwo: Uwierzytelnianie OAuth 2.0
- Wydajność: CDN dla zasobów statycznych
- Monitoring: Śledzenie metryk użycia

## Zależności
- Integracja bramki płatności
- Usługa email dla powiadomień
- Konfiguracja śledzenia analitycznego

## Metryki sukcesu
- 80% wskaźnik adopcji funkcji
- < 2% wskaźnik błędów
- 50% redukcja zgłoszeń do wsparcia

Konwersja starszego kodu

Analiza istniejącej bazy kodu

1. Wygeneruj początkową dokumentację

   # Użyj AI do analizy i dokumentowania
   "Przeanalizuj tę bazę kodu i utwórz:
   - Przegląd architektury
   - Lista głównych komponentów
   - Szczegóły stosu technologicznego
   - Kluczowe używane wzorce
   - Obszary wymagające refaktoryzacji"

2. Zidentyfikuj anti-wzorce

   "Przejrzyj kod pod kątem:
   - Code smells
   - Luki bezpieczeństwa
   - Wąskie gardła wydajności
   - Przestarzałe zależności
   - Brakujące testy"

3. Utwórz plan migracji

   # Plan migracji
   
   ## Faza 1: Dokumentacja (Tydzień 1)
   - Utwórz CLAUDE.md
   - Udokumentuj endpointy API
   - Zmapuj zależności
   
   ## Faza 2: Testowanie (Tydzień 2)
   - Dodaj brakujące testy jednostkowe
   - Utwórz testy integracyjne
   - Skonfiguruj CI/CD
   
   ## Faza 3: Refaktoryzacja (Tydzień 3-4)
   - Zaktualizuj zależności
   - Napraw krytyczne problemy
   - Popraw strukturę kodu

Strategia modernizacji

Podejście stopniowe

• Zacznij od dokumentacji
• Dodaj testy do istniejącego kodu
• Refaktoryzuj moduł po module
• Utrzymuj kompatybilność wsteczną

Podejście big bang

• Planowanie kompletnego przepisania
• Równoległy rozwój
• Lista kontrolna parzystości funkcji
• Strategia stopniowego wdrażania

Punkty integracji AI

1. Automatyczna dokumentacja

Przepływ pracy generowania dokumentacji

.github/workflows/docs.yml

name: Aktualizuj dokumentację

on:
  push:
    branches: [main]

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Wygeneruj dokumentację API
        run: |
          # AI generuje z kodu
          npx ai-doc-gen --source ./src --output ./docs/api

      - name: Aktualizuj CLAUDE.md
        run: |
          # AI aktualizuje kontekst projektu
          npx update-claude-md

      - name: Zatwierdź zmiany
        run: |
          git add docs/
          git commit -m "docs: auto-aktualizacja dokumentacji"
          git push

2. Egzekwowanie jakości kodu

Przegląd kodu wspierany AI

.github/ai-review.yml

review:
  models:
    - claude-4-sonnet
    - gpt-4

  checks:
    - security_vulnerabilities
    - performance_issues
    - code_duplication
    - test_coverage
    - documentation_gaps

  rules:
    - enforce_typescript
    - require_tests
    - max_complexity: 10
    - min_coverage: 80

3. Generowanie testów

Strategia generowania testów AI

ai-test-template.ts

describe('[Komponent/Funkcja]', () => {
  // AI generuje kompleksowe testy

  describe('Szczęśliwa ścieżka', () => {
    it('powinien obsłużyć normalne dane wejściowe', () => {
      // Implementacja testu
    });
  });

  describe('Przypadki brzegowe', () => {
    it('powinien obsłużyć puste dane wejściowe', () => {
      // Implementacja testu
    });

    it('powinien obsłużyć wartości null', () => {
      // Implementacja testu
    });
  });

  describe('Scenariusze błędów', () => {
    it('powinien rzucić błąd przy nieprawidłowych danych', () => {
      // Implementacja testu
    });
  });
});

Mierzenie sukcesu konwersji

Metryki sukcesu

Metryka	Przed	Po	Cel
Zrozumienie AI	0%	80%	90%
Pokrycie dokumentacji	20%	90%	95%
Pokrycie testów	40%	85%	90%
Szybkość refaktoryzacji	1 plik/godz	10 plików/godz	15 plików/godz
Wykrywanie błędów	Ręczne	Wspomagane AI	Zautomatyzowane
Czas przeglądu kodu	2 godziny	30 minut	15 minut

Częste pułapki do unikania

Nadmierna dokumentacja

Nie dokumentuj oczywistych rzeczy. Skup się na:

• Decyzjach architektonicznych
• Uzasadnieniu logiki biznesowej
• Złożonych algorytmach
• Integracjach zewnętrznych

Sztywne zasady

Zasady powinny prowadzić, nie ograniczać:

• Pozwalaj na wyjątki z uzasadnieniem
• Aktualizuj zasady na podstawie nauki
• Trzymaj zasady zwięzłe i jasne

Ignorowanie kontekstu

Zawsze zapewniaj kontekst biznesowy:

• Dlaczego funkcje istnieją
• Zrozumienie podróży użytkownika
• Wymagania wydajności
• Kwestie bezpieczeństwa

Lista kontrolna konwersji

Kompletna lista kontrolna konwersji

• Dokumentacja

  • CLAUDE.md utworzony i kompleksowy
  • Architektura udokumentowana
  • Dokumentacja API kompletna
  • PRD dla głównych funkcji

• Konfiguracja AI

  • Katalog .cursor/rules/ skonfigurowany
  • Standardy kodowania udokumentowane
  • Wzorce testów zdefiniowane
  • Zasady bezpieczeństwa określone

• Jakość kodu

  • Linting skonfigurowany
  • Testy osiągające >80% pokrycia
  • Pipeline CI/CD aktywny
  • Proces przeglądu kodu zdefiniowany

• Struktura projektu

  • Jasna organizacja folderów
  • Spójne konwencje nazewnictwa
  • Modularna architektura
  • Zależności udokumentowane

• Gotowość zespołu

  • Zespół przeszkolony w narzędziach AI
  • Przepływy pracy udokumentowane
  • Metryki sukcesu zdefiniowane
  • Pętla feedbacku ustanowiona

Ciągłe doskonalenie

Konwersja projektu to nie jednorazowa aktywność. Ciągle aktualizuj dokumentację, udoskonalaj zasady i optymalizuj strukturę, ucząc się, co najlepiej sprawdza się z narzędziami AI.

Następne kroki

1. Zacznij od dokumentacji - Utwórz CLAUDE.md już dziś
2. Dodaj jeden plik zasad - Zacznij od ogólnych standardów kodowania
3. Konwertuj jeden moduł - Wybierz dobrze zrozumiany komponent
4. Zmierz poprawę - Śledź zaoszczędzony czas i zyski jakościowe
5. Iteruj i rozszerzaj - Zastosuj nauki do reszty projektu

Celem nie jest perfekcja—to stworzenie fundamentu, który czyni asystę AI bardziej efektywną i twój rozwój bardziej wydajnym.