architect/research/WORKSPACE_DOCS_SOLUTION.md

РЕШЕНИЕ: Система управления документацией workspace

Дата: 2026-02-04
Версия: 1.0.0
Статус: proposal

КОНТЕКСТ

Проблема: Необходима единая логичная система хранения и ведения файлов/документов в workspace.

Текущее состояние:
- 1479 MD файлов в projects/
- 110 CLAUDE.md файлов
- Дублирование информации в 3+ местах
- Нет единого источника истины (SSOT)
- Разнесённое планирование (TODO в 6+ местах)
- Архитектура в 4+ файлах без индекса
- ADR почти не используется

Исследования:
- DOCS_MANAGEMENT_COMPARATIVE_ANALYSIS.md — 5 систем индустрии
- DOCS_MANAGEMENT_DECISION_MATRIX.md — матрицы выбора
- DOCS_MANAGEMENT_IMPLEMENTATION_GUIDE.md — план миграции

КЛЮЧЕВЫЕ ПРОБЛЕМЫ

1. Дублирование без SSOT

Проблема: Одна и та же информация в 3+ местах без связи.

Примеры:

Информация Место 1 Место 2 Место 3 Результат
Структура проекта architect/standards/structure/PROJECT.md architect/templates/PROJECT_BASE.md projects/*/PROJECT.md 3 версии, не синхронны
Архитектура платформы concept/ARCHITECTURE.md design/MASTER_PLAN.md design/PRO_SCHEMA.md Непонятно что актуально
Статус проекта design/MASTER_PLAN.md projects/*/PROJECT.md projects/*/management/STATUS.md Разные данные

Последствия:
- Непонятно где источник истины
- Обновление требует синхронизации 3+ файлов
- Риск устаревания информации

2. Фрагментация планирования

Проблема: Планирование разнесено по 6+ местам без связи.

Где сейчас:

TODO размазано:
├── projects/*/TODO.md              (актуальные задачи проекта)
├── projects/*/TODO_ACTUAL.md       (ещё более актуальные??)
├── architect/operations/           (задачи платформы)
├── architect/management/TODO.md    (задачи архитектора)
├── .queue/pending/*.yaml           (очередь задач)
└── .tickets/resolved/              (архив тикетов)

Последствия:
- Не видно полной картины
- Нужно проверять 6 мест
- Сложно приоритизировать
- Нет единой системы статусов

3. Отсутствие ADR

Проблема: Архитектурные решения не документируются.

Что есть: 3 файла в architect/decisions/
Что нужно: ADR в каждом проекте для всех значимых решений

Примеры не задокументированных решений:
- Почему выбрали OZON, а не WB?
- Почему перешли с app/ на it/web/?
- Почему NocoDB, а не Airtable?
- Почему Python, а не Node.js для роботов?

Последствия:
- Потеря контекста решений
- Повторное обсуждение старых вопросов
- Сложно для новичков понять "почему так"

4. Разнесённая архитектура

Проблема: Архитектура проекта в 4+ файлах без индекса.

Пример (pirotehnika):

pirotehnika/
├── ARCHITECTURE.md                     ← Общая?
├── ARCHITECTURE_DOMAINS.md             ← Домены?
├── app/pim/ARCHITECTURE.md             ← PIM?
├── app/pim/docs/ARCHITECTURE_ERP.md    ← ERP?
├── app/mp1/design/ARCHITECTURE_v2.md   ← MP1 v2?
└── data/connectors/ARCHITECTURE_COMPARISON.md  ← Сравнение коннекторов?

Последствия:
- Непонятно какая архитектура актуальна
- Нет единого представления
- Дублирование описаний
- Нет версионирования

5. 110 CLAUDE.md без системы

Проблема: 110 CLAUDE.md файлов с дублированием правил.

Что сейчас:

CLAUDE.md везде:
├── $WORKSPACE/CLAUDE.md           ← Базовые правила
├── $WORKSPACE/architect/CLAUDE.md ← Правила архитектора
├── projects/*/CLAUDE.md                      ← Контекст проекта (×12)
├── system/agents/*/CLAUDE.md                 ← Контекст агента (×20)
└── library/*/CLAUDE.md                       ← Контекст модуля (×76)

Проблемы:
- Дублирование базовых правил
- Сложно обновить общие правила (нужно 110 файлов)
- Нет механизма наследования (extends не реализован)
- Много устаревших

Что работает:
- Контекст близко к коду
- Легко найти правила для конкретного модуля

6. Нет реестра документов

Проблема: Нет единого индекса всех документов.

Что есть:
- architect/INDEX.md — только для architect/
- index.yaml в проектах — не заполнено
- Нет глобального реестра

Что нужно:
- Реестр всех документов с метаданными
- Тип (план/архитектура/бизнес/ADR/задача)
- Статус (актуально/устарело/в работе)
- Дата последнего обновления
- Связанные документы
- Зависимости

ВАРИАНТЫ РЕШЕНИЯ

Вариант 1: "Git-native с минимальными изменениями"

Суть: Оставить всё в git, но навести порядок.

Что делаем:

  1. SSOT через ссылки
    - Выбрать один файл для каждого типа информации
    - Все остальные ссылаются на него
    - Запретить дублирование

  2. Консолидация TODO
    - Все TODO → projects/*/management/TODO.md
    - Платформа → architect/management/TODO.md
    - .queue/ только для автоматизации

  3. ADR в каждом проекте
    - Создать projects/*/decisions/
    - Шаблон ADR
    - Правило: все значимые решения → ADR

  4. Единая архитектура
    - Один ARCHITECTURE.md в корне проекта
    - Подмодули → sections внутри или architecture/*.md
    - Индекс архитектур

  5. Наследование CLAUDE.md
    - Базовый CLAUDE.md остаётся
    - Проекты extends через секцию наследования
    - Убрать дублирование правил

  6. Реестр документов
    - Создать architect/DOCS_INDEX.md
    - Автогенерация через скрипт
    - Метаданные из frontmatter

Структура:

workspace/
├── CLAUDE.md                      ← Базовые правила
├── architect/
│   ├── DOCS_INDEX.md              ← NEW: Глобальный реестр
│   └── ...
├── projects/org/pirotehnika/
│   ├── CLAUDE.md                  ← extends: ../../../CLAUDE.md
│   ├── PROJECT.md                 ← SSOT: описание проекта
│   ├── ARCHITECTURE.md            ← SSOT: архитектура
│   ├── decisions/                 ← NEW: ADR
│   │   ├── 001-ozon-vs-wb.md
│   │   └── 002-nocodb.md
│   └── management/
│       ├── TODO.md                ← SSOT: задачи
│       └── STATUS.md              ← SSOT: статус
└── ...

Плюсы:
- ✅ Минимальные изменения
- ✅ Всё в git (версионирование)
- ✅ Бесплатно
- ✅ Близко к коду
- ✅ Не нужны внешние инструменты

Минусы:
- ❌ Нет удобного UI
- ❌ Сложно искать (только grep/git)
- ❌ Нет структурированных данных
- ❌ Ручная синхронизация ссылок
- ❌ Нет автоматических проверок

Трудоемкость: 3-5 дней

Подходит для:
- Малые команды (1-5)
- Технические проекты
- Приоритет: контроль версий

Вариант 2: "Docusaurus + ADR в git"

Суть: Docusaurus для публичной документации, ADR в git для решений.

Что делаем:

  1. Docusaurus site
    - Создать docs/ с Docusaurus
    - Красивый UI с поиском
    - Версионирование документации
    - Автодеплой на docs.0kt.ru

  2. Разделение типов документов
    - Docusaurus: Документация (как использовать, API, гайды)
    - Git: Код, ADR, CLAUDE.md
    - Таблицы: NocoDB (структурированные данные)
    - Задачи: GitHub Issues или .queue/

  3. ADR в git
    - projects/*/decisions/
    - Шаблон ADR
    - Скрипт генерации индекса

  4. Автоматизация
    - CI/CD: автодеплой Docusaurus
    - Скрипт: генерация DOCS_INDEX.md
    - Линтер: проверка ссылок

Структура:

workspace/
├── docs/                          ← NEW: Docusaurus site
│   ├── docusaurus.config.js
│   ├── docs/
│   │   ├── platform/
│   │   │   ├── intro.md
│   │   │   └── agents.md
│   │   └── projects/
│   │       ├── pirotehnika.md
│   │       └── lideravto.md
│   └── versioned_docs/
│
├── projects/org/pirotehnika/
│   ├── decisions/                 ← ADR в git
│   │   └── 001-ozon.md
│   ├── management/
│   │   └── TODO.md                ← Задачи в git
│   └── CLAUDE.md                  ← Контекст в git
│
└── architect/
    └── decisions/                 ← ADR платформы

Что где:

Тип документа Система Формат
Документация (how-to) Docusaurus MDX
API docs Docusaurus OpenAPI
Архитектурные решения Git (ADR) Markdown
Контекст Claude Git (CLAUDE.md) Markdown
Задачи Git (.queue/) YAML
Структурированные данные NocoDB Database

Плюсы:
- ✅ Красивый UI с поиском
- ✅ Версионирование документации
- ✅ Бесплатно
- ✅ ADR в git (контроль версий)
- ✅ Автодеплой
- ✅ Разделение: публичное (Docusaurus) vs внутреннее (git)

Минусы:
- ❌ Два места для документов
- ❌ Нужна настройка CI/CD
- ❌ Сложнее для малых проектов
- ❌ Нет структурированных данных

Трудоемкость: 1-2 недели

Подходит для:
- Средние команды (5-20)
- Публичная документация важна
- Нужен красивый UI

Вариант 3: "Notion + ADR в git (Hybrid)"

Суть: Notion для структурированной документации, ADR в git.

Что делаем:

  1. Notion workspace
    - База проектов (таблица)
    - База документов (связи)
    - База задач (канбан)
    - База архитектурных решений (связи с проектами)

  2. ADR остаются в git
    - Технические решения версионируются
    - Notion ссылается на git
    - Best of both worlds

  3. Разделение типов
    - Notion: Планирование, статус, процессы, knowledge base
    - Git: Код, ADR, CLAUDE.md
    - Docusaurus: Публичная документация (опционально)

  4. Автоматизация
    - Синхронизация Notion ↔ Git через API
    - Статус из .queue/ → Notion
    - ADR из git → Notion (ссылки)

Структура Notion:

Workspace
├── 📊 Проекты (Database)
│   ├── Pirotehnika
│   │   ├── 📄 PROJECT (page)
│   │   ├── 📋 TODO (kanban)
│   │   ├── 🏛️ Архитектура (связь → Architecture DB)
│   │   └── 💡 Решения (связь → Decisions DB)
│   └── Lideravto
│       └── ...
│
├── 🏛️ Architecture (Database)
│   ├── Pirotehnika Platform
│   ├── Lideravto Structure
│   └── ...
│
├── 💡 Decisions (Database)
│   ├── 001: OZON vs WB
│   │   ├── Контекст
│   │   ├── Решение
│   │   ├── Последствия
│   │   └── Link to ADR in git ← ссылка
│   └── ...
│
└── 📚 Knowledge Base (Database)
    ├── How-to: Deploy
    ├── FAQ: NocoDB
    └── ...

В git остаётся:

workspace/
├── projects/org/pirotehnika/
│   ├── decisions/                 ← ADR (версионирование)
│   │   └── 001-ozon-vs-wb.md
│   └── CLAUDE.md                  ← Контекст для Claude
│
└── .queue/                        ← Задачи (автоматизация)

Что где:

Тип документа Система Почему
Планирование (TODO) Notion UI, связи, статусы
Статус проекта Notion SSOT, обновляется часто
Архитектура (описание) Notion Связи, структурировано
Архитектурные решения (ADR) Git Версионирование, review
Процессы (how-to) Notion Поиск, updates
Knowledge Base / FAQ Notion Relations, теги
Контекст Claude Git Близко к коду
Код Git Очевидно

Плюсы:
- ✅ Структурированные данные (Relations)
- ✅ Красивый UI
- ✅ Поиск и фильтры
- ✅ ADR версионируются
- ✅ Best of both worlds

Минусы:
- ❌ Платно ($10-25/чел/мес)
- ❌ Два места (git + Notion)
- ❌ Нужна синхронизация
- ❌ Vendor lock-in

Трудоемкость: 2-3 недели

Подходит для:
- Средние-большие команды (10-50)
- Нужна структурированность
- Бюджет есть ($2400-7200/год на 20 человек)

Вариант 4: "Всё в одном: Confluence Cloud"

Суть: Confluence для всего (кроме кода).

Что делаем:

  1. Confluence Cloud
    - Spaces для каждого проекта
    - Templates для типов документов
    - Версионирование встроенное
    - Поиск и права доступа

  2. Jira для задач
    - Issues для TODO
    - Epics для больших задач
    - Связь Confluence ↔ Jira

  3. ADR в Confluence
    - Templates для ADR
    - Версионирование Confluence
    - Или дублирование в git (master copy)

  4. Код остаётся в git
    - CLAUDE.md в git
    - Confluence ссылается на git

Структура Confluence:

Confluence Spaces
│
├── Platform Architecture
│   ├── 🏠 Home
│   ├── 📐 Architecture
│   ├── 📜 Standards
│   ├── 💡 Decisions (ADR)
│   └── 📚 Patterns
│
├── Pirotehnika Project
│   ├── 🏠 PROJECT
│   ├── 📋 Roadmap
│   ├── 🏛️ Architecture
│   ├── 💡 Decisions
│   ├── 📊 Status Reports
│   └── 📝 Meeting Notes
│
└── Lideravto Project
    └── ...

Что где:

Тип документа Система Почему
Всё (кроме кода) Confluence SSOT, поиск, версии
Задачи Jira Управление, dashboards
Код Git Очевидно
CLAUDE.md Git Близко к коду

Плюсы:
- ✅ Всё в одном месте
- ✅ Мощный поиск
- ✅ Версионирование встроенное
- ✅ Права доступа
- ✅ Интеграции (Jira, GitHub, etc)
- ✅ Проверен Enterprise

Минусы:
- ❌ Платно ($6-12/чел/мес)
- ❌ Vendor lock-in (Atlassian)
- ❌ Сложнее для малых команд
- ❌ Не близко к коду

Трудоемкость: 3-4 недели

Подходит для:
- Большие команды (50+)
- Нужна Enterprise-готовность
- Бюджет есть ($1440-3360/год на 20 человек)

СРАВНЕНИЕ ВАРИАНТОВ

Быстрая таблица

Критерий Вариант 1: Git Вариант 2: Docusaurus Вариант 3: Notion Вариант 4: Confluence
Стоимость $0 $0-100/год $2400-7200/год $1440-3360/год
Трудоемкость 3-5 дней 1-2 недели 2-3 недели 3-4 недели
Команда 1-5 5-20 10-50 50+
UI ❌ Нет ✅ Красиво ✅ Красиво ✅ Профессионально
Поиск grep/git ✅ Algolia ✅ Встроенный ✅ Мощный
Версионирование ✅ Git ✅ Git ⚠️ История ✅ Встроенное
Структурированность ❌ Markdown ❌ Markdown ✅ Database ⚠️ Pages
ADR ✅ Git ✅ Git ✅ Git + Notion ⚠️ Confluence
Близость к коду ✅ ✅ ❌ ❌
Vendor lock-in ✅ Нет ✅ Нет ❌ Notion ❌ Atlassian

Подробное сравнение

Аспект Git Docusaurus Notion Confluence
SSOT ⚠️ Вручную ✅ Git ⚠️ Синхронизация ✅ Confluence
Дублирование ⚠️ Риск ⚠️ Риск ⚠️ Два места ✅ Одно место
Навигация ❌ Ссылки ✅ Sidebar ✅ Relations ✅ Tree
Миграция ✅ Простая ⚠️ Средняя ⚠️ Средняя ❌ Сложная
Обучение ✅ Простое ⚠️ Среднее ⚠️ Среднее ❌ Сложное
Автоматизация ✅ Скрипты ✅ CI/CD ⚠️ API ✅ Macros
Права доступа ❌ Нет ❌ Нет ✅ Есть ✅ Гранулярные

РЕКОМЕНДАЦИЯ

Для workspace (текущая ситуация)

Рекомендую: Вариант 1 + элементы Варианта 2

Почему:

  1. Малая команда (1-5)
    - Не нужен сложный UI
    - Технически подкованные
    - Приоритет: контроль версий

  2. Всё в git
    - Уже есть привычка работать с git
    - Docusaurus для публичной документации (позже)
    - Минимальные изменения

  3. Бюджет = $0
    - Notion/Confluence = overkill
    - Git + Docusaurus бесплатны

  4. Близость к коду
    - CLAUDE.md рядом с кодом
    - ADR рядом с кодом
    - Правильно архитектурно

План действий:

Фаза 1: Наведение порядка (3-5 дней)

День 1-2: SSOT
- [ ] Определить источник истины для каждого типа
- [ ] Создать таблицу SSOT
- [ ] Добавить ссылки вместо дублирования

День 3: ADR
- [ ] Создать architect/decisions/README.md с шаблоном ADR
- [ ] Создать projects/*/decisions/ в каждом проекте
- [ ] Задокументировать 5 главных решений

День 4: Консолидация TODO
- [ ] Собрать все TODO в одно место
- [ ] Удалить дублирующие файлы
- [ ] Обновить CLAUDE.md с новыми правилами

День 5: Реестр документов
- [ ] Создать architect/DOCS_INDEX.md
- [ ] Скрипт автогенерации индекса
- [ ] Добавить метаданные в frontmatter

Фаза 2: Улучшения (1-2 недели, опционально)

Неделя 1: Docusaurus
- [ ] Создать docs/ с Docusaurus
- [ ] Мигрировать публичную документацию
- [ ] Настроить автодеплой

Неделя 2: Автоматизация
- [ ] Линтер для проверки ссылок
- [ ] CI/CD: проверка SSOT
- [ ] Скрипт: генерация индекса

ПРАВИЛА (после внедрения)

1. SSOT (Single Source of Truth)

Правило: Каждый тип информации имеет ОДИН источник истины.

Таблица SSOT:

Тип информации Источник истины Формат
Описание проекта projects/*/PROJECT.md Markdown
Архитектура проекта projects/*/ARCHITECTURE.md Markdown
Статус проекта projects/*/management/STATUS.md Markdown
Задачи проекта projects/*/management/TODO.md Markdown
Архитектурные решения projects/*/decisions/*.md ADR
Контекст Claude projects/*/CLAUDE.md Markdown
Структура проекта architect/standards/structure/PROJECT.md Markdown (шаблон)
Правила платформы /CLAUDE.md Markdown
Архитектура платформы architect/concept/ARCHITECTURE.md Markdown
Решения платформы architect/decisions/*.md ADR
Задачи платформы architect/management/TODO.md Markdown

Действия:
- ✅ Ссылаться на SSOT
- ✅ Обновлять только SSOT
- ❌ НЕ копировать информацию
- ❌ НЕ дублировать без ссылок

2. ADR обязательны

Правило: Все значимые решения документируются в ADR.

Что значимо:
- Выбор технологии (Python vs Node.js)
- Выбор поставщика (OZON vs WB)
- Изменение структуры (app/ → it/web/)
- Изменение архитектуры (монолит → микросервисы)
- Изменение процесса (ручное → автоматическое)

Формат ADR:

# ADR-001: Выбор маркетплейса (OZON vs WB)

**Статус:** Принято
**Дата:** 2026-02-04
**Контекст:** pirotehnika
**Автор:** Operator

## Контекст

Нужно выбрать маркетплейс для продажи пиротехники.

## Варианты

1. OZON — большая аудитория, API
2. Wildberries — популярен, но ограничения на пиротехнику
3. Оба — дублирование усилий

## Решение

Выбрали OZON.

## Причины

- Разрешена категория пиротехники
- Есть API для автоматизации
- Меньше комиссия на эту категорию

## Последствия

+ Быстрая интеграция (API готов)
+ Автоматизация заказов
- Зависимость от одного маркетплейса
- Нужно мониторить изменения правил

## Ссылки

- [OZON API](https://docs.ozon.ru)
- [Connector](library/connectors/api/ozon/)

Где хранить:
- Платформа: architect/decisions/
- Проект: projects/*/decisions/

3. Один TODO файл

Правило: Все задачи проекта в одном файле.

Где:
- Проект: projects/*/management/TODO.md
- Платформа: architect/management/TODO.md

Формат:

# TODO: Pirotehnika

**Обновлено:** 2026-02-04

## В работе

- [ ] Синхронизация заказов FBS — @operator (ETA: 2h)
- [ ] Создать sync_returns.py — @coder (ETA: 1h)

## Следующие

- [ ] Отменить нерентабельные заказы O2 — @operator (ETA: 30m)
- [ ] Тесты для sync_orders — @coder (ETA: 45m)

## Бэклог

- [ ] Dashboard для аналитики
- [ ] Уведомления в Telegram

## Завершено (последние 5)

- [x] Импорт товаров из OZON — 2026-02-03
- [x] Настройка NocoDB — 2026-02-02

Запрещено:
- ❌ TODO_ACTUAL.md
- ❌ TODO_NEW.md
- ❌ TODO в 5 разных файлах

4. Один ARCHITECTURE файл

Правило: Одна архитектура проекта в одном файле (или папке).

Где:
- Проект: projects/*/ARCHITECTURE.md
- Подмодули: projects/*/architecture/*.md (если нужно разбить)

Формат:

# Архитектура: Pirotehnika

**Версия:** 2.0.0
**Дата:** 2026-02-04

## Обзор

[Общая картина системы]

## Компоненты

### PIM (Product Information Management)

[Описание PIM]

Детали: [architecture/pim.md](architecture/pim.md)

### Маркетплейсы

[Описание интеграции]

Детали: [architecture/marketplaces.md](architecture/marketplaces.md)

## Решения

См. [decisions/](decisions/)

## Версионирование

- v2.0.0 (2026-02-04): Переход на NocoDB
- v1.0.0 (2025-12-20): Первая версия

Запрещено:
- ❌ ARCHITECTURE.md + ARCHITECTURE_v2.md + ARCHITECTURE_DOMAINS.md
- ❌ Архитектура размазана по 4+ файлам без индекса

5. CLAUDE.md наследование

Правило: Проектные CLAUDE.md наследуют базовый через extends.

Формат:

---
extends: ../../../CLAUDE.md
version: 1.0.0
---

# Pirotehnika — Контекст проекта

[Только специфичная информация проекта]

## Структура

[Структура проекта]

## Текущий фокус

[Что сейчас делаем]

## Ссылки

[Быстрые ссылки]

Что НЕ дублировать:
- ❌ Базовые правила Claude (уже в корневом CLAUDE.md)
- ❌ Протокол диалога (уже есть)
- ❌ Правила планирования (уже есть)

6. Реестр документов

Правило: Все документы в глобальном реестре.

Где: architect/DOCS_INDEX.md (автогенерируется)

Формат:

# Реестр документов workspace

**Обновлено:** 2026-02-04 12:35:00
**Документов:** 1479

## По типам

### Архитектура (47)

| Документ | Проект | Версия | Обновлено | Статус |
|----------|--------|--------|-----------|--------|
| ARCHITECTURE.md | pirotehnika | 2.0.0 | 2026-02-04 | ✅ Актуально |
| ARCHITECTURE.md | lideravto | 9.0.0 | 2026-02-03 | ✅ Актуально |
| ...

### Решения (ADR) (12)

| ADR | Проект | Дата | Статус |
|-----|--------|------|--------|
| 001-ozon-vs-wb.md | pirotehnika | 2026-02-04 | Принято |
| ...

### Задачи (TODO) (8)

| Файл | Проект | Задач | Обновлено |
|------|--------|-------|-----------|
| TODO.md | pirotehnika | 12 | 2026-02-04 |
| ...

Генерация:

python3 system/scripts/generate_docs_index.py

МИГРАЦИЯ

Чеклист

Фаза 1: Подготовка (1 день)
- [ ] Создать бэкап workspace
- [ ] Создать таблицу SSOT
- [ ] Определить что удалять, что оставлять

Фаза 2: ADR (1 день)
- [ ] Создать шаблон ADR
- [ ] Создать projects/*/decisions/
- [ ] Задокументировать 5 главных решений

Фаза 3: Консолидация (2 дня)
- [ ] Собрать все TODO → один файл
- [ ] Собрать архитектуру → один файл
- [ ] Удалить дублирующие файлы
- [ ] Добавить ссылки на SSOT

Фаза 4: Реестр (1 день)
- [ ] Создать architect/DOCS_INDEX.md
- [ ] Скрипт генерации индекса
- [ ] Добавить frontmatter в документы

Фаза 5: Проверка (1 день)
- [ ] Проверить все ссылки
- [ ] Проверить SSOT
- [ ] Обновить CLAUDE.md

СВЯЗАННЫЕ ДОКУМЕНТЫ

Исследования

Стандарты

Версия: 1.0.0
Дата: 2026-02-04
Статус: proposal