Dokumentacja konfiguracji

Każde narzędzie AI do kodowania używa pliku konfiguracyjnego do zrozumienia twojego projektu. Ustaw go źle, a narzędzie zignoruje twoje standardy kodowania, wygeneruje zły framework testowy lub użyje złego stylu importów przy każdym żądaniu. Ta dokumentacja pokazuje dokładnie, jak skonfigurować każde narzędzie, z kompletnymi przykładami, które możesz skopiować do swojego projektu już dziś.

Czego się nauczysz

• Kompletna składnia pliku konfiguracyjnego dla Cursor, Claude Code i Codex
• Starter template dla każdego narzędzia, który możesz wkleić do dowolnego projektu
• Mapowanie funkcji między systemami konfiguracji
• Zaawansowane wzorce dla monorepo, projektów wielojęzycznych i konfiguracji zespołowych

Systemy konfiguracji w pigułce

Aspekt	Cursor	Claude Code	Codex
Główny plik	.cursor/rules/*.mdc	CLAUDE.md	AGENTS.md
Dodatkowa konfiguracja	.cursorrules (legacy)	.claude/settings.json	~/.codex/config.toml
Format	MDC (Markdown + frontmatter)	Markdown	Markdown + TOML
Zakres	Per projekt, per katalog	Per projekt, per użytkownik, per katalog	Per projekt, per użytkownik
Autodetekcja	Tak (.cursor/rules/)	Tak (CLAUDE.md w korzeniu projektu)	Tak (AGENTS.md w korzeniu projektu)
Targetowanie globem	Tak (frontmatter globs)	Przez umiejscowienie w katalogach	Nie
Wersjonowane	Tak	Tak	Tak (AGENTS.md), Nie (config.toml)

Cursor: .cursor/rules/

Struktura katalogów

.cursor/
  rules/
    project.mdc          # Globalne reguły projektu (zawsze aktywne)
    typescript.mdc       # Aktywne tylko dla plików .ts/.tsx
    testing.mdc          # Aktywne tylko dla plików testowych
    api-routes.mdc       # Aktywne tylko dla plików routów API
    react-components.mdc # Aktywne dla plików komponentów React

Format pliku reguł (MDC)

Każdy plik .mdc używa frontmatter do kontrolowania, kiedy reguła się aktywuje:

---
description: "TypeScript coding standards for the project"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

## TypeScript Standards

- Use strict mode. Never use `any` -- use `unknown` with type guards instead.
- Prefer interfaces for object shapes, type aliases for unions and intersections.
- All exported functions must have explicit return types.
- Use single quotes for imports and strings.
- Organize imports: external deps, then internal absolute imports (`~/`), then relative imports, then type imports.

## Error Handling

- Never swallow errors silently. Always log or rethrow.
- Use custom error classes that extend `Error` for domain errors.
- API routes must return structured error responses with status codes.

## Naming Conventions

- Files: kebab-case (`user-auth.ts`)
- Components: PascalCase (`UserAuth.tsx`)
- Functions: camelCase (`getUserById`)
- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
- Types/Interfaces: PascalCase with descriptive names (`UserAuthResponse`)

Pola frontmatter

Pole	Typ	Opis
description	string	Co robi ta reguła (wyświetlane w UI i używane do autowybioru)
globs	string[]	Wzorce plików aktywujące tę regułę (np. ["**/*.ts"])
alwaysApply	boolean	Jeśli true, reguła jest aktywna dla każdego żądania niezależnie od kontekstu pliku

Typy reguł

Typ	alwaysApply	globs	Zachowanie
Zawsze aktywna	true	—	Dołączana do każdego żądania
Automatycznie dołączana	false	Ustawione	Aktywowana przy pracy z pasującymi plikami
Wybierana przez agenta	false	—	Agent czyta opis i decyduje, czy ją dołączyć

Kompletny starter template

---
description: "Core project rules -- always active"
alwaysApply: true
---

## Project: [Your Project Name]

Tech stack: Next.js 15 (App Router), TypeScript 5, Tailwind CSS, Drizzle ORM, PostgreSQL.

## Coding Standards

- TypeScript strict mode, no `any` types
- Functional components with hooks, no class components
- Server Components by default, "use client" only when needed
- All API routes return typed JSON responses
- Tests with Vitest, integration tests with Playwright

## File Organization

- `src/app/` -- Next.js App Router pages and layouts
- `src/components/` -- Reusable React components
- `src/lib/` -- Shared utilities, database queries, type definitions
- `src/server/` -- Server-only code (API handlers, background jobs)

## Common Commands

- Build: `npm run build`
- Test: `npm run test`
- Lint: `npm run lint`
- Dev: `npm run dev`
- Database migrate: `npm run db:migrate`

## Rules

- ALWAYS run tests after making changes to core business logic
- NEVER commit code that fails type checking
- ALWAYS use parameterized queries for database operations
- NEVER expose internal error details in API responses

Zaawansowane: reguły ograniczone do plików

---
description: "API route conventions for Next.js App Router"
globs: ["src/app/api/**/*.ts"]
---

## API Route Pattern

Every API route must:
1. Validate input with zod schemas
2. Return typed responses using the ApiResponse<T> generic
3. Handle errors with the withErrorHandler wrapper
4. Log request metadata for observability

Example structure:
- Parse request body/params with zod
- Call service layer (never query DB directly in routes)
- Return { success: true, data } or { success: false, error }

Legacy: .cursorrules

Plik .cursorrules w korzeniu projektu to starszy format jednoplikowy. Nadal działa, ale dla nowych projektów preferowany jest system oparty na katalogach. Jeśli oba istnieją, .cursor/rules/ ma pierwszeństwo.

Claude Code: CLAUDE.md

Lokalizacje plików

Lokalizacja	Zakres	Odkrywanie
./CLAUDE.md	Korzeń projektu (główna konfiguracja)	Automatycznie ładowany, gdy Claude startuje w tym katalogu
./src/CLAUDE.md	Specyficzny dla podkatalogu	Ładowany, gdy Claude czyta pliki w src/
~/.claude/CLAUDE.md	Poziom użytkownika (wszystkie projekty)	Zawsze ładowany, stosowany globalnie

Claude Code czyta wszystkie pliki CLAUDE.md od korzenia projektu przez podkatalogi. Pliki w podkatalogach dodają kontekst dla tej części bazy kodu. Pliki poziomu użytkownika ustawiają osobiste preferencje stosowane wszędzie.

Format pliku

Czysty Markdown. Frontmatter nie jest wymagany. Claude czyta to jako instrukcje w języku naturalnym.

CLAUDE.md

## Project Overview

This is a SaaS billing platform built with Express.js and TypeScript.
The API serves a React frontend and handles Stripe subscription management.

## Architecture

- `src/api/` -- Express route handlers (REST API)
- `src/services/` -- Business logic layer
- `src/models/` -- Drizzle ORM schema and queries
- `src/jobs/` -- Background job processors (Bull queue)
- `src/middleware/` -- Auth, rate limiting, error handling
- `tests/` -- Vitest unit tests and Supertest integration tests

## Coding Standards

- TypeScript strict mode, explicit return types on exported functions
- Use `Result<T, E>` pattern for error handling (no throwing in services)
- All database queries go through the repository pattern in `src/models/`
- API responses follow the shape: `{ ok: boolean, data?: T, error?: string }`

## Common Commands

- Build: `npm run build`
- Test: `npm test` (runs Vitest)
- Test single file: `npm test -- src/services/billing.test.ts`
- Lint: `npm run lint`
- Dev server: `npm run dev` (port 3000)
- Database migrate: `npm run db:migrate`
- Database seed: `npm run db:seed`
- Type check: `npx tsc --noEmit`

## Testing Patterns

- Unit tests go next to the source file: `billing.ts` -> `billing.test.ts`
- Integration tests for API routes go in `tests/integration/`
- Use `createTestContext()` from `tests/helpers.ts` for database fixtures
- Mock external services (Stripe, email) using `vi.mock()`

## Important Notes

- NEVER import from `src/api/` inside `src/services/` (dependency flows downward)
- ALWAYS run `npm test` before suggesting a task is complete
- The `STRIPE_SECRET_KEY` env var must be set for billing tests
- Rate limiting middleware is applied globally -- do not add it per-route

CLAUDE.md w podkatalogu

Umieszczaj dodatkowe pliki CLAUDE.md w podkatalogach dla instrukcji specyficznych dla kontekstu:

src/services/CLAUDE.md

## Service Layer Rules

All services in this directory:
- Accept typed input parameters (no raw request objects)
- Return `Result<T, ServiceError>` -- never throw exceptions
- Are stateless -- no instance variables or module-level state
- Have corresponding test files in the same directory

## Dependencies

Services can import from:
- `src/models/` (database access)
- `src/lib/` (shared utilities)
- Other services (but watch for circular dependencies)

Services must NOT import from:
- `src/api/` (routes)
- `src/middleware/`
- `src/jobs/` (use event emitters instead)

Ustawienia Claude: .claude/settings.json

Ten plik kontroluje uprawnienia i zachowanie, nie kontekst projektu:

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run lint*)",
      "Bash(npm run build)",
      "Bash(npx tsc --noEmit)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)",
      "Bash(npm publish*)",
      "Bash(curl*)",
      "Bash(wget*)"
    ]
  }
}

.claude/commands/ Niestandardowe polecenia slash

Twórz wielokrotnego użytku przepływy pracy jako pliki markdown:

---
allowed-tools: [Read, Edit, Bash]
description: Fix a GitHub issue end to end
argument-hint: issue-number
---

Fix GitHub issue #$ARGUMENTS:

1. Run: !gh issue view $ARGUMENTS --json title,body,labels
2. Understand the problem described
3. Find the relevant code
4. Implement the fix
5. Write or update tests
6. Run: !npm test
7. Create a descriptive commit message

Każdy plik staje się poleceniem slash nazwanym po pliku. Na przykład .claude/commands/fix-issue.md staje się /fix-issue 42.

Codex: AGENTS.md i config.toml

AGENTS.md

Konfiguracja na poziomie projektu. Umieszczana w korzeniu repozytorium. Format to czysty Markdown, podobny do CLAUDE.md.

AGENTS.md

## Project

SaaS billing platform. Express.js + TypeScript backend, React frontend.
Stripe integration for subscriptions. PostgreSQL via Drizzle ORM.

## Architecture

- `src/api/` -- REST route handlers
- `src/services/` -- Business logic
- `src/models/` -- Database schema and queries
- `src/jobs/` -- Background processors
- `tests/` -- Test suites

## Standards

- TypeScript strict mode
- Functional patterns preferred over classes
- Result type for error handling in services
- All DB access through repository pattern
- API responses: `{ ok: boolean, data?, error? }`

## Commands

- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`
- Dev: `npm run dev`
- Migrate: `npm run db:migrate`

## Rules

- ALWAYS run tests before marking work complete
- NEVER modify migration files that have already been applied
- ALWAYS use parameterized queries
- NEVER expose stack traces in API responses
- ALWAYS validate input with zod schemas at API boundaries

AGENTS.md w podkatalogu

Podobnie jak Claude Code, Codex obsługuje pliki AGENTS.md w podkatalogach dla instrukcji specyficznych dla kontekstu:

src/api/AGENTS.md

## API Route Conventions

Routes in this directory:
- Use Express Router pattern
- Validate all inputs with zod
- Call service layer for business logic
- Return consistent response shapes
- Include OpenAPI JSDoc annotations

config.toml (konfiguracja CLI)

Znajduje się w ~/.codex/config.toml. Kontroluje zachowanie CLI, nie kontekst projektu.

~/.codex/config.toml

# Default AI model
model = "gpt-5.3-codex"

# Default approval policy: untrusted | on-failure | on-request | never
approval_policy = "on-failure"

# Default provider
model_provider = "openai"

# History and session settings
[history]
persistence = "save-all"
max_bytes = 10485760

# Sandbox configuration
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# Custom providers (for non-default API endpoints)
[model_providers.custom]
name = "My Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"

Konfiguracja automatyzacji Codex

Codex obsługuje automatyzacje GitHub, Slack i Linear konfigurowane przez Codex App (interfejs webowy). Nie są oparte na plikach, ale warto je znać obok plików konfiguracyjnych.

Automatyzacja	Wyzwalacz	Konfiguracja
GitHub Issues	Przypisz do @codex	Codex App > Settings > Automations
Slack	Wiadomość w skonfigurowanym kanale	Codex App > Settings > Slack
Linear	Przypisz do agenta Codex	Codex App > Settings > Linear

Porównanie obok siebie

Informowanie AI o projekcie

Cursor

---
description: "Project overview"
alwaysApply: true
---

## Project
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Stack
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

Plik: .cursor/rules/project.mdc

Claude Code

CLAUDE.md

## Project Overview
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Architecture
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

Plik: CLAUDE.md (korzeń projektu)

Codex

AGENTS.md

## Project
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Standards
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

Plik: AGENTS.md (korzeń projektu)

Definiowanie standardów kodowania

Cursor

---
description: "TypeScript coding standards"
globs: ["**/*.ts", "**/*.tsx"]
---

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

Plik: .cursor/rules/typescript.mdc

Claude Code

## Coding Standards

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

Sekcja w CLAUDE.md

Codex

## Standards

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

Sekcja w AGENTS.md

Określanie poleceń budowania i testowania

Cursor

---
description: "Build and test commands"
alwaysApply: true
---

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev: `npm run dev`

Plik: .cursor/rules/commands.mdc

Claude Code

## Common Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev: `npm run dev`

Sekcja w CLAUDE.md

Codex

## Commands

- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`
- Dev: `npm run dev`

Sekcja w AGENTS.md

Ustawianie barier ochronnych (rób / nie rób)

Cursor

---
description: "Project guardrails"
alwaysApply: true
---

## Always
- Run tests after changing business logic
- Use parameterized queries for all DB operations
- Validate inputs at API boundaries

## Never
- Import from `src/api/` inside `src/services/`
- Commit code that fails type checking
- Expose internal errors to API consumers

Plik: .cursor/rules/guardrails.mdc

Claude Code

## Important Notes

- ALWAYS run tests after changing business logic
- ALWAYS use parameterized queries for all DB operations
- ALWAYS validate inputs at API boundaries
- NEVER import from `src/api/` inside `src/services/`
- NEVER commit code that fails type checking
- NEVER expose internal errors to API consumers

Sekcja w CLAUDE.md

Codex

## Rules

- ALWAYS run tests after changing business logic
- ALWAYS use parameterized queries for all DB operations
- ALWAYS validate inputs at API boundaries
- NEVER import from `src/api/` inside `src/services/`
- NEVER commit code that fails type checking
- NEVER expose internal errors to API consumers

Sekcja w AGENTS.md

Konfiguracja monorepo

Gdy repozytorium zawiera wiele pakietów lub usług, każde narzędzie obsługuje zakres inaczej.

Cursor

Twórz reguły na wielu poziomach katalogów:

.cursor/
  rules/
    monorepo.mdc          # alwaysApply: true (wspólne standardy)

packages/
  api/
    .cursor/
      rules/
        api-rules.mdc     # globs: ["**/*.ts"] (specyficzne dla API)
  web/
    .cursor/
      rules/
        web-rules.mdc     # globs: ["**/*.tsx"] (specyficzne dla frontendu)

Reguły scalają się, gdy agent uzyskuje dostęp do plików w różnych pakietach.

Claude Code

Umieszczaj pliki CLAUDE.md na każdym poziomie:

CLAUDE.md                  # Root: wspólne standardy, struktura monorepo
packages/
  api/
    CLAUDE.md              # Usługa API: wzorce Express, dostęp do DB
  web/
    CLAUDE.md              # Frontend: wzorce React, zarządzanie stanem
  shared/
    CLAUDE.md              # Biblioteka wspólna: konwencje eksportów

Claude czyta plik root plus plik podkatalogu podczas pracy w danym pakiecie.

Codex

Umieszczaj pliki AGENTS.md na każdym poziomie:

AGENTS.md                  # Root: wspólne standardy, struktura monorepo
packages/
  api/
    AGENTS.md              # Usługa API: wzorce Express, dostęp do DB
  web/
    AGENTS.md              # Frontend: wzorce React, zarządzanie stanem
  shared/
    AGENTS.md              # Biblioteka wspólna: konwencje eksportów

Codex odkrywa i scala konfiguracje w miarę nawigowania po repozytorium.

Konfiguracja wielonarzędziowa

Wiele zespołów używa więcej niż jednego narzędzia. Oto jak utrzymywać konfiguracje bez duplikacji.

Strategia: jedno źródło prawdy

Trzymaj standardy w jednym kanonicznym pliku i wyprowadzaj konfiguracje specyficzne dla narzędzi:

docs/
  coding-standards.md      # Źródło prawdy

CLAUDE.md                  # Zawiera: "See docs/coding-standards.md for full standards"
AGENTS.md                  # Zawiera: "See docs/coding-standards.md for full standards"
.cursor/rules/
  standards.mdc            # Skopiuj odpowiednie sekcje z coding-standards.md

Uwaga

Reguły Cursor nie mogą dynamicznie odwoływać się do zewnętrznych plików. Musisz skopiować odpowiednią treść do plików .cursor/rules/. Claude Code i Codex mogą podążać za odwołaniami do plików jak “read docs/coding-standards.md for standards”, ponieważ mają dostęp do systemu plików podczas wykonywania.

Strategia: wspólne bariery, funkcje specyficzne dla narzędzi

# .cursor/rules/project.mdc (specyficzne dla Cursor)
---
alwaysApply: true
---
[Wspólne standardy skopiowane tutaj]

## Cursor-Specific
- Use Tab autocomplete for boilerplate
- Use @codebase for cross-file analysis
- Generate commit messages with Cmd+Shift+P > Generate Commit

# CLAUDE.md (specyficzne dla Claude Code)
[Wspólne standardy tutaj]

## Claude Code-Specific
- Run /compact when context exceeds 100K tokens
- Use claude -p for CI/CD pipeline integration
- Create custom commands in .claude/commands/ for repeated tasks

# AGENTS.md (specyficzne dla Codex)
[Wspólne standardy tutaj]

## Codex-Specific
- Use auto-edit mode for normal development
- Reserve full-auto for sandboxed environments
- Assign GitHub issues to @codex for automated fixes

Lista kontrolna konfiguracji

Użyj przy konfiguracji nowego projektu lub wdrażaniu nowego narzędzia:

1. Zdefiniuj kontekst projektu: Stos technologiczny, architektura, organizacja plików. Dołącz to do pliku konfiguracyjnego, aby AI wiedziało, z czym pracuje.

2. Określ standardy kodowania: Konwencje nazewnictwa, kolejność importów, wzorce obsługi błędów, konwencje typów. Bądź konkretny — “use interfaces for object shapes” jest lepsze niż “follow TypeScript best practices”.

3. Wymień popularne polecenia: Build, test, lint, serwer deweloperski, migracja bazy danych. AI będzie je uruchamiać, aby zweryfikować swoją pracę.

4. Ustaw bariery ochronne: Co AI powinno zawsze robić? Czego nigdy nie powinno robić? Zapobiegają kosztownym błędom, takim jak usuwanie plików migracji czy pushowanie bezpośrednio na main.

5. Dodaj wzorce testowe: Gdzie mieszkają testy? Jaki runner testów? Jak uruchomić pojedynczy test? Jakie wzorce mockowania? AI pisze lepsze testy, gdy zna twoje konwencje.

6. Udokumentuj granice architektury: Które moduły mogą importować z których? Jaki jest kierunek zależności? Zapobiega to tworzeniu cyklicznych zależności przez AI.

7. Dołącz uwagi o środowisku: Wymagane zmienne środowiskowe, connection stringi bazy danych (nie wartości — nazwy), zależności zewnętrznych usług. Pomaga to AI poprawnie konfigurować fixtures testowe.

Szybka karta referencyjna

Co chcesz	Cursor	Claude Code	Codex
Globalne reguły projektu	.cursor/rules/project.mdc z alwaysApply: true	Sekcje najwyższego poziomu w CLAUDE.md	Sekcje najwyższego poziomu w AGENTS.md
Reguły per typ pliku	globs: ["**/*.ts"] we frontmatter	CLAUDE.md w podkatalogu	AGENTS.md w podkatalogu
Preferencje użytkownika	settings.json VS Code	~/.claude/CLAUDE.md	~/.codex/config.toml
Kontrola uprawnień	Privacy Mode w ustawieniach	.claude/settings.json	Flaga --ask-for-approval
Niestandardowe polecenia	Rozszerzenia palety poleceń	.claude/commands/*.md	Polecenia slash Codex
Wielokrotnego użytku przepływy	.cursor/rules/ z description	Niestandardowe polecenia slash	Automatyzacje Codex
Wzorce ignorowania	Standardowy .gitignore	Standardowy .gitignore	Standardowy .gitignore
Wybór modelu	Settings > Models	Polecenie /model	Flaga --model lub config.toml

Wskazówka

Najważniejszą rzeczą, jaką możesz zrobić, jest określenie polecenia testowego. Gdy AI wie, jak zweryfikować swoją pracę, łapie własne błędy, zanim je zobaczysz. Dodaj “ALWAYS run npm test before reporting task completion” do pliku konfiguracyjnego niezależnie od tego, jakiego narzędzia używasz.