Playbook konwersji projektu

Konwersja projektu to procedura, która sprawia, że istniejące repozytorium nadaje się do pracy z agentami kodującymi: jeden plik AGENTS.md wygenerowany z prawdziwego kodu i poprawiony przez człowieka, cienkie adaptery dla Claude Code i Cursora, kontrola w CI, która pilnuje, by opisane polecenia działały, oraz pilotaż przed/po na prawdziwych zgłoszeniach, który dowodzi, że agenci trzymają się konwencji projektu.

Wskazujesz agentowi trzyletnie repozytorium Next.js i prosisz o nową funkcję. Agent dodaje bibliotekę stanu, którą usunęliście kwartał temu, umieszcza handler trasy (route handler) w złym katalogu i uruchamia npm test w repozytorium, które rok temu przeszło na pnpm. Kod nie jest zły. Agent po prostu nie wie, jak działa twój projekt, i lepszy prompt tego nie naprawi. Ten playbook jest dla tech leada, który odpowiada za repozytorium i musi sprawić, by działało dla ośmiu osób i trzech narzędzi.

Co zyskasz dzięki konwersji projektu

• Kanoniczny AGENTS.md wygenerowany z repozytorium, z każdym poleceniem sprawdzonym w praktyce
• Cienkie adaptery, dzięki którym Claude Code, Codex i Cursor ładują ten sam rdzeń zamiast trzech rozjeżdżających się kopii
• Cztery prompty do skopiowania: szkic AGENTS.md z repozytorium, sprawdzenie, co załadowała sesja, audyt kodu legacy i przełożenie audytu na plan konwersji w fazach
• Deterministyczną kontrolę w CI, która zawodzi, gdy AGENTS.md wymienia polecenie, którego już nie ma
• Kartę wyników pilotażu, która na trzech zamkniętych zgłoszeniach pokazuje, czy konwersja zmieniła zachowanie agentów

Gdzie konwersja projektu mieści się we wdrożeniu zespołowym

Konwersja to krok wykonywany dla pojedynczego repozytorium w ramach mapy drogi adopcji. Następuje po zmierzeniu punktu odniesienia, a przed przebudową delegowania i code review. Dwie sąsiednie strony omawiają jej części dokładniej:

• Jak przygotować repozytorium do pracy agentów ocenia cechy repozytorium (kontrola jednym poleceniem, deterministyczne testy, wymuszone granice modułów), dzięki którym kontrole zastępują czytanie diffów. Ten audyt uruchamiasz w kroku 1 poniżej.
• Wspólne reguły agentów to pełne omówienie tego, jak każde narzędzie odnajduje pliki instrukcji i jak sprawdzić, że każdy agent je załadował. Ta strona korzysta z opisanego tam wzorca adapterów, ale go nie powtarza.

Przekonwertuj repozytorium w pięciu krokach

Kolejność ma znaczenie. Pliki kontekstu napisane, zanim powstaną kontrole, każą agentowi uruchamiać polecenia, które nie działają, a pilotaż przed wdrożeniem plików kontekstu niczego nie mierzy.

1. Zmierz punkt odniesienia, zanim cokolwiek zmienisz. Wybierz trzy zamknięte zgłoszenia, które dotykały różnych części kodu. Dla każdego zapisz, co dziś robi nowa sesja agenta z oryginalną treścią zgłoszenia: jakim poleceniem sprawdza swoją pracę, które katalogi edytuje i ile poprawek musiałeś jej przekazać. Uruchom też audyt gotowości repozytorium i zanotuj polecenie kontrolne albo jego brak.

2. Zadbaj o jedno polecenie kontrolne. Jeśli pnpm check (albo make check, albo ./gradlew check) nie uruchamia jeszcze w jednym kroku lintera, sprawdzania typów i testów, dodaj je najpierw. Każda kolejna instrukcja mówi „gotowe oznacza, że to polecenie przechodzi”, więc musi ono istnieć i przechodzić na gałęzi głównej.

3. Wygeneruj AGENTS.md z repozytorium, a potem go popraw. Użyj poniższego promptu w narzędziu, które masz otwarte. Porównaj szkic z rzeczywistością, rozstrzygnij lub usuń każdą linię TODO: confirm i zatwierdź plik w osobnym pull requeście, aby recenzenci mogli sprawdzić konwencje, które opisuje.

4. Dodaj adaptery i reguły o ograniczonym zasięgu. Podłącz każde narzędzie do tego samego rdzenia (następna sekcja). Wskazówki dotyczące konkretnych ścieżek, na przykład „handlery API walidują dane schematami Zod z lib/schemas/”, umieść w regułach ładowanych tylko dla tych ścieżek, a nie w pliku głównym.

5. Powtórz zgłoszenia z punktu odniesienia i zatwierdź konwersję. Uruchom te same trzy zgłoszenia w nowych sesjach i wypełnij kartę wyników pilotażu (zobacz jak udowodnić, że konwersja zadziałała). Tech lead zatwierdza konwersję, gdy karta wyników się poprawia, a nie wtedy, gdy pliki istnieją.

Prompt do skopiowania: szkic AGENTS.md z repozytorium

Read this repository before writing anything: the package manifest and lockfile, the
directory layout, the CI workflow files, and a sample of source files from each top-level
module. Then draft AGENTS.md for the repository root with these sections:

1. Stack: frameworks and major versions exactly as the manifest pins them. Do not guess.
2. Commands: the exact dev, check, test and build commands, taken from the scripts and
   the CI config. Name the package manager the lockfile implies.
3. Definition of done: "the check command passes" plus anything CI enforces.
4. Conventions you can observe in the code: where routes, UI components, data access and
   business logic live, and one example file path for each.
5. Boundaries: directories an agent must not edit without asking (generated code,
   migrations, vendored code, infrastructure).
6. Traps: deprecated areas still in the tree that must not be extended.

Mark anything you cannot confirm from the files with "TODO: confirm" instead of guessing.
Keep it under 150 lines. Do not describe anything the agent can infer from reading a file.
Finally, list every command you wrote into the file and run each one, reporting which fail.

Najważniejsza jest ostatnia instrukcja. Szkic, który w repozytorium opartym na pnpm wymienia npm test, czyta się dobrze i zawodzi przy pierwszym użyciu, więc każ agentowi sprawdzić każde polecenie, zanim zaczniesz recenzować tekst.

Tak wygląda dobry wynik dla aplikacji Next.js: konkretny, krótki i sprawdzalny.

# Acme Storefront

Next.js App Router application. React Server Components by default. pnpm only.

## Commands
- Check (lint + types + tests): `pnpm check`. A task is done only when this passes.
- Dev server: `pnpm dev` · Unit tests: `pnpm test` · Migrations: `pnpm db:migrate`

## Conventions
- Server Components by default; add `'use client'` only for interactivity.
- Route handlers live in `app/api/<resource>/route.ts`, one folder per resource.
- Data access goes through `lib/db/`; never import the Prisma client in a component.
- Money is integer cents everywhere. See `lib/money.ts`.

## Boundaries (ask first)
- `prisma/migrations/`, `infra/`, anything under `generated/`

## Traps
- `pages/checkout/` is being migrated to the App Router. Do not extend it.

Jak każde narzędzie ładuje przekonwertowany kontekst?

Rdzeń jest taki sam dla wszystkich trzech narzędzi. Adaptery się różnią, bo każde narzędzie inaczej odnajduje pliki instrukcji. Pełne zasady wykrywania i testy sprawdzające są na stronie wspólnych reguł agentów; tu jest minimum na dzień konwersji.

Claude Code

Obok każdego AGENTS.md dodaj CLAUDE.md, którego pierwsza linia go importuje. Linie specyficzne dla Claude Code umieść pod importem.

@AGENTS.md

## Claude Code only
- Use plan mode for changes under `services/billing/`.

Import @AGENTS.md działa w każdym kanale wydań i u każdego dostawcy. Claude Code czyta też AGENTS.md (lub .claude/AGENTS.md) bezpośrednio, gdy nie ma CLAUDE.md, ale dopiero od v2.1.277 (v2.1.281 na Bedrocku, Google Cloud, Microsoft Foundry, bramkach LLM i w sesjach z wyłączoną telemetrią). Obie wersje są na kanałach latest i stable, odkąd stable doszedł do v2.1.287 (sprawdzone 2026-10-12). Z reguły wyszukiwania wynikają dwie pułapki:

• Dowolny CLAUDE.md, .claude/CLAUDE.md lub CLAUDE.local.md w katalogu roboczym albo wyżej wyłącza bezpośrednie czytanie, więc CLAUDE.md bez importu całkowicie ukrywa AGENTS.md. Prywatny CLAUDE.local.md inżyniera robi to samo, tylko u niego. Tak jest domyślnie. Aby zachować prywatny CLAUDE.local.md i nadal ładować AGENTS.md, ustaw Project instructions na claude-md-and-agents-md w /config (v2.1.277+).
• CLAUDE.md, który jedynie słownie każe „przeczytać AGENTS.md”, nie działa niezawodnie: Claude zobaczy ten plik tylko wtedy, gdy sam zdecyduje się go otworzyć.

Wskazówki dla konkretnych ścieżek umieść w .claude/rules/*.md z listą paths we frontmatterze. Takie reguły ładują się, gdy Claude czyta pasujący plik, a nie przy starcie:

---
paths:
  - "app/api/**/*.ts"
---

- Validate request bodies with the Zod schemas in `lib/schemas/`.
- Wrap handlers in `withErrorHandler` from `lib/api/errors.ts`.

Pliki CLAUDE.md w podkatalogach też ładują się na żądanie, gdy Claude czyta pliki w danym katalogu. Sprawdź, co się załadowało, poleceniem /context w nowej sesji: pliki pojawiają się w sekcji Memory files.

Codex

Codex czyta AGENTS.md natywnie, więc rdzeń nie potrzebuje adaptera. Dwa zachowania zmieniają sposób organizacji monorepo (sprawdzone w źródłach agents_md.rs i config_toml.rs oraz w Codex CLI 0.157.1 dnia 2026-09-26):

• Codex zbiera pliki AGENTS.md od katalogu głównego projektu w dół do katalogu, w którym startuje sesja, i łączy je, zaczynając od głównego. packages/api/AGENTS.md ładuje się tylko wtedy, gdy Codex startuje w packages/api/ lub głębiej, na przykład przez codex -C packages/api. Nie ładuje się dlatego, że agent później edytuje tam plik.
• project_doc_max_bytes domyślnie ogranicza cały łańcuch do 32 KiB. Po przekroczeniu limitu najpierw obcinane są pliki najgłębiej położone.

Sprawdź, co zobaczy Codex, bez uruchamiania zadania:

# Terminal, from the directory where engineers start Codex
codex debug prompt-input "noop" | grep -c "pnpm check"

Jeśli repozytorium ma już kanoniczny CLAUDE.md, którego nie da się jeszcze przenieść, ustawienie project_doc_fallback_filenames = ["CLAUDE.md"] w config.toml sprawia, że Codex przeczyta go w katalogach bez AGENTS.md. Traktuj to jako pomost, nie stan docelowy. Od Codeksa 0.150.0 niezaufane projekty nie dostarczają projektowego AGENTS.md, więc najpierw oznacz projekt jako zaufany.

Cursor

Cursor stosuje instrukcje projektu przez Rules (cursor.com/docs/rules, sprawdzone 2026-10-12). Reguły projektu to pliki .mdc w .cursor/rules (zwykły plik .md jest tam ignorowany), a Cursor obsługuje też AGENTS.md w katalogu głównym projektu i w podkatalogach. Ta strona nie odtwarza składni plików reguł; zanim je napiszesz, sprawdź stronę Rules. Niezależnie od formatu testem akceptacyjnym jest poniższy prompt testowy: adapter dla Cursora jest gotowy, gdy nowy czat Agenta poprawnie odpowiada na wszystkie cztery pytania, bez względu na to, co mówi dokumentacja.

• Jeśli nowy czat Agenta w twojej wersji Cursora 3.x poprawnie odpowiada na prompt testowy, nie dodawaj niczego.
• W przeciwnym razie dodaj jedną regułę projektu stosowaną zawsze, która kieruje agenta do AGENTS.md i zawiera tylko linie specyficzne dla Cursora. Powtórz test.
• Wskazówki dla konkretnych ścieżek umieść w regułach ograniczonych do tych ścieżek, z tą samą treścią co pliki .claude/rules/ dla Claude Code.
• Jeśli repozytorium ma już reguły projektu Cursora, przenieś ich trwałą treść do AGENTS.md, a reguły ogranicz do odnośników i linii dla konkretnych ścieżek. Nie wklejaj rdzenia do reguły: właśnie przez kopię nieaktualne npm test przeżywa przejście na pnpm.

Prompt do skopiowania: sprawdź, co załadowała nowa sesja

Without opening any files, answer from the instructions you already have:
1. What exact command must pass before you call a task done?
2. Which package manager does this repository use?
3. Which directories must you not edit without asking?
4. Which area of the code is deprecated and must not be extended?
If you do not have an instruction for a question, answer "no instruction" rather than guessing.

Uruchom ten test w nowej sesji każdego narzędzia, z katalogu, w którym inżynierowie zwykle zaczynają pracę. Cztery poprawne odpowiedzi oznaczają, że narzędzie załadowało rdzeń. „No instruction” w którejkolwiek linii oznacza, że brakuje adaptera albo plik nie leży na ścieżce wykrywania danego narzędzia.

Konwersja kodu legacy ze skąpą dokumentacją

Starszy projekt wymaga przed krokiem 3 dwóch dodatkowych przejść: mapy tego, co naprawdę istnieje, i planu, który stawia testy przed refaktoryzacją. Oba przeprowadź z agentem, a wynik porównaj z kodem.

Prompt do skopiowania: audyt kodu legacy

Audit this codebase and write the report to docs/agent-audit.md with five sections:
1. Architecture: the real module boundaries and data flow, not the intended ones. Cite
   the files that prove each boundary.
2. Stack: frameworks and versions from the manifests, flagging any that are end-of-life
   or a major version behind.
3. Risks: concrete files with missing input validation, N+1 queries, or shared mutable
   state, cited by path and line.
4. Test gaps: which critical paths (payments, auth, data writes) have no tests, based on
   what the test files actually import.
5. Fix order: a list ordered by risk and effort.
Cite a file path for every claim. Do not propose a rewrite. Do not edit any source file.

Prompt do skopiowania: plan konwersji w fazach

Using docs/agent-audit.md, write a three-phase conversion plan as a checklist in
docs/agent-conversion-plan.md.
Phase 1: context. AGENTS.md, the Claude Code adapter, and path-scoped rules, one task
per area.
Phase 2: characterization tests that pin the current behaviour of the highest-risk
untested paths from the audit, so later refactors have an oracle.
Phase 3: refactors, smallest blast radius first, each an independent task that one agent
can complete in one pull request.
For every task, list the files it touches, the command that proves it is done, and
whether a human must approve it before merge.

Najpierw wdróż fazę 1, żeby każde kolejne zadanie z niej korzystało. Fazę 2 najłatwiej pominąć: bez testów charakteryzacyjnych refaktoryzacja w fazie 3 nie ma wyroczni i wracasz do czytania każdego diffa. Gdy faza 2 jest gotowa, rozdziel niezależne zadania fazy 3 między zadania w chmurze Codeksa, sesje Claude Code w osobnych worktree lub w wersji webowej (claude.ai/code) albo Cloud Agents w Cursorze. Migrację trwającą kilka kwartałów prowadź jako program: zobacz modernizację legacy z agentami.

Udowodnij, że konwersja zadziałała, bez czytania każdego diffa

Przekonwertowane repozytorium to takie, w którym agenci zachowują się inaczej, a nie takie, w którym istnieją pliki. Weryfikuj na dwóch poziomach.

Deterministyczne kontrole przy każdym pull requeście. Nie potrzebują modelu i nie da się ich przegadać. Pierwsza zawodzi, gdy AGENTS.md wymienia skrypt, którego package.json nie definiuje. Liczy tylko polecenia w blokach kodu inline, więc proza w rodzaju „pnpm only.” nie może zablokować CI, i pomija flagi takie jak --filter czy -w po nazwie menedżera pakietów. Nazwa skryptu nie mówi jednak nic o menedżerze pakietów: npm test przechodzi kontrolę nazw, o ile istnieje skrypt test. Dlatego ostatnia część osobno zawodzi, gdy istnieje pnpm-lock.yaml, a blok kodu inline zaczyna się od npm lub yarn. Przetestowana w Node.js 22 dnia 2026-09-26 na przykładowym AGENTS.md powyżej, z błędną nazwą skryptu i z npm test w repozytorium opartym na pnpm.

// scripts/check-agents-commands.mjs: run from the repository root in CI
import { existsSync, readFileSync } from 'node:fs';

const scripts = Object.keys(JSON.parse(readFileSync('package.json', 'utf8')).scripts ?? {});
const doc = readFileSync('AGENTS.md', 'utf8');
// Only commands inside `code spans` count, so prose such as "pnpm only." is ignored.
const named = [...doc.matchAll(/`(?:npm|pnpm|yarn|bun) (?:run )?([\w:-]+)[^`]*`/g)].map((m) => m[1]);
const builtins = new Set(['i', 'install', 'ci', 'add', 'remove', 'update', 'exec', 'dlx', 'x', 'create', 'init']);
const unique = [...new Set(named)];
// Skip flags such as `pnpm --filter api build` or `npm run -w web test`.
const missing = unique.filter((s) => !s.startsWith('-') && !builtins.has(s) && !scripts.includes(s));
// Script names say nothing about the package manager, so check the lockfile separately.
const wrongManager = existsSync('pnpm-lock.yaml')
  ? [...doc.matchAll(/`((?:npm|yarn) [^`]*)`/g)].map((m) => m[1])
  : [];

if (missing.length) console.error(`AGENTS.md names scripts that package.json does not define: ${missing.join(', ')}`);
if (wrongManager.length) console.error(`pnpm-lock.yaml exists, but AGENTS.md says: ${wrongManager.join(', ')}`);
if (missing.length || wrongManager.length) process.exit(1);
console.log(`AGENTS.md commands OK (${unique.length} checked)`);

Dodaj go do tego samego zadania (job) CI, które uruchamia polecenie kontrolne, obok kontroli adapterów i rozmiaru ze strony wspólnych reguł agentów. Przy wyzwalaczu pull_request GitHub uruchamia plik workflow i ten skrypt z samego pull requesta, więc pull request może osłabić kontrolę w tym samym diffie, w którym zmienia AGENTS.md; obejmij /.github/, scripts/ i AGENTS.md plikiem CODEOWNERS i wymagaj recenzji właściciela kodu, zanim uznasz ją za bramkę.

Karta wyników pilotażu na zgłoszeniach z punktu odniesienia. Powtórz trzy zgłoszenia z kroku 1 w nowych sesjach i wypełnij jeden wiersz na zgłoszenie i narzędzie. Dwa poniższe wiersze ilustrują format, nie są wynikami pomiarów:

Zgłoszenie	Narzędzie	Sam uruchomił polecenie kontrolne	Edytował tylko oczekiwane moduły	Kontrola zielona przy przekazaniu	Poprawki człowieka (przed → po)
SHOP-412	Claude Code	tak	tak	tak	4 → 1
SHOP-388	Codex	tak	nie (pages/checkout/)	tak	3 → 2

Zalecana przez nas reguła zatwierdzenia dla tech leada: każde narzędzie poprawnie odpowiada na prompt testowy, deterministyczne kontrole są zielone, a liczba poprawek spada w co najmniej dwóch z trzech zgłoszeń. Przebiegi agentów się różnią, więc jedno uruchomienie na zgłoszenie może samo zmienić tę liczbę: uruchom każde zgłoszenie trzy razy w każdym narzędziu i porównuj mediany. Trzy zgłoszenia to test dymny, a nie pomiar. Wiersz bez poprawy wskazuje brakującą konwencję; dopisz ją do AGENTS.md i powtórz tylko to jedno zgłoszenie.

Utrzymuj aktualny kontekst w CI

Nieaktualny plik kontekstu każe agentowi z pełnym przekonaniem robić coś złego, na przykład uruchamiać usunięty skrypt. Powyższa deterministyczna kontrola wyłapuje zepsute polecenia przy każdym pull requeście. Na wolniejszy dryf, na przykład zmienione nazwy katalogów albo wymienioną bibliotekę, uruchamiaj cykliczne odświeżanie, które otwiera pull request do zatwierdzenia przez człowieka.

Workflow dzieli pracę na dwa zadania. Zadanie z agentem ma klucz API, ale tylko prawo odczytu repozytorium. Zadanie tworzące pull request ma prawo zapisu, ale nigdy nie uruchamia agenta. Warunek if: w zadaniu z agentem sprawia, że działa ono tylko na gałęzi domyślnej, niezależnie od tego, czy uruchomił je harmonogram, czy człowiek, więc nigdy nie wykonuje kodu, hooków ani konfiguracji MCP kontrybutora, gdy sekret jest w środowisku. --strict-mcp-config dodatkowo pomija serwery MCP zadeklarowane w repozytorium.

.github/workflows/refresh-agent-context.yml

name: Refresh agent context
on:
  schedule:
    - cron: '0 6 * * 1' # Mondays 06:00 UTC
  workflow_dispatch:

permissions: {}

jobs:
  draft:
    # A manual run from another branch would load that branch's hooks and MCP config with the key set.
    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Let Claude Code correct AGENTS.md in place
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Pinned; bump deliberately after reading the changelog.
          npm install -g @anthropic-ai/claude-code@2.1.283
          claude -p "Compare AGENTS.md with the current repository. Edit AGENTS.md only where \
            a command, version, path or convention no longer matches the code. Change nothing else." \
            --permission-mode acceptEdits \
            --allowedTools "Read,Glob,Grep,Edit" \
            --disallowedTools "Bash" \
            --permission-prompts none \
            --strict-mcp-config \
            --max-budget-usd 2
          git diff -- AGENTS.md > context.patch
      - uses: actions/upload-artifact@v7
        with:
          name: context-patch
          path: context.patch

  open-pr:
    needs: draft
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/download-artifact@v8
        with:
          name: context-patch
      - name: Apply the proposed change
        run: |
          if [ -s context.patch ]; then git apply context.patch; fi
          rm context.patch
      - uses: peter-evans/create-pull-request@v8
        with:
          commit-message: 'docs: refresh AGENTS.md from the codebase'
          title: 'docs: refresh agent context'
          branch: chore/refresh-agent-context

--allowedTools z góry zatwierdza odczyt i edycję, --disallowedTools "Bash" odbiera dostęp do powłoki, --permission-prompts none odrzuca wszystko inne, co wymagałoby zgody, a --max-budget-usd ogranicza koszt jednego uruchomienia. Każda flaga w tym kroku, łącznie z --permission-mode i --strict-mcp-config, jest w claude --help dla v2.1.283. Aby zadanie ze szkicem działało z Codeksem, zastąp krok Claude Code akcją openai/codex-action@v1 z openai-api-key: ${{ secrets.OPENAI_API_KEY }}, permission-profile: ":workspace" i tym samym promptem. :read-only nie pozwala edytować plików, więc :workspace jest konieczny, ale w przeciwieństwie do kroku Claude Code pozwala też Codeksowi uruchamiać polecenia powłoki, więc oba zadania nie mają równych uprawnień. Krok z łatką nadal ogranicza wynik do AGENTS.md, bo do zadania tworzącego pull request trafia tylko git diff -- AGENTS.md. Więcej wzorców uruchamiania bez interfejsu znajdziesz w agentach headless w CI.

Nigdy nie pozwól zadaniu odświeżającemu wypychać zmian na gałąź główną

Pull request jest bramką recenzji. Człowiek zatwierdza każdą zmianę, bo agent potrafi z pełnym przekonaniem przepisać poprawną konwencję na błędną, a diff to jedyne miejsce, które to pokazuje. Pliki kontekstu są też kanałem instrukcji do każdej przyszłej sesji, więc recenzuj je z taką samą starannością jak konfigurację CI.

Co psuje się przy konwersji projektu dla agentów?

Agent ignoruje konwencje z AGENTS.md

Najczęstsze przyczyny to długość i położenie. Dokumentacja pamięci Claude Code zaleca, by każdy CLAUDE.md miał mniej niż 200 linii, bo dłuższe pliki obniżają stosowanie się do instrukcji, a Codex domyślnie obcina wszystko powyżej 32 KiB. Naprawa: ogranicz plik główny do poleceń, definicji ukończenia, granic i pułapek; reguły dla konkretnych ścieżek przenieś do reguł o ograniczonym zasięgu; usuń wszystko, co agent może wyczytać z kodu. Jeśli jedna reguła jest stale łamana, zamień ją na kontrolę lub hook zamiast dopisywać kolejne zdania. Zobacz przycinanie plików kontekstu.

Każde narzędzie zachowuje się inaczej przy tym samym zadaniu

Trzy narzędzia korzystające z trzech plików to objaw rozwidlonego kontekstu. Często zaczyna się to w dniu konwersji: /init i /import w Claude Code kopiują instrukcje innych narzędzi do CLAUDE.md, co jest przydatne raz, a potem staje się rozwidleniem. Naprawa: niech AGENTS.md będzie jedynym miejscem trwałych konwencji, ogranicz CLAUDE.md do @AGENTS.md i linii tylko dla Claude, ogranicz reguły Cursora do odnośników i uruchom prompt testowy we wszystkich trzech narzędziach.

Codex ignoruje AGENTS.md pakietu w monorepo

Codex czyta łańcuch od katalogu głównego repozytorium do katalogu, w którym wystartowała sesja. Inżynierowie, którzy uruchamiają Codeksa w katalogu głównym, nigdy nie ładują packages/api/AGENTS.md. Naprawa: uruchamiaj sesje w pakiecie (codex -C packages/api) albo przenieś reguły, które muszą obowiązywać zawsze, do pliku głównego.

Kontekst zestarzał się po refaktoryzacji

Jeśli agent proponuje dawny układ katalogów, plik kontekstu jest błędny. Naprawa: uruchom workflow odświeżający przez workflow_dispatch albo powtórz prompt generujący szkic, zrecenzuj pull request i od tej pory zmieniaj pliki kontekstu w tym samym pull requeście co zmianę struktury, którą opisują.

Refaktoryzacje z fazy 3 psują zachowanie, którego nikt nie testował

Plan pominął lub okroił fazę 2. Naprawa: wycofaj refaktoryzację, napisz testy charakteryzacyjne dla tej ścieżki, potwierdź, że przechodzą na starym kodzie, i ponownie uruchom zadanie refaktoryzacji na ich podstawie.

Lista kontrolna konwersji

Minimum dla projektu gotowego na agentów

• Istnieje jedno polecenie kontrolne (lint, typy, testy) i przechodzi na gałęzi głównej
• AGENTS.md wygenerowany z repozytorium, każde polecenie sprawdzone, linie TODO: confirm rozstrzygnięte
• CLAUDE.md zaczyna się od @AGENTS.md; reguły Cursora wskazują rdzeń zamiast go kopiować
• Wskazówki dla konkretnych ścieżek są w regułach o ograniczonym zasięgu, nie w pliku głównym
• Prompt testowy przechodzi w każdym narzędziu, którego używa zespół
• scripts/check-agents-commands.mjs działa w CI przy każdym pull requeście
• Ścieżki o najwyższym ryzyku i bez testów mają testy charakteryzacyjne przed jakąkolwiek refaktoryzacją
• Karta wyników pilotażu pokazuje mniej poprawek w co najmniej dwóch z trzech zgłoszeń
• Workflow odświeżający otwiera pull request i nigdy nie wypycha zmian na gałąź główną

Co dalej po konwersji projektu

• Transformacja przepływu pracy: przebuduj delegowanie i code review teraz, gdy repozytorium je wspiera
• Jak pomóc zespołowi przestać czytać każdy diff: przestaw recenzentów z czytania linia po linii na dowody, które umożliwia ta konwersja
• Wspólne reguły agentów: pełne omówienie adapterów i testów ładowania dla każdego narzędzia
• Współpraca zespołowa: wspólny kontekst i reguły: utrzymaj przekonwertowany kontekst w dobrym stanie, gdy zmienia go osiem osób
• Przejście między Codeksem, Cursorem i Claude Code: pracuj we wszystkich trzech narzędziach według jednego zestawu konwencji
• Playbooki wdrożenia zespołowego: pozostałe przewodniki wdrożeniowe