$ cat /architektura
Pod kapotou
operačního systému
Git jako databáze firemních znalostí. YAML frontmatter jako strojově čitelná metadata. MCP jako protokol pro AI agenty. Pull Requesty jako schvalovací workflow.
Architektura repozitáře
# Adresářová struktura
Sensio-os/
context/ # Firemní kontext
company/ # Profil, hodnoty, tým, KPI
products/ # iZUŠ, EOS, B2B, MyCello
clients/ # ICP (Ideal Client Profile)
market/ # Konkurence
strategy/ # Vize, roadmapa, cíle
decisions/ # ADR záznamy
processes/ # Workflow a procesy
sales/ # Discovery, nabídky
delivery/ # Onboarding, projekty
finance/ # Fakturace, mzdy
agents/ # AI agenti
personas/ # Agent identity
prompts/ # System prompts
tools/ # Tool inventory
templates/ # Šablony dokumentů
blueprints/ # Technické plány
reference/ # Glossary, tech stack
docs/ # Konvence, SOUL.md
CLAUDE.md # Routovací tabulka
Proč tato struktura?
Každá složka odpovídá jedné „doméně" firmy. AI agent dostane kontext jen pro svou úlohu – nepotřebuje načítat celý repo. Princip progressive context disclosure.
CLAUDE.md = sitemap pro AI
100+ záznamů ve formátu | Potřebuji... | Jdi do... |. Agent nepotřebuje prohledávat celý repo – podívá se do routovací tabulky a najde správný soubor.
Konvence řídí kvalitu
docs/conventions.md definuje pravidla pro všechny soubory: jazyk, formát, pojmenování, frontmatter schema. AI i lidé se řídí stejnými pravidly.
YAML frontmatter – metadata pro AI
Každý soubor v repo má povinnou YAML hlavičku. To jsou strojově čitelná metadata, která AI agentu říkají: co je to za dokument, kdo ho vlastní, v jakém je stavu a jak ho má interpretovat.
Schema
| Pole | Typ | Popis |
|---|---|---|
| title | string | Název dokumentu |
| type | enum | persona, process, workflow, strategy... |
| status | enum | ai-generated, draft, review, approved |
| version | string | Epoch.Revision (0.1, 1.0, 1.3) |
| owner | string | Odpovědná osoba |
| tags | array | Klasifikační štítky |
| domain | enum | sales, finance, products... |
| summary | string | Stručný popis obsahu |
# Příklad: mzdový workflow
---
title: "Mzdový workflow"
type: workflow
status: approved # ai-generated → draft → review → approved
version: "1.3" # Epoch.Revision
created: 2026-01-15
updated: 2026-03-01
owner: "Jan Tobolík"
tags: [mzdy, finance, workflow]
domain: finance
summary: "6krokový proces zpracování mezd"
---
# Co AI vidí:
"Toto je schválený workflow verze 1.3
pro doménu finance, vlastní ho Jan Tobolík.
Mohu mu důvěřovat jako autoritativnímu zdroji."
Trust Model
AI agent se řídí statusem dokumentu – ví, čemu může věřit.
ai-generated
Nedůvěryhodné
AI verze bez lidského ověření. Vždy upozorní uživatele.
draft
Nízká důvěra
Rozpracované. Agent pracuje s výhradou.
review
Vysoká důvěra
Pravděpodobně správné. Upozorní na nejistotu.
approved
Pravda
Ověřeno člověkem. Plná jistota.
archived
Neplatné
Historický záznam. Nepoužívat.
# Status workflow
ai-generated → draft → review → approved → archived
# Klíčové pravidlo:
# Status "approved" může nastavit POUZE člověk
# AI navrhuje, člověk rozhoduje
AI integrace – tři úrovně
Od pasivního čtení po aktivní údržbu systému.
AI čte dokumentaci
User:
"Řekni mi, jak funguje náš onboarding"
Agent:
→ Najde processes/delivery/onboarding.md
→ Přečte, odpoví v kontextu firmy
Pasivní. Agent slouží jako znalostní asistent.
AI vykonává procesy
User:
"Připrav podklady pro mzdy za únor"
Agent:
→ Projde 6krokový workflow
→ Připojí Google Sheets (MCP)
→ Pošle e-mail přes Gmail (MCP)
Aktivní. Agent vykonává práci podle procesů z repo.
AI udržuje systém
User:
"Aktualizuj roadmapu"
Agent:
→ Přečte ADR, goals
→ Navrhne změnu
→ Vytvoří Pull Request
Autonomní. Agent navrhuje změny, člověk schvaluje.
MCP – Model Context Protocol
Standardizovaný protokol, kterým AI přistupuje k externím službám.
# Architektura
Claude (AI) <--> MCP server <--> Gmail / Drive / Sheets
# .mcp.json – konfigurace
{
"mcpServers": {
"google-workspace": {
"command": "uvx",
"args": ["mcp-google-workspace"],
"env": {
"CLIENT_ID": "${...}",
"CLIENT_SECRET": "${...}"
}
}
}
}
Jeden OAuth token
Jedno přihlášení = přístup ke Gmail, Google Drive i Google Sheets. Bez opakované autorizace.
Credentials mimo repo
OAuth tokeny žijí v .env (v .gitignore). SessionStart hook kontroluje jejich přítomnost.
Praktické využití
AI přečte e-mail s výplatními páskami, stáhne přílohy, uloží na Drive, zapíše data do Sheets – vše přes MCP.
Zone Model pro Drive
GREEN volný zápis YELLOW na požádání RED pouze čtení
Git workflow a Tier systém
Kdo co může. Pull Requesty jako schvalovací proces.
| Tier | Kdo | Může | Nemůže |
|---|---|---|---|
| Admin | Vlastník | Vše | – |
| T1 | Tým | Push, PR, edit | Merge do main |
| T2 | Čtenáři | Číst, komentovat | Push |
| T3 | AI agenti | Větve agent/*, PR | Merge, push main |
# Pojmenování větví
Lidé: feature/izus-cenik-2026
Opravy: fix/broken-links
Docs: docs/conventions-update
AI: agent/sales-nabidka-template
Klíčové pravidlo
AI agent nikdy nemerge vlastní PR. Vždy vytvoří branch, commitne změny, otevře PR s popisem – a čeká na lidský review.
SOUL.md – identita AI agenta
AI agent má vlastní „duši" – soubor pravidel, jak se chová.
Transparentnost
Vždy přizná, že je AI. Nikdy se nevydává za člověka.
Bez halucinací
Neví-li odpověď, řekne „nevím". Neznámá data označí TODO.
Respekt ke konvencím
Dodržuje docs/conventions.md – frontmatter, jazyk, formát.
Lidé rozhodují
AI navrhuje změny. Schválení (approved) může udělat jen člověk.
Tři cesty k AI
Začněte tam, kde to dává smysl. Každá úroveň přináší reálnou hodnotu.
Úroveň 1
Průzkumník
"Správné nástroje, správný přístup. Výsledky se dostaví okamžitě."
- AI nástroje nastavené pro váš tým
- Osobní AI plán pro každého účastníka
- Žádné programování, žádné nastavování
- Výsledky od prvního dne
Úroveň 2
Stavitel
"Žádný kód se nepíše, ale hodně se přemýšlí. Celá vaše firma, její postupy, je v podstatě kód."
- Firemní paměť: AI si pamatuje procesy, klienty, historii
- Automatizace opakovaných úkolů (CRM, reporting, dokumenty)
- Systém, který se každý týden učí a zlepšuje
- Data zůstávají vaše. Žádný vendor lock-in.
Úroveň 3
Architekt
"Smlouva za 5 hodin mi trvá 2,5 hodiny. To je o 50 % větší marže."
- 50-80% nárůst efektivity v rutinních operacích
- Plná automatizace celých byznys procesů
- Chytřejší firma, ne jen rychlejší. Znalosti se násobí.
- Strategická konkurenční výhoda na roky dopředu
Proč Git + Markdown?
Srovnání s běžnými nástroji pro správu znalostí.
| Kritérium | Git + Markdown | Notion / Confluence |
|---|---|---|
| Verzování | Plné (každý commit) | Omezené (30 dní / žádné) |
| Vlastnictví dat | 100 % vaše | Na serverech dodavatele |
| AI-ready | YAML + MD = ideální pro LLM | Proprietární API, složitý parsing |
| Cena | Zdarma (GitHub) | $8–15/uživatel/měsíc |
| Review workflow | Pull Requesty | Manuální (komentáře, email) |
| Offline přístup | Ano | Ne (jen cloud) |
Chcete to vidět v akci?
Na workshopu ukazujeme celou architekturu živě – včetně mzdového workflow a AI agentů.