Система совместной работы — Платформа ЦИФРА

/opt/claude-workspace/   ← Монорепозиторий (один Git для всего)
│
├── .git/                ← Git история ВСЕГО
│
├── platform/            ← ЯДРО ПЛАТФОРМЫ (общее для всех)
│   ├── CLAUDE.md                      # Правила работы
│   ├── PLATFORM_OVERVIEW.md           # Обзор платформы
│   ├── DESIGN_SYSTEM.md               # Система проектирования
│   ├── DEVELOPMENT_SEQUENCE.md        # План разработки
│   ├── TECHNICAL_TOOLS.md             # Инструменты
│   ├── SOFTWARE_EXPLAINED.md          # Объяснение софта
│   ├── COLLABORATION_SYSTEM.md        # Этот документ
│   │
│   ├── .claude/         ← МЕЖСЕССИОННАЯ ПАМЯТЬ
│   │   ├── system-journal.md          # История событий (ЧТО произошло)
│   │   ├── session-YYYY-MM-DD.md      # Сессии (детали дня)
│   │   └── decisions/                 # Архитектурные решения
│   │       └── ADR-001-git-strategy.md
│   │
│   ├── agents/          ← КОД АГЕНТОВ
│   │   ├── base_agent.py
│   │   ├── document_agent.py
│   │   └── DocumentAgent/             # Документация агента
│   │       ├── DESIGN.md              # Спецификация
│   │       └── CHANGELOG.md           # История изменений
│   │
│   └── config/          ← КОНФИГУРАЦИЯ
│       └── agents.yaml
│
├── templates/           ← ШАБЛОНЫ (переиспользуемые)
│   ├── by-feature/      # По функциям (auth, payments)
│   ├── by-task/         # По задачам (crud, dashboard)
│   └── library/         # Библиотека компонентов
│
├── components/          ← КОМПОНЕНТЫ (FSD)
│   ├── catalog.yaml     # Реестр компонентов
│   └── shared/lib/
│
├── projects/            ← ВАШИ ПРОЕКТЫ
│   ├── marketplace/     # Проект 1
│   │   ├── PROJECT.md              # Главный файл проекта
│   │   ├── design/                 # 📋 Проектирование
│   │   │   ├── ROADMAP.md          # План версий
│   │   │   ├── ARCHITECTURE.md     # Архитектура + ADR
│   │   │   └── REQUIREMENTS.md     # Требования
│   │   ├── management/             # ⚙️ Управление
│   │   │   ├── README.md           # Быстрый старт
│   │   │   ├── CHANGELOG.md        # История изменений
│   │   │   └── TODO.md             # Задачи
│   │   ├── solution/               # 💻 Код
│   │   │   ├── mvp/                # MVP версия
│   │   │   ├── backend/            # Backend (если есть)
│   │   │   └── mobile/             # Mobile (если есть)
│   │   └── infrastructure/         # 🏗️ Серверы
│   │       ├── deploy.yaml         # Деплой конфигурация
│   │       └── servers.md          # Описание серверов
│   │
│   └── analytics/       # Проект 2
│       └── ... (та же структура)
│
└── archive/             ← АРХИВ старых версий

---
version: 1.0.0
created_at: 2025-11-10
template: streamlit-mvp-v1
status: active
tags: [ecommerce, mvp, streamlit]
---

# Marketplace — Платформа маркетплейсов

## Описание
Система для управления несколькими маркетплейсами...

## Стек технологий
- Python 3.11
- Streamlit
- PostgreSQL

## Ссылки
- Production: https://marketplace.example.com
- Staging: http://91.218.142.168:8501
- Git: этот репозиторий

## Быстрый старт
См. management/README.md

# Roadmap

## v1.0 (MVP) ✅ Завершено 2025-11-01
- Авторизация
- Список товаров
- Заказы

## v2.0 (Backend) 🔄 В работе
- FastAPI backend
- REST API
- Асинхронная обработка

## v3.0 (Масштабирование) 📋 Планируется
- Микросервисы
- Kubernetes

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

## Общая схема
[Диаграмма]

## ADR (Architecture Decision Records)

### ADR-001: Выбор Streamlit для MVP
**Дата:** 2025-10-01
**Статус:** Принято

**Контекст:**
Нужен быстрый MVP для демонстрации.

**Решение:**
Используем Streamlit.

**Последствия:**
+ Быстрая разработка
+ Простой UI
- Ограничения масштабирования

# Требования

## Функциональные
- FR-001: Пользователь может войти через email
- FR-002: Пользователь видит список заказов

## Нефункциональные
- NFR-001: Время ответа < 2 секунды
- NFR-002: Доступность 99.5%

# Marketplace — Быстрый старт

## Установка
\`\`\`bash
cd solution/mvp
pip install -r requirements.txt
\`\`\`

## Запуск
\`\`\`bash
streamlit run app.py
\`\`\`

## Тестирование
\`\`\`bash
pytest tests/
\`\`\`

# Changelog

## [1.1.0] - 2025-11-10

### Added
- Экспорт заказов в Excel

### Fixed
- Исправлена ошибка авторизации

### Changed
- Улучшена производительность запросов

# TODO

## В работе
- [ ] Добавить фильтры по датам
- [ ] Оптимизировать запросы к БД

## Планируется
- [ ] Интеграция с Ozon API
- [ ] Push уведомления

## Завершено
- [x] Авторизация через email
- [x] CRUD для товаров

### 2025-11-10: Создана система проектирования

**Действие:** Создан DESIGN_SYSTEM.md

**Изменения:**
- 6 этапов процесса проектирования
- Применена к самой себе

**Статус:** ✅ Утверждено

# Сессия 2025-11-10

## Задачи
1. Создать систему проектирования
2. Обсудить технические инструменты

## Решения
- Используем YAML для метаданных
- Git как единое хранилище

## Созданные файлы
- platform/DESIGN_SYSTEM.md
- platform/TECHNICAL_TOOLS.md

# ADR-001: Git монорепозиторий

**Дата:** 2025-11-10
**Статус:** Принято

**Контекст:**
Нужно решить как хранить код платформы, агентов, проектов.

**Варианты:**
1. Монорепозиторий (всё в одном)
2. Мультирепозиторий (каждый проект отдельно)

**Решение:**
Монорепозиторий.

**Обоснование:**
+ Простота (один git clone)
+ История всех изменений в одном месте
+ Проще Cascade Search

**Последствия:**
+ Проще управление
- Размер репозитория будет расти

┌─────────────────────────────────────┐
│ ОСНОВНОЕ ХРАНИЛИЩЕ: Git             │
│                                     │
│ ✅ Документация (Markdown)          │
│ ✅ Код (Python)                     │
│ ✅ Конфигурация (YAML)              │
│ ✅ Метаданные (YAML frontmatter)    │
│ ✅ История изменений                 │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ ОПЦИОНАЛЬНО: База данных            │
│                                     │
│ 🟡 Метрики (SQLite)                 │
│ 🟡 Кэш поиска (Whoosh index)        │
│ 🟡 Runtime состояние агентов        │
└─────────────────────────────────────┘

# Python
__pycache__/
*.pyc
*.pyo
*.egg-info/

# Secrets
.env
secrets.yaml
*.key

# Logs
*.log
platform/.claude/session-*.md  # Сессии опционально в Git

# Временные
.tmp/
*.swp

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Базы данных (опционально)
*.db
*.sqlite

-- Метрики агентов
CREATE TABLE metrics (
    timestamp DATETIME,
    agent TEXT,
    operation TEXT,
    duration REAL,
    tokens_used INTEGER,
    status TEXT
);

-- Индекс компонентов (Whoosh как альтернатива)
CREATE VIRTUAL TABLE components_fts USING fts5(
    name, path, description, tags
);

master (main branch)
    ↓
    ├─ commit 1: docs: создан DESIGN_SYSTEM.md
    ├─ commit 2: feat: DocumentAgent реализован
    ├─ commit 3: fix: исправлена ошибка в CodeAgent
    ├─ commit 4: refactor: улучшен Cascade Search
    └─ ...

master
    ├─ feature/voice-interface  (для экспериментов)
    ├─ hotfix/critical-bug      (для срочных исправлений)

<type>(<scope>): <subject>

<body>

<footer>

# Хорошие
git commit -m "feat: добавлен DocumentAgent"
git commit -m "docs: создан DESIGN_SYSTEM.md"
git commit -m "fix: исправлена ошибка в Cascade Search"

# С телом
git commit -m "feat(agents): добавлен DocumentAgent

- Генерация PROJECT.md из примеров
- Поддержка YAML frontmatter
- Интеграция с Cascade Search

Resolves: #12"

# Плохие
git commit -m "update"
git commit -m "changes"
git commit -m "фикс"

# 1. Проверить статус
git status

# 2. Посмотреть изменения
git diff

# 3. Добавить файлы
git add platform/agents/document_agent.py
# Или всё:
git add .

# 4. Commit
git commit -m "feat: добавлен DocumentAgent"

# 5. История
git log --oneline -10

# 6. Посмотреть конкретный коммит
git show a1b2c3d

# Откатить файл (до последнего коммита)
git checkout -- platform/agents/document_agent.py

# Откатить последний коммит (но оставить изменения)
git reset --soft HEAD~1

# Откатить последний коммит (удалить изменения)
git reset --hard HEAD~1

# Откатить к конкретному коммиту
git reset --hard a1b2c3d

# Коммиты с DocumentAgent
git log --oneline --grep="DocumentAgent"

# Изменения в конкретном файле
git log --oneline -- platform/agents/document_agent.py

# Кто менял файл
git blame platform/agents/document_agent.py

# Поиск в коде
git log -S "def execute" --source --all

# Добавить remote (GitHub)
git remote add origin git@github.com:username/cifra-platform.git

# Push
git push -u origin master

# Pull (если работаем с разных мест)
git pull origin master

"Привет! Давай продолжим работу над платформой"

1. Читаю platform/.claude/system-journal.md (последние события)
2. Читаю platform/.claude/session-YYYY-MM-DD.md (вчерашняя сессия)
3. git log --oneline -10 (последние коммиты)
4. Показываю вам краткий статус:

📊 Статус платформы (2025-11-10)

Последние изменения:
- ✅ Создана система проектирования (DESIGN_SYSTEM.md)
- ✅ Проанализированы технические инструменты
- 🔄 В процессе: валидация системы проектирования

Что делаем сегодня?

"Давай спроектируем DocumentAgent"

Применяю систему проектирования:

ЭТАП 1: ОПРЕДЕЛЕНИЕ
DocumentAgent — агент для генерации документации проектов.

Назначение:
- Создание PROJECT.md для новых проектов
- Генерация ROADMAP.md, ARCHITECTURE.md
- Обновление CHANGELOG.md

Кто использует:
- CentralAgent (при создании проекта)
- Вы (вручную через CLI)

Переходим к ЭТАПУ 2: Контекстный анализ?

"Да, продолжай"

ЭТАП 2: КОНТЕКСТНЫЙ АНАЛИЗ

Существующие решения:
- ✅ templates/library/README.md (примеры документации)
- ✅ projects/marketplace/design/PROJECT.md (пример проекта)

Зависимости:
- Claude API (для генерации текста)
- python-frontmatter (для YAML метаданных)
- Cascade Search (поиск примеров)

Интеграции:
- ProjectAgent (создаёт структуру, DocumentAgent заполняет)
- GitAgent (коммитит результат)

Переходим к ЭТАПУ 3: Многосрезовый анализ?

"Пока хватит, создавай DESIGN.md"

Создаю platform/agents/DocumentAgent/DESIGN.md...
[Создание файла]

✅ Создан DESIGN.md (версия 0.1.0, черновик)

Теперь ЭТАП 5: Валидация.

Вопросы:
Q1: Какие типы документов генерировать приоритетно?
    A) PROJECT.md
    B) ROADMAP.md
    C) ARCHITECTURE.md
    D) Все три

Q2: Откуда брать примеры для генерации?
    A) Из существующих проектов (marketplace)
    B) Из шаблонов
    C) Из обоих

Q3: Как обновлять существующие документы?
    A) Перезаписывать полностью
    B) Обновлять только метаданные
    C) Спрашивать пользователя

"Q1: D, Q2: C, Q3: C"

Обновляю DESIGN.md с вашими ответами...

✅ DESIGN.md обновлён (версия 0.2.0)

Ещё вопросы или утверждаем (переход к v1.0.0)?

"Утверждаем"

ЭТАП 6: УТВЕРЖДЕНИЕ

✅ DESIGN.md → версия 1.0.0
✅ Статус: Утверждено
✅ Git commit

[Выполняю команды]
git add platform/agents/DocumentAgent/
git commit -m "docs: спецификация DocumentAgent утверждена

- Версия 1.0.0
- Генерация PROJECT.md, ROADMAP.md, ARCHITECTURE.md
- Использует примеры из проектов и шаблонов
- Интерактивное обновление документов

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

✅ Коммит создан: a1b2c3d

Переходим к реализации кода?

"На сегодня хватит"

Фиксирую сессию:

1. Обновляю platform/.claude/system-journal.md:

### 2025-11-10: Спроектирован DocumentAgent
**Действие:** Создана спецификация DocumentAgent
**Изменения:**
- DESIGN.md v1.0.0 утверждён
- Определены функции агента
**Статус:** ✅ Готов к реализации

2. Создаю platform/.claude/session-2025-11-10.md:

# Сессия 2025-11-10

## Задачи
- Проектирование DocumentAgent

## Решения
- Генерирует 3 типа документов
- Использует примеры из проектов
- Интерактивное обновление

## Созданные файлы
- platform/agents/DocumentAgent/DESIGN.md

## Следующие шаги
- Реализация кода DocumentAgent

3. Git commit:
git add platform/.claude/
git commit -m "chore: обновлён журнал сессии 2025-11-10"

До завтра! 👋

"Создай новый проект analytics используя шаблон streamlit-mvp-v1"

- Проверяю существование шаблона
- Спрашиваю переменные (если нужны)
- Создаю структуру projects/analytics/
- Копирую файлы из templates/streamlit-mvp-v1/
- Заменяю переменные {{PROJECT_NAME}} → analytics
- Создаю PROJECT.md с метаданными
- Git commit

✅ Проект analytics создан

Структура:
projects/analytics/
├── PROJECT.md
├── design/
├── management/
│   └── README.md
└── solution/mvp/
    ├── app.py
    └── requirements.txt

Быстрый старт:
cd projects/analytics/solution/mvp
pip install -r requirements.txt
streamlit run app.py

Что дальше?

"Запусти приложение"

cd projects/analytics/solution/mvp
streamlit run app.py

Обновляю management/CHANGELOG.md:

### [1.1.0] - 2025-11-10
#### Added
- Экспорт заказов в Excel

Обновить PROJECT.md (версия 1.0.0 → 1.1.0)?

"Да"

git add projects/marketplace/
git commit -m "docs: обновлена документация marketplace v1.1.0"

Нужно решить как хранить метрики агентов.

Варианты:
A. YAML файлы (простота, Git friendly)
B. SQLite (быстрые запросы, не Git friendly)
C. CSV файлы (простота, легко импортировать)

Плюсы/минусы:
[Таблица сравнения]

Мои рекомендации: Вариант A для Фазы 0-1, потом B

"Согласен, начинаем с YAML"

Создаю platform/.claude/decisions/ADR-002-metrics-storage.md:

# ADR-002: Хранение метрик в YAML

**Дата:** 2025-11-10
**Статус:** Принято

**Контекст:** ...
**Решение:** YAML файлы
**Обоснование:** ...

Git commit -m "docs: ADR-002 хранение метрик"

❌ Ошибка при выполнении:
[Traceback]

Варианты:
A. Откатить изменения (git reset)
B. Исправить ошибку
C. Начать заново

Что делаем?

"Откатить"

git status  # Что изменилось
git diff    # Посмотреть diff
git reset --hard HEAD~1  # Откатить последний коммит

✅ Откат выполнен

1. platform/.claude/system-journal.md
   ↓ Последние 3-5 событий
   ↓ Что важного произошло

2. platform/.claude/session-YYYY-MM-DD.md (вчера)
   ↓ Детали последней сессии
   ↓ Незавершённые задачи

3. git log --oneline -10
   ↓ Последние коммиты
   ↓ Что менялось

4. git status
   ↓ Незакоммиченные изменения
   ↓ Что в процессе

↓

ВОССТАНОВЛЕН КОНТЕКСТ ✅

# platform/.claude/notes-for-claude.md

## 2025-11-10
- Завтра продолжим реализацию DocumentAgent
- Не забудь про тесты!
- Проверить работу с русскими символами в именах файлов

# platform/.claude/progress.yaml

projects:
  marketplace:
    status: active
    version: 1.1.0
    completion: 85%

agents:
  DocumentAgent:
    status: in_design
    version: 0.2.0
  CodeAgent:
    status: planned
    version: 0.0.0

platform:
  total_commits: 25
  total_files: 150
  total_lines: 15000

# platform/.claude/metrics/2025-11-10.csv

timestamp,agent,operation,tokens_input,tokens_output,tokens_cached
2025-11-10 14:30:00,DocumentAgent,create_project_md,1234,567,890
2025-11-10 15:00:00,CodeAgent,generate_function,2345,1234,1500

# platform/.claude/reports/week-2025-W45.md

# Отчёт за неделю 2025-W45

## Достижения
- ✅ Создана система проектирования
- ✅ Спроектирован DocumentAgent
- ✅ Реализовано 50% функций CodeAgent

## Метрики
- Коммиты: 15
- Файлов создано: 25
- Строк кода: 2500
- Токенов использовано: 150K (экономия: 80%)

## Следующая неделя
- Завершить CodeAgent
- Начать GitAgent
- Первый end-to-end workflow

A: НЕ в Git!

Создайте .env файл:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Добавьте в .gitignore:
.env

Загрузка в коде:
from dotenv import load_dotenv
load_dotenv()

A: Git LFS или хранить вне Git

Git LFS:
git lfs install
git lfs track "*.xlsx"
git add .gitattributes

A: Да, через Git remote

1. Создать GitHub private repo
2. git remote add origin ...
3. git push -u origin master
4. На другом компьютере: git clone ...

A: 3 уровня:

1. Локальный:
   tar -czf /backup/workspace-$(date +%Y%m%d).tar.gz /opt/claude-workspace/

2. Git remote:
   git push origin master

3. Облако:
   rsync -avz /opt/claude-workspace/ user@backup-server:/backups/

ВЫ                          Я (Claude)
 ↓                               ↓
"Что нужно"  ────────→  "Как сделать" (предложения)
                               ↓
"Утверждаю"  ←────────  Варианты A/B/C
 ↓                               ↓
                        Реализация (код/документы)
                               ↓
Проверка     ←────────  Результат
 ↓                               ↓
"ОК"/"Правка" ─────→   Исправления (если нужно)
 ↓                               ↓
                        Git commit + Документация
                               ↓
                        Обновление журнала