PROJECT-STANDARDS.md

Workspace: Claude Code Workspace
Версия: 2.0.0
Дата создания: 2025-11-08
Последнее обновление: 2025-11-08

🎯 НАЗНАЧЕНИЕ

Этот документ определяет универсальные стандарты для ведения ЛЮБОГО проекта в Claude Code Workspace.

При создании нового проекта используйте шаблоны из /opt/claude-workspace/templates/

Доступно шаблонов: 19 (17 Markdown + 2 конфигурационных)

📑 СОДЕРЖАНИЕ

🏗️ ТИПЫ ПРОЕКТОВ {#типы-проектов}

1. Infrastructure (@infra-*)

Примеры: Серверы, Docker платформы, Kubernetes кластеры
Документы: акцент на DEPLOYMENT, INFRASTRUCTURE, MONITORING

2. Application

Примеры: Web-приложения, API сервисы, микросервисы
Документы: акцент на API-GUIDE, ARCHITECTURE, DEPLOYMENT

3. Library/Package

Примеры: Python библиотеки, npm пакеты
Документы: акцент на API-GUIDE, CONTRIBUTING, примеры использования

4. Data/Analytics

Примеры: ETL пайплайны, аналитические дашборды
Документы: акцент на DATA-DICTIONARY, WORKFLOWS, примеры запросов

5. Composite

Примеры: Платформы из нескольких подпроектов
Документы: акцент на ARCHITECTURE, интеграции между компонентами

✅ ОБЯЗАТЕЛЬНЫЕ ДОКУМЕНТЫ {#обязательные-документы}

Эти документы ОБЯЗАТЕЛЬНЫ для ЛЮБОГО проекта:

1. README.md

Назначение: Точка входа для разработчиков
Размер: 100-200 строк
Содержание:
- Что это за проект (1-2 абзаца)
- Быстрый старт (как запустить за 5 минут)
- Основные команды
- Ссылки на другую документацию
- Контакты/поддержка

2. {PROJECT}-PROJECT-MASTER.md

Назначение: Источник правды о проекте
Размер: 400-800 строк
Содержание:
- Описание проекта и бизнес-модели
- Архитектура (компоненты, технологии)
- База данных (модели, схемы)
- Интеграции
- Текущее состояние (что работает/не работает)
- НЕ содержит: roadmap, API методы, code standards

3. {PROJECT}-CHANGELOG.md

Назначение: История изменений
Формат: Keep a Changelog
Содержание:
- Unreleased (планы)
- Версии с датами
- Added/Changed/Fixed/Removed для каждой версии

4. DOCUMENTATION.md

Назначение: Навигация по документам
Размер: 200-400 строк
Содержание:
- Какие документы есть в проекте
- Для чего каждый документ
- Как они связаны
- Lifecycle правила

5. .env.example

Назначение: Пример конфигурации
Содержание:
- Все переменные окружения (без значений)
- Комментарии где взять значения
- Значения по умолчанию для dev окружения

🔧 ОПЦИОНАЛЬНЫЕ ДОКУМЕНТЫ {#опциональные-документы}

Уровень 2: Для сложных проектов

{PROJECT}-ROADMAP.md

Когда нужен: Проект развивается > 3 месяцев
Содержание: План развития, приоритеты, TODO на ближайшие недели
Шаблон: /opt/claude-workspace/templates/ROADMAP.template.md

{PROJECT}-API-GUIDE.md

Когда нужен: Проект имеет API интеграции
Содержание: Справочник методов, примеры, rate limits

ARCHITECTURE.md

Когда нужен: Сложная архитектура (> 5 компонентов)
Содержание: Диаграммы, data flow, компоненты
Шаблон: /opt/claude-workspace/templates/ARCHITECTURE.template.md

DEPLOYMENT.md

Когда нужен: Нестандартный deployment или production система
Содержание: Как деплоить на dev/staging/prod, rollback, zero-downtime
Шаблон: /opt/claude-workspace/templates/DEPLOYMENT.template.md

SECURITY.md

Когда нужен: Проект работает с чувствительными данными
Содержание: Security checklist, известные уязвимости, best practices
Шаблон: /opt/claude-workspace/templates/SECURITY.template.md

SECRETS.md

Когда нужен: Проект использует пароли, API ключи, SSH ключи
Содержание: Инвентарь секретов, ротация паролей, emergency access, break glass процедура
Шаблон: /opt/claude-workspace/templates/SECRETS.template.md

BACKUP.md

Когда нужен: Production система с важными данными
Содержание: Стратегия бэкапов (3-2-1), RTO/RPO, расписание, restore процедуры
Шаблон: /opt/claude-workspace/templates/BACKUP.template.md

MONITORING.md

Когда нужен: Production система
Содержание: Метрики (CPU/RAM/disk), health checks, алерты, логи, dashboards
Шаблон: /opt/claude-workspace/templates/MONITORING.template.md

MAINTENANCE.md

Когда нужен: Production система требующая регулярного обслуживания
Содержание: Ежедневные/еженедельные/ежемесячные задачи, очистка данных, обновления
Шаблон: /opt/claude-workspace/templates/MAINTENANCE.template.md

TROUBLESHOOTING.md

Когда нужен: Сложная система с частыми проблемами
Содержание: Диагностика проблем, типичные ошибки и решения, когда эскалировать
Шаблон: /opt/claude-workspace/templates/TROUBLESHOOTING.template.md

RUNBOOK.md

Когда нужен: Production система с дежурными/операторами
Содержание: Операционное руководство, пошаговые процедуры, алерты, контакты
Шаблон: /opt/claude-workspace/templates/RUNBOOK.template.md

Уровень 3: Для больших команд и open-source

TESTING.md

Когда нужен: Сложная стратегия тестирования, CI/CD
Содержание: Unit/Integration/E2E тесты, coverage требования, fixtures, mocks
Шаблон: /opt/claude-workspace/templates/TESTING.template.md

CONTRIBUTING.md

Когда нужен: Open-source или команда > 3 человек
Содержание: Как контрибьютить, code review процесс, git workflow
Шаблон: /opt/claude-workspace/templates/CONTRIBUTING.template.md

LICENSE

Когда нужен: Open-source проект
Содержание: Лицензия проекта (MIT, Apache 2.0, GPL v3, Proprietary)
Шаблон: /opt/claude-workspace/templates/LICENSE.template

USER-GUIDE.md

Когда нужен: Продукт для внешних пользователей
Содержание: Руководство пользователя, скриншоты, FAQ

DATA-DICTIONARY.md

Когда нужен: Много таблиц/полей в БД (> 10 таблиц)
Содержание: Описание каждого поля, типы, ограничения, бизнес-правила

📁 СТРУКТУРА ПРОЕКТА {#структура-проекта}

Минимальная структура

project-name/
├── README.md
├── DOCUMENTATION.md
├── {PROJECT}-PROJECT-MASTER.md
├── {PROJECT}-CHANGELOG.md
├── .env.example
├── .gitignore
└── [код проекта]

Полная структура (Application)

project-name/
├── README.md
├── DOCUMENTATION.md
├── {PROJECT}-PROJECT-MASTER.md
├── {PROJECT}-CHANGELOG.md
├── {PROJECT}-ROADMAP.md
├── {PROJECT}-API-GUIDE.md
├── CODE-GUIDE.md
├── WORKFLOWS.md
├── ARCHITECTURE.md
├── DEPLOYMENT.md
├── SECURITY.md
├── SECRETS.md
├── BACKUP.md
├── MONITORING.md
├── MAINTENANCE.md
├── TROUBLESHOOTING.md
├── TESTING.md
├── .env.example
├── .gitignore
├── LICENSE
├── docs/
│   ├── diagrams/          # Mermaid/PlantUML диаграммы
│   ├── screenshots/       # Скриншоты UI
│   └── examples/          # Примеры использования
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── scripts/               # Утилиты (backup, deploy, etc)
│   ├── backup.sh
│   ├── restore.sh
│   └── deploy.sh
└── [код проекта]

Полная структура (Infrastructure)

@infra-project-name/
├── README.md
├── DOCUMENTATION.md
├── {PROJECT}-PROJECT-MASTER.md
├── {PROJECT}-CHANGELOG.md
├── DEPLOYMENT.md
├── INFRASTRUCTURE.md
├── MONITORING.md
├── BACKUP.md
├── MAINTENANCE.md
├── SECURITY.md
├── SECRETS.md
├── TROUBLESHOOTING.md
├── RUNBOOK.md
├── .env.example
├── .gitignore
├── ansible/
│   ├── playbooks/
│   └── roles/
├── docker/
│   ├── docker-compose.yml
│   └── Dockerfile
├── scripts/
│   ├── backup.sh
│   ├── restore.sh
│   ├── deploy.sh
│   ├── rollback.sh
│   └── check-health.sh
└── configs/
    ├── nginx/
    └── systemd/

🏷️ ИМЕНОВАНИЕ ФАЙЛОВ {#именование-файлов}

Правила

Формат названий

♻️ ЖИЗНЕННЫЙ ЦИКЛ ДОКУМЕНТОВ {#жизненный-цикл-документов}

Правило 1: Актуализация

После КАЖДОГО значительного изменения:
- Обновить дату в документе
- Добавить запись в CHANGELOG
- Закоммитить с понятным сообщением

Правило 2: Версионирование

CHANGELOG.md - единственный источник версий:
- Версии в формате Semantic Versioning (major.minor.patch)
- Каждое изменение = запись в CHANGELOG

Правило 3: Ревью документации

Периодичность: Раз в месяц или перед релизом
- Проверить актуальность всех документов
- Удалить устаревшие разделы
- Обновить примеры кода

Правило 4: Архивация

Старые документы:
- Перемещать в docs/archive/
- НЕ удалять (может понадобиться история)
- Добавлять метку [ARCHIVED] в заголовок

✅ ЧЕКЛИСТ СОЗДАНИЯ ПРОЕКТА {#чеклист-создания-проекта}

1. Подготовка

# Создать папку проекта
mkdir -p /opt/claude-workspace/projects/project-name
cd /opt/claude-workspace/projects/project-name

# Скопировать шаблоны
cp /opt/claude-workspace/templates/README.template.md README.md
cp /opt/claude-workspace/templates/PROJECT-MASTER.template.md PROJECT-NAME-PROJECT-MASTER.md
cp /opt/claude-workspace/templates/CHANGELOG.template.md PROJECT-NAME-CHANGELOG.md
cp /opt/claude-workspace/templates/DOCUMENTATION.template.md DOCUMENTATION.md
cp /opt/claude-workspace/templates/.env.example.template .env.example
cp /opt/claude-workspace/templates/.gitignore.template .gitignore

2. Заполнение шаблонов

3. Инициализация Git

# Git init
git init
git add .
git commit -m "docs: initial project setup"

# Создать .gitignore
echo ".env" >> .gitignore
echo "*.pyc" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "venv/" >> .gitignore

git add .gitignore
git commit -m "chore: add .gitignore"

4. Опциональные документы

Определить нужные документы на основе типа проекта:

5. Финализация

git add .
git commit -m "docs: complete initial documentation"
git tag v1.0.0 -m "Release v1.0.0"

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

Документ	Infrastructure	Application	Library	Data/Analytics
Обязательные для всех:
README.md	✅	✅	✅	✅
PROJECT-MASTER.md	✅	✅	✅	✅
CHANGELOG.md	✅	✅	✅	✅
DOCUMENTATION.md	✅	✅	✅	✅
.env.example	✅	✅	⚪	✅
.gitignore	✅	✅	✅	✅
Стандарты разработки:
CODE-GUIDE.md	⚪	✅	✅	✅
WORKFLOWS.md	✅	✅	⚪	✅
ROADMAP.md	⚪	✅	⚪	✅
Техническая документация:
API-GUIDE.md	⚪	✅	✅	⚪
ARCHITECTURE.md	✅	✅	⚪	✅
DATA-DICTIONARY.md	⚪	⚪	⚪	✅
Production операции:
DEPLOYMENT.md	✅	✅	⚪	⚪
MONITORING.md	✅	✅	⚪	✅
BACKUP.md	✅	✅	⚪	✅
MAINTENANCE.md	✅	✅	⚪	✅
TROUBLESHOOTING.md	✅	✅	⚪	⚪
RUNBOOK.md	✅	✅	⚪	⚪
Безопасность:
SECURITY.md	✅	✅	⚪	✅
SECRETS.md	✅	✅	⚪	✅
Тестирование и качество:
TESTING.md	⚪	✅	✅	✅
Для команд/open-source:
CONTRIBUTING.md	⚪	⚪	✅	⚪
LICENSE	⚪	⚪	✅	⚪
USER-GUIDE.md	⚪	✅	⚪	✅

Легенда:
- ✅ Обязательно или настоятельно рекомендуется
- ⚪ Опционально (создавать по необходимости)

🎓 BEST PRACTICES

1. Документируйте СРАЗУ

Не откладывайте документирование "на потом". Пишите по мере разработки.

2. Краткость

Лучше короткий актуальный документ, чем длинный устаревший.

3. Примеры

Один пример лучше тысячи слов. Добавляйте code snippets.

4. Ссылки

Не дублируйте информацию. Давайте ссылки на другие документы.

5. Актуальность

Документ без даты = бесполезный документ. Всегда указывайте дату обновления.

6. Структура

Используйте заголовки, списки, таблицы. Документ должен легко сканироваться.

7. Диаграммы

Одна диаграмма заменяет страницу текста. Используйте Mermaid, PlantUML.

🔗 ПОЛЕЗНЫЕ ССЫЛКИ

📜 ИСТОРИЯ ИЗМЕНЕНИЙ

Версия 2.0.0 (2025-11-08)

Добавлено:
- ✅ BACKUP.md - стратегия резервного копирования (3-2-1, RTO/RPO)
- ✅ SECRETS.md - управление паролями и ключами (инвентарь, ротация, emergency access)
- ✅ MAINTENANCE.md - регулярное обслуживание (daily/weekly/monthly задачи)
- ✅ TROUBLESHOOTING.md - диагностика проблем (быстрые команды, типичные ошибки)
- ✅ RUNBOOK.md - операционное руководство для дежурных
- ✅ LICENSE.template - шаблон лицензии (MIT + альтернативы)

Обновлено:
- Матрица документов по типам проектов (добавлены новые категории)
- Полная структура Application (добавлены новые документы)
- Полная структура Infrastructure (добавлены новые документы)
- Описания опциональных документов (Level 2 и Level 3)

Итого: 19 шаблонов (17 Markdown + 2 конфигурационных)

Версия 1.0.0 (2025-11-08)

Добавлено:
- Первая версия PROJECT-STANDARDS.md
- 13 базовых шаблонов
- Типы проектов (5 типов)
- Обязательные документы (6 штук)
- Опциональные документы
- Чеклист создания проекта

Последнее обновление: 2025-11-08
Автор: Claude Code Workspace Team

📋 PROJECT STANDARDS - Стандарты ведения проектов