Meta-Workspace Pattern

Problém: Fragmentovaný kontext

Vaše firma má frontend repo, backend repo, infrastructure-as-code, sdílené knihovny, možná datovou pipeline nebo dvě. Když otevřete Claude Code nebo Cursor v jednom repu, AI o ostatních neví vůbec nic. Nedokáže posoudit, jak změna v backend API ovlivní frontend. Nedokáže naplánovat feature, která sahá přes tři repozitáře.

To je zásadní úzké hrdlo. AI nástroje jsou silné v rámci jednoho repa, ale většina reálné práce překračuje hranice repozitářů. Typický feature ticket znamená: přidat API endpoint (backend), postavit UI (frontend), aktualizovat deployment (infra) a možná přidat migrační job (data). Bez sjednoceného kontextu je AI nástroj, který vidí jen jeden dílek skládačky.

Řešení: Meta-Workspace

Meta-workspace je Git repozitář, který obsahuje všechny vaše ostatní repozitáře jako podadresáře. Child repos si zachovávají vlastní Git historii — meta-workspace je pouze agreguje přes .gitignore. Představte si ho jako 'repo repozitářů' se sdíleným mozkem.

company-workspace/
  AGENTS.md                    # Jediný zdroj pravdy pro AI agenty
  .claude/                     # Konfigurace Claude Code
    agents/                    # Definice agentů
    skills/                    # Definice skills (pipeline)
  repos/                       # Všechny child repos (gitignored)
    backend/                   # Django/Rails/Express repo
    frontend/                  # Next.js/React/Vue repo
    infra/                     # Terraform + k8s manifesty
    shared-libs/               # Sdílené balíčky
    data-pipeline/             # ETL joby
  projects/                    # Sledování projektů
    ACTIVE                     # Aktuálně aktivní projekt
    TICKET-123/
      README.md                # Plán a stav projektu
  docs/                        # Cross-repo dokumentace
  setup.sh                     # Setup workspace jedním příkazem

Klíčový poznatek: meta-workspace je sám o sobě Git repo, ale všechny child repos pod repos/ jsou gitignored. Každé child repo si udržuje vlastní větve, PR a CI. Meta-workspace sleduje pouze sdílenou konfiguraci — definice agentů, skills, plány projektů a dokumentaci na úrovni workspace.

AGENTS.md: Jediný zdroj pravdy

AGENTS.md (nebo CLAUDE.md pro Claude Code, GEMINI.md pro Gemini CLI) je nejdůležitější soubor ve vašem workspace. Každý AI agent ho čte jako první. Říká AI: jaké repozitáře existují, co každý dělá, jaké konvence dodržovat a které agenty/skills máte k dispozici.

# Company Workspace

Meta-workspace pro správu všech firemních repozitářů s AI agenty.

## Mapa repozitářů

| Repo | Cesta | Stack | Popis |
|------|-------|-------|-------|
| Backend API | repos/backend/ | Django + Ninja | REST API, auth, platby |
| Frontend | repos/frontend/ | Next.js 15 | Zákaznický web |
| Admin | repos/admin/ | Next.js 15 | Interní admin dashboard |
| Infra | repos/infra/ | Terraform + k8s | Cloud infrastruktura |
| Shared Types | repos/shared-types/ | TypeScript | Sdílené API typy |

## Konvence

- Všechny repos používají trunk-based development (krátkodobé feature větve)
- Backend: Django apps pod apps/, testy zrcadlí strukturu appek
- Frontend: App Router, server components jako výchozí
- Infra: Terraform moduly v modules/, prostředí v envs/

## Agenti

| Agent | Soubor | Model | Role |
|-------|--------|-------|------|
| Solution Architect | .claude/agents/solution-architect.md | opus | Cross-repo plánování |
| Backend Developer | .claude/agents/backend-dev.md | sonnet | Django implementace |
| Frontend Developer | .claude/agents/frontend-dev.md | sonnet | Next.js implementace |
| Infra Engineer | .claude/agents/infra-eng.md | sonnet | Terraform + k8s |
| Reviewer | .claude/agents/reviewer.md | opus | Code review |

## Skills

| Skill | Soubor | Popis |
|-------|--------|-------|
| /feature | .claude/skills/feature-pipeline.md | Kompletní implementace feature |
| /deploy | .claude/skills/deploy.md | Deploy na staging/produkci |
| /review | .claude/skills/review.md | Cross-repo code review |

Symlinky pro kompatibilitu s nástroji

Různé AI nástroje hledají různé názvy souborů. Claude Code čte CLAUDE.md, Cursor čte .cursorrules nebo .cursor/rules, Gemini CLI čte GEMINI.md. Místo udržování více kopií použijte symlinky.

# Vytvořte kanonický zdroj
vi AGENTS.md

# Symlink pro každý nástroj
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
mkdir -p .cursor && ln -s ../AGENTS.md .cursor/rules

# Ověřte
ls -la CLAUDE.md
# lrwxr-xr-x  CLAUDE.md -> AGENTS.md

Když teď aktualizujete AGENTS.md, každý nástroj automaticky převezme změny. To je klíčové pro týmy — jeden člověk aktualizuje konvence a AI nástroje každého vývojáře to okamžitě promítnou.

Strategie .gitignore

.gitignore v meta-workspace je tmel, který drží vše pohromadě. Ignoruje všechny child repos (ty mají vlastní Git) a sleduje vše ostatní.

# .gitignore pro meta-workspace

# Child repos — každé má vlastní git historii
repos/

# OS soubory
.DS_Store

# IDE soubory (volitelné — některé týmy je sledují)
.idea/
.vscode/

To znamená, že commity meta-workspace obsahují pouze: AGENTS.md, definice agentů, definice skills, plány projektů a dokumentaci. Samotný kód žije v child repos s vlastními větvemi a CI.

Co kam patří

• Meta-workspace repo: AGENTS.md, definice agentů/skills, sledování projektů, cross-repo dokumentace, setup.sh
• Child repos: Veškerý zdrojový kód, testy, CI/CD konfigurace, repo-specifické AGENTS.md soubory
• Nikdy v meta-workspace: zdrojový kód, závislosti, build artefakty, secrets

Reálný příklad: Otevření workspace

Takto to vypadá v praxi. Otevřete terminál v kořenu workspace a spustíte Claude Code. AI okamžitě přečte AGENTS.md a ví o každém repu, každém agentovi, každé skill. Řeknete 'implementuj TICKET-456' a ví, kterých repozitářů se to týká.

$ cd ~/company-workspace
$ claude

> Implementuj TICKET-456: Přidej API endpoint pro uživatelské
  preference a settings stránku ve frontendu.

# Claude přečte AGENTS.md a vidí:
# - Backend repo na repos/backend/ (Django + Ninja)
# - Frontend repo na repos/frontend/ (Next.js)
# - Solution Architect agent pro plánování
# - Backend Developer agent pro implementaci
# - Frontend Developer agent pro UI

# Naplánuje práci napříč oběma repos,
# vytvoří větve v každém a implementuje feature.

Proč ne monorepo?

Monorepo řeší stejný problém s kontextem — vše na jednom místě. Ale vyžaduje těžký tooling (Nx, Turborepo, Bazel), nutí všechny repos do jednoho CI systému a těžko se zavádí postupně. Meta-workspace pattern funguje s jakýmkoliv existujícím nastavením repozitářů. Nemusíte měnit CI, branching strategii ani deployment pipeline. Jen přidáte tenkou vrstvu navrch.

Pokud už máte monorepo, meta-workspace stále přidává hodnotu: poskytuje definice agentů, skills a sledování projektů, které monorepo nástroje neřeší.