Паттерн мета-воркспейса

Проблема: фрагментированный контекст

В вашей компании есть репозиторий фронтенда, бэкенда, инфраструктуры как кода, общих библиотек, возможно один-два пайплайна данных. Когда вы открываете Claude Code или Cursor в одном репозитории, AI не имеет никакого представления об остальных. Он не может рассуждать о том, как изменение backend API влияет на фронтенд. Он не может спланировать фичу, затрагивающую три репозитория.

Это фундаментальное узкое место. AI-инструменты мощны в рамках одного репозитория, но большинство реальной работы пересекает границы репозиториев. Задача по добавлению фичи нередко означает: добавить API-эндпоинт (бэкенд), создать UI (фронтенд), обновить деплой (инфра) и, возможно, добавить джоб миграции (данные). Без унифицированного контекста AI становится инструментом, который видит лишь один кусочек пазла.

Решение: мета-воркспейс

Мета-воркспейс — это Git-репозиторий, содержащий все остальные репозитории в виде поддиректорий. Дочерние репозитории сохраняют собственные Git-истории — мета-воркспейс просто агрегирует их через .gitignore. Думайте об этом как о «репозитории репозиториев» с единым мозгом.

company-workspace/
  AGENTS.md                    # Single source of truth for AI agents
  .claude/                     # Claude Code configuration
    agents/                    # Agent definitions
    skills/                    # Skill definitions (pipelines)
  repos/                       # All child repos (gitignored)
    backend/                   # Django/Rails/Express repo
    frontend/                  # Next.js/React/Vue repo
    infra/                     # Terraform + k8s manifests
    shared-libs/               # Shared packages
    data-pipeline/             # ETL jobs
  projects/                    # Project tracking
    ACTIVE                     # Current active project
    TICKET-123/
      README.md                # Project plan and status
  docs/                        # Cross-repo documentation
  setup.sh                     # One-command workspace setup

Ключевой инсайт: сам мета-воркспейс — это Git-репозиторий, но все дочерние репозитории в директории repos/ добавлены в .gitignore. Каждый дочерний репозиторий ведёт собственные ветки, PR и CI. Мета-воркспейс отслеживает только общую конфигурацию: определения агентов, навыки, планы проектов и документацию на уровне воркспейса.

AGENTS.md: единственный источник истины

AGENTS.md (или CLAUDE.md для Claude Code, GEMINI.md для Gemini CLI) — самый важный файл в вашем воркспейсе. Каждый AI-агент читает его первым. Он сообщает AI: какие репозитории существуют, что делает каждый из них, какие соглашения соблюдать и какие агенты/навыки доступны.

# Company Workspace

Meta-workspace for managing all company repositories with AI agents.

## Repository Map

| Repo | Path | Stack | Description |
|------|------|-------|-------------|
| Backend API | repos/backend/ | Django + Ninja | REST API, auth, payments |
| Frontend | repos/frontend/ | Next.js 15 | Customer-facing web app |
| Admin | repos/admin/ | Next.js 15 | Internal admin dashboard |
| Infra | repos/infra/ | Terraform + k8s | Cloud infrastructure |
| Shared Types | repos/shared-types/ | TypeScript | Shared API types |

## Conventions

- All repos use trunk-based development (short-lived feature branches)
- Backend: Django apps under apps/, tests mirror app structure
- Frontend: App Router, server components by default
- Infra: Terraform modules in modules/, environments in envs/

## Agents

| Agent | File | Model | Role |
|-------|------|-------|------|
| Solution Architect | .claude/agents/solution-architect.md | opus | Cross-repo planning |
| Backend Developer | .claude/agents/backend-dev.md | sonnet | Django implementation |
| Frontend Developer | .claude/agents/frontend-dev.md | sonnet | Next.js implementation |
| Infra Engineer | .claude/agents/infra-eng.md | sonnet | Terraform + k8s |
| Reviewer | .claude/agents/reviewer.md | opus | Code review |

## Skills

| Skill | File | Description |
|-------|------|-------------|
| /feature | .claude/skills/feature-pipeline.md | Full feature implementation |
| /deploy | .claude/skills/deploy.md | Deploy to staging/production |
| /review | .claude/skills/review.md | Cross-repo code review |

Символические ссылки для совместимости с инструментами

Разные AI-инструменты ищут разные имена файлов. Claude Code читает CLAUDE.md, Cursor — .cursorrules или .cursor/rules, Gemini CLI — GEMINI.md. Вместо поддержки нескольких копий используйте символические ссылки.

# Create the canonical source
vi AGENTS.md

# Symlink for each tool
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
mkdir -p .cursor && ln -s ../AGENTS.md .cursor/rules

# Verify
ls -la CLAUDE.md
# lrwxr-xr-x  CLAUDE.md -> AGENTS.md

Теперь при обновлении AGENTS.md все инструменты автоматически подхватывают изменения. Это критично для команд — один человек обновляет соглашения, и AI-инструменты всех разработчиков немедленно это отражают.

Стратегия .gitignore

Файл .gitignore мета-воркспейса — связующее звено всей конструкции. Он игнорирует все дочерние репозитории (у них есть собственный Git), отслеживая при этом всё остальное.

# .gitignore for the meta-workspace

# Child repos — each has its own git history
repos/

# OS files
.DS_Store

# IDE files (optional — some teams track these)
.idea/
.vscode/

Это означает, что коммиты в мета-воркспейс содержат только: AGENTS.md, определения агентов, определения навыков, планы проектов и документацию. Реальный код живёт в дочерних репозиториях со своими ветками и CI.

Что куда идёт

• Репозиторий мета-воркспейса: AGENTS.md, определения агентов/навыков, отслеживание проектов, кросс-репозиторная документация, setup.sh
• Дочерние репозитории: весь исходный код, тесты, конфигурации CI/CD, репозиторно-специфичные файлы AGENTS.md
• Никогда в мета-воркспейсе: исходный код, зависимости, артефакты сборки, секреты

Реальный пример: открытие воркспейса

Вот как это выглядит на практике. Вы открываете терминал в корне воркспейса и запускаете Claude Code. AI сразу читает AGENTS.md и знает о каждом репозитории, каждом агенте, каждом навыке. Вы говорите «реализуй TICKET-456» — и он знает, какие репозитории затронуть.

$ cd ~/company-workspace
$ claude

> Implement TICKET-456: Add user preferences API endpoint
  with a settings page in the frontend.

# Claude reads AGENTS.md, sees:
# - Backend repo at repos/backend/ (Django + Ninja)
# - Frontend repo at repos/frontend/ (Next.js)
# - Solution Architect agent for planning
# - Backend Developer agent for implementation
# - Frontend Developer agent for UI

# It plans the work across both repos,
# creates branches in each, and implements the feature.

Почему не монорепозиторий?

Монорепозитории решают ту же проблему контекста — всё в одном месте. Но они требуют тяжёлого инструментария (Nx, Turborepo, Bazel), принудительно объединяют все репозитории в одну CI-систему и с трудом внедряются постепенно. Паттерн мета-воркспейса работает с любой существующей структурой репозиториев. Вам не нужно менять CI, стратегию ветвления или пайплайн деплоя. Вы просто добавляете тонкий слой сверху.

Если у вас уже есть монорепозиторий, мета-воркспейс всё равно добавляет ценность: он предоставляет определения агентов, навыки и отслеживание проектов, которые инструменты монорепозитория не поддерживают.