Vývoj s pomocí AI

Tento starter je postavený tak, aby ho obsluhovali AI kódovací agenti (Cursor, Claude, Copilot, Windsurf, ChatGPT, …). Přináší malý „operační systém“ instrukcí, kanonickou znalostní bázi designu a přenositelné auditní prompty, takže agent — nebo vy — můžete provádět změny, které zůstávají on-system místo aby se rozjížděly.

Co agent čte

Každý nástroj si vezme svůj vlastní instrukční soubor, ale všechny míří na stejná pravidla:

Soubor	Používá	Účel
AGENTS.md	Cursor, Codex, většina agentů	Univerzální zadání: architektonické vrstvy, tvrdá pravidla, verifikační příkazy
.cursor/rules/*.mdc	Cursor	Pravidla projektu (architecture, design-system) aplikovaná automaticky
.cursor/hooks/ + .cursor/hooks.json	Cursor	Ochranné hooky, které označí úpravy mimo konvence
.windsurfrules	Windsurf	Stejná pravidla ve formátu Windsurfu
.github/copilot-instructions.md	GitHub Copilot	Stejná pravidla pro Copilot Chat
.agents/skills/ + .agent-skills.lock.md	Agenti podporující skills	Skills v rámci projektu; lock soubor pinuje zrevidované skills (kontrolováno v CI)

Znalostní báze designu

Designová rozhodnutí jsou centralizovaná, takže agent nikdy nemusí hádat:

• system/globals/ — jediný zdroj pravdy pro barvy, typografii, mezery, interakci, obrazovost, efekty, responzivitu, přístupnost a katalog komponent/ vzorů. Přečtěte si je před jakoukoli prací na UI.
• src/config/site.config.ts — vstup pro váš vlastní brand. Hodnoty brandu jsou překládány do designových tokenů, nikdy nejsou vkládány natvrdo.
• src/registry.json — strojově čitelný katalog každé komponenty, sekce a stránky.

Architektura (tři vrstvy): komponenty (src/components/ui/**) → sekce (src/components/sections/**) → stránky (src/pages/**). Stránky stavějte skládáním sekcí; sekce stavějte z komponent.

Tvrdá pravidla (co znamená „on-system“)

• Jen tokeny. Barvy/mezery/typografie pocházejí z designových tokenů — žádné natvrdo psané hex/rgb, žádné surové utility z Tailwind palety (bg-blue-500). Používejte sémantické tokeny jako bg-primary, text-foreground, var(--muted-foreground).
• Dark mode zůstává funkční. Class strategie; nikdy nesměte barvy invertovat ručně.
• Zachovejte průřezové funkce. i18n (výchozí angličtina, locale routing připravený pod src/pages/[locale]/), SEO/OG/RSS/sitemap, Pagefind vyhledávání a Starlight dokumentace.
• Obsah žije v Kafe-CMS. Blogové příspěvky a stránky pocházejí z CMS — viz Správa obsahu. Nepiště natvrdo texty stránek, které patří do kolekce.

Ověřte než prohlásíte „hotovo“

Požádejte agenta, aby toto spustil a opravil cokoli, co selže:

pnpm build          # kompletní server build
pnpm lint           # eslint + stylelint + type-check + KPIs + i18n + secrets
pnpm run check:kpis # kontroly designových konvencí (on-system zdroj pravdy)

Promptování

Zahájení úkolu

Nejprve nasměrujte agenta na systém, pak uveďte cíl:

Read AGENTS.md and system/globals/ before editing.
Add a "Logos" section to the homepage that reuses existing components and tokens.
Keep dark mode and i18n intact, then run `pnpm build` and `pnpm lint`.

Prompty pro self-audit

system/prompts/ obsahuje přenositelné prompty, které můžete vložit do libovolného chat nástroje a zauditovat projekt proti jeho konvencím. Odkazují na system/globals/ a skript check:kpis.

Prompt	Auditovaná oblast
system/prompts/tokens.md	Natvrdo psané barvy / používání mimo tokeny
system/prompts/accessibility.md	WCAG AA: klávesnice, focus, alt texty, landmarky
system/prompts/responsive.md	Integrita layoutu od 375–1920px
system/prompts/darkmode.md	Parita a kontrast dark módu
system/prompts/performance.md	Islands, assety, Lighthouse
system/prompts/seo.md	Metadata, OG, sitemap, strukturovaná data

Příklad:

Run the audit in system/prompts/accessibility.md against src/pages/contact.astro
and list concrete fixes with file:line references.

Udržování zrevidovaných skills

Skills projektu žijí v .agents/skills/. Zrevidovaná, zapinovaná sada je zaznamenaná v .agent-skills.lock.md; CI job Skills Verification reportuje zamčené skills při každém běhu. Přidejte nebo aktualizujte skill a poté obnovte lock soubor, aby spolupracovníci (a CI) viděli stejnou zapinovanou sadu.