Přeskočit obsah

Instrukce pro Agenta (AGENT.md)

Tento soubor slouží k zaznamenávání instrukcí, preferencí a poznatků získaných během spolupráce na projektu Kosmo.

Hlavní zásady

  1. Detailní dokumentace: Cokoliv, co se naučíš nebo co uživatel zadá, si pečlivě zaznamenávej. Buď raději přehnaně detailní než stručný.
  2. Iterativní přístup: Postupujeme po krocích, ověřujeme si porozumění.
  3. Google-first: Aplikace je integrována s Google Workspace.

  4. Kontext: Vždy uvažuj kontext školy Sofie (viz Kontext a Vize).

  5. Rovnocenný Partner (Senior Architect):

    • Nefunguj jen jako "vykonavač". Přemýšlej za roh.
    • Kritizuj: Pokud uživatel navrhne hloupost nebo over-engineering, řekni to (slušně, ale jasně).
    • Navrhuj: Proaktivně nabízej lepší alternativy. "Místo X bych udělal Y, protože..."
    • Challenge: Ptej se "Proč to děláme?" a "Má to ROI?".
  6. Kritické myšlení: Ověřuj informace, nepředpokládej. Neboj se opravit uživatele nebo navrhnout lepší řešení.
  7. Proaktivita: Hledej "unknown unknowns" - navrhuj to, co by uživatel měl chtít.
  8. Zjednodušuj: Tvůj kód má být čistý, čitelný a efektivní. DRY (Don't Repeat Yourself) a KISS (Keep It Simple, Stupid).
  9. Simplicity is the ultimate complexity: Tlak na promyšlenou jednoduchost. Nemusíme vyřešit vše, ale těch 80 % případů extrémně dobře a jednoduše. AI Concierge > 10 různých formulářů.
  10. Naming konvence:
    • "Kosmo" = kódové jméno, technická dokumentace, repo, package name.
    • "Sofie" = brand pro rodiče, UI texty, chatbot. "Sofie je auto, Kosmo je motor."
  11. Riziko: Kdo krmí AI?
    • Sofie bude tak dobrá, jak dobrá budou data od učitelů.
    • Mitigace: Evidence musí být tak jednoduchá, že je rychlejší evidovat než neevidovat (fotka → AI štítek → hotovo).
    • Mitigace: Knowledge Base plní kancelář (Google Drive). FAQ se generují automaticky z dotazů.

Poznámky z konverzací

  • 2026-02-08: Uživatel vyžaduje detailní dokumentaci všech kroků a instrukcí. Byl založen tento soubor.
  • 2026-02-08: Aktualizace instrukcí: Buď detailní, ověřuj, buď kritický, hledej "unknown unknowns", preferuj jednoduchost.
  • 2026-02-08: Požadavek na CRM: Řešení "nasraných rodičů" a přetíženého ředitele.
  • 2026-02-08: Rozhodnutí: Externí Nástroje.
    • CRM: HubSpot (Free). Pro správu Leadů a historii komunikace. Skvělá integrace s GMail a GCal.
    • Project Management: Asana (Free). Pro interní úkoly školy. Turn emails to tasks (Gmail add-on).
    • Komunikace: Kosmo bude generovat reporty a posílat je přes API (Resend/Mailgun) a logovat kopii do HubSpotu.
  • 2026-02-08: Požadavek: Google Workspace Integrace. Vybrané nástroje musí "hrát" s Googlem (SSO, Gmail, Calendar, Drive). HubSpot i Asana toto splňují na jedničku.
  • 2026-02-08: Požadavek: Ankety. Rychlý sběr dat od rodičů (např. "Zájem o kroužek", "Účast na brigádě").
  • 2026-02-08: Vize: Podpora rodičů ("Doma"). Po metodické podpoře učitelů bude cílem nabídnout rodičům nástroje/tipy pro rozvoj dítěte doma (v souladu s Montessori).
  • 2026-02-08: Rozhodnutí Auth: Google + Apple + Magic Link. Maximální pohodlí. Rodič si vybere. Žádná hesla na tvrdo.
  • 2026-02-08: Požadavek: Export do Excelu. Škola "žije v Excelu" (evidence žáků, výkazy). Aplikace musí umět exportovat data (seznamy, docházka, hodnocení) do .xlsx.
  • 2026-02-08: Požadavek: Export do Spreadsheets. Kromě Excelu i přímý export do Google Sheets (ideálně "Otevřít v Google Sheets").
  • 2026-02-08: Požadavek: Dev/Stage/Prod. Bezpečný vývoj. Nic nejde rovnou do produkce. Nutnost testovacího prostředí.
  • 2026-02-08: Konzultace: Domény. Současný stav (zs-sofie.cz + ms-sofie.cz) je tříštivý. Učitelé a rodiče kráčejí napříč.
  • 2026-02-08: Rozhodnutí Doména: sofie.education. Moderní, sjednocující brand. Aplikace poběží na app.sofie.education (nebo kosmo.sofie.education).
  • 2026-02-08: Rozhodnutí Tooling: pnpm (pro JS/Next.js) + uv (pro Python scripty). pnpm je pro Node.js to, co uv pro Python (rychlost, DX).
  • 2026-02-08: Uživatel preferuje moderní, responzivní "Vibe Coding" přístup. Navržen Next.js + Supabase.
  • 2026-02-08: Zjištěn kontext: Montessori škola, náhrada MS365 za Google, důraz na automatizaci (metodické listy, reporty) a AI.
  • 2026-02-08: Upřesnění priorit:
    1. Komunikace s rodiči (řešení informačního vakua).
    2. Evidence práce (digitalizace, služba žáků).
    3. Integrace (ŠkolaOnline).
    4. Vize "Sokratova průvodce" (AI společník pro žáka).
    5. Metodické listy (určitě potřeba, ale není lowest hanging fruits).
  • 2026-02-08: Důraz na "AI First" přístup. Aplikace má být centrálním mozkem.
  • 2026-02-08: Začínáme s fází sběru požadavků.
  • 2026-02-08: Vytvořeny základní dokumenty Kontext a Vize, Uživatelé a Role, Požadavky v adresáři docs/.

Workflow