# Jedno źródło reguł dla każdego agenta: AGENTS.md, Ruler i rulesync

URL: https://developertoolkit.ai/pl/ecosystem/frameworks/rules-sync/
Description: Jeden zestaw reguł dla Claude Code, Codeksa i Cursora: import AGENTS.md, Ruler, rulesync i zadanie CI, które wykrywa rozjazd plików.

Synchronizacja reguł to utrzymywanie jednego źródła instrukcji, które czytają agenci, tak aby Claude Code, Codex i Cursor używali tych samych komend budowania i tych samych konwencji. Przy zwykłych regułach wystarczy `AGENTS.md` importowany z jednolinijkowego `CLAUDE.md`. Ruler i rulesync generują plik każdego agenta z jednego źródła, gdy synchronizujesz też serwery MCP, skille albo więcej agentów.

Twoje repozytorium ma 140-linijkowy `CLAUDE.md`, o który dbają użytkownicy Claude Code, `AGENTS.md` napisany wiosną dla Codeksa i katalog `.cursor/rules/`, którego nikt od dawna nie otwierał. W zeszłym tygodniu komenda testów zmieniła się z `npm test` na `pnpm test:unit`. Poprawkę dostał tylko `CLAUDE.md`, więc sesje Codeksa i Cursora nadal uruchamiają starą komendę, dostają błąd i „naprawiają” go po swojemu.

Ta strona jest dla programisty albo tech leada, który odpowiada za konfigurację agentów w takim repozytorium. Zakłada, że wiesz już, co powinno trafić do pliku reguł (zob. [AGENTS.md i CLAUDE.md: zwięzły kontekst repozytorium](/pl/developer-scorecard-guide/claude-md-context/)). Najpierw pokazuje konfigurację bez żadnego narzędzia, potem rulesync i Rulera z komendami, które uruchomiliśmy 2026-09-26, a na końcu zadanie CI, które blokuje pull request, gdy wygenerowane pliki rozjadą się ze źródłem.

**Wersje na tej stronie**

Sprawdzone 2026-09-26: Claude Code 2.1.283 (kanał `latest`) i dokumentacja pamięci Claude Code; codex-cli 0.157.1 i kod źródłowy `openai/codex` z tego samego dnia; `rulesync` 21.0.0 i `@intellectronica/ruler` 0.3.44 z npm. Oba narzędzia uruchomiliśmy w testowym repozytorium Git: w rulesync `import`, `generate`, `generate --check` i `generate --delete`, w Rulerze `init` i `apply`. Każdy „zaobserwowany” wynik poniżej pochodzi z tych przebiegów. Strona cursor.com była tego dnia niedostępna; to, co ta strona mówi o wczytywaniu `AGENTS.md` przez Cursora, pochodzi z dokumentacji Cursora sprawdzonej 2026-10-12.

## Co daje jedno źródło reguł

- Tabelę, który plik czyta każdy agent, łącznie z regułą Claude Code, na której potyka się większość zespołów: `AGENTS.md` jest pomijany, gdy istnieje `CLAUDE.md`.
- Konfigurację bez zależności: `AGENTS.md` plus jednolinijkowy import `@AGENTS.md`.
- Pełną migrację na rulesync: `import` → edycja → `generate --targets claudecode,codexcli,cursor`.
- Odpowiednik w Rulerze i domyślne ustawienie, które ukrywa jego wynik przed Gitem.
- Zadanie GitHub Actions, które blokuje pull request, gdy ktoś ręcznie zmieni wygenerowany plik.
- Miejsce, w które u każdego agenta trafia reguła zawężona ścieżką, łącznie z jedynym agentem, który gubi zakres.
- Trzy prompty do skopiowania: scalenie rozproszonych reguł w jeden plik, migracja repozytorium na rulesync i dowód, że każdy agent wczytał reguły.

## Który plik z regułami czyta każdy agent?

Każdy agent ma swój natywny plik. Problem synchronizacji bierze się właśnie z tych różnic.

| Agent | Natywny plik | Czyta `AGENTS.md`? | Szczegół, który ma znaczenie |
| ----- | ------------ | ------------------ | ---------------------------- |
| Claude Code | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` | Tylko gdy żaden z tych trzech plików nie istnieje w katalogu roboczym ani wyżej (v2.1.277; oba kanały wydań na 2026-10-12) | Gdy są oba pliki, Claude Code czyta tylko `CLAUDE.md`, chyba że zaimportujesz z niego `AGENTS.md` |
| Codex | `AGENTS.md` | Tak, natywnie | Od 0.150.0 niezaufany projekt nie dostarcza swojego `AGENTS.md`; `project_doc_max_bytes` ma w kodzie Codeksa domyślnie 32768 bajtów (32 KiB), a treść ponad limit jest ucinana |
| Cursor | Reguły projektu w `.cursor/rules/` | Tak, w katalogu głównym projektu i w podkatalogach, a `CLAUDE.md` czyta tak samo (dokumentacja Cursora, sprawdzone 2026-10-12) | rulesync zapisuje `.cursor/rules/overview.mdc`; Ruler dla identyfikatora `cursor` zapisuje tylko `AGENTS.md` |

Trzy szczegóły z dokumentacji pamięci Claude Code zmieniają konfigurację:

- **Domyślnie działa zasada „albo, albo”.** Ustawienie **Project instructions** w `/config` ma domyślnie wartość `claude-md-or-agents-md`. `claude-md-and-agents-md` wczytuje oba pliki, `claude-md` ignoruje `AGENTS.md`, a `managed-only` pomija wszystkie pliki projektu.
- **Repozytorium nie przełączy tego ustawienia za zespół.** Wartość trafia pod wpis wbudowanej wtyczki `agents-md` w `pluginConfigs`, a Claude Code ignoruje ją w ustawieniach projektu i ustawieniach lokalnych. Czyta ją z `~/.claude/settings.json`, z pliku `--settings` albo z ustawień zarządzanych.
- **Obsługa `AGENTS.md` zależy od wersji Claude Code.** Wymaga v2.1.277, a w sesjach przez Amazon Bedrock, Google Cloud, Foundry, bramki LLM i z wyłączoną telemetrią v2.1.281. Oba kanały wydań ją mają, odkąd `stable` doszedł do v2.1.287 (sprawdzone 2026-10-12). Osoba z zespołu na starszej wersji nie dostaje w ogóle zastępczego wczytania `AGENTS.md`; dociera do niej tylko import.

Samo `AGENTS.md` wystarcza więc repozytorium, które nie ma `CLAUDE.md`, i zespołowi, w którym każdy ma Claude Code w wersji v2.1.277 lub nowszej (v2.1.281 u dostawców chmurowych). We wszystkich innych przypadkach użyj importu.

## Czy w ogóle potrzebujesz narzędzia do synchronizacji?

Zacznij od najmniejszej konfiguracji, która obsłuży twoich agentów, a generator dodaj dopiero wtedy, gdy pasuje któryś wiersz poniżej.

| Twoja sytuacja | Użyj | Dlaczego |
| -------------- | ---- | -------- |
| Claude Code i Codex, zwykłe reguły w Markdownie | `AGENTS.md` + `@AGENTS.md` w `CLAUDE.md` | Nie ma generatora, o którego uruchomieniu można zapomnieć; jeden plik, dwóch agentów |
| Potrzebujesz też plików `.cursor/rules/*.mdc` dla Cursora, reguł zawężonych globami albo pliku instrukcji Copilota | rulesync | Zapisuje natywny format reguł każdego narzędzia z jednego źródła |
| Chcesz mieć te same serwery MCP, skille, subagentów, hooki albo uprawnienia w każdym agencie | rulesync | Jego funkcje obejmują `rules`, `mcp`, `subagents`, `commands`, `skills`, `hooks`, `permissions` |
| Pięciu lub więcej agentów, reguły jako sklejany Markdown, minimum konfiguracji | Ruler | Ponad 30 identyfikatorów agentów; jeden katalog plików Markdown sklejany do pliku każdego agenta |
| Tylko jeden agent | Jego natywny plik | Warstwa synchronizacji dokłada ruchomą część i nic nie daje |

## Udostępnij AGENTS.md Claude Code przez import

Tę konfigurację wypróbuj najpierw. `AGENTS.md` jest źródłem prawdy, a `CLAUDE.md` to jedna linijka plus to, czego potrzebuje wyłącznie Claude Code.

1. Przenieś wspólne reguły do `AGENTS.md` w katalogu głównym repozytorium. Trzymaj tam komendy budowania i testów, konwencje oraz reguły typu „nigdy nie rób X”. Scalanie wykona za ciebie prompt pod tymi krokami.

2. Zastąp `CLAUDE.md` importem:

   ```markdown
   @AGENTS.md

   ## Claude Code only
   - Use the Explore subagent before editing more than three files.
   ```

   Claude Code rozwija importy `@path` przy starcie: najpierw czyta importowany plik, potem resztę `CLAUDE.md`. Ścieżki względne liczą się od pliku, który zawiera import, a importy zagnieżdżają się maksymalnie na cztery poziomy. `@path` w backtickach albo w bloku kodu zostaje zwykłym tekstem.

3. Sprawdź, czy każdy agent wczytał reguły.

     **Claude Code**

       Uruchom nową sesję, wpisz `/context` i sprawdź, czy `CLAUDE.md` jest w sekcji **Memory files**. Import nigdy nie wczyta `AGENTS.md` dwa razy, niezależnie od wartości **Project instructions**.

     **Codex**

       Upewnij się, że projekt jest zaufany, bo niezaufany projekt nie dostarcza swojego `AGENTS.md` (0.150.0). Potem uruchom poniższy prompt weryfikacyjny w nowej sesji.

     **Cursor**

       Cursor obsługuje `AGENTS.md` w katalogu głównym projektu i w podkatalogach, łączy zagnieżdżone pliki z plikami katalogów nadrzędnych (bardziej szczegółowe instrukcje mają pierwszeństwo) i czyta `CLAUDE.md` tak samo (dokumentacja Cursora, sprawdzone 2026-10-12). Uruchom poniższy prompt weryfikacyjny w nowym czacie Agenta. Jeśli odpowiedź nie cytuje twoich reguł, wygeneruj `.cursor/rules/` za pomocą rulesync, jak w następnej sekcji.

**Prompt do skopiowania: scal rozproszone reguły w jeden AGENTS.md**

```text
Read CLAUDE.md, AGENTS.md, every file under .cursor/rules/ and .github/copilot-instructions.md if they exist.
Produce one AGENTS.md at the repository root that:
- keeps every rule that applies to all agents, deduplicated;
- resolves conflicts by checking package.json scripts and CI config, and lists each conflict you resolved with the evidence;
- puts build, test, lint and typecheck commands first, exactly as CI runs them;
- stays under 150 lines;
- leaves out anything that names one tool's features (subagents, slash commands, Cursor modes) and lists those lines separately at the end of your reply.
Do not delete the old files. Show me the diff of AGENTS.md only.
```

Dowiązanie symboliczne (`ln -s AGENTS.md CLAUDE.md`) też działa, ale według dokumentacji Claude Code ma dwa koszty: narzędzia Edit i Write odmawiają zapisu przez dowiązanie, a klon na Windowsie bez `core.symlinks` dostaje zamiast niego jednolinijkowy plik tekstowy. W zespole z różnymi systemami wybierz import.

## Synchronizuj reguły do każdego agenta za pomocą rulesync

rulesync trzyma źródło w `.rulesync/` i zapisuje natywne pliki każdego narzędzia. Ten przykład migruje repozytorium, którego reguły są dziś w `CLAUDE.md` i `.claude/rules/`, ścieżką `import` → edycja → `generate`.

1. Zainstaluj rulesync i przypnij wersję. Pakiet nazywa się `rulesync`, a identyfikatory celów to `claudecode`, `codexcli` i `cursor`, nie `claude` ani `codex`.

   ```bash
   npm install -g rulesync@21.0.0
   # or: brew tap dyoshikawa/rulesync https://github.com/dyoshikawa/rulesync && brew install rulesync
   ```

   Instalacja jest taka sama dla każdego agenta; rulesync i Ruler to samodzielne CLI, a nie wtyczki.

   rulesync opublikował wersje główne 18, 19, 20 i 21 między 2026-09-24 a 2026-09-26 (rejestr npm), więc nieprzypięte `npx rulesync` może zmienić wynik między dwoma przebiegami CI.

2. Zaimportuj to, co już masz. W repozytorium, które ma już reguły, pomiń `rulesync init` (zob. ostrzeżenie pod krokami).

   ```bash
   rulesync import --targets claudecode
   mv .rulesync/rules/CLAUDE.md .rulesync/rules/overview.md
   ```

   Zaobserwowaliśmy, że `import` kopiuje `CLAUDE.md` do `.rulesync/rules/CLAUDE.md` jako regułę główną, a każdy plik `.claude/rules/*.md` do osobnej reguły. Zmiana nazwy jest opcjonalna; bez niej plik dla Cursora nazywa się `CLAUDE.mdc`.

3. Napisz minimalny `rulesync.jsonc` w katalogu głównym repozytorium, żeby każda kolejna komenda, łącznie z testem w CI, obywała się bez flag:

   ```jsonc
   {
     "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
     "targets": ["claudecode", "codexcli", "cursor"],
     "features": ["rules"],
     "delete": false
   }
   ```

   `"delete": false` nie pozwala rulesync usuwać plików, których sam nie zapisał. Dodaj `"mcp"` do `features`, gdy `.rulesync/mcp.jsonc` będzie zawierał twoje serwery. Cursor czyta `AGENTS.md` i `CLAUDE.md` bezpośrednio (dokumentacja Cursora, sprawdzone 2026-10-12), więc cel `cursor` zapisuje kopię w Rules tekstu, który Cursor już czyta: zostaw `cursor` w `targets` dla reguł tylko dla Cursora lub z `globs`, a usuń go, gdy takich nie masz.

4. Edytuj źródło. Reguła główna po zmianie nazwy wygląda tak:

   ```markdown
   ---
   root: true
   targets: ["*"]
   description: "Project overview, commands and hard rules"
   globs: ["**/*"]
   ---

   # Commands
   - Install: `pnpm install --frozen-lockfile`
   - Test: `pnpm test:unit` (CI runs exactly this)
   - Typecheck: `pnpm typecheck`

   # Hard rules
   - Never bind a `Date` to D1; convert to an ISO string first.
   - Every pull request links an issue and lists the commands you ran.
   ```

   `targets: ["*"]` wysyła regułę do każdego narzędzia; lista identyfikatorów ją zawęża. Blok we frontmatterze, np. `cursor: { alwaysApply: true }`, przekazuje opcję do formatu jednego narzędzia (dokumentacja formatów plików rulesync).

5. Wygeneruj natywne pliki, jeśli chcesz, najpierw z podglądem:

   ```bash
   rulesync generate --dry-run
   rulesync generate
   ```

   Zaobserwowany wynik: `CLAUDE.md`, `AGENTS.md` i `.cursor/rules/overview.mdc`, plus po jednym pliku na każdą regułę niegłówną (tabela niżej). rulesync wypisuje tylko pliki, których treść się zmieniła, więc zaraz po `import` pliki Claude Code mogą nie pojawić się na liście. `rulesync doctor` sprawdza konfigurację w trybie tylko do odczytu.

6. Zacommituj razem `.rulesync/`, `rulesync.jsonc` i wygenerowane pliki. Zacommitowany wynik widzą zadania Codex w chmurze, boty do review i świeży klon, bez uruchamiania rulesync.

**rulesync init i --delete usuwają ręcznie pisane reguły**

`rulesync init` (21.0.0) tworzy `rulesync.jsonc` z `"delete": true`, celami `codexcli`, `claudecode` i `opencode` (bez `cursor`) oraz przykładowy `.rulesync/rules/overview.md` z ogólnikowymi wytycznymi. W naszym teście `init`, a po nim `import`, dokleiły ten przykład do wygenerowanego `CLAUDE.md`, a `rulesync doctor` nie zgłosił problemu. `generate --delete` albo `"delete": true` usunęły ręcznie napisane `.claude/rules/billing.md` i `.cursor/rules/legacy.mdc`, których rulesync nie zaimportował. Najpierw importuj, potem sam napisz konfigurację.

### Gdzie u każdego agenta trafia reguła zawężona ścieżką?

Reguła główna wczytuje się wszędzie. Agenci różnią się przy regule niegłównej z `globs`, a tego szczegółu README rulesync nie rozpisuje. Wygenerowaliśmy taką regułę i przeczytaliśmy wynik:

```markdown
---
root: false
targets: ["*"]
globs: ["src/billing/**"]
---
Billing: amounts are integer cents.
```

| Agent | Zaobserwowany wynik (rulesync 21.0.0) | Czy zakres zostaje? |
| ----- | ------------------------------------- | ------------------- |
| Claude Code | `.claude/rules/billing.md` z `paths: [src/billing/**]` | Tak: wczytuje się, gdy Claude czyta pasujący plik |
| Cursor | `.cursor/rules/billing.mdc` z `globs: src/billing/**` | Zakres jest w pliku; reguły projektu to pliki `.mdc` w `.cursor/rules` z frontmatterem `description`, `globs` i `alwaysApply`, a stosowane są tylko w czacie Agenta (dokumentacja Cursora, sprawdzone 2026-10-12) |
| Codex | Treść reguły doklejona do głównego `AGENTS.md` | Nie: wczytuje ją każda sesja Codeksa i liczy się do budżetu 32 KiB |

Każda reguła zawężona ścieżką kosztuje więc Codeksa kontekst w każdej sesji. Dla monorepo dokumentacja formatów plików rulesync opisuje opcję `agentsmd.subprojectPath`, która zapisuje osobny, zagnieżdżony `AGENTS.md` dla każdego pakietu; tej opcji nie uruchamialiśmy.

Co dostaje każdy agent i jak to potwierdzić:

**Claude Code**

    `CLAUDE.md` w katalogu głównym i reguły zawężone w `.claude/rules/`. Skoro `CLAUDE.md` istnieje, domyślny tryb **Project instructions** ignoruje wygenerowany `AGENTS.md`, więc reguły wczytują się raz. Potwierdź przez `/context` w sekcji **Memory files**. Nie przełączaj tu na `claude-md-and-agents-md`: te same reguły wczytałyby się dwa razy.

**Codex**

    `AGENTS.md` w katalogu głównym, czyli natywny plik Codeksa, z doklejonymi regułami zawężonymi. Trzymaj go poniżej domyślnego limitu `project_doc_max_bytes` wynoszącego 32 KiB (`wc -c AGENTS.md`) i oznacz projekt jako zaufany, żeby Codex go przeczytał.

**Cursor**

    `.cursor/rules/overview.mdc` i po jednym `.mdc` na każdą regułę zawężoną. Otwórz nowy czat Agenta i uruchom poniższy prompt weryfikacyjny.

**Prompt do skopiowania: przenieś to repozytorium na rulesync**

```text
Migrate this repository's agent rules to rulesync 21.0.0 without losing any rule.
1. List every existing rules file: CLAUDE.md, .claude/rules/*, AGENTS.md, .cursor/rules/*.
2. Run `npx -y rulesync@21.0.0 import --targets claudecode`. Do not run `rulesync init`.
3. Rename .rulesync/rules/CLAUDE.md to overview.md.
4. Create rulesync.jsonc with targets claudecode, codexcli, cursor; features rules; "delete": false.
5. Diff AGENTS.md and every .cursor/rules file against .rulesync/rules/. Any rule that exists only there: add it to the right .rulesync rule and tell me which one.
6. Run `npx -y rulesync@21.0.0 generate`, then `npx -y rulesync@21.0.0 generate --check`.
7. Show me `git status` and `git diff --stat`. Do not commit.
Stop and ask before deleting any file.
```

**Prompt do skopiowania: udowodnij, że agent wczytał wspólne reguły**

```text
Without opening any file, answer from the instructions you were given at session start:
1. Which file or files did your project instructions come from?
2. What is the exact command to run the unit tests?
3. Quote the rule about binding values to D1 word for word.
If you do not have an answer from your loaded instructions, say "not loaded" rather than reading the repository.
```

Drugi prompt uruchamiaj w świeżej sesji każdego agenta po każdej zmianie reguł. Agent, który odpowiada „not loaded” albo najpierw czyta plik, nie dostał reguł przy starcie.

## Synchronizuj reguły Rulerem

Ruler skleja Markdown z `.ruler/` i zapisuje go do pliku każdego agenta. Pakiet to `@intellectronica/ruler`; `ruler` w npm to niezwiązana biblioteka asercji, ostatnio wydana w 2013 roku.

```bash
npm install -g @intellectronica/ruler@0.3.44   # Node.js ^20.19, ^22.12 or >=23 (package engines)
ruler init                                     # creates .ruler/AGENTS.md and .ruler/ruler.toml
ruler apply --agents claude,codex,cursor       # writes CLAUDE.md and AGENTS.md, and edits .gitignore
ruler revert                                   # restores .bak files and removes generated files
```

Identyfikatory agentów w Rulerze to `claude`, `codex` i `cursor`, więc komenda rulesync wklejona do Rulera nie zadziała, i odwrotnie.

**Ruler domyślnie ukrywa swój wynik przed Gitem**

`ruler apply` dopisuje do `.gitignore` blok `# START Ruler Generated Files` z `/AGENTS.md`, `/CLAUDE.md` i `/.codex/config.toml`. Klon, w którym nikt nie uruchomił Rulera, zadanie Codex w chmurze i recenzent PR nie widzą wtedy żadnych reguł. Żeby commitować wynik, uruchom `ruler apply --no-gitignore` albo ustaw `enabled = false` w sekcji `[gitignore]` pliku `.ruler/ruler.toml`.

Przed wdrożeniem warto znać jeszcze dwa zachowania. Ruler czyta `AGENTS.md` z katalogu głównego repozytorium jako pierwszy, przed `.ruler/AGENTS.md`, więc wygenerowany główny `AGENTS.md` wraca do źródła przy następnym `apply`, jeśli nie jest ignorowany. Ostatnie wydanie w npm to 0.3.44 z 2026-06-30, choć do repozytorium trafił commit 2026-09-23.

## Ruler czy rulesync?

| | rulesync 21.0.0 | Ruler 0.3.44 |
| - | --------------- | ------------ |
| Źródło | `.rulesync/` + `rulesync.jsonc` | `.ruler/*.md` + `ruler.toml` |
| Identyfikatory Claude Code / Codex / Cursor | `claudecode`, `codexcli`, `cursor` | `claude`, `codex`, `cursor` |
| Wynik dla Cursora | `.cursor/rules/*.mdc` | `AGENTS.md` |
| Poza regułami | MCP, skille, subagenci, komendy, hooki, uprawnienia | MCP, skille, subagenci |
| Domyślnie w Gicie | Decydujesz ty; `rulesync gitignore` dodaje wpisy na żądanie | Dodaje wygenerowane pliki do `.gitignore` |
| Reguły zawężone | Natywnie w każdym narzędziu; dla Codeksa doklejane do `AGENTS.md` | Sklejane do jednego pliku każdego agenta |
| Wykrywanie rozjazdu | `generate --check`, kod wyjścia 1 przy rozjeździe (uruchomiliśmy) | Brak flagi w `apply --help`; użyj `git diff` |
| Tempo wydań | Cztery wersje główne w trzy dni (wrzesień 2026) | Ostatnie wydanie w npm 2026-06-30 |

Popularność na 2026-09-26 (GitHub search API, nasz przegląd): agentsmd/agents.md ma 24 617 gwiazdek, intellectronica/ruler 2934, dyoshikawa/rulesync 1474. Strona agents.md podaje, że format jest „used by over 60k open-source projects”. Oba narzędzia do synchronizacji rozwija jedna osoba; gwiazdki mierzą zainteresowanie, a nie niezawodność.

## Blokuj pull request, gdy reguły się rozjadą

Generator pomaga tylko wtedy, gdy nikt ręcznie nie edytuje jego wyniku. To zadanie uruchamia się przy każdym pull requeście, który dotyka reguł, i kończy się błędem, gdy zacommitowane pliki różnią się od tego, co generuje źródło. Używa wyzwalacza `pull_request`, nie ma żadnych sekretów i potrzebuje tylko prawa odczytu.

```yaml
# .github/workflows/rules-drift.yml
name: rules-drift
on:
  pull_request:
    paths:
      - ".rulesync/**"
      - "rulesync.jsonc"
      - "CLAUDE.md"
      - "AGENTS.md"
      - ".claude/rules/**"
      - ".cursor/rules/**"
      - ".github/workflows/rules-drift.yml"
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Generated rules match .rulesync/
        run: npx -y rulesync@21.0.0 generate --check
```

`--check` bierze cele i funkcje z `rulesync.jsonc`, niczego nie zapisuje i kończy się kodem 1, gdy wygenerowany plik by się zmienił. W naszym teście jedna linijka dopisana ręcznie do `AGENTS.md` dała komunikat `Files are not up to date. Run 'rulesync generate' to update.` i kod wyjścia 1; nietknięte repozytorium dało `✓ All files are up to date.` i kod 0.

Jeśli ustawisz to zadanie jako wymagany check, usuń filtr `paths:`: GitHub zostawia wymagany check w stanie oczekiwania na każdym pull requeście pominiętym przez filtr, a takiego pull requesta nie da się scalić.

Dla czytelności przykład przypina `actions/checkout` i `actions/setup-node` tagiem `v7`. Tag można przesunąć, więc na chronionej gałęzi przypnij każdą akcję pełnym SHA commita, z wersją w komentarzu na końcu linii.

Drugi wzorzec działa z każdym generatorem, także z Rulerem. To nasza propozycja, a nie funkcja któregokolwiek z narzędzi: wygeneruj pliki ponownie i pozwól rozstrzygnąć Gitowi.

```yaml
      - name: Generated rules match the source (git variant)
        run: |
          npx -y rulesync@21.0.0 generate
          git diff --exit-code -- CLAUDE.md AGENTS.md .claude/rules .cursor/rules
          test -z "$(git status --porcelain -- CLAUDE.md AGENTS.md .claude/rules .cursor/rules)"
```

Ostatnia linia łapie nowy, nieśledzony wygenerowany plik, którego sam `git diff` nie widzi. Dla Rulera zastąp pierwszą linię komendą `npx -y @intellectronica/ruler@0.3.44 apply --agents claude,codex,cursor --no-gitignore`. Dodaj wpis w `CODEOWNERS` dla `.rulesync/` (albo `.ruler/`), żeby właściciel reguł zatwierdzał każdą zmianę źródła, oraz wpis dla `.github/workflows/rules-drift.yml`: przy `pull_request` GitHub uruchamia workflow z merge refa pull requesta, więc bez tej recenzji pull request mógłby zmienić samą kontrolę.

## Skąd wiesz, że agenci stosują zsynchronizowane reguły?

Zielony test rozjazdu dowodzi, że pliki się zgadzają. Nie dowodzi, że którykolwiek agent ich przestrzega. Sprawdzaj zachowanie w trzech warstwach, od najtańszej:

1. **Test wczytania.** Prompt weryfikacyjny powyżej, w świeżej sesji każdego agenta, po każdej zmianie reguł. Uruchamia go właściciel reguł i wkleja trzy odpowiedzi do pull requesta.
2. **To, co ważne, egzekwuj w kodzie, nie w prozie.** Reguły to kontekst, a nie egzekwowanie; dokumentacja pamięci Claude Code nazywa je wprost „context rather than enforced configuration”. „Testy muszą przechodzić” wstaw do CI i hooka pre-commit; tekst reguły zostaw jako wyjaśnienie.
3. **Zmierz zmianę reguł, zanim ją wdrożysz.** Uruchom stały zestaw zadań na starych i nowych regułach i porównaj odsetek zaliczonych, jak w [ewaluacji zmian w CLAUDE.md](/pl/ecosystem/observability/evals-coding-agents/).

Tech lead zatwierdza zmianę źródła; CI zatwierdza wygenerowane pliki.

## Ile kontekstu kosztuje wspólny plik reguł?

Każda linijka głównego pliku reguł trafia do każdej sesji każdego agenta przed pierwszym promptem. Dokumentacja Claude Code zaleca poniżej 200 linijek na `CLAUDE.md`, bo dłuższe pliki zużywają więcej kontekstu i obniżają przestrzeganie reguł. Codex ucina dokumentację projektu na `project_doc_max_bytes` (w kodzie domyślnie 32768 bajtów), więc traci reguły z końca długiego wygenerowanego `AGENTS.md`, czyli dokładnie stamtąd, gdzie rulesync dokleja reguły zawężone. Importy nie zmniejszają kosztu: `@AGENTS.md` wczytuje się przy starcie tak samo jak sam plik. Narzędzie do synchronizacji oszczędza duplikację, nie tokeny. Żeby ograniczyć tokeny w Claude Code i Cursorze, przenieś reguły dla konkretnych typów plików do reguł zawężonych globami (`globs:` w rulesync); w Codeksie użyj zagnieżdżonych plików `AGENTS.md`, które Codex skleja od katalogu głównego projektu w dół do katalogu, w którym startuje (kod źródłowy Codeksa, 2026-09-26). Potem skorzystaj z poradnika [odchudzania plików kontekstu](/pl/workflows/context/pruning-context-files/).

**Pułapki ze starych poradników (sprawdzone 2026-09-26)**

- **„Claude Code ignoruje AGENTS.md”** jest nieaktualne od v2.1.277. Odwrotne twierdzenie też jest błędne: gdy istnieje `CLAUDE.md`, Claude Code domyślnie czyta tylko `CLAUDE.md`.
- **Nazwy pakietów.** Ruler to `@intellectronica/ruler`; `ruler` w npm to coś innego. `agents-md` w npm to zewnętrzne narzędzie niezwiązane z projektem agentsmd, a pakiet `agentsmd` w npm nie istnieje.
- **Identyfikatory celów.** rulesync używa `claudecode` i `codexcli`; Ruler używa `claude` i `codex`.
- **`CLAUDE.local.md` liczy się jako `CLAUDE.md`.** Dodanie prywatnego pliku do repozytorium opartego tylko na `AGENTS.md` po cichu wyłącza ci wczytywanie `AGENTS.md` w Claude Code.
- **`rulesync gitignore` zawsze dopisuje wpisy dla `AGENTS.md`**, niezależnie od celów, jak podaje jego przewodnik konfiguracji. Uruchamiaj go tylko wtedy, gdy świadomie nie commitujesz wygenerowanych plików.

## Co się psuje przy synchronizacji reguł między agentami?

**Codex stosuje stare reguły po edycji.** Objaw: `AGENTS.md` się zmienił, a Codex uruchamia starą komendę testów. Przyczyna: ktoś zmienił `CLAUDE.md` albo źródło i nie wygenerował plików ponownie, albo projekt jest w Codeksie niezaufany. Naprawa: uruchom `rulesync generate`, zacommituj, dodaj zadanie wykrywające rozjazd i oznacz projekt jako zaufany.

**Claude Code ignoruje `AGENTS.md` u jednej osoby.** Objaw: prompt weryfikacyjny odpowiada „not loaded” tylko na jednym komputerze. Przyczyna: `CLAUDE.local.md` albo `.claude/CLAUDE.md` na ścieżce, wersja Claude Code starsza niż v2.1.277 albo **Project instructions** ustawione na `claude-md`. Naprawa: dodaj import `@AGENTS.md` do zacommitowanego `CLAUDE.md`; działa w każdej wersji i przy każdym ustawieniu poza `managed-only`.

**Reguły wczytują się dwa razy.** Objaw: `/context` pokazuje w sekcji **Memory files** zarówno `CLAUDE.md`, jak i `AGENTS.md`, z tą samą treścią. Przyczyna: generator zapisał identyczną treść do obu plików, a użytkownik wybrał `claude-md-and-agents-md`. Naprawa: wróć do trybu domyślnego albo generuj `CLAUDE.md` jako jednolinijkowy import.

**Ręczna poprawka znika.** Objaw: poprawki w `CLAUDE.md` nie ma po następnym `generate`. Przyczyna: wygenerowane pliki to wynik; `generate` nadpisuje je ze źródła. Naprawa: edytuj `.rulesync/rules/`. Zacznij treść reguły głównej od `<!-- Generated from .rulesync/rules/. Edit there. -->`; w naszym teście rulesync skopiował tę linię na początek `CLAUDE.md` i `AGENTS.md`, więc ludzie i agenci widzą, gdzie jest źródło.

**Ręcznie pisane reguły znikają po pierwszym `generate`.** Objaw: nie ma plików z `.claude/rules/` albo `.cursor/rules/`, których nikt nie zaimportował. Przyczyna: `"delete": true` z `rulesync init` albo flaga `--delete`. Naprawa: przywróć je przez `git checkout -- .claude/rules .cursor/rules`, uruchom `rulesync import` dla każdego narzędzia, do którego należą, i ustaw `"delete": false`.

**Recenzenci i agenci w chmurze nie widzą reguł.** Objaw: reguły działają lokalnie, ale zadanie Codex w chmurze albo bot do review je ignoruje. Przyczyna: domyślny blok `.gitignore` Rulera albo `rulesync gitignore`. Naprawa: usuń te wpisy, zacommituj wynik i zostaw test rozjazdu.

**Aktualizacja rulesync zmienia wynik.** Objaw: zadanie wykrywające rozjazd pada na pierwszym pull requeście z regułami po tym, jak ktoś podbił przypiętą wersję. Przyczyna: nieprzypięta albo podniesiona wersja główna. Naprawa: przypnij tę samą wersję lokalnie i w CI, a podbijaj ją w osobnym pull requeście razem z ponownie wygenerowanymi plikami.

## Dokąd dalej ze wspólnymi regułami agentów

- [Odchudzanie plików kontekstu](/pl/workflows/context/pruning-context-files/) — Przytnij główny plik reguł do tego, czego potrzebuje każda sesja.
- [System pamięci Claude Code](/pl/claude-code/build/memory-system/) — Zakresy CLAUDE.md, importy, reguły zawężone ścieżkami i pamięć automatyczna.
- [Kod gotowy na agentów](/pl/workflows/harness/agent-ready-codebase/) — Czego jeszcze potrzebuje repozytorium, zanim agenci zaczną w nim pracować bez nadzoru.
- [Ewaluacja zmian w CLAUDE.md](/pl/ecosystem/observability/evals-coding-agents/) — Test A/B zmiany reguł na stałym zestawie zadań przed wdrożeniem.
- [Codex: AGENTS.md](/pl/codex/quick-start/agents-md/) — Jak Codex wyszukuje, nakłada na siebie i uznaje za zaufane pliki AGENTS.md.
- [Jak uniknąć uzależnienia od dostawcy](/pl/org/lock-in-and-portability/) — Dlaczego przenośny plik reguł przetrwa zmianę narzędzia.
- [Poza wielką trójką](/pl/ecosystem/agent-tools/other-coding-agents/) — Pozostali agenci, do których może musieć trafić źródło reguł.
- [Frameworki pracy z agentami: porównanie](/pl/ecosystem/frameworks/) — Metodyki, które uruchamiasz na wspólnym pliku reguł.
