Kompletny przewodnik po pliku CLAUDE.md: Jak 10x zwiększyć produktywność Claude Code

Czym jest plik CLAUDE.md i dlaczego ma znaczenie

Jeśli używasz Claude Code bez pliku CLAUDE.md, zostawiasz większość jego mocy na stole.

CLAUDE.md to plik konfiguracyjny Markdown, który Claude Code automatycznie czyta na początku każdej sesji. Mówi Claude'owi o architekturze twojego projektu, standardach kodowania, preferowanych narzędziach, wzorcach testowania i regułach przepływu pracy. Zamiast powtarzać te same instrukcje w każdej rozmowie, piszesz je raz, a Claude podąża za nimi za każdym razem.

Pomyśl o tym jak o różnicy między zatrudnieniem kontraktora, który nic nie wie o twojej firmie, a takim, który przeczytał cały podręcznik inżynierski. Plik CLAUDE.md jest tym podręcznikiem.

Dlaczego CLAUDE.md bije powtarzające się promptowanie

Same oszczędności tokenów są znaczące. Jeśli wydajesz 500 tokenów na ustawienie kontekstu na rozmowę i masz 20 rozmów dziennie, to 10 000 tokenów dziennie — czyli mniej więcej 0,15-0,75 USD dziennie zależnie od modelu. W ciągu miesiąca plik CLAUDE.md oszczędza ci 4,50-22,50 USD w surowych kosztach API, produkując jednocześnie lepsze wyniki.

Kredyty Anthropic | Kredyty AWS | Kredyty Google Cloud

---

Jak Claude Code czyta pliki CLAUDE.md

Claude Code szuka plików CLAUDE.md w określonej kolejności priorytetu. Zrozumienie tej hierarchii jest niezbędne do efektywnej organizacji instrukcji.

Kolejność ładowania plików

Claude Code łączy wszystkie obowiązujące pliki. Jeśli twój globalny plik mówi „używaj wcięć 2-spacjowych", a plik projektu mówi „używaj 4-spacjowych tabów", plik projektu wygrywa dla tego projektu.

Co gdzie idzie

Globalny CLAUDE.md (~/.claude/CLAUDE.md) — preferencje obowiązujące wszędzie:

# Global Preferences
- Always use TypeScript over JavaScript when possible
- Prefer functional components over class components in React
- Write concise commit messages under 72 characters
- Use ESM imports, never CommonJS require()

CLAUDE.md projektu (główny katalog projektu) — wszystko specyficzne dla tej bazy kodu:

# Project: Acme Dashboard
## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM with PostgreSQL
- Jest + React Testing Library for tests

## Architecture
- /app — Next.js routes (App Router only, no Pages Router)
- /components — reusable UI components
- /lib — business logic and utilities
- /prisma — database schema and migrations

---

Tworzenie pierwszego pliku CLAUDE.md

Oto setup krok po kroku, żeby zacząć z Claude Code i prawidłowo skonfigurowanym plikiem CLAUDE.md.

Krok 1: Zainstaluj Claude Code

npm install -g @anthropic-ai/claude-code

Krok 2: Stwórz CLAUDE.md w katalogu głównym projektu

touch CLAUDE.md

Krok 3: Dodaj podstawową konfigurację

Zacznij od tego minimalnego szablonu i rozszerzaj go w razie potrzeby:

# Project: [Your Project Name]

## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]

## Coding Standards
- [Indentation preference]
- [Naming conventions]
- [Import ordering]

## Rules
- Always write tests for new functions
- Never commit directly to main
- Use conventional commit messages

Krok 4: Uruchom Claude Code

claude

Claude Code automatycznie wykrywa i ładuje plik CLAUDE.md. Zobaczysz potwierdzenie w wyjściu sesji.

---

Szablony CLAUDE.md: startowy, zaawansowany i zespołowy

Szablon 1: Prosty projekt (20 linii)

Najlepszy dla solo deweloperów, projektów pobocznych i małych baz kodu.

# My App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest for testing

## Rules
- Use type hints on all function signatures
- Write docstrings for public functions
- Keep functions under 30 lines
- Use async/await for all database operations
- Format with black, lint with ruff

## Patterns
- Repository pattern for data access
- Pydantic models for request/response validation
- Dependency injection via FastAPI Depends()

Szablon 2: Zaawansowany pełnostackowy projekt (80+ linii)

Dla aplikacji produkcyjnych z wieloma deweloperami i złożoną architekturą.

# Acme SaaS Platform

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Database: PostgreSQL 16, Redis 7
- Infrastructure: Vercel (frontend), Railway (backend)
- Testing: Vitest, Playwright, MSW

## Architecture
All code follows Clean Architecture principles:
- /packages/web — Next.js frontend (App Router only)
- /packages/api — tRPC backend
- /packages/shared — shared types and utilities
- /packages/db — Prisma schema and client

## Coding Standards
- Strict TypeScript: no any, no ts-ignore
- All components must be functional with hooks
- Server Components by default, "use client" only when needed
- All API routes must have Zod input validation
- Database queries go through repository layer, never raw SQL

## Testing Requirements
- Minimum 80% coverage for new code
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
- Use MSW for API mocking, never mock fetch directly

## Git Workflow
- Conventional commits: feat:, fix:, chore:, docs:
- All PRs require passing CI before merge
- Squash merge to main
- Branch naming: feature/TICKET-123-description

## Security Rules
- NEVER hardcode secrets or API keys
- Always use environment variables for config
- Sanitize all user input
- Use parameterized queries (Prisma handles this)
- NEVER expose internal error details to clients

Szablon 3: Konfiguracja zespołowa (współdzielona przez git)

Dla zespołów chcących spójnego zachowania Claude Code u wszystkich członków.

# Team Engineering Standards — Acme Corp

## Overview
This file ensures Claude Code follows our team's engineering
standards. Committed to Git so all engineers get identical behavior.

## Code Review Checklist (Claude must follow before suggesting code)
1. Does this change have tests?
2. Are error cases handled?
3. Is the function documented?
4. Does it follow our naming conventions?
5. Are there any security implications?

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE (MAX_RETRIES)
- Database tables: snake_case (user_profiles)
- API routes: kebab-case (/api/user-settings)

## Forbidden Patterns
- DO NOT use console.log in production code (use our logger)
- DO NOT use any TypeScript escape hatches (any, @ts-ignore)
- DO NOT install new dependencies without justification
- DO NOT modify database schema without migration file
- DO NOT use default exports (use named exports only)

## Preferred Libraries (do not suggest alternatives)
- State management: Zustand (not Redux)
- Forms: React Hook Form + Zod (not Formik)
- HTTP client: native fetch (not Axios)
- Date handling: date-fns (not Moment.js)
- Animation: Framer Motion (not React Spring)

---

Porównanie: CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

Jeśli oceniasz narzędzia kodowania AI, zrozumienie, jak każde z nich obsługuje konfigurację, jest kluczowe.

Kluczowym wyróżnikiem Claude Code jest ekosystem wokół CLAUDE.md — hooki, niestandardowe polecenia, serwery MCP i wsparcie multi-agent zmieniają go z pliku konfiguracyjnego w pełny framework automatyzacji.

---

Hooki: automatyzacja przepływu pracy Claude Code

Hooki są konfigurowane w .claude/settings.json, nie w samym CLAUDE.md. Uruchamiają polecenia shell automatycznie przed lub po zdarzeniach Claude Code.

Struktura konfiguracji hooków

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

Najbardziej użyteczne wzorce hooków

Praktyczne przykłady hooków

Auto-formatowanie po każdej edycji pliku:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Uruchom testy dla zmienionych plików:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

Niestandardowe polecenia slash

Polecenia slash pozwalają tworzyć szablony promptów wielokrotnego użytku, wyzwalane pojedynczym poleceniem /.

Jak tworzyć polecenia slash

1. Stwórz katalog .claude/commands/ w swoim projekcie
2. Dodaj pliki Markdown — każdy plik staje się poleceniem
3. Użyj $ARGUMENTS jako placeholdera dla dynamicznego wejścia

Przykład: .claude/commands/review.md

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Missing error handling
4. Test coverage gaps

Code to review: $ARGUMENTS

Provide a severity rating (low/medium/high/critical) for each finding.

Użycie w Claude Code:

/project:review src/auth/login.ts

Użyteczne pomysły na polecenia slash

---

Serwery MCP: rozszerzanie możliwości Claude Code

Serwery MCP (Model Context Protocol) łączą Claude Code z zewnętrznymi narzędziami i usługami. Po prawidłowej konfiguracji Claude Code może odpytywać bazy danych, przeglądać sieć, zarządzać plikami, współdziałać z GitHub i wiele więcej — wszystko z poziomu sesji kodowania.

Jak skonfigurować serwery MCP

Serwery MCP są ustawiane w .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Najpopularniejsze serwery MCP dla deweloperów

Odnoszenie się do MCP w CLAUDE.md

Twój CLAUDE.md może instruować Claude Code, kiedy i jak używać podłączonych serwerów MCP:

## Available Tools
- Use the postgres MCP to check schema before writing migrations
- Use the github MCP to create PRs after completing feature branches
- Use the memory MCP to track progress on multi-step tasks

---

Wiralny setup z 27 agentami: jak inżynier Google zautomatyzował 80% swojej pracy

Na początku 2026 wątek na Twitterze inżyniera Google stał się wiralem, opisując, jak skonfigurował 27 wyspecjalizowanych agentów Claude Code do obsługi różnych części przepływu pracy. Każdy agent miał własny CLAUDE.md z wąskimi, skupionymi instrukcjami.

Kluczowe spostrzeżenie

Zamiast jednej ogólnej sesji Claude Code próbującej robić wszystko, rozłożył swoją pracę na wyspecjalizowane role. Każdy agent miał:

• Dedykowany CLAUDE.md z wiedzą specyficzną dla domeny
• Ograniczony dostęp do narzędzi (tylko to, czego ten agent potrzebuje)
• Jasne granice tego, czego powinien i nie powinien dotykać
• Specyficzne formaty wyjścia i standardy jakości

Przykładowy podział agentów

Jak zreplikować ten setup

Nie potrzebujesz 27 agentów, żeby skorzystać z tego wzorca. Zacznij od 3-5 wyspecjalizowanych konfiguracji:

1. Stwórz oddzielne pliki CLAUDE.md na rolę:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. Uruchom Claude Code z określoną konfiguracją:

# Use different profiles by combining global + agent-specific context
claude --profile frontend

3. Zdefiniuj jasne punkty przekazania:

Twój główny CLAUDE.md może odnosić się do tego, kiedy przełączać agentów:

## Agent Workflow
- Frontend changes: use the frontend agent profile
- API changes: use the backend agent profile
- After any code change: run the test agent
- Before merging: run the review agent

Dlaczego to działa

Podejście z 27 agentami działa z powodu fundamentalnej zasady w produktywności AI: wąski kontekst produkuje lepsze wyjście niż szeroki kontekst. Sesja Claude Code załadowana z 400 liniami instrukcji o frontendzie, backendzie, DevOps, testowaniu i dokumentacji będzie działać gorzej w każdym pojedynczym zadaniu niż jedna załadowana 50 wysoce istotnymi liniami.

---

Typowe błędy CLAUDE.md (i jak je naprawić)

Błąd 1: Bycie zbyt ogólnym

Źle:

Write good code that follows best practices.

Dobrze:

- Use TypeScript strict mode, no implicit any
- All functions must have JSDoc comments
- Error handling: wrap async operations in try/catch
- Max function length: 30 lines

Błąd 2: Przeładowanie instrukcjami

Umieszczanie 500+ linii instrukcji powoduje, że Claude Code obniża priorytet ważnych reguł. Utrzymuj CLAUDE.md skupiony.

Błąd 3: Brak kontroli wersji CLAUDE.md

Twój CLAUDE.md powinien być commitowany do gita. To zapewnia:

• Spójność zespołu
• Historia zmian i odpowiedzialność
• Łatwy rollback, jeśli instrukcje powodują problemy
• Code review zmian instrukcji

Błąd 4: Ignorowanie sekcji bezpieczeństwa

Zawsze dołączaj reguły bezpieczeństwa do CLAUDE.md:

## Security (CRITICAL — never ignore)
- NEVER hardcode API keys, tokens, or passwords
- NEVER commit .env files
- ALWAYS use parameterized database queries
- ALWAYS validate and sanitize user input
- NEVER expose stack traces or internal errors to users

Błąd 5: Zapominanie o wzmiance o stosie technologicznym

Claude Code może wnioskować o twoim stosie z kodu, ale wyraźne deklaracje zapobiegają błędnym założeniom:

## Stack (authoritative — do not infer differently)
- Runtime: Node.js 22 (NOT Deno, NOT Bun)
- Framework: Next.js 15 App Router (NOT Pages Router)
- ORM: Prisma (NOT Drizzle, NOT TypeORM)
- Package manager: pnpm (NOT npm, NOT yarn)

---

Najlepsze praktyki Claude Code: wskazówki dla power użytkowników

Wskazówka 1: Używaj instrukcji warunkowych

## Environment-Specific Rules
- In development: use verbose logging, skip minification
- In production: no console.log, enable all optimizations
- In CI: run full test suite, fail on any warning

Wskazówka 2: Definiuj formaty wyjścia

## When I ask for a code review, respond with:
1. **Summary** (1-2 sentences)
2. **Issues found** (bulleted, severity-tagged)
3. **Suggested fixes** (with code snippets)
4. **Overall grade** (A/B/C/D/F)

Wskazówka 3: Ustaw granice dla zależności

## Dependency Rules
- NEVER install packages with fewer than 1,000 weekly downloads
- NEVER install packages with known CVEs
- Prefer built-in Node.js APIs over third-party packages
- Always check bundle size impact before adding frontend deps

Wskazówka 4: Używaj plików pamięci dla długich projektów

## Memory
- Track all completed features in .claude/memory/features.md
- Log all architecture decisions in .claude/memory/decisions.md
- Update progress after each session

Wskazówka 5: Integruj z CI/CD

Twój CLAUDE.md może instruować Claude Code, żeby respektował twój pipeline CI:

## Before pushing any code:
1. Run `pnpm lint` — fix all errors
2. Run `pnpm test` — all tests must pass
3. Run `pnpm build` — build must succeed
4. Check bundle size — must not exceed 250KB

---

Ile kosztuje Claude Code? (I jak zdobyć kredyty)

Claude Code używa kredytów API, co oznacza, że twoje koszty zależą od tego, którego modelu używasz i ile kontekstu mu dajesz.

Rozbicie kosztów Claude Code

Typowy intensywny dzień Claude Code zużywa 500K-2M tokenów, kosztując 2-30 USD w zależności od wyboru modelu. Dobrze skonfigurowany CLAUDE.md redukuje użycie tokenów, eliminując powtarzający się kontekst.

Zdobywanie darmowych kredytów na Claude Code

Najlepszym sposobem finansowania użycia Claude Code są programy kredytowe:

Łączne kredyty do stakowania: do 230 000+ USD we wszystkich programach.

Kredyty Anthropic | Kredyty AWS | Kredyty Google Cloud | Kredyty Azure

Pojedynczy plik CLAUDE.md w połączeniu z 5 000-25 000 USD w kredytach startupowych daje ci 3-6 miesięcy intensywnego rozwoju Claude Code przy zerowym koszcie. Przeglądaj wszystkie dostępne programy kredytowe w ClaimAICredits, żeby znaleźć to, do czego się kwalifikujesz.

---

Szybkie odniesienie: ściągawka CLAUDE.md

---

Zacznij już dziś

Plik CLAUDE.md to pojedyncza najwyższa dźwignia konfiguracyjna, jaką możesz ustawić dla rozwoju wspomaganego AI. Zacznij od prostego szablonu z tego przewodnika, commituj go do swojego repo i iteruj na podstawie tego, co działa dla twojego przepływu pracy.

Inżynierowie uzyskujący największą wartość z Claude Code nie piszą lepszych promptów — piszą lepsze pliki CLAUDE.md. Wiralny setup z 27 agentami udowadnia, że przemyślana konfiguracja bije brutalne promptowanie za każdym razem.

Jeśli koszty API Claude Code powstrzymują cię przed eksperymentowaniem z zaawansowanymi setupami jak przepływy multi-agent, eksploruj darmowe programy kredytowe dostępne przez ClaimAICredits. Stakowanie kredytów od Anthropic, AWS i Google Cloud może dać ci miesiące darmowego czasu rozwoju do udoskonalenia konfiguracji CLAUDE.md.