CLAUDE.md jako mozek projektu

Proč je CLAUDE.md nejdůležitější soubor v projektu

CLAUDE.md je soubor, který Claude Code čte automaticky při startu každé konverzace. Je to váš způsob, jak AI říct: 'Takhle funguje tento projekt, tyhle jsou pravidla, takhle se tu pracuje.' Bez něj Claude Code pracuje naslepo — hádá konvence, neví o vaší architektuře a opakovaně se ptá na věci, které byste mu mohli říct jednou.

Dobrý CLAUDE.md dramaticky změní kvalitu výstupů. Špatný CLAUDE.md je horší než žádný — zahltí kontext irelevantními informacemi a plýtvá tokeny. V této lekci se naučíte navrhnout CLAUDE.md, který funguje.

Tři vrstvy konfigurace

Claude Code má třívrstvý systém konfigurace. Každá vrstva má jiný scope a jiný účel. Pochopení tohoto systému je klíčové — většina lidí používá jen jednu vrstvu a přichází o 80 % potenciálu.

1. Globální CLAUDE.md (~/.claude/CLAUDE.md)

Soubor v domovském adresáři. Platí pro VŠECHNY projekty, na kterých pracujete. Sem patří vaše osobní preference — formátovací pravidla, preferovaný jazyk, nástroje které používáte, váš coding style. Neměňte ho pro každý projekt — to je antipattern.

# ~/.claude/CLAUDE.md

## Preferences
- Piš kód v angličtině, komentáře v češtině
- Preferuji funkcionální přístup před OOP kde to dává smysl
- Vždy používej type hints v Pythonu
- Commituj s Conventional Commits formátem

## Tools
- Package manager: uv (nikdy pip)
- Formatter: ruff
- Test runner: pytest

## Communication
- Odpovídej stručně, neomlouvej se
- Když si nejsi jistý, udělej to a ukaž mi výsledek

2. Projektový CLAUDE.md (./CLAUDE.md)

Soubor v kořeni projektu. Commituje se do gitu — sdílí ho celý tým. Obsahuje informace specifické pro projekt: architekturu, konvence, API endpoints, deployment postup. Toto je zdaleka nejdůležitější vrstva.

# MyApp Backend

Django + Django Ninja REST API.

## Quick Start
    docker compose up -d db
    uv run python manage.py migrate
    uv run python manage.py runserver 0.0.0.0:8000
    uv run pytest
    uv run ruff check .

## App Structure
    app_name/
      models.py
      api/
        routers.py         # Django Ninja Router
        endpoint_name.py   # Jeden soubor per endpoint group
        schemas.py         # Pydantic schemas
      tests/
        test_*.py

## Testing Rules
- ALL tests MUST hit a real Postgres database
- NO mocking of models, ORM queries, or database operations
- Mocking is ONLY allowed for 3rd party HTTP API calls

## Architecture Notes
- Global ObjectDoesNotExist handler — no try/except in endpoints
- Two NinjaAPI instances — public + internal with API key auth
- Trailing slash enforcement via APPEND_SLASH=True

3. Uživatelský projektový CLAUDE.md

Soubor v ~/.claude/projects/<cesta-k-projektu>/CLAUDE.md. Toto je vaše osobní konfigurace pro konkrétní projekt — necommituje se, nevidí ji kolegové. Ideální pro lokální development nastavení, vaše poznámky, nebo instrukce které nechcete sdílet s týmem.

# ~/.claude/projects/-Users-karel-myapp/CLAUDE.md

## Moje lokální setup
- Dev server běží na portu 8008 (ne default 8000)
- Používám branch naming: karel/<ticket-id>-<popis>

## Aktuální kontext
- Pracuji na refactoru payment systému
- Comgate API credentials jsou v .env.local

Co do CLAUDE.md patří

• Quick start příkazy — jak rozjet projekt, jak spustit testy
• Adresářová struktura — kde co žije, jak jsou organizovány soubory
• Konvence — naming, formátování, patterns které projekt používá
• Testovací pravidla — co mockovat, co ne, jak psát testy
• Architektonická rozhodnutí — proč je kód organizovaný tak jak je
• API přehled — endpointy, auth, klíčové flows
• Deployment postup — jak nasadit, jaké jsou prostředí

Co do CLAUDE.md NEPATŘÍ

• Celý zdrojový kód — Claude Code si ho přečte sám když potřebuje
• Detailní API dokumentace — tu generujte z kódu (OpenAPI)
• Historie změn — na to je git log
• TODO listy — ty patří do issue trackeru
• Citlivé údaje — hesla, API klíče, tokeny

Jak Claude Code čte CLAUDE.md

Claude Code čte CLAUDE.md soubory automaticky na začátku každé konverzace. Pořadí je: globální → projektový → uživatelský projektový. Všechny tři se zřetězí do systémového promptu. To znamená, že pozdější soubory mohou přepisovat instrukce z dřívějších — projektový CLAUDE.md může přepsat globální preference.

Direktiva @import

CLAUDE.md podporuje direktivu @soubor, která vloží obsah jiného souboru. To je extrémně užitečné pro organizaci — místo jednoho obřího souboru máte modulární strukturu.

# ~/.claude/CLAUDE.md

@RTK.md
@coding-style.md

## Memory maintenance
When you change project infrastructure, update the memory files.

Importovaný soubor se vloží na místo direktivy. Můžete mít separátní soubory pro různé oblasti — nástroje, coding style, workflow pravidla — a importovat je z hlavního CLAUDE.md.

Reálný příklad: produkční CLAUDE.md

Následující příklad je zjednodušená verze reálného CLAUDE.md z produkčního Django projektu. Všimněte si struktury — začíná tím nejdůležitějším (jak rozjet projekt) a postupuje k detailům.

# PraktickAI Backend

Django + Django Ninja REST API for auth, courses, payments.

## Quick Start
    docker compose up -d db
    uv run python manage.py migrate
    uv run python manage.py runserver 0.0.0.0:8008
    uv run pytest
    uv run ruff check .
    uv run mypy .

## Testing Rules
- ALL tests MUST hit a real Postgres database
- NO mocking of models or ORM queries — ever
- Mocking ONLY for 3rd party HTTP APIs (Comgate via respx)
- Every endpoint: success, validation errors, auth errors, edge cases

## Content System (i18n)
Content lives in files, not the database.
```
content/courses/ai-start/
  _course.json          # Shared: slug, difficulty, price
  cs/_meta.json          # Czech: title, description
  cs/01-lesson.json      # Czech lesson content
  en/_meta.json          # English metadata
  en/01-lesson.json      # English lesson content
```

## Key Patterns
- Global ObjectDoesNotExist handler — no try/except boilerplate
- Two NinjaAPI instances — public (JWT) + internal (API key)
- Trailing slash enforcement — APPEND_SLASH=True
- Non-root Docker — app user, gunicorn with access logs

Anti-patterns: co nedělat

• Příliš dlouhý CLAUDE.md (500+ řádků) — plýtvá tokeny, důležité informace se ztrácí v šumu
• Duplikace kódu — nepaste celé soubory, Claude Code si je přečte sám
• Vágní instrukce ('piš dobrý kód') — buďte specifičtí ('používej select_related pro ForeignKey')
• Zastaralé informace — CLAUDE.md musí být aktuální, jinak AI dělá chybná rozhodnutí
• Instrukce které nikdy nepoužijete — pokud se na to Claude Code neptá, nepotřebuje to vědět