Markdown soubory (proto .md) jsou dokumentace projektu – to první, co uvidí kolega, přispěvatel nebo za půl roku vy sami, až zapomenete, jak to celé funguje. Pár z nich je povinná výbava, zbytek přidáváte podle toho, jak je projekt velký a jestli je veřejný. A extrémně důležité jsou pro vibe coding, tady pro AI co umí programovat.
Které .md soubory patří do (skoro) každého projektu
Must-have
README.md – vstupní brána projektu. GitHub i GitLab ho automaticky vykreslí na úvodní stránce repozitáře. Měl by odpovědět na tři otázky dřív, než návštěvník odroluje: co to je, k čemu to je, jak to spustím. Když (v repu) není nic jiného, tohle tam být musí.
LICENSE – sice většinou bez přípony .md, ale patří do stejné skupiny. Bez licence totiž platí, že dílo je plně chráněné a nikdo ho nesmí legálně použít – i u „veřejného“ projektu na GitHubu. Pokud chcete, aby to lidi směli používat, licenci doplňte (MIT, Apache-2.0, GPL…). Samozřejmě pokud je daná věc čistě váš internetí projekt a nikdy nepůjde “ven”, tak licenční pravidla třeba nejsou.
TIP: Čím začít? No právě hlavně s README.md a LICENSE. Zbytek přidávejte, až ho reálně bude potřeba – prázdný CONTRIBUTING.md (viz dále) nikomu nepomůže.
Nice-to-have
Tyhle se vyplatí přidat, jakmile projekt přeroste „skript jen pro mě“:
- CHANGELOG.md – přehled změn po verzích. Ušetří dohledávání „kdy se tohle rozbilo“. Osvědčený formát: Keep a Changelog + sémantické verzování.
- CONTRIBUTING.md – jak přispět: jak rozjet vývojové prostředí, styl commitů, jak poslat pull request. GitHub na něj sám odkáže, když někdo zakládá PR.
- SECURITY.md – kam nahlásit bezpečnostní chybu. GitHub z něj udělá samostatnou záložku „Security“.
- CODE_OF_CONDUCT.md – pravidla chování v komunitě. U veřejných projektů s víc přispěvateli skoro standard.
- AUTHORS.md / CONTRIBUTORS.md – kdo se na projektu podílel.
Novější přírůstek: instrukce pro AI
Když s projektem pracuje AI agent (Claude Code, Copilot a spol.), hodí se soubor s instrukcemi přímo pro něj:
- CLAUDE.md (Claude Code) nebo AGENTS.md (obecnější, napříč nástroji sdílený standard) kontext projektu, konvence, čemu se vyhnout. Agent si ho načte automaticky a nemusíte mu totéž opakovat v každém promptu.
AGENTS.md i CLAUDE.md držte krátké a konkrétní (build a test příkazy, cesty k souborům, „dělej tohle, tamto ne“). Nemá opakovat README ani to, co si agent domyslí ze samotného projektu. Dlouhý a obecný soubor spíš uškodí, než pomůže (bude stát víc tokenů).
Kam ty soubory dát
GitHub je hledá v kořeni repa, ve složce .github/ nebo docs/. Když je dáte do .github/, kořen zůstane čistý.
Speciálně se chovají i šablony: .github/PULL_REQUEST_TEMPLATE.md a složka .github/ISSUE_TEMPLATE/ předvyplní text nového PR nebo issue.
Pokud neřešíte GitHub, tak to klidně dávejte do kořene projektu.
TIP: Vibe coding aplikace umí výše uvedené soubory běžně vytvořit i “od nuly”. Takže pokud na ně v návalu “chci něco zkusit nechat naprogramovat” zapomenete, stačí si prostě Codexu/Claude Code říct o vytvoření konkrétních .md souborů. A pak už jen projít a ručně doladit (pokud to bude třeba).
Best practices
Jeden zdroj pravdy. Neopisujte tytéž informace do víc souborů, radši mezi nimi odkazujte. Duplicity se dřív nebo později rozejdou.
Relativní odkazy (./docs/setup.md), ať fungují na GitHubu i lokálně.
README píšete pro nováčka, ne pro sebe, kdo kód zná. Nejčastější osnova: název → k čemu to je → instalace → použití → konfigurace → licence.
Dokumentaci měňte spolu s kódem. Zastaralá dokumentace je horší než žádná, protože klame. AI agenti to umí dělat dobře za vás.
Držte to stručné. Dlouhé texty přesuňte do docs/, README nechte přehledné a naskenovatelné.
Badges s mírou – pár užitečných (build, verze, licence) ano, řada dvaceti odznáčků spíš odrazuje.
Kam dál
Make a README – návod, jak napsat README, s editovatelnou šablonou a živým náhledem. Nejrychlejší start.
Best-README-Template – asi nejpopulárnější hotová šablona READMEmu na GitHubu. Zkopírujete BLANK_README.md a upravíš.
awesome-readme – kurátorovaný seznam povedených READMEmů reálných projektů. Dobré pro inspiraci, jak to dělají ostatní.
Standard Readme – specifikace, jak má „standardní“ README vypadat, včetně příkladů a lintru. Když chceš mít v tom systém.
Keep a Changelog – standard pro CHANGELOG.md (existuje i v češtině). Vysvětluje, co do changelogu patří a co ne.
Contributor Covenant – hotový, široce používaný CODE_OF_CONDUCT.md. Stačí zkopírovat a doplnit kontakt.
Instrukce pro AI (AGENTS.md / CLAUDE.md): kam dál
agents.md – oficiální stránka standardu AGENTS.md včetně ukázkového souboru, který si zkopíruješ a upravíš. Formát čte většina nástrojů (Codex, Copilot, Cursor, Gemini).
Memory (Claude Code) – oficiální dokumentace Anthropicu ke CLAUDE.md. Vysvětluje, kam soubor patří, jak se načítá a jak do něj přes @cesta importovat další soubory.
awesome-claude-md – přes sto reálných CLAUDE.md z veřejných projektů, roztříděných a okomentovaných. Přesně to, když chceš vidět, jak to píšou ostatní.
Další tipy týkající se AI (ChatGPT a další)
