CLAUDE.md: Nejdůležitější soubor vašeho AI projektu

Spustíte Claude Code na novém projektu. Napíšete prompt. AI vygeneruje kód — funkční, ale špatně. Jiná konvence pojmenování, komponenty ve špatné složce, inline styly místo Tailwindu. Strávíte 20 minut opravováním toho, co AI mohla udělat správně hned.

Tento problém nemá nic společného s kvalitou Claude Code. Má co do činění s tím, že jste AI nedali kontext.

CLAUDE.md tento problém řeší. Je to konfigurační soubor, který Claude Code načte jako první — ještě než zpracuje váš první prompt. Všechno, co tam napíšete, je pro AI “zákon projektu”.

Proč CLAUDE.md nestačí ignorovat

Claude Code je agenční nástroj. Nečeká na instrukce krok za krokem — autonomně čte codebase, rozhoduje a provádí změny. Bez kontextu si tento autonomní přístup doplňuje domněnkami.

A domněnky jsou v produkčním projektu drahé.

Praktický dopad: vývojáři, kteří používají CLAUDE.md správně, reportují o 60-70 % méně iterací při generování kódu. Pracující feature za 30 minut místo 90 minut s back-and-forth opravami. Čísla z reálných projektů, ne marketingový slogan.

CLAUDE.md není dokumentace pro lidi. Je to onboarding pro AI. Pište ho tak.

Anatomie funkčního CLAUDE.md

Dobrý soubor pokryje čtyři oblasti. Každá má jiný účel.

1. Stack a technické závislosti

## Tech Stack
- Next.js 15 App Router (NE Pages Router)
- TypeScript strict mode, žádné `any`
- Tailwind CSS v4 — žádné inline styly, žádné CSS moduly
- Prisma ORM, PostgreSQL
- React Query pro server state, Zustand pro client state

Tohle není readme. Je to seznam pravidel. Claude Code si tato pravidla aktivně aplikuje — pokud napíšete “NE Pages Router”, AI bude App Router používat bez ptaní. Pokud to tam nemáte, může to být 50/50.

2. Architekturní konvence

## Struktura projektu
- Komponenty: `/components/[feature]/[ComponentName].tsx`
- Serverové actions: `/app/actions/[feature].ts`
- Utility funkce: `/lib/[domain].ts`
- Typy: vždy v `/types/` nebo inline v komponentě, NE globální `types.ts`

## Naming conventions  
- Komponenty: PascalCase
- Hooks: camelCase s prefixem `use`
- Serverové actions: camelCase sloveso + podstatné jméno (createUser, updatePost)

Bez tohoto sekce AI vymyslí strukturu sama. Někdy trefí vaší konvenci, někdy ne. V monorepu to může být katastrofa.

3. Co nedělat

Tohle je nejpodceňovanější část CLAUDE.md. Explicitní zákazy fungují lépe než implicitní pravidla.

## Zakázáno
- NIKDY nepoužívej `console.log` v produkčním kódu — místo toho logger z `/lib/logger.ts`
- NIKDY nepřidávej nové npm balíčky bez komentáře proč
- NIKDY neměň soubory v `/config/` bez mého potvrzení
- NEZJEDNODUŠUJ error handling — každá chyba musí být explicitně ošetřena

Tenhle seznam vychází z toho, co vás v projektu nejvíc bolí. Doplňujte ho průběžně.

4. Kontext projektu a business pravidla

## O projektu
E-commerce platforma pro B2B zákazníky. Uživatelé jsou procurement manažeři 
ve firmách, ne tech-savvy spotřebitelé.

## Kritické business pravidla
- Ceny se vždy zobrazují bez DPH (B2B standard)
- Minimální objednávka: 5 000 Kč
- Dostupnost produktů se načítá real-time z ERP (nikdy z cache)

Claude Code s tímto kontextem píše fundamentálně jiný kód než bez něj. Bude automaticky validovat minimální hodnoty objednávek, bude věčet na caching kde by to bylo špatně, bude navrhovat UI odpovídající B2B kontextu.

CLAUDE.md pro různé typy projektů

Next.js + Tailwind (nejčastější stack 2025/2026)

Klíčové věci, které tam nesmí chybět:

Explicitně App Router nebo Pages Router
Pravidla pro Server vs Client Components ('use client' jen kde nutné)
Způsob práce s environment variables
Jak řešit loading a error states

Monorepo (Turborepo, Nx)

CLAUDE.md dejte jak do root, tak do každého package zvlášť. Root soubor pokryje globální konvence, package-level soubory upřesní specifika každé aplikace. Claude Code je načte oba a správně aplikuje.

Design system / komponentová knihovna

Zaměřte se na:

Jak se pojmenovávají props (size vs variant vs appearance?)
Co patří do atomic vs molecular komponent
Jak se exportují typy

Jak CLAUDE.md udržovat živý

Největší chyba: napíšete CLAUDE.md jednou a zapomenete na něj.

Správný workflow je jiný. Pokaždé, když opravujete kód vygenerovaný Claude Code, ptejte se: “Proč to AI udělala špatně?” Pokud odpověď je “protože to nevěděla” — přidejte to do CLAUDE.md.

Za měsíc aktivního používání Claude Code budete mít CLAUDE.md, který pokryje 90 % edge cases specifických pro váš projekt. AI pak bude generovat kód, který skoro nepotřebuje review.

Konkrétní trigger pro update: kdykoli opravíte stejnou věc dvakrát, musí to jít do CLAUDE.md.

Pokročilé: CLAUDE.md pro týmy

Pokud Claude Code používá více lidí na stejném projektu, CLAUDE.md se stává sdílenou konvencí. Verzujete ho v gitu jako jakýkoli jiný soubor.

Přidejte sekci pro workflow:

## Git workflow
- Větve: `feature/`, `fix/`, `chore/` prefix
- Commit messages: Conventional Commits (feat, fix, docs, refactor)
- PR: vždy include testing checklist
- Claude Code NESMÍ commitovat přímo na main

Tato pravidla Claude Code aktivně respektuje — nebude vám dělat přímé commity na main, bude navrhovat správné commit messages.

Šablona pro začátek

Nechci vám dávat copy-paste šablonu, protože CLAUDE.md musí odpovídat vašemu projektu, ne generickému příkladu. Ale minimální struktura, od které začít:

# [Název projektu]

## Co tento projekt dělá
[Jedna věta]

## Tech stack
[Seznam technologií s explicitními verzemi]

## Architektura
[Struktura složek, naming conventions]

## Zakázáno
[Co AI nesmí dělat]

## Jak spustit projekt
[Development, build, test příkazy]

Tohle minimum zabrání 70 % problémů. Zbytek přidávejte iterativně.

Investice vs. návratnost

Napsání dobrého CLAUDE.md zabere 2-3 hodiny na projektu, který neznáte. Na projektu, kde pracujete, třeba 45 minut.

Návratnost: každý vývojář, který Claude Code na tom projektu použije, ušetří iterace od prvního dne. U týmu tří lidí se to vrátí do týdne.

Pokud Claude Code používáte a CLAUDE.md nemáte, nebo ho máte prázdný — to je low-hanging fruit, který stojí méně než jedno odpolední okno.

Pokud váháte, jak CLAUDE.md strukturovat pro váš konkrétní projekt, nebo chcete pochopit, kde ve vašem AI workflow ztrácíte čas, napište mi — rád se podívám na váš setup.

Pro hlubší audit toho, jak máte AI integrováno do vývoje, se hodí AI audit. Projdeme nejen CLAUDE.md, ale celý workflow od promptů po deployment.

Sdílejte článek

Pomohl vám článek? Sdílejte ho s kolegy, kterým by se mohl hodit.