architect/_archive/2025-11-cleanup/DOCUMENTATION_GUIDE.md

📖 РУКОВОДСТВО ПО РАБОТЕ С ДОКУМЕНТАЦИЕЙ

Дата создания: 2025-11-14
Версия: 1.0
Назначение: Полное руководство по организации, поиску и работе с документацией workspace

🎯 СОДЕРЖАНИЕ

  1. Общие принципы
  2. Структура документации
  3. Типы документов
  4. Где что искать
  5. Создание новых документов
  6. Обновление документации
  7. Стандарты оформления
  8. Примеры использования

📐 ОБЩИЕ ПРИНЦИПЫ

Иерархия документации

/opt/claude-workspace/
├── CLAUDE.md                    # 📌 ГЛАВНЫЙ ВХОД для Claude Code
├── SYSTEM_CATALOG.md            # 📌 КАТАЛОГ всех компонентов системы
├── DOCUMENTATION_GUIDE.md       # 📌 Этот документ - как работать с документацией
│
├── platform/                    # 🏗️ Документация ПЛАТФОРМЫ
│   ├── PLATFORM_v2_COMPLETE.md  # Полная документация платформы
│   ├── PLATFORM_v2_STATUS.md    # Статус платформы
│   ├── CLAUDE_v2.md             # Инструкции для Claude v2
│   ├── administrator/           # Роль: администратор
│   ├── architect/               # Роль: архитектор
│   ├── developer/               # Роль: разработчик
│   ├── tester/                  # Роль: тестировщик
│   └── ...                      # Другие роли
│
├── projects/                    # 📦 Документация ПРОЕКТОВ
│   ├── marketplace/
│   │   ├── CLAUDE.md            # 📌 ГЛАВНЫЙ ВХОД для проекта Marketplace
│   │   ├── management/
│   │   │   ├── CHANGELOG.md     # История изменений
│   │   │   └── README.md        # Управление проектом
│   │   ├── solution/mvp/
│   │   │   ├── RELEASE_NOTES_v3.0.md      # Release notes версии
│   │   │   ├── USER_GUIDE_DELIVERY_v3.md  # Руководство пользователя
│   │   │   ├── TEST_REPORT_DAY19.md       # Отчеты тестирования
│   │   │   ├── MVP_SPECIFICATION.md       # Спецификация
│   │   │   └── ...
│   │   └── infrastructure/
│   │       └── ...
│   │
│   └── @remote-beget-kondurov/
│       ├── ACCESS_RESTORED_REPORT.md
│       ├── management/
│       └── projects/
│
└── .claude/                     # 🔧 Системная документация
    ├── SESSION_RECOVERY.md      # Система восстановления сессий
    └── scripts/                 # Скрипты

Принципы организации

  1. Точка входа на каждом уровне
    - Корень workspace: CLAUDE.md
    - Каждый проект: {project}/CLAUDE.md
    - Каждое решение: {project}/solution/{name}/README.md

  2. Каталогизация
    - SYSTEM_CATALOG.md - полный каталог всех компонентов
    - Для каждого компонента - своя секция в каталоге

  3. Версионирование
    - Документы версий: RELEASE_NOTES_v3.0.md, USER_GUIDE_v3.md
    - Старые версии: *_old.md или перемещать в archive/

  4. Типизация
    - Технические: SPECIFICATION.md, ARCHITECTURE.md
    - Пользовательские: USER_GUIDE.md, QUICK_START.md
    - Отчеты: TEST_REPORT.md, AUDIT_REPORT.md
    - Процедуры: WORKFLOW.md, DEPLOYMENT.md

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

Уровень 1: Workspace (корень)

/opt/claude-workspace/
├── CLAUDE.md                    # Главный файл для Claude Code
├── SYSTEM_CATALOG.md            # Каталог всех компонентов
├── DOCUMENTATION_GUIDE.md       # Это руководство
├── README.md                    # Общее описание workspace (если есть)
└── CHANGELOG.md                 # История изменений workspace (если есть)

Назначение:
- Общие инструкции для всего workspace
- Навигация по проектам
- Системная документация

Уровень 2: Платформа

/opt/claude-workspace/platform/
├── PLATFORM_v2_COMPLETE.md      # Полная документация
├── PLATFORM_v2_STATUS.md        # Текущий статус
├── CLAUDE_v2.md                 # Инструкции для Claude
├── {role}/                      # Документация по ролям
│   ├── README.md
│   ├── PROCEDURES.md
│   └── EXAMPLES.md
└── .claude/
    └── SHARED-HOSTING-RULES.md  # Специфичные правила

Назначение:
- Архитектура платформы
- Роли и процедуры
- Стандарты разработки

Уровень 3: Проект

/opt/claude-workspace/projects/{project}/
├── CLAUDE.md                    # 📌 Точка входа в проект
├── design/                      # Проектирование
│   ├── PROJECT.md               # Описание проекта
│   ├── ARCHITECTURE.md          # Архитектура
│   └── ROADMAP.md               # План развития
├── management/                  # Управление
│   ├── README.md                # Быстрый старт
│   └── CHANGELOG.md             # История изменений
├── solution/{name}/             # Решения (код)
│   ├── LOCATION.md              # Расположение и структура
│   ├── RELEASE_NOTES_v*.md      # Release notes
│   ├── USER_GUIDE_*.md          # Руководства
│   ├── TEST_REPORT_*.md         # Отчеты тестирования
│   └── code/                    # Исходный код
└── infrastructure/              # Инфраструктура
    ├── DEPLOYMENT.md            # Развертывание
    └── SERVER.md                # Информация о сервере

Назначение:
- Документация конкретного проекта
- Техническая и пользовательская документация
- Отчеты и спецификации

Уровень 4: Решение (код)

/opt/claude-workspace/projects/{project}/solution/{name}/
├── README.md                    # Описание решения
├── RELEASE_NOTES_v3.0.md        # Что нового в версии
├── USER_GUIDE_*.md              # Руководства пользователя
├── TEST_REPORT_*.md             # Отчеты тестирования
├── SPECIFICATION.md             # Спецификация
├── WORKFLOW_*.md                # Рабочие процессы
└── code/                        # Исходный код
    ├── README.md                # Технические инструкции
    ├── TESTING_INSTRUCTIONS.md  # Инструкции по тестированию
    └── ...

Назначение:
- Документация конкретной реализации
- Технические детали
- Инструкции для разработчиков

📋 ТИПЫ ДОКУМЕНТОВ

1. Входные точки (Entry Points)

Файлы: CLAUDE.md, README.md

Назначение:
- Первое, что читается при входе в директорию
- Навигация по документации
- Быстрый старт

Пример структуры:

# Название проекта/компонента

## Обзор
- Краткое описание
- Назначение
- Статус

## Быстрая навигация
- Ссылки на основные документы
- Структура директорий
- Основные команды

## Основные документы
- design/PROJECT.md - описание
- solution/mvp/RELEASE_NOTES.md - что нового
- infrastructure/DEPLOYMENT.md - развертывание

2. Технические спецификации

Файлы: SPECIFICATION.md, ARCHITECTURE.md, PAGES_SPECIFICATION.md

Назначение:
- Детальное описание архитектуры
- Спецификации компонентов
- Технические требования

Пример структуры:

# Спецификация {компонента}

## Обзор
## Архитектура
## Компоненты
## API/Интерфейсы
## Модели данных
## Технические требования

3. Руководства пользователя

Файлы: USER_GUIDE_*.md, QUICK_START.md

Назначение:
- Инструкции для пользователей
- Пошаговые руководства
- Примеры использования

Пример структуры:

# Руководство пользователя

## Введение
## Начало работы
## Основные сценарии
  - Сценарий 1
  - Сценарий 2
## Расширенные функции
## Часто задаваемые вопросы
## Устранение неполадок

4. Отчеты

Файлы: TEST_REPORT_*.md, AUDIT_REPORT.md, FIXES_REPORT.md

Назначение:
- Результаты тестирования
- Аудиты системы
- Отчеты о выполненных работах

Пример структуры:

# Отчет о {действии}

**Дата:** YYYY-MM-DD
**Версия:** X.Y.Z
**Статус:** ✅/⚠️/❌

## Резюме
## Результаты
## Обнаруженные проблемы
## Рекомендации
## Приложения

5. Процедуры и workflow

Файлы: WORKFLOW_*.md, DEPLOYMENT.md, PROCEDURES.md

Назначение:
- Описание процессов
- Инструкции по развертыванию
- Стандартные процедуры

Пример структуры:

# Процедура {название}

## Цель
## Предварительные требования
## Шаги
  1. Шаг 1
  2. Шаг 2
## Проверка результата
## Откат (если нужно)
## Troubleshooting

6. Release Notes

Файлы: RELEASE_NOTES_v*.md, CHANGELOG.md

Назначение:
- Что нового в версии
- История изменений
- Migration guide

Пример структуры:

# Release Notes v3.0

**Дата релиза:** YYYY-MM-DD
**Версия:** 3.0.0

## Что нового
### Новые функции
### Улучшения
### Исправления

## Breaking Changes
## Migration Guide
## Известные проблемы

7. Каталоги

Файлы: SYSTEM_CATALOG.md, CATALOG.md

Назначение:
- Полный список компонентов
- Навигация по системе
- Справочная информация

Пример структуры:

# Каталог {системы}

## Навигация
## Компоненты
  - Компонент 1
    - Назначение
    - Путь
    - Документация
## Статистика
## Полезные ссылки

🔍 ГДЕ ЧТО ИСКАТЬ

Я хочу найти...

"Как начать работу с проектом X?"

1. /opt/claude-workspace/projects/{X}/CLAUDE.md
   → Главная точка входа

2. /opt/claude-workspace/projects/{X}/management/README.md
   → Быстрый старт, команды запуска

3. /opt/claude-workspace/projects/{X}/solution/{name}/QUICK_START.md
   → Руководство быстрого старта (если есть)

"Что нового в версии Y?"

1. /opt/claude-workspace/projects/{X}/solution/{name}/RELEASE_NOTES_vY.md
   → Release notes версии

2. /opt/claude-workspace/projects/{X}/management/CHANGELOG.md
   → История всех изменений

"Как работает компонент Z?"

1. /opt/claude-workspace/projects/{X}/design/ARCHITECTURE.md
   → Общая архитектура

2. /opt/claude-workspace/projects/{X}/solution/{name}/{Z}_SPECIFICATION.md
   → Спецификация компонента

3. /opt/claude-workspace/projects/{X}/solution/{name}/code/modules/{Z}/README.md
   → Техническая документация модуля

"Как развернуть систему?"

1. /opt/claude-workspace/projects/{X}/infrastructure/DEPLOYMENT.md
   → Полное руководство по развертыванию

2. /opt/claude-workspace/projects/{X}/management/README.md
   → Быстрые команды запуска/остановки

"Где находится код компонента W?"

1. /opt/claude-workspace/projects/{X}/solution/{name}/LOCATION.md
   → Описание расположения и структуры

2. /opt/claude-workspace/SYSTEM_CATALOG.md
   → Каталог всех компонентов системы

"Как выполнить задачу T?"

1. /opt/claude-workspace/projects/{X}/solution/{name}/USER_GUIDE_*.md
   → Руководства пользователя

2. /opt/claude-workspace/projects/{X}/solution/{name}/WORKFLOW_*.md
   → Процедуры и workflow

3. /opt/claude-workspace/projects/{X}/CLAUDE.md
   → Раздел "Основные задачи"

"Что делать при ошибке E?"

1. /opt/claude-workspace/projects/{X}/CLAUDE.md
   → Раздел "Troubleshooting"

2. /opt/claude-workspace/projects/{X}/solution/{name}/USER_GUIDE_*.md
   → Раздел "Устранение неполадок"

3. /opt/claude-workspace/projects/{X}/management/README.md
   → Раздел "Известные проблемы"

"Какие есть компоненты в системе?"

1. /opt/claude-workspace/SYSTEM_CATALOG.md
   → Полный каталог всех компонентов

2. /opt/claude-workspace/CLAUDE.md
   → Обзор workspace

3. /opt/claude-workspace/platform/PLATFORM_v2_COMPLETE.md
   → Документация платформы

✏️ СОЗДАНИЕ НОВЫХ ДОКУМЕНТОВ

Когда создавать новый документ?

  1. Новый проект → создать projects/{name}/CLAUDE.md
  2. Новая версия → создать RELEASE_NOTES_vX.Y.md
  3. Новый компонент → создать {component}_SPECIFICATION.md
  4. Новый процесс → создать WORKFLOW_{process}.md
  5. Результаты работы → создать {TYPE}_REPORT_{date}.md

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

Шаблон: Точка входа (CLAUDE.md)

# {Название проекта/компонента}

## Обзор

**Название:** ...
**Тип:** ...
**Назначение:** ...
**Статус:** ...
**Версия:** ...
**Последнее обновление:** YYYY-MM-DD

---

## Быстрая навигация

### Основные документы

**Проектирование:**
- design/PROJECT.md - описание
- design/ARCHITECTURE.md - архитектура

**Управление:**
- management/README.md - быстрый старт

**Решения:**
- solution/{name}/RELEASE_NOTES.md - что нового

---

## Основные задачи

### Задача 1
```bash
# Команды

Задача 2

...

Troubleshooting

Проблема 1

Решение: ...

Дата создания: YYYY-MM-DD
Версия: X.Y
Автор: ...

#### Шаблон: Отчет

```markdown
# {Тип} Отчет - {Название}

**Дата:** YYYY-MM-DD
**Версия:** X.Y.Z
**Статус:** ✅ Готово / ⚠️ В работе / ❌ Проблемы
**Автор:** ...

---

## Резюме

Краткое описание...

---

## Детали

### Секция 1

### Секция 2

---

## Результаты

- ✅ Успешно выполнено 1
- ✅ Успешно выполнено 2
- ⚠️ С предупреждениями 3
- ❌ Не выполнено 4

---

## Проблемы

### Проблема 1
**Описание:** ...
**Статус:** ...
**Решение:** ...

---

## Рекомендации

1. Рекомендация 1
2. Рекомендация 2

---

**Создано:** YYYY-MM-DD HH:MM
**Обновлено:** YYYY-MM-DD HH:MM

Где размещать новые документы?

Тип документа Местоположение
Главная точка входа проекта projects/{name}/CLAUDE.md
Спецификация проекта projects/{name}/design/SPECIFICATION.md
Архитектура projects/{name}/design/ARCHITECTURE.md
Release Notes projects/{name}/solution/{name}/RELEASE_NOTES_vX.md
Руководство пользователя projects/{name}/solution/{name}/USER_GUIDE_*.md
Отчет тестирования projects/{name}/solution/{name}/TEST_REPORT_*.md
Workflow projects/{name}/solution/{name}/WORKFLOW_*.md
Развертывание projects/{name}/infrastructure/DEPLOYMENT.md
Управление проектом projects/{name}/management/README.md
История изменений projects/{name}/management/CHANGELOG.md
Системная документация .claude/{NAME}.md
Отчеты временные /tmp/{NAME}_REPORT.md

🔄 ОБНОВЛЕНИЕ ДОКУМЕНТАЦИИ

Когда обновлять?

  1. После значительных изменений - обновить CHANGELOG.md
  2. При создании новой версии - создать новый RELEASE_NOTES_vX.md
  3. При изменении архитектуры - обновить ARCHITECTURE.md
  4. При добавлении функций - обновить USER_GUIDE.md
  5. После тестирования - создать TEST_REPORT.md
  6. При обнаружении проблем - обновить раздел Troubleshooting

Процедура обновления

# 1. Определить какие документы затронуты
# 2. Прочитать текущую версию
# 3. Внести изменения
# 4. Обновить дату "Последнее обновление"
# 5. Если нужно - обновить номер версии
# 6. Зафиксировать в git

cd /opt/claude-workspace
git add projects/{name}/...
git commit -m "docs: обновлена документация {компонента}"

Версионирование документов

Для документов с версиями:
- RELEASE_NOTES_v3.0.md - новая версия
- RELEASE_NOTES_v2.5.md - старая версия (оставить)
- Или: USER_GUIDE_v3.md → USER_GUIDE_v3_old.md

Для общих документов:
- Просто обновлять файл
- Обновлять дату в начале: **Последнее обновление:** 2025-11-14
- Git история покажет изменения

🎨 СТАНДАРТЫ ОФОРМЛЕНИЯ

Заголовки

# H1 - Название документа (только один в документе)
## H2 - Главные секции
### H3 - Подсекции
#### H4 - Детали (использовать редко)

Метаданные

В начале каждого документа:

# Название документа

**Дата создания:** YYYY-MM-DD
**Версия:** X.Y.Z
**Статус:** ✅/⚠️/❌
**Автор:** ...
**Последнее обновление:** YYYY-MM-DD

В конце документа:

---

**Создано:** YYYY-MM-DD
**Версия:** X.Y
**Автор:** ...

Форматирование

Выделение:
- **Жирный** - для важных терминов
- *Курсив* - для акцентов
- `Код` - для команд, файлов, переменных
- блок кода - для многострочного кода

Списки:

- Обычный список
  - Вложенный пункт

1. Нумерованный список
2. Пункт 2

Статусы:
- ✅ Готово / Работает / Успешно
- ⚠️ В работе / Предупреждение
- ❌ Не готово / Ошибка / Проблема
- 🔄 В процессе
- 📌 Важно
- 🚀 Новое

Таблицы:

| Колонка 1 | Колонка 2 |
|-----------|-----------|
| Значение 1 | Значение 2 |

Ссылки:

[Текст ссылки](путь/к/файлу.md)
[Внутренняя ссылка](#якорь-секции)

Структура секций

## Секция

### Краткое описание

Текст описания...

### Детали

#### Подсекция 1
...

#### Подсекция 2
...

### Примеры

```bash
# Пример команды

См. также

---

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

### Пример 1: Начало работы с новым проектом

**Задача:** Нужно понять как работает проект Marketplace

**Действия:**
```bash
# 1. Прочитать главную точку входа
cat /opt/claude-workspace/projects/marketplace/CLAUDE.md

# 2. Посмотреть что нового в последней версии
cat /opt/claude-workspace/projects/marketplace/solution/mvp/RELEASE_NOTES_v3.0.md

# 3. Изучить архитектуру
cat /opt/claude-workspace/projects/marketplace/design/ARCHITECTURE.md

# 4. Запустить проект (из инструкций в CLAUDE.md)
cd /opt/claude-workspace/projects/marketplace/solution/mvp/code/
tmux new -d -s marketplace 'source venv/bin/activate && streamlit run app.py --server.port 8503'

Пример 2: Поиск информации о компоненте

Задача: Найти информацию о модуле доставки СДЭК

Действия:

# 1. Посмотреть в каталоге системы
grep -n "cdek" /opt/claude-workspace/SYSTEM_CATALOG.md

# 2. Найти файл модуля
find /opt/claude-workspace/projects/marketplace -name "*cdek*"

# 3. Прочитать код модуля
cat /opt/claude-workspace/projects/marketplace/solution/mvp/code/modules/delivery/cdek_service.py

# 4. Посмотреть в руководстве пользователя
grep -n "СДЭК" /opt/claude-workspace/projects/marketplace/solution/mvp/USER_GUIDE_DELIVERY_v3.md

Пример 3: Создание отчета о тестировании

Задача: Создать отчет после тестирования новой функции

Действия:
```bash

1. Создать файл отчета

cat > /opt/claude-workspace/projects/marketplace/solution/mvp/TEST_REPORT_FEATURE_X.md << 'EOF'

Отчет тестирования - Feature X

Дата: 2025-11-14
Версия: 3.0.1
Статус: ✅ Готово
Тестировщик: Claude Code

Резюме

Протестирована функция X...

Результаты

Тест 1: ...

✅ Успешно

Тест 2: ...

✅ Успешно

Проблемы

Проблем не обнаружено.

Создано: 2025-11-14 10:00