Współpraca zespołowa

Współpraca zespołowa w Cursorze stoi na wspólnej konfiguracji, a nie na umiejętnościach pojedynczych osób: reguły projektu, ustawienia MCP, pliki promptów i komendy slash trafiają do repozytorium, a Team Rules zarządzane z panelu biją zarówno reguły projektu, jak i osobiste. Efekt jest taki, że agent nowego dewelopera daje pierwszego dnia to samo co agent weterana.

Ośmiu inżynierów korzysta z Cursora, a jakość wyników skacze na wszystkie strony. Trasy API wygenerowane u jednego mają obsługę błędów, walidację i logowanie. U drugiego obsługi błędów nie ma wcale. Trzeciemu wychodzi var zamiast const, bo jego reguły osobiste nadpisują ustawienia projektu. Jeden agent stawia średniki, drugi nie; jeden sypie typami any, drugi pisze ścisły TypeScript.

Kod wygenerowany przez AI wygląda, jakby pisało go pięć różnych osób, bo skonfigurowało go pięć różnych osób. Lekarstwem nie jest lepsze promptowanie na każdej maszynie, tylko przeniesienie konfiguracji do repozytorium, gdzie przechodzi review, ma historię i jest identyczna dla wszystkich.

Co daje skoordynowana konfiguracja Cursora w zespole

Zacommitowany katalog .cursor/rules/, dzięki któremu kod generowany przez AI jest spójny w całym zespole
Konfigurację Team Rules na planach Team i Enterprise oraz kolejność pierwszeństwa rozstrzygającą, która reguła wygrywa
Wspólną konfigurację MCP, żeby agent każdego dewelopera miał te same narzędzia
Wielokrotnego użytku pliki promptów i komendy slash zapisujące dobre praktyki zespołu
Listę onboardingową, po której nowy deweloper pracuje produktywnie w Cursorze po jednym dniu
Proces wstępnego review z AI, dzięki któremu czas ludzi idzie na ocenę, a nie na odhaczanie listy
Politykę bezpieczeństwa równoważącą produktywność i zgodność z wymogami

Wspólne reguły projektu w repozytorium

To najważniejsza praktyka zespołowa: reguły projektu należą do repozytorium, a nie do ustawień pojedynczych osób. Każda reguła z .cursor/rules/ jest dostępna dla każdego, kto sklonuje repo, i każda rozmowa z agentem toczy się pod tymi samymi ograniczeniami.

mkdir -p .cursor/rules

Reguła startowa, którą powinien mieć każdy zespół

Zacznij od jednej zawsze stosowanej reguły, która nazywa stack i rzeczy nienegocjowalne:

Copy-paste: reguły startowe dla spójności w zespole

Utwórz .cursor/rules/project-standards.mdc:

---
alwaysApply: true
---

Project: [Your project name]
Stack: [Your tech stack]

Code standards:
- TypeScript strict mode, no `any` types
- All public functions must have JSDoc comments
- Error handling: use AppError from @src/lib/errors.ts
- Logging: use logger from @src/lib/logger.ts, never console.log
- Tests: Vitest, test files adjacent to source

When creating new files, check for existing patterns before inventing new ones.
Reference @src/routes/users.ts for API patterns.
Reference @src/components/UserProfile.tsx for component patterns.

Rozbijanie reguł, które rosną

Reguła startowa zostaje krótka, bo stosuje się zawsze. Wszystko dłuższe ląduje we własnym pliku, żeby agent wczytywał to wtedy, gdy jest istotne, a nie przy każdej wiadomości:

## Code Style

- TypeScript strict mode. No 'any' types except where explicitly documented.
- Named exports only. No default exports.
- Functional components with hooks for React.
- camelCase for variables and functions. PascalCase for types, interfaces, and components.
- Use async/await. Never use .then() chains.
- All async functions must have try-catch error handling.
- Prefer fetch over axios for HTTP requests.
- Use pnpm for all package manager commands.

## Testing Conventions

- Use vitest for all unit and integration tests.
- Test files live next to the code they test: src/services/__tests__/user.test.ts
- Use descriptive test names that explain the scenario: "should return 404 when user does not exist"
- Mock external dependencies (database, APIs) but not internal modules.
- Aim for 80% code coverage on new code.
- Always test error cases, not just happy paths.

## Architecture Rules

- API routes in src/api/ handle HTTP concerns only (parsing, validation, response formatting).
- Business logic goes in src/services/. Services never import from src/api/.
- Database operations go in src/repositories/. Services use repositories, never raw queries.
- Shared types go in src/types/. Types are the only thing that every layer can import.
- Do not create circular dependencies. If service A needs service B, inject it as a parameter.

git add .cursor/rules/
git commit -m "Add Cursor project rules for consistent AI behavior

Adds code style, testing, and architecture rules that apply to
all AI-generated code. These ensure consistency across team members."

Utrzymywanie reguł przy życiu

Traktuj reguły jak kod, bo gniją jak kod:

Review reguł w PR-ach: dodanie albo zmiana reguły przechodzi przez to samo review co każda inna zmiana
Reguły poprawiane po wpadkach: gdy review człowieka wyłapie wzorzec, który agent przekręcił, popraw regułę w tym samym PR-ze, żeby to się nie powtórzyło
Kwartalny audyt: usuń nieaktualne odwołania i dopisz wzorce, których zespół zaczął używać w międzyczasie

Prompt copy-paste do utrzymania reguł:

Review the rules in @.cursor/rules/ and identify:
1. Rules that reference files or patterns that no longer exist in the codebase
2. Rules that contradict each other
3. Patterns we use frequently that are not documented in any rule
4. Rules that are too long (Cursor recommends keeping rules under 500 lines) and should be split

Output a summary of recommended changes.

Team Rules zarządzane z panelu

Plany Team i Enterprise dokładają Team Rules: reguły zarządzane centralnie z panelu Cursora i stosowane u wszystkich członków zespołu we wszystkich projektach.

Team Rules czy reguły projektu?

Zastosowanie	Team Rules	Reguły projektu
Standardy kodowania w całej organizacji	Tak	Nie
Wymogi bezpieczeństwa i zgodności	Tak	Nie
Wzorce architektoniczne konkretnego projektu	Nie	Tak
Konwencje związane z konkretną technologią	Nie	Tak
Preferencje co do stylu komunikacji	Tak	Nie

Jak je ustawić

Otwórz panel Cursora pod cursor.com/dashboard
Przejdź do zakładki z treściami zespołu
Kliknij “Add Rule”, żeby utworzyć nową regułę zespołową
Napisz regułę jako zwykły tekst (Team Rules nie obsługują globów, alwaysApply ani typów reguł)
Zdecyduj, czy regułę wymusić (blokuje wyłączenie jej przez członków zespołu)
Włącz regułę, żeby zaczęła działać

Która reguła wygrywa

Kolejność pierwszeństwa to Team Rules > reguły projektu > reguły użytkownika. Wymuszona Team Rule nadpisuje każdą sprzeczną regułę projektu czy osobistą i właśnie dlatego jest właściwym miejscem na standardy, które nie mogą się różnić: praktyki bezpieczeństwa, wzorce obsługi błędów, wymogi zgodności.

Ujednolicenie konfiguracji MCP

Jeśli zespół korzysta z serwerów MCP (baza danych, GitHub, Jira), zacommituj konfigurację, żeby każdy miał do dyspozycji te same narzędzia. Sięgaj po serwery utrzymywane — stare paczki npm @modelcontextprotocol/server-github i @modelcontextprotocol/server-postgres są oznaczone jako przestarzałe (“no longer supported”). Firmowy serwer GitHuba działa teraz jako zdalny endpoint, a referencyjny serwer Postgresa trafił do archiwum:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@henkey/postgres-mcp-server", "--connection-string", "${DATABASE_URL}"]
    }
  }
}

Wpis GitHuba korzysta z hostowanego github/github-mcp-server (https://api.githubcopilot.com/mcp/); w zespole odciętym od sieci albo hostującym u siebie podmień go na build Dockera ze stdio z tego samego repozytorium. Dla Postgresa utrzymywany i świadomy odczytu jest @henkey/postgres-mcp-server (albo postgres-mcp od crystaldby). Wymagane zmienne środowiskowe opisz w README albo w przewodniku onboardingowym — tokeny każdy podaje własne, ale konfiguracja serwerów jest wspólna.

Wspólne prompty i własne komendy

Pliki promptów, po które sięgnie każdy

Prompty, które zespół uruchamia raz po raz, zapisz jako pliki w repozytorium:

mkdir -p .cursor/prompts

Create a new API endpoint following these project conventions:

1. Route handler in src/api/[resource]/route.ts using the pattern in @src/api/users/route.ts
2. Service layer in src/services/[resource].ts using the pattern in @src/services/user.ts
3. Type definitions in src/types/[resource].ts
4. Vitest tests in src/services/__tests__/[resource].test.ts
5. Zod validation schema for request body
6. Proper error handling using our AppError class from @src/lib/errors.ts

Run pnpm test after implementation to verify everything passes.

Review and fix all issues before this PR is ready:

1. pnpm run typecheck -- fix TypeScript errors
2. pnpm run lint -- fix linting issues
3. pnpm run test -- fix test failures (do not modify assertions)
4. Remove any console.log/debug statements
5. Verify all new exports are added to index files
6. Check that no sensitive data (API keys, passwords) is committed

Summarize all changes made.

Członkowie zespołu wciągają je do dowolnej rozmowy z agentem przez @.cursor/prompts/new-endpoint.md. Prompt zapisuje konwencje zespołu, więc najnowsza osoba produkuje wynik w tym samym kształcie co ta z najdłuższym stażem.

Komendy slash do przepływów, które uruchamiają wszyscy

Własne komendy slash mieszkają w .cursor/commands/ i wywołuje się je przedrostkiem /. To właściwa forma dla przepływu bez argumentów, który wszyscy uruchamiają tak samo.

Utwórz .cursor/commands/review.md:

---
description: Review code changes for quality, security, and consistency
---

Review the current changes (use git diff to see them) and check for:

1. **Security**: SQL injection, XSS, hardcoded secrets, missing auth checks
2. **Error handling**: All async operations have try/catch, errors use AppError format
3. **Testing**: New logic has corresponding tests, edge cases are covered
4. **Patterns**: Code follows existing patterns in the codebase (check similar files)
5. **Performance**: No N+1 queries, no unnecessary re-renders, no blocking operations

For each issue found, provide:
- The file and line number
- What the issue is
- A specific fix

Use only search tools -- do not make any edits.

Oraz .cursor/commands/pr-description.md:

---
description: Generate a PR description from current changes
---

Analyze the current branch changes (compare against main) and generate a PR description with:

1. **Summary**: 2-3 sentence overview of what changed and why
2. **Changes**: Bulleted list of specific changes, organized by area
3. **Testing**: How these changes were tested
4. **Migration notes**: Any database changes, environment variable additions, or breaking changes

Use git diff main...HEAD to see all changes. Do not make any edits.

Onboarding nowego dewelopera

Większość onboardingu dzieje się przy klonowaniu: .cursor/rules/, .cursor/commands/ i .cursor/prompts/ przychodzą razem z repozytorium, a Team Rules z panelu stosują się same. Zostaje konfiguracja maszyny i kilka pierwszych godzin prowadzonej praktyki.

# Cursor Onboarding Checklist

## Day 1 Setup (2 hours)

1. Install Cursor: `brew install --cask cursor`
2. Import VS Code settings: Cmd+Shift+P > "Import VS Code Settings"
3. Install shell commands: Cmd+Shift+P > "Install cursor command in PATH"
4. Configure Auto-Run: Settings > Cursor Settings > Agents > Auto-Run. Choose Run in Sandbox (recommended) or Ask Every Time, and add the team Command Allowlist from this doc. Do not enable Run Everything.
5. Set default model to Claude Sonnet 5
6. Clone the repo and verify indexing completes (should take under 5 minutes)
7. Verify project rules load: open agent, ask "What rules apply to this project?"
8. Set up required environment variables for MCP servers

## Day 1 Practice (2 hours)

1. Use Cmd+K to add error handling to any function in the codebase
2. Use agent mode to implement a small bug fix from the backlog
3. Use @.cursor/prompts/pre-pr.md to run the pre-PR checklist
4. Try the Tab completion flow: write two test cases manually, let Tab generate the third
5. Generate a commit message using the sparkle icon in Source Control

## First Week

1. Complete one feature using the test-driven agent workflow
2. Use Ask mode to understand one unfamiliar module
3. Try a background agent for generating test coverage on a module
4. Review and improve one project rule based on your experience

Dwie rzeczy warto zrobić na żywo, a nie z listy: niech nowa osoba przejdzie jedno zadanie w trybie Ask, zanim dotknie trybu Agent, żeby najpierw zbudowała obraz bazy kodu, i usiądźcie razem do jej pierwszego zadania w trybie Agent, żeby pokazać, jak w tym repozytorium wygląda skuteczny prompt.

Jak nie dać praktyce zardzewieć

Oddaj Cursorowi pięć minut jednego cotygodniowego standupu. Co tydzień jedna osoba pokazuje prompt, który zadziałał wyjątkowo dobrze, znaleziony przepływ pracy, problem, którego nie umiała rozwiązać (zespół zwykle umie), albo propozycję nowej reguły projektu.

To właśnie ta pętla zwrotna nie pozwala wspólnej konfiguracji zwietrzeć: najlepsze prompty lądują w .cursor/prompts/, powtarzające się poprawki zamieniają się w reguły, a do przodu idzie cały zespół, a nie jeden entuzjasta.

Zespołowe review kodu wygenerowanego przez AI

Kod wygenerowany przez AI wymaga innego spojrzenia w review. Agent dobrze trzyma się wzorców, ale gubi logikę biznesową, wprowadza luki bezpieczeństwa i przekombinowuje proste rzeczy.

Na co patrzeć w PR-ach pisanych przez AI

Zmyślone importy: paczki, których nie ma w zależnościach
Niespójne wzorce: inny wzorzec niż ten, który już istnieje, zwłaszcza tam, gdzie reguły są niepełne
Pominięte przypadki brzegowe: ścieżka szczęśliwa obsłużona dobrze, ścieżki błędów wcale
Przekombinowanie: abstrakcje, cache albo obsługa błędów, których ta funkcja jeszcze nie potrzebuje
Martwe pola bezpieczeństwa: SQL injection przez sklejanie stringów, brak sprawdzeń autoryzacji, testowe dane logowania zostawione w kodzie produkcyjnym

Potok wstępnego review

Zanim poprosi o review człowieka, każdy przepuszcza zmiany przez przebieg AI:

Deweloper kończy funkcję
Uruchamia @.cursor/prompts/pre-pr.md, żeby poprawić lintera, typy i testy
Odpala Bugbota na gałęzi albo PR-ze (automatyczne wykrywanie błędów w Cursorze)
Uruchamia zespołowy prompt review opisany niżej
Naprawia wszystko, co wyszło w krokach 2-4
Otwiera PR-a do review przez człowieka

Takie wstępne review wyłapuje większość rzeczy, które i tak zgłosiłby człowiek, dzięki czemu człowiek patrzy na decyzje architektoniczne, poprawność logiki biznesowej i kompromisy projektowe — dokładnie tam, gdzie AI jest najsłabsze.

Prompty, które to napędzają

Zapisana komenda /review powyżej to wersja na co dzień. Dłuższy prompt wklej wtedy, gdy chcesz, by review wprost sięgnęło po zacommitowane reguły i polowało na naruszenia architektury w rodzaju zależności cyklicznych:

@git diff main

Review this PR as a senior engineer on this team. Reference our project rules in @.cursor/rules/ for standards.

Check for:
1. Architecture violations (direct database access from routes, circular dependencies)
2. Missing error handling on async operations
3. Type safety issues (any types, missing null checks)
4. Test coverage gaps for new functionality
5. Naming inconsistencies with existing code
6. Security issues (unvalidated input, exposed credentials, SQL injection)

For each issue found, explain why it matters and suggest a specific fix.

Ostatnie sprawdzenie przed wystawieniem PR-a jest węższe i mechaniczne — dotyczy rzeczy wstydliwych, a nie architektonicznych:

Prompt copy-paste do autoreview przed wystawieniem PR-a:

Before I submit this PR, review all my changes and check for:

1. Any imports of packages not in package.json
2. Any TODO comments or placeholder values I need to fill in
3. Any console.log statements that should use the logger
4. Any hardcoded URLs, API keys, or test values
5. Any missing error handling on async operations
6. Any new files that are missing test coverage

Run `npm run build` and `npm test` to verify everything passes.

Polityka bezpieczeństwa dla narzędzi AI

Spisz politykę jako regułę, żeby egzekwował ją ten sam mechanizm co resztę, i omawiaj ją przy onboardingu:

## AI Security Policy

### What the AI Can Access
- All source code in the repository
- Development and staging databases via MCP (never production)
- Public documentation and APIs
- CI/CD logs and build artifacts

### What the AI Must Not Do
- Access production databases or servers
- Commit or push code without human review
- Store API keys, passwords, or secrets in code
- Disable security middleware or authentication checks
- Modify .env files or deployment configurations

### Privacy Requirements
- Enable Privacy Mode for all proprietary code
- Do not paste customer data into agent conversations
- Do not reference internal company documents by URL
- Review all AI-generated code for accidentally exposed credentials

### Auto-Run Restrictions
- Set Auto-Run Mode to Run in Sandbox or Ask Every Time. Never enable Run Everything.
- Restrict the Command Allowlist to test, build, lint, and file-creation commands only.
- Keep git push, deploy, npm publish, and any credential-touching commands off the allowlist so they always require approval.
- Do not rely on a denylist. Cursor deprecated the command denylist in 1.3 (it was trivially bypassable); the sandbox plus a tight allowlist is the supported safety model.

Na planie Team albo Enterprise przenieś nienegocjowalną połowę tego do wymuszonej Team Rule. Standard bezpieczeństwa, który każdy może sobie wyłączyć w ustawieniach, jest sugestią, a nie standardem.

Gdy zespołowe konwencje przestają działać

Ludzie dostają różne wyniki mimo wspólnych reguł. Reguły użytkownika mają najniższe pierwszeństwo, więc nie nadpiszą Team Rules ani reguł projektu, ale lokalne, niezacommitowane pliki reguł wciąż mogą grać. Poszukaj plików reguł, które nigdy nie trafiły do repozytorium, a tam, gdzie osobista preferencja naprawdę kłóci się z regułą projektu, rozstrzygnijcie to zespołowo i zaktualizujcie regułę, zamiast utrzymywać obie.

Reguły wietrzeją razem z rozwojem bazy kodu. Zrób z aktualizacji reguły część samej zmiany: refaktorujesz wzorzec, do którego reguła się odwołuje — poprawiasz regułę w tym samym PR-ze.

Zbyt wiele reguł spowalnia agenta. Reguły zjadają tokeny kontekstu. Trzydzieści reguł z alwaysApply: true oznacza, że każda rozmowa startuje z sporym narzutem. Przejrzyj, które naprawdę muszą działać zawsze, a które wystarczy zawęzić globem albo zostawić decyzji agenta.

Review AI za bardzo hałasuje. Dopisz do promptu swoje wyjątki: “Our project intentionally uses ‘any’ types in the GraphQL resolver layer — do not flag these.” Im konkretniejszy prompt, tym mniej fałszywych alarmów i tym większa szansa, że ludzie będą go dalej uruchamiać.

Nikt nie wie, jakie komendy istnieją. Przedrostek / wylistuje je w czacie, ale nowe osoby nie wiedzą, żeby tam zajrzeć. Opisz je w README albo w przewodniku dla kontrybutorów, obok plików promptów.

Lista onboardingowa się dezaktualizuje. Przypisz jedną osobę do jej aktualizowania przy każdym większym wydaniu Cursora albo zmianie przepływu pracy i przeglądaj ją co najmniej raz na kwartał.

Tokeny do serwerów MCP wygasają. Ustaw przypomnienia w kalendarzu i opisz proces rotacji w przewodniku onboardingowym. Krótko żyjące tokeny z firmowego systemu zarządzania sekretami są lepsze niż długowieczne w .env.

Dokąd dalej ze współpracą zespołową

Własne reguły i szablony — głębiej o budowaniu reguł, których potrzebuje twój zespół
Prywatność i bezpieczeństwo — egzekwuj praktyki bezpieczeństwa przez Team Rules
Zarządzanie tokenami — panuj nad kosztami w zespole korzystającym z Cursora
Code review — powierzchnie review, w które wpina się ten potok