AGENTS.md i CLAUDE.md — zwięzły kontekst repozytorium

Instrukcje repo powinny dawać każdemu świeżemu agentowi tę samą prawdę operacyjną: strukturę projektu, bezpieczne komendy, granice i dowód wymagany przed ukończeniem. W Q9 długi manifest jest słabym dowodem. Najlepszy setup ma jeden zwięzły rdzeń, cienkie adaptery narzędziowe, szczegóły zakresowe i test potwierdzający, że każdy klient wczytał właściwe reguły.

Scorecard Q9: Jak skonfigurowana jest wiedza instytucjonalna repozytorium?

Dowód na maksymalny wynik: wersjonowane, zakresowe instrukcje, których wykrywanie i zachowanie przetestowano w Claude Code, Cursorze i Codexie.

Użyj wspólnego rdzenia i jawnych adapterów

Zacznij od AGENTS.md jako czytelnego kontraktu projektu:

# Repository operating contract

## Structure
- Application code: `src/`; tests: `tests/`; docs: `src/content/docs/`.

## Safe commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
- Never deploy or access production data from a local agent session.
- Ask before changing dependencies or public APIs.

## Completion evidence
- Report changed files, commands run, results, and unresolved risks.

Następnie dostosuj wykrywanie bez kopiowania polityki:

Narzędzie	Punkt wejścia instrukcji projektu	Szczegóły zakresowe
Claude Code	CLAUDE.md lub .claude/CLAUDE.md; może importować @AGENTS.md	.claude/rules/*.md, opcjonalnie z frontmatter paths
Cursor	główny AGENTS.md lub CLAUDE.md	.cursor/rules/ z trybami stosowania lub wzorcami plików
Codex	AGENTS.md, wykrywany w hierarchii repo	Bardziej szczegółowe zagnieżdżone AGENTS.md, gdy są potrzebne

Źródła: pamięć i reguły Claude Code, reguły Cursora i AGENTS.md w Codexie.

Dla Claude Code adapter może mieć jedną linię:

@AGENTS.md

Dodawaj reguły tylko dla faktycznych różnic klienta. Nie kopiuj całego kontraktu do trzech plików; kopie się rozjeżdżają.

Umieść instrukcje we właściwej warstwie

• Fakty, komendy i granice potrzebne zawsze umieść w kontrakcie głównym.
• Konwencje zależne od ścieżki trzymaj przy kodzie lub w mechanizmie scoped rules danego klienta.
• Procedury wieloetapowe umieść w skills, aby ładowały się na żądanie.
• Twarde egzekwowanie umieść w uprawnieniach, hookach, branch protection i CI. Instrukcje kierują zachowaniem; nie są granicą bezpieczeństwa.
• Stan zadania trzymaj w intent.md, spec.md i plan.md, nie w trwałej regule repo.

Przetestuj świeżą sesję

Po zmianie instrukcji uruchom tę samą diagnostykę w każdym wspieranym kliencie.

Prompt do skopiowania — wykrywanie:

Before editing anything, list the repository instruction files you loaded, summarize the safe build and test commands, and name every production boundary. Cite each answer to its source file.

Prompt do skopiowania — reguła zakresowa:

Inspect src/auth/ without editing it. Which repository-wide and auth-specific instructions apply? If no scoped instruction loaded, say so explicitly.

Prompt do skopiowania — audyt sprzeczności:

Review all instruction files that apply from this directory to the repository root. Report duplicate, stale, vague, or conflicting rules. Propose the smallest consolidation patch and do not change runtime code.

Zapisz oczekiwane odpowiedzi w krótkiej checkliście testowej. Nowa komenda nie jest zaufana, dopóki nie zadziała w czystym checkoutcie lub udokumentowanym środowisku lokalnym.

Pułapka: kontekst bez testu

Typowe błędy to skopiowane pliki, które sobie przeczą, proza typu „testuj dokładnie” bez komendy, nieaktualne ścieżki, sekrety w osobistych instrukcjach i plik główny tak duży, że trudno znaleźć krytyczne reguły. Błędem jest też założenie, że każdy klient wykrywa każdy katalog dostawcy. Testuj wykrywanie zamiast ufać deklaracji przenośności.

Dowód ukończenia

• Wspólny rdzeń opisuje strukturę, bezpieczne komendy, granice i wymagany dowód.
• Pliki narzędziowe zawierają wyłącznie prawdziwe różnice lub importy.
• Każda udokumentowana komenda została wykonana we wspieranym środowisku.
• Świeża sesja w każdym kliencie raportuje oczekiwany zestaw instrukcji.
• Właściciel i rytm review są zapisane przy kontrakcie.

Przejdź do trwałych artefaktów

Łańcuch artefaktów Przenoś stan zadania przez przeglądalne intent, spec, plan, diff i dowody.

Q6 · Agent skills Przenieś procedury warunkowe poza stale ładowany kontekst.

Q12 · Hooki agenta Egzekwuj wybrane niezmienniki testowanymi kontrolami.