Playbook konwersji projektu

Kierujesz Claude Code na trzyletnie repozytorium Next.js i prosisz o dodanie funkcji. AI wymyśla bibliotekę do zarządzania stanem, którą usunąłeś w zeszłym kwartale, umieszcza trasę API w niewłaściwym katalogu i pisze testy we frameworku, którego nie używasz. Kod nie jest zły — po prostu nie ma pojęcia, jak działa Twój projekt. Rozwiązaniem nie jest lepszy prompt; to danie agentowi kontekstu, który nowy pracownik dostałby pierwszego dnia.

Ten playbook przekształca istniejący projekt w taki, w którym Cursor, Claude Code i Codex mogą produktywnie pracować, korzystając z jednego źródła prawdy, które wszystkie trzy czytają.

Z czym wyjdziesz

• Prawdziwy CLAUDE.md / AGENTS.md wygenerowany z Twojego repozytorium, a nie z pustego szablonu
• Reguły .mdc Cursora ograniczone do tych części bazy kodu, których dotyczą
• Gotowe do wklejenia prompty do audytu starszej bazy kodu i stworzenia etapowego planu konwersji
• Zadanie CI, które utrzymuje pliki kontekstu na bieżąco za pomocą prawdziwego CLI agenta — bez fikcyjnych narzędzi npm
• Jasny obraz tego, jak każde narzędzie konsumuje kontekst, byś nie utrzymywał trzech rozjeżdżających się kopii

Jedno źródło prawdy

Błędem, który popełniają zespoły, jest ręczne pisanie trzech osobnych plików kontekstu. Zamiast tego zapisz konwencje raz i pozwól, by plik wejściowy każdego narzędzia wskazywał na tę samą treść. Wszystkie trzy narzędzia czytają plik Markdown na poziomie katalogu głównego:

Narzędzie	Czyta	Uwagi
Claude Code	CLAUDE.md	Katalog główny projektu; pliki CLAUDE.md w podkatalogach nadpisują dla tej ścieżki
Codex	AGENTS.md	Ten sam pomysł, otwarty standard AGENTS.md
Cursor	.cursor/rules/*.mdc	Pliki reguł z zakresem i frontmatterem; czyta też AGENTS.md

Trzymaj je w synchronizacji, nie rozgałęziaj

Konfiguracja o najniższym koszcie utrzymania: uczyń CLAUDE.md plikiem kanonicznym, a AGENTS.md jednolinijkowym wskaźnikiem (See CLAUDE.md for project conventions.) lub dowiązaniem symbolicznym. Wytyczne specyficzne dla Cursora, ograniczone do ścieżek, umieść w .cursor/rules/ i utrzymuj je krótkie, odwołując się do plików, zamiast wklejać ich zawartość.

Zacznij od generowania kontekstu, nie od jego pisania

Nie otwieraj pustego CLAUDE.md. Pozwól agentowi przeczytać repozytorium i sporządzić jego szkic — będziesz edytować znacznie mniej, niż byś napisał. To jest identyczne we wszystkich trzech narzędziach; uruchom prompt w tym, które masz akurat otwarte.

Prompt do wklejenia: wygeneruj CLAUDE.md z repozytorium

Read this repository — package.json, the directory layout, the CI config, and a sample of source files — and generate a CLAUDE.md for the project root. Include: the actual tech stack with versions from package.json (do not guess), the real directory conventions you observe (where routes, components, and business logic live), the exact dev/test/build commands from the scripts, and any non-obvious patterns you can infer (state management, error handling, auth). Mark anything you’re unsure about with TODO: confirm instead of guessing. Keep it under 150 lines.

Skonfrontuj szkic z rzeczywistością, usuń linie TODO: confirm, na które potrafisz odpowiedzieć, i zatwierdź go. Ugruntowany plik na 120 linii bije szablon na 400 linii pełen [YOUR_FRAMEWORK].

Oto kształt dobrego wyniku dla prawdziwej aplikacji Next.js — konkretny, a nie formularz do wypełnienia:

# Acme Storefront

Next.js 16 e-commerce app. App Router, RSC by default.

## Stack
- Next.js 16.2 (App Router), React 19, TypeScript 5.6 (strict)
- Tailwind CSS 4, Prisma 6 + PostgreSQL 16, Stripe, Auth.js v5

## Conventions
- Server Components by default; add `'use client'` only for interactivity
- Route handlers live in `app/api/`, one folder per resource
- Shared UI in `components/ui/`, feature components beside their route
- Data access goes through `lib/db/` — never call Prisma from a component
- Money is stored and computed in integer cents, never floats

## Commands
- Dev: `npm run dev` | Test: `npm test` (Vitest) | Migrate: `npx prisma migrate dev`

## Watch out
- The legacy `/pages/checkout` route is being migrated to App Router — don't extend it

Jak każde narzędzie to konsumuje

Przepływ pracy konwersji rozchodzi się w zależności od narzędzia, gdy plik kontekstu już istnieje. Oto, co skonfigurować w każdym z nich.

Cursor

Cursor czyta .cursor/rules/*.mdc. Używaj .mdc (Markdown z frontmatterem), abyś mógł ograniczać reguły do ścieżek i kontrolować, kiedy się stosują — .md też działa, ale nie daje żadnego ograniczania zakresu.

.cursor/rules/
  general.mdc        # alwaysApply: true — core standards
  api.mdc            # globs: app/api/** — backend rules
  components.mdc     # globs: components/** — UI rules

Reguła z zakresem i prawdziwym frontmatterem:

---
description: API route conventions
globs: app/api/**
alwaysApply: false
---

- Validate request bodies with Zod schemas from `lib/schemas/`
- Wrap handlers in `withErrorHandler` from `lib/api/errors.ts`
- Return `NextResponse.json` with explicit status codes
- Never expose Prisma errors to the client

Odwołuj się do plików, zamiast je wklejać (@lib/api/errors.ts), by reguły nie traciły aktualności, gdy kod się zmienia.

Claude Code

Claude Code czyta CLAUDE.md z katalogu głównego i scala wszelkie pliki CLAUDE.md z podkatalogów dla pracy w tej ścieżce. Załóż go komendą /init wewnątrz REPL, która skanuje repozytorium i sporządza dla Ciebie szkic pliku:

> /init

Następnie dopracuj go promptem generującym z powyżej. W przypadku monorepo dodaj skupiony CLAUDE.md w każdym pakiecie — na przykład packages/api/CLAUDE.md opisujący tylko tę usługę — i utrzymuj plik główny na wysokim poziomie ogólności. Claude Code automatycznie wybiera najbliższy plik dla kodu, który edytuje.

Codex

Codex czyta AGENTS.md. Jeśli napisałeś już CLAUDE.md, nie powielaj go — wskaż na niego Codex:

AGENTS.md

See CLAUDE.md for project conventions, stack, and commands.

## Codex-specific
- Run `npm run lint && npm test` before declaring a task done
- For parallel Cloud tasks, scope each task to one package

Podobnie jak Claude Code, Codex obsługuje zagnieżdżone pliki AGENTS.md, więc plik na poziomie pakietu nadpisuje główny dla pracy w tym katalogu.

Konwersja starszej bazy kodu

W przypadku starszego projektu z ubogą dokumentacją poprowadź konwersję dwoma promptami: jednym do zmapowania tego, co istnieje, drugim do zaplanowania pracy.

1. Zmapuj bazę kodu. Pozwól agentowi zbudować obraz, który inaczej rekonstruowałbyś ręcznie.

   Prompt do wklejenia: audyt starszej bazy kodu

   Audit this codebase and produce a report with five sections: (1) Architecture — the real module boundaries and data flow, not the aspirational ones; (2) Stack — frameworks and versions, flagging any that are EOL or a major version behind; (3) Anti-patterns and risks — concrete files with code smells, missing input validation, or N+1 query patterns, cited by path; (4) Test coverage gaps — which critical paths have no tests; (5) A prioritized list of what to fix first, ordered by risk × effort. Be specific and cite file paths. Do not suggest a rewrite.

2. Zamień audyt w etapowy plan. Przekuj ustalenia w pracę, którą faktycznie da się zaplanować.

   Prompt do wklejenia: stwórz etapowy plan migracji

   Using the audit above, write a three-phase conversion plan as a checklist. Phase 1: documentation and context files (CLAUDE.md, scoped Cursor rules) — one task per area. Phase 2: characterization tests around the highest-risk untested paths you identified, so refactors are safe. Phase 3: the refactors themselves, smallest-blast-radius first, each as an independent task I can hand to a separate agent. For every task, note the files touched and how I’ll verify it’s done.

3. Wykonuj przyrostowo. Pracuj moduł po module, zachowując kompatybilność wsteczną. Najpierw wprowadź pliki kontekstu (Faza 1), aby każde kolejne zadanie z nich korzystało, potem testy charakteryzujące, a na końcu refaktoryzacje. Rozprosz niezależne zadania Fazy 3 na zadania Codex Cloud lub subagentów Claude Code i recenzuj diffy w miarę, jak napływają.

Utrzymanie kontekstu na bieżąco w CI

CLAUDE.md sprzed pół roku jest gorszy niż żaden — aktywnie wprowadza agenta w błąd. Zautomatyzuj odświeżanie w CI za pomocą prawdziwego CLI agenta, a nie fikcyjnego narzędzia npx. Claude Code działa headless z -p; Codex działa nieinteraktywnie z codex exec.

.github/workflows/refresh-context.yml

name: Refresh project context
on:
  schedule:
    - cron: '0 6 * * 1' # Monday mornings
  workflow_dispatch:

jobs:
  update-claude-md:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update CLAUDE.md from the current codebase
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review CLAUDE.md against the current repo. Update the \
            stack versions, commands, and directory conventions only where \
            they no longer match reality. Output the corrected file." \
            --output-format text > CLAUDE.md

      - name: Open a PR if anything changed
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: 'docs: refresh CLAUDE.md from codebase'
          title: 'docs: refresh project context'
          branch: chore/refresh-context

Nie commituj wyjścia agenta automatycznie do main

Wygeneruj aktualizację na branchu i otwórz PR, jak powyżej — nigdy nie wypychaj dokumentacji napisanej przez agenta prosto do main. Rzut oka człowieka wyłapuje sporadyczną edycję pewną siebie, lecz błędną, a diff czyni rozjazd widocznym. Ten sam wzorzec działa z codex exec "...", jeśli Twoje CI uwierzytelnia się przez Codex.

Kiedy to się psuje

Agent ignoruje Twój CLAUDE.md

Najczęściej plik jest zbyt długi albo zatopiony w narracji. Agenci ważą zwięzłe, rozkazujące reguły wyżej niż prozę. Przytnij go poniżej ~150 linii, zacznij od twardych ograniczeń („never call Prisma from a component”) i usuń wszystko, co agent mógłby wywnioskować z samego kodu. Jeśli konkretna reguła wciąż jest łamana, przenieś ją do reguły .mdc Cursora z zakresem i pasującym globs, by ładowała się dokładnie wtedy, gdy jest istotna.

Reguły kolidują między narzędziami

Gdy CLAUDE.md, AGENTS.md i .cursor/rules się nie zgadzają, każde narzędzie podąża za własnym plikiem i dostajesz trzy zachowania. To objaw rozgałęziania zamiast synchronizacji. Zwiń do jednego pliku kanonicznego i spraw, by pozostałe się do niego odwoływały. Uruchom git grep w poszukiwaniu tej samej reguły sformułowanej inaczej w wielu plikach i uzgodnij je.

Dokumentacja straciła aktualność po dużej refaktoryzacji

Jeśli zmieniłeś nazwy katalogów lub podmieniłeś bibliotekę, a agent zaczyna sugerować starą strukturę, Twój plik kontekstu go okłamuje. Uruchom zadanie odświeżania CI ręcznie (workflow_dispatch) albo ponownie odpal prompt generujący, a następnie zrecenzuj PR. Traktuj pliki kontekstu jak kod: należą do tego samego commita, co zmiana, którą opisują.

Lista kontrolna konwersji

Minimalny działający projekt gotowy na AI

• ☐ Kanoniczny CLAUDE.md (lub AGENTS.md) wygenerowany z repozytorium i zrecenzowany
• ☐ Wtórne pliki wejściowe wskazują na kanoniczny — a nie rozgałęzione kopie
• ☐ .cursor/rules/*.mdc dla standardów z zakresem ścieżek (API, komponenty, testy)
• ☐ Ścieżki o najwyższym ryzyku bez testów mają testy charakteryzujące przed jakąkolwiek refaktoryzacją
• ☐ Zadanie odświeżania CI otwiera PR, nigdy nie commituje automatycznie do main
• ☐ Pliki kontekstu aktualizowane w tym samym PR co zmiany strukturalne

Co dalej

• Między Codex, Cursor a Claude Code — uruchom wszystkie trzy z jednego zestawu konwencji
• Transformacja przepływu pracy — przekształć pętle delegowania i recenzji
• Strategie migracji zespołowej — wdróż konwersję w całym zespole
• Centrum strategii migracji — pełna mapa playbooków migracji

Celem nie jest perfekcyjny dokument. To fundament, który sprawia, że agent zachowuje się jak ktoś, kto już zna Twoją bazę kodu.