Wspólne reguły agenta — managed policy + per-repo CLAUDE.md + .claude/rules/

Pytanie 5 (Wspólna infrastruktura): Czy zespół dzieli reguły agenta (CLAUDE.md / AGENTS.md / managed policy)?

Odpowiedź na maks: Wielowarstwowo z procesem aktualizacji — managed policy + per-repo CLAUDE.md + .claude/rules/ lub Cursor Team Rules.

Dlaczego to ma znaczenie w 2026

Scentralizowane reguły zamieniają “wiedzę plemienną” na “harness to wymusza”. Bez warstwy managed policy nie da się zagwarantować ograniczeń security ani stylistycznych — każdy developer jest o jeden prompt od dania agentowi innej definicji “production-ready”, a dowiesz się o tym w code review (jeśli masz szczęście) albo na produkcji (jeśli nie).

W 2025 większość organizacji inżynierskich traktowała CLAUDE.md jako per-repo ciekawostkę, którą utrzymywało jedno-dwóch entuzjastów. W 2026 obraz się odwrócił. Anthropic wypuścił managed settings dla planów Team i Enterprise — warstwę konfiguracji organizacyjnej, która siedzi nad każdym ustawieniem developera i nie może być nadpisana przez user settings ani project settings. Cursor wydał Team Rules w tej samej formie: współdzieloną politykę, która propaguje się do każdego workspace w organizacji. A AGENTS.md — wielonarzędziowy standard zarządzany przez Agentic AI Foundation pod Linux Foundation, wspierany przez OpenAI, Sourcegraph, Cursor, Google i Factory — przekroczył 60 000+ publicznych repozytoriów.

CTO, którzy traktują wspólne reguły agenta jako “miło mieć”, to ci sami, którzy będą pisać post-mortem, kiedy agent zacommituje hardcoded credentials, force-pushnie na main, albo autonomicznie zaktualizuje krytyczną zależność w piątek po południu. CTO, którzy maksują Q5, te tryby awarii usunęli już na warstwie narzędziowej — nie licząc na to, że deweloperzy przeczytają wiki, tylko sprawiając, że agent fizycznie nie jest w stanie zrobić złej rzeczy.

Dźwignia jest brutalna. Jeden dobrze przygotowany managed policy plus per-repo CLAUDE.md plus garść plików .claude/rules/ oszczędza każdemu developerowi dziesięć minut na sesję na primingu kontekstu i usuwa całą klasę incydentów typu “agent zrobił coś, czego nie powinien”. Pomiń warstwę managed-policy, a będziesz wiecznie płacić podatek “wytłumacz reguły znowu” — i nie będziesz miał audit trail, kiedy coś pójdzie nie tak.

Jak wygląda “max score” w praktyce

Odpowiedź na maks ma trzy warstwy plus jawny, nazwany proces aktualizacji. Pomiń którąkolwiek z nich, a nie jesteś na szczycie tego pytania.

Warstwa 1 · Managed policy (org-wide, enforcowana, nie do wyłączenia)
  └── managed-settings.json na każdej maszynie developera (lub Cursor Team Rules)
        - permission allow/deny lists
        - wymagane hooki (pre-commit, pre-push)
        - approved MCP servers
        - zabronione modele lub komendy

Warstwa 2 · Per-repo CLAUDE.md / AGENTS.md (zacommitowany do main, share'owany)
  └── jeden plik per repo, w source control
        - opis projektu, stack, komendy
        - non-obvious traps i konwencje
        - linki do odpowiednich per-area rules

Warstwa 3 · .claude/rules/ per obszar (scoped przez glob)
  └── auth.md, db.md, deploy.md, payments.md, testing.md
        - głębokie specyfiki, które ładują się tylko gdy potrzebne
        - każdy plik ma paths: frontmatter

Proces aktualizacji · Kwartalny audyt + RFC + nazwany owner
  └── AI tooling lead robi review reguł co kwartał
        - nowe reguły wchodzą przez RFC, nie przypadkowo
        - przestarzałe reguły są pruned
        - zmiany są ogłaszane na engineering all-hands

Słowo kluczowe to i. Dwa-z-czterech to “Optimized”; cztery-z-czterech to “Strategic Leader”. Managed policy bez per-area rules znaczy, że zablokowałeś security, ale nie engineering style. Per-repo CLAUDE.md bez managed policy — dzielisz się wiedzą, ale nic nie powstrzymuje developera przed wyłączeniem reguł lokalnie. Reguły bez procesu aktualizacji robią się przestarzałe w dwa sprinty i zaczynają kłamać twoim agentom.

Aktualny krajobraz (zweryfikowany web-search’em)

Managed policy (Anthropic managed settings, Cursor Team Rules)

Większość organizacji nadal nie ma tej warstwy — a to ona przerzuca twój maturity rating z “shared best practices” na “enforced policy”. Anthropic wypuścił managed settings jako część rollout’u Team/Enterprise. Plik leży na specyficznej dla OS ścieżce na każdej maszynie developera:

macOS:        /Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL:    /etc/claude-code/managed-settings.json
Windows:      C:\ProgramData\ClaudeCode\managed-settings.json

Resolvuje się przed user settings, project settings i CLI flags. Cokolwiek tu ustawisz, nie może być nadpisane przez flagę developera ani plik projektowy. Typowa zawartość: permissions.deny dla niebezpiecznych komend (Bash(git push --force *), Bash(rm -rf *)), wymagane hooks dla pre-commit lint i pre-push test gates, allowlist przez enabledMcpjsonServers oraz managed apiKeyHelper. Drop-in fragmenty idą do managed-settings.d/ obok pliku bazowego, sortowane alfabetycznie i merge’owane — security shipuje 00-banned-commands.json, platform team 50-required-hooks.json bez konfliktów.

Odpowiednikiem w Cursorze są Team Rules: reguły zdefiniowane przez org-admina, propagujące się do każdego workspace w teamie Cursor, siedzące nad user i project rules w tym samym łańcuchu precedensu.

Dystrybucja to trudna część. MDM (Jamf, Intune, Workspace ONE) to najczystsza ścieżka dla laptopów; Ansible/Chef/Puppet dla flot linuksowych; najprostszą opcją jest skrypt bootstrap w dotfiles, który kopiuje kanoniczny managed-settings.json przy pierwszym uruchomieniu i weryfikuje hash w każdej kolejnej powłoce.

Źródła: Claude Code settings docs, Claude Code Enterprise Rollout Playbook, What’s new in Claude admin controls 2026.

Per-repo CLAUDE.md / AGENTS.md (zacommitowany do main)

Środkowa warstwa to coś, co większość zespołów już ma w jakiejś formie — ale max-score wersja traktuje to jako first-class deliverable, nie projekt poboczny. Każde aktywne repo ma project-level plik zacommitowany do main. Odpowiada na pytania, które nowy contributor (lub świeży agent) zadałby w pierwszej godzinie: co robi ten projekt, jaki jest stack, jakie są komendy, gdzie co leży i jakie są non-obvious rules.

Dwa warianty:

CLAUDE.md — natywny plik Claude Code, ładowany automatycznie na start sesji.
AGENTS.md — wielonarzędziowy standard (60 000+ repo w 2026, włącznie z n8n i awesome-go), czytany przez Codex, Cursor, Copilot, Aider i Claude Code.

Jeśli twój zespół używa więcej niż jednego agenta (prawie wszyscy w 2026), napisz AGENTS.md i zsymlinkuj CLAUDE.md → AGENTS.md. Jeśli potrzebujesz specyficznego dla Claude’a zachowania, wrzuć to do .claude/CLAUDE.md. Badanie Prompt Shelf na 60 000+ repo pokazuje, że wzorzec dwóch plików jest teraz dominującą konwencją.

Trzymaj plik projektowy poniżej 200 linii. Powyżej tego frontier modele zaczynają cicho gubić instrukcje. Podziel głębokie specyfiki do .claude/rules/.

.claude/rules/ per obszar (auth.md, db.md, deploy.md)

Warstwa, którą większość setupów pomija — i ta, która oddziela “dobre” od “max score”. Katalog .claude/rules/ zawiera modułowe pliki .md, każdy scoped do jednego wycinka systemu, z YAML frontmatter deklarującym, które ścieżki triggerują regułę:

.claude/rules/
├── auth.md         # paths: ["src/lib/auth/**", "src/pages/api/auth/**"]
├── db.md           # paths: ["src/lib/db/**", "drizzle/**", "scripts/schema.sql"]
├── deploy.md       # paths: [".github/workflows/**", "wrangler.toml"]
├── payments.md     # paths: ["src/lib/polar/**", "src/pages/api/webhooks/**"]
└── testing.md      # paths: ["tests/**", "**/*.test.ts"]

Reguła z frontmatter paths: ładuje się tylko wtedy, gdy agent dotyka plików matchujących — możesz napisać 300 linii szczegółów flow płatności bez zatłaczania okna kontekstu. Agent dostaje reguły auth przy edycji auth, reguły db przy edycji schem, nic ekstra przez resztę czasu.

Użytkownicy Cursora dostają ten sam kształt z .cursor/rules/ plus warstwę Team Rules na wierzchu.

Proces aktualizacji (kwartalny audyt, RFC, ownership AI tooling leada)

To warstwa, która nie pojawia się w żadnej dokumentacji, bo jest czysto organizacyjna — ale to ona zapobiega gniciu pierwszych trzech warstw. Max-score setup ma:

Nazwanego AI tooling leada (lub mały AI platform team), który jest ownerem reguł. Nie odpowiedzialność z boku biurka — pozycja w opisie roli kogoś.
Kwartalny audyt w kalendarzu. Otwórz każdą warstwę, prune to, co przestarzałe, promuj częste korekty do reguł, demuj reguły, do których nikt już nie odsyła.
Proces RFC dla nowych reguł managed-policy. Dodanie wpisu permissions.deny, który łamie każdy workflow developera, to rodzaj błędu, który niszczy zaufanie do centralized governance. Puść to jako engineering RFC z tygodniowym okresem komentarzy, potem ship.
Changelog albo ogłoszenie na all-hands, kiedy zmienia się polityka. Jeśli deweloperzy nie wiedzą, że reguła się zmieniła, będą walczyć z narzędziem zamiast go używać.

Realna hierarchia

Tak naprawdę wygląda łańcuch precedensu w runtime, góra wygrywa:

1. managed-settings.json              ← org-wide, ENFORCED, bez nadpisania
   + managed-settings.d/*.json        ← drop-in fragmenty (merge alfabetyczny)
2. Cursor Team Rules                  ← cross-tool odpowiednik dla Cursora
3. CLI flags                          ← override per uruchomienie
4. .claude/settings.local.json        ← osobiste, nie w source control
5. .claude/settings.json              ← project, w source control, share'owane
6. ~/.claude/settings.json            ← user defaults (preferencje globalne)
   + ~/.claude/CLAUDE.md              ← user memory (cross-project)
7. ./AGENTS.md (lub ./CLAUDE.md)      ← project memory, share'owane z zespołem
8. .claude/rules/*.md                 ← per-area memory, scoped przez `paths:`

Managed policy banująca git push --force na main nie może być cofnięta przez ustawienie developera w ~/.claude/settings.json — o to chodzi. Ale pliki reguł (CLAUDE.md, AGENTS.md, .claude/rules/*.md) są memory, nie settings: mówią agentowi, co robić, ale fizycznie go nie blokują. Potrzebujesz obu warstw — settings dla twardego enforcement, memory dla wspólnego stylu.

Krok po kroku: wdrażanie warstwowych reguł

Wyznacz ownera, zanim napiszesz pierwszą regułę.

Wybierz jednego inżyniera ownerem hierarchii reguł AI-tooling. Wpisz to w opis stanowiska, alokuj ~10% czasu, daj autorytet do shipowania zmian managed-policy. Bez nazwanego ownera całość rozkłada się w ciągu kwartału.
Zaudytuj to, co istnieje dziś.

Przejdź przez każde aktywne repo. Zanotuj, które ma CLAUDE.md lub AGENTS.md, które ma .claude/rules/ i co jest w środku. Znajdziesz trzy wzorce: dobrze utrzymane (rzadko), wygenerowane /init i porzucone (najczęściej), nieistniejące w ogóle.
Drafnij managed policy jako pierwszą — zacznij od małego.

Nie enforcuj dwudziestu reguł pierwszego dnia. Zacznij od trzech: permissions.deny dla najgroźniejszych komend, jeden wymagany hook (pre-commit lint) i allowlist MCP przez enabledMcpjsonServers. Shipnij to, dodawaj kolejne, jak deweloperzy się dostosują.
Wybierz mechanizm dystrybucji managed settings.

MDM jest najczystszy. W przeciwnym razie: skrypt bootstrap w dotfiles, który uruchamia się przy pierwszym loginie, kopiuje kanoniczny managed-settings.json na ścieżkę OS i weryfikuje hash przy każdym starcie shell’a. Udokumentuj w onboarding runbook.
Ustandaryzuj AGENTS.md dla warstwy per-repo.

Odpal /init w każdym aktywnym repo, zmień nazwę outputu na AGENTS.md, zsymlinkuj CLAUDE.md → AGENTS.md. Wytnij generyczny boilerplate, zastąp specyfikami (stack, komendy, traps, konwencje). Każdy plik poniżej 200 linii.
Wykraj .claude/rules/ dla głębokich specyfik.

Dla każdego repo zidentyfikuj dwa-trzy obszary, gdzie agent popełnia najwięcej błędów — auth, baza, deploye, płatności. Stwórz po jednym pliku .md per obszar w .claude/rules/, każdy z frontmatter paths:. Przenieś głębokie specyfiki z AGENTS.md do plików obszarowych.
Skonfiguruj kwartalny audyt.

Cykliczny 90-minutowy “rules audit” w kalendarzu, ownerem AI tooling lead. Otwórz każdą warstwę, prune obsolete rules, promuj częste korekty, szukaj sprzeczności, sprawdź czy managed policy nadal odzwierciedla bieżące threat modele.
Udokumentuj proces RFC dla zmian managed-policy.

Nowe wpisy permissions.deny, wymagane hooki, zmiany MCP allowlist — cokolwiek uderza w każdego developera — przez tygodniowy RFC. Próg to nie “executive approval”, tylko “tydzień, żeby deweloperzy oznaczyli workflow, który to łamie”.
Ogłaszaj zmiany na engineering all-hands.

Pięć minut per all-hands na “co się zmieniło w regułach agenta w tym sprincie, dlaczego i jak się dostosować”.
Zweryfikuj świeżą sesją na czystym repo.

Raz na kwartał, na czystej maszynie, spytaj agenta: “Streść reguły, które masz załadowane — managed policy, project memory, area rules.” Jeśli odpowiedź nie pasuje, coś się nie propaguje. Częste podejrzane: managed-settings.json nie ląduje na nowych maszynach, brak paths:, symlink CLAUDE.md zepsuty.

Częste pułapki

Reguły kontrujące się między warstwami. Managed policy banuje Bash(npm publish), ale per-repo CLAUDE.md instruuje agenta, żeby uruchomił npm publish w release flow. Agent zdezorientowany, reguła traci autorytet. Audytuj sprzeczności co kwartał; rozwiązuj decydując, która warstwa jest ownerem reguły.

Brak cadence aktualizacji. CLAUDE.md napisany pierwszego dnia i nigdy więcej nie tknięty jest przestarzały w dwa sprinty. Nowe konwencje się pojawiają, stare giną, plik kłamie. Każdy PR zmieniający konwencję aktualizuje też reguły.

Managed policy bez enforcementu samego środowiska. Shipnąłeś managed-settings.json, ale nie zweryfikowałeś, że wylądował na każdej maszynie. Bootstrap-script-plus-hash-check łapie drift; MDM raportujący compliance też. Bez enforcementu enforcementu “managed” jest aspiracyjne.

Aspiracyjne reguły bez zębów. “Pisz czysty kod” nie mówi agentowi nic testowalnego. Każda reguła powinna być czymś, co możesz zreviewować w PR: “Używaj Drizzle dla zapytań D1; żadnego raw SQL poza scripts/schema.sql” jest testowalne.

Per-area rules bez scope paths:. Plik bez frontmatter ładuje się na każdą sesję, pokonując sens .claude/rules/. Dodaj paths: do każdego pliku area-specific.

Brak “dlaczego” dla non-obvious rules. Reguła bez powodu nie generalizuje. Pierwsze edge case agent strzeli na ślepo. Dwa zdania uzasadnienia są warte więcej niż dziesięć reguł bez nich.

Setup Claude-only, kiedy połowa zespołu siedzi na Cursorze. Jeśli user Cursora otwiera repo, .claude/rules/ jest niewidzialne. Użyj AGENTS.md dla warstwy projektowej, zmirroruj area rules w .cursor/rules/, zweryfikuj że oba narzędzia widzą ten sam kontekst.

Owner-by-rotation. Rotowanie ownership co kwartał brzmi sprawiedliwie, ale zabija wiedzę instytucjonalną. Owner nie musi być senior — musi być konsekwentny.

Pomijanie RFC dla zmian managed-policy. Dodanie permissions.deny, które łamie workflow każdego bez ostrzeżenia, to najszybszy sposób na zniszczenie zaufania do centralized governance.

Jak zweryfikować, że jesteś u celu

Dalsza lektura

Q6 · Wspólne skills Kiedy reguły są warstwowe, wspólne skills (firmowe repo + bootstrap + onboarding hook) rozszerzają to samo governance na capabilities.

Q18 · Governance hooków Hooki to jak managed policy dostaje zęby — repo, auto-install via dotfiles, podpisane i audytowane skrypty.

Q20 · Dzielenie wiedzy Repo ai-toolkit-internal + brown-bag sessions — ludzka strona utrzymywania wspólnych reguł przy życiu.

Zrób CTO Scorecard 25 pytań, ~12 minut. Ocena tier + plan 30/60/90 + risk register.