📚 DOCUMENTATION - Система документации проекта

Версия: 1.0
Дата: 2025-11-08
Назначение: Мета-документ о системе документации

🎯 КОНЦЕПЦИЯ

Принципы:

1. Разделение ответственностей - каждый документ = одна четкая цель
2. Уровни документов - проектные vs. универсальные
3. Связь с Claude Code - специальные файлы для Claude
4. Именование - понятные названия, единый формат

📊 СТРУКТУРА ДОКУМЕНТАЦИИ

2 УРОВНЯ ДОКУМЕНТОВ:

┌─────────────────────────────────────────────┐
│         УРОВЕНЬ 1: ПРОЕКТНЫЕ               │
│   (специфичны для marketplace-mvp)          │
├─────────────────────────────────────────────┤
│ • PROJECT-MASTER.md                         │
│ • ROADMAP.md                                │
│ • API-GUIDE.md                              │
│ • CHANGELOG.md                              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│      УРОВЕНЬ 2: УНИВЕРСАЛЬНЫЕ              │
│  (стандарты для любого Streamlit проекта)   │
├─────────────────────────────────────────────┤
│ • STYLE-GUIDE.md                            │
│ • CODE-GUIDE.md                             │
│ • WORKFLOWS.md                              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│      УРОВЕНЬ 3: СЛУЖЕБНЫЕ                  │
│        (для Claude Code)                    │
├─────────────────────────────────────────────┤
│ • CLAUDE.md                                 │
│ • .claude/settings.json                     │
│ • DOCUMENTATION.md (этот файл)              │
└─────────────────────────────────────────────┘

📋 КАТАЛОГ ДОКУМЕНТОВ

🔵 УРОВЕНЬ 1: ПРОЕКТНЫЕ ДОКУМЕНТЫ

Расположение: Корень проекта
Назначение: Специфичны для marketplace-mvp
Формат имени: НАЗВАНИЕ.md

1.1 PROJECT-MASTER.md

Что: Источник данных о проекте
Для кого: Claude Code, разработчики
Содержание:
- Описание проекта
- Архитектура БД
- Схемы fulfillment
- Модели БД (справочник)
- Текущее состояние

Обновляется: При изменении архитектуры
Размер: ~400 строк
Связь с Claude: Основной источник контекста проекта

1.2 ROADMAP.md

Что: Пошаговый план развития
Для кого: Claude Code, менеджер проекта
Содержание:
- Текущий статус
- Приоритеты
- Roadmap на 3 месяца
- TODO первоочередные
- Метрики успеха

Обновляется: Еженедельно
Размер: ~300 строк
Связь с Claude: Источник задач для разработки

1.3 API-GUIDE.md

Что: Справочник API интеграций
Для кого: Claude Code, разработчики
Содержание:
- Ozon API (методы, примеры)
- СДЭК API (в разработке)
- Почта России API (в разработке)
- Best practices

Обновляется: При добавлении интеграций
Размер: ~600 строк
Связь с Claude: Справочник при работе с API

1.4 CHANGELOG.md

Что: История изменений
Для кого: Все
Содержание:
- Версии (Major.Minor.Patch)
- Added/Changed/Fixed/Removed
- Даты релизов

Обновляется: При каждом коммите
Размер: Растет со временем
Связь с Claude: Информация о версиях

🟢 УРОВЕНЬ 2: УНИВЕРСАЛЬНЫЕ СТАНДАРТЫ

Расположение: Корень проекта
Назначение: Переиспользуемые для любого Streamlit проекта
Формат имени: ТИП-GUIDE.md

2.1 STYLE-GUIDE.md

Что: Стандарты UI/UX
Для кого: Claude Code при создании UI
Содержание:
- Цветовая палитра
- Типографика
- Компоненты (таблицы, кнопки, формы)
- Layout
- Spacing

Универсален: ✅ Можно использовать в любом Streamlit проекте
Обновляется: При изменении дизайна
Размер: ~500 строк
Связь с Claude: Руководство при создании UI

2.2 CODE-GUIDE.md

Что: Стандарты написания кода
Для кого: Claude Code, разработчики
Содержание:
- Naming conventions
- Шаблоны кода
- Error handling
- Performance
- Security
- Testing
- Database
- Git

Универсален: ✅ Можно использовать в любом Python/Streamlit проекте
Обновляется: При изменении стандартов
Размер: ~700 строк
Связь с Claude: Руководство при написании кода

2.3 WORKFLOWS.md

Что: Процессы работы с проектом
Для кого: Claude Code, разработчики
Содержание:
- Как добавить фичу (чек-лист)
- Как добавить страницу Streamlit
- Как работать с БД
- Как сделать релиз
- Troubleshooting

Универсален: ⚠️ Частично (некоторые процессы универсальны)
Обновляется: При появлении новых процессов
Размер: ~400 строк
Связь с Claude: Руководство по процессам

🟡 УРОВЕНЬ 3: СЛУЖЕБНЫЕ (для Claude Code)

Расположение: Корень + .claude/
Назначение: Управление работой Claude Code
Формат: Специальный

3.1 CLAUDE.md

Что: Инструкции для Claude Code
Для кого: Claude Code (основной файл!)
Содержание:
- Краткое описание проекта
- Структура проекта
- Расположение документации
- Правила работы
- Ссылки на детальные документы

Обновляется: При изменении структуры проекта
Размер: ~200 строк
Связь с Claude: Первый файл, который читает Claude

Особенность: Находится в /opt/claude-workspace/projects/mp1/CLAUDE.md
(если проект как отдельный workspace)

3.2 .claude/settings.json

Что: Настройки Claude Code для проекта
Для кого: Claude Code
Содержание:

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "Bash": "always-allow",
    "Read": "always-allow",
    "Write": "always-allow"
  },
  "context": {
    "docs": [
      "PROJECT-MASTER.md",
      "ROADMAP.md",
      "STYLE-GUIDE.md",
      "CODE-GUIDE.md"
    ]
  }
}

Обновляется: Редко (при настройке проекта)

3.3 DOCUMENTATION.md (этот файл)

Что: Мета-документ о системе документации
Для кого: Claude Code, разработчики
Содержание:
- Концепция документации
- Уровни документов
- Именование
- Связи между документами
- Правила ведения

Обновляется: При изменении системы документации
Размер: ~300 строк

📝 ДОПОЛНИТЕЛЬНЫЕ ДОКУМЕНТЫ

README.md

Уровень: Входная точка
Что: Быстрый старт
Размер: ~50 строк
Содержание:

# Проект

## Быстрый старт
[3 команды]

## Документация
- PROJECT-MASTER.md - о проекте
- ROADMAP.md - план
- STYLE-GUIDE.md - дизайн
- CODE-GUIDE.md - код
- WORKFLOWS.md - процессы

🏷️ ПРАВИЛА ИМЕНОВАНИЯ

Формат: НАЗВАНИЕ-ТИП.md

Типы документов:

Префиксы по областям:

Примеры правильного именования:

✅ Хорошо:
- PROJECT-MASTER.md - главный о проекте
- STYLE-GUIDE.md - руководство по стилю
- CODE-GUIDE.md - руководство по коду
- ROADMAP.md - дорожная карта
- API-GUIDE.md - руководство по API
- CHANGELOG.md - стандартное имя
- README.md - стандартное имя

❌ Плохо:
- guide-style.md - неправильный порядок
- style_guide.md - underscore вместо дефиса
- StyleGuide.md - camelCase
- documentation.md - слишком общее (это мета-документ, поэтому DOCUMENTATION.md)

📂 РАСПОЛОЖЕНИЕ ФАЙЛОВ

Корень проекта:

/home/claude-helper/marketplace-mvp/
├── README.md                  ← Входная точка
├── DOCUMENTATION.md           ← Мета-документ (этот файл)
├── PROJECT-MASTER.md          ← О проекте
├── ROADMAP.md                 ← План развития
├── CHANGELOG.md               ← История версий
├── STYLE-GUIDE.md             ← Стандарты UI/UX
├── CODE-GUIDE.md              ← Стандарты кода
├── WORKFLOWS.md               ← Процессы работы
└── API-GUIDE.md               ← Справочник API

Папка docs/:

docs/
├── diagrams/                  ← Диаграммы
│   ├── database_er.png
│   ├── architecture.png
│   └── fulfillment_flows.png
│
├── archive/                   ← Архив старых планов
│   ├── ARCHITECTURE_AUDIT.md
│   ├── PRODUCTS_IMPLEMENTATION_PLAN.md
│   └── TESTING_REPORT.md
│
└── DOCUMENTATION_*.md         ← Аналитические документы
    ├── DOCUMENTATION_AUDIT.md
    ├── DOCUMENTATION_STRATEGY.md
    └── DOCUMENTATION_FINAL_STRUCTURE.md

Служебная папка .claude/:

.claude/
├── settings.json              ← Настройки Claude Code
└── context/                   ← Дополнительный контекст (опционально)

🔗 СВЯЗИ МЕЖДУ ДОКУМЕНТАМИ

Иерархия (кто на кого ссылается):

README.md
    ├─→ PROJECT-MASTER.md
    ├─→ ROADMAP.md
    ├─→ STYLE-GUIDE.md
    ├─→ CODE-GUIDE.md
    ├─→ WORKFLOWS.md
    └─→ API-GUIDE.md

PROJECT-MASTER.md
    ├─→ ROADMAP.md (для планов)
    ├─→ API-GUIDE.md (для API методов)
    ├─→ diagrams/ (для визуализации)
    └─→ CHANGELOG.md (для истории)

ROADMAP.md
    ├─→ PROJECT-MASTER.md (для контекста)
    └─→ WORKFLOWS.md (как выполнять задачи)

STYLE-GUIDE.md
    └─→ CODE-GUIDE.md (для шаблонов кода)

CODE-GUIDE.md
    ├─→ WORKFLOWS.md (для процессов)
    └─→ STYLE-GUIDE.md (для UI компонентов)

WORKFLOWS.md
    ├─→ CODE-GUIDE.md (для стандартов)
    ├─→ STYLE-GUIDE.md (для UI)
    └─→ API-GUIDE.md (для интеграций)

API-GUIDE.md
    └─→ CODE-GUIDE.md (для best practices)

Формат ссылок:

# Внутри проекта (относительные)
См. [ROADMAP.md](ROADMAP.md)
См. [API-GUIDE.md → Ozon API](API-GUIDE.md#ozon-api)
См. [diagrams/database_er.png](docs/diagrams/database_er.png)

# Якоря для навигации
## Раздел {#имя-раздела}
[Ссылка на раздел](#имя-раздела)

🤖 СВЯЗЬ С CLAUDE CODE

Как Claude использует документы:

1. Первый запуск (новый проект)

Claude читает:
1. README.md              ← Быстрое понимание (2 мин)
2. DOCUMENTATION.md       ← Структура документации (5 мин)
3. PROJECT-MASTER.md      ← Детали проекта (10 мин)

2. Работа над фичей

Claude читает:
1. ROADMAP.md             ← Взять задачу
2. PROJECT-MASTER.md      ← Контекст (архитектура)
3. CODE-GUIDE.md          ← Как писать код
4. STYLE-GUIDE.md         ← Как делать UI
5. API-GUIDE.md           ← Как работать с API (если нужно)
6. WORKFLOWS.md           ← Чек-лист выполнения

3. Исправление бага

Claude читает:
1. PROJECT-MASTER.md      ← Понять архитектуру
2. CODE-GUIDE.md          ← Стандарты
3. WORKFLOWS.md           ← Процесс bugfix

4. Обновление документации

Claude обновляет:
1. CHANGELOG.md           ← Добавить в Unreleased
2. ROADMAP.md             ← Вычеркнуть из TODO (если задача)
3. PROJECT-MASTER.md      ← Если изменилась архитектура

📜 ПРАВИЛА ВЕДЕНИЯ ДОКУМЕНТОВ

1. АКТУАЛЬНОСТЬ

Правило: Документ должен отражать текущее состояние

Как обеспечить:
- Обновлять сразу после изменений
- Указывать дату последнего обновления
- Версионировать (если нужно)

Пример:

# PROJECT-MASTER.md

**Версия:** 2.4.0
**Последнее обновление:** 2025-11-08

## Текущее состояние
- ✅ Реализовано X
- ❌ НЕ реализовано Y

2. СВЯЗНОСТЬ

Правило: Документы должны ссылаться друг на друга

Как:
- Использовать относительные ссылки
- Не дублировать информацию
- При упоминании - давать ссылку

Пример:

# PROJECT-MASTER.md

## API Методы

Подробный справочник API методов см. в [API-GUIDE.md](API-GUIDE.md)

Краткий список:
- Ozon: см. [API-GUIDE → Ozon](API-GUIDE.md#ozon-api)
- СДЭК: (в разработке)

3. ЕДИНООБРАЗИЕ

Правило: Единый формат и стиль

Стандарты:
- Markdown (GitHub Flavored)
- Заголовки: # для H1, ## для H2, и т.д.
- Списки: - для ненумерованных, 1. для нумерованных
- Код: ``` блоки с указанием языка
- Эмодзи: для визуальной навигации (🎯, 📋, ✅, ❌)

Шаблон документа:

# НАЗВАНИЕ ДОКУМЕНТА

**Версия:** X.Y.Z
**Дата:** YYYY-MM-DD
**Назначение:** Краткое описание

---

## 📑 СОДЕРЖАНИЕ

- [Раздел 1](#раздел-1)
- [Раздел 2](#раздел-2)

---

## Раздел 1

Контент...

---

## Раздел 2

Контент...

---

**Последнее обновление:** YYYY-MM-DD

4. МИНИМАЛИЗМ

Правило: Документ должен содержать только необходимое

Как:
- Одна тема = один документ
- Убирать устаревшее
- Не дублировать
- Переносить детали в отдельные файлы

Анти-пример:

# PROJECT-MASTER.md (1773 строки!)

## Описание
...
## Архитектура
...
## API методы (500 строк!)  ← В отдельный API-GUIDE.md
...
## Roadmap (300 строк!)      ← В отдельный ROADMAP.md
...
## Стандарты кода (200 строк!) ← В CODE-GUIDE.md

5. ДОСТУПНОСТЬ

Правило: Легко найти нужное

Как:
- TOC (Table of Contents) в больших документах
- Якоря для навигации
- Понятные заголовки
- Визуальные разделители (эмодзи, линии)

Пример:

# PROJECT-MASTER.md

## 📑 СОДЕРЖАНИЕ

1. [Описание](#описание)
2. [Архитектура](#архитектура)
   - [Структура БД](#структура-бд)
   - [Схемы Fulfillment](#схемы-fulfillment)
3. [Модели БД](#модели-бд)

---

## 📋 Описание {#описание}

...

---

## 🏗️ Архитектура {#архитектура}

### Структура БД {#структура-бд}

...

🔄 LIFECYCLE (Жизненный цикл документов)

Создание нового документа:

1. Определить цель - зачем нужен документ?
2. Выбрать тип - GUIDE / MAP / MASTER / другое
3. Назвать по правилам - НАЗВАНИЕ-ТИП.md
4. Создать по шаблону - структура + TOC
5. Добавить ссылки - из README и других документов
6. Обновить DOCUMENTATION.md - добавить в каталог

Обновление документа:

1. Внести изменения
2. Обновить дату - Последнее обновление: YYYY-MM-DD
3. Проверить ссылки - все работают?
4. Commit - docs: обновлён [документ]

Удаление/архивирование:

1. Проверить ссылки - кто ссылается на этот документ?
2. Обновить ссылки - убрать или заменить
3. Переместить в archive/ - если нужно сохранить
4. Удалить - если не нужен
5. Обновить DOCUMENTATION.md - убрать из каталога

🎓 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ

Пример 1: Новый разработчик присоединяется

# День 1
1. Читает README.md (2 мин)
   → Понимает: что это, как запустить

2. Запускает проект (5 мин)
   → Видит работающее приложение

3. Читает DOCUMENTATION.md (10 мин)
   → Понимает: структуру документации

4. Читает PROJECT-MASTER.md (30 мин)
   → Понимает: архитектуру, схемы, модели

# День 2
5. Читает ROADMAP.md (15 мин)
   → Понимает: что делать дальше

6. Читает CODE-GUIDE.md (1 час)
   → Понимает: как писать код

7. Берёт задачу из ROADMAP → работает

Пример 2: Claude Code работает над фичей

# Задача: Добавить интеграцию СДЭК

# Шаг 1: Читает контекст
claude.read("ROADMAP.md")
# → Видит в TODO: "СДЭК API интеграция"

claude.read("PROJECT-MASTER.md")
# → Понимает: архитектуру, где что лежит

claude.read("API-GUIDE.md")
# → Видит: как сделаны другие интеграции (Ozon)

claude.read("CODE-GUIDE.md")
# → Видит: шаблон API клиента

claude.read("WORKFLOWS.md")
# → Видит: чек-лист "Интеграция нового API"

# Шаг 2: Реализует
# - Создаёт modules/delivery/cdek.py по шаблону
# - Следует стандартам из CODE-GUIDE

# Шаг 3: Обновляет документы
claude.update("CHANGELOG.md")
# → Добавляет в [Unreleased]: "Added СДЭК API"

claude.update("ROADMAP.md")
# → Вычёркивает задачу из TODO

claude.update("API-GUIDE.md")
# → Добавляет раздел "СДЭК API"

# Шаг 4: Commit
git commit -m "feat: добавлена интеграция СДЭК API"

Пример 3: Изменение дизайна

# Задача: Изменить цвет кнопок

# Claude читает:
claude.read("STYLE-GUIDE.md")
# → Находит: "Primary: #3B82F6"

# Изменяет:
# STYLE-GUIDE.md: Primary: #3B82F6 → #2563EB

# Применяет во всех компонентах
# Обновляет дату в STYLE-GUIDE.md

# Commit:
git commit -m "style: изменён цвет primary кнопок"

📊 МЕТРИКИ КАЧЕСТВА ДОКУМЕНТАЦИИ

Чек-лист хорошей документации:

• [ ] Полнота - все аспекты покрыты
• [ ] Актуальность - соответствует текущему коду
• [ ] Связность - документы ссылаются друг на друга
• [ ] Доступность - легко найти нужное (TOC, якоря)
• [ ] Единообразие - единый формат
• [ ] Минимализм - нет лишнего, нет дублирования
• [ ] Примеры - есть примеры кода
• [ ] Визуализация - есть диаграммы (для сложного)

Периодический аудит (раз в месяц):

# Проверить актуальность
- PROJECT-MASTER отражает текущую архитектуру?
- ROADMAP отражает текущие планы?
- CODE-GUIDE соответствует коду?

# Проверить связность
- Все ссылки работают?
- Нет битых ссылок?

# Проверить дублирование
- Информация в одном месте?
- Нет копипаста между документами?

🚀 ВНЕДРЕНИЕ В НОВЫЙ ПРОЕКТ

Шаблон для нового Streamlit проекта:

# 1. Скопировать универсальные гайды
cp marketplace-mvp/STYLE-GUIDE.md new-project/
cp marketplace-mvp/CODE-GUIDE.md new-project/
cp marketplace-mvp/WORKFLOWS.md new-project/

# 2. Создать проектные документы
touch new-project/README.md
touch new-project/PROJECT-MASTER.md
touch new-project/ROADMAP.md
touch new-project/CHANGELOG.md
touch new-project/DOCUMENTATION.md

# 3. Создать служебные
mkdir new-project/.claude
touch new-project/.claude/settings.json

# 4. Заполнить шаблоны
# README.md - описание проекта
# PROJECT-MASTER.md - архитектура
# ROADMAP.md - планы

📚 ДОПОЛНИТЕЛЬНЫЕ РЕСУРСЫ

Стандарты Markdown:

• GitHub Flavored Markdown: https://github.github.com/gfm/
• CommonMark: https://commonmark.org/

Стандарты changelog:

• Keep a Changelog: https://keepachangelog.com/
• Semantic Versioning: https://semver.org/

Инструменты диаграм:

• dbdiagram.io - ER диаграммы БД
• draw.io - блок-схемы
• excalidraw - наброски

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

Этот документ версионируется:

• 1.0 (2025-11-08) - Первая версия
• 1.1 (будущее) - Дополнения по мере использования

❓ FAQ

Q: Обязательно ли следовать этой структуре?

A: Да, для проектов с Claude Code. Это обеспечивает единообразие.

Q: Можно ли добавить свои документы?

A: Да, но следуя правилам именования и размещения.

Q: Что делать если документ стал слишком большим?

A: Разбить на тематические поддокументы. Пример: API-GUIDE.md → API-OZON-GUIDE.md, API-CDEK-GUIDE.md

Q: Нужно ли документировать каждую функцию?

A: Нет. Docstrings для публичных API. Комментарии для сложной логики.

Q: Как часто обновлять ROADMAP?

A: Минимум раз в неделю. Идеально - после каждого завершенного таска.

Этот документ - живой. Обновляется по мере развития системы документации.

Вопросы и предложения: Обновите этот файл!