Skip to content

README.md

Latest commit

 

History

History
233 lines (167 loc) · 6.84 KB

README.md

File metadata and controls

233 lines (167 loc) · 6.84 KB

Development Guide

Дата создания: 26.10.2025 Версия: 1.0 Целевая аудитория: Разработчики проекта Super Valera Тип документа: HOW (Практическое руководство)

Важно: Это руководство для разработчиков ПРОЕКТА Super Valera. О продукте (AI-боте) см. docs/product/

🚀 Быстрый старт для разработчиков

Вариант 1: Docker (рекомендуется)

# Клонирование
git clone <repo-url>
cd valera

# Установить dip (один раз)
gem install dip

# Полный setup
dip provision

# Запуск
dip dev

Вариант 2: Локальная установка

# Клонирование
git clone <repo-url>
cd valera

# Зависимости
bundle install

# База данных
bin/rails db:create db:migrate

# Запуск
bin/dev

Первые шаги

  1. ../CLAUDE.md - инструкции и архитектура
  2. Product Constitution - требования к продукту
  3. FLOW.md - процесс разработки
  4. Глоссарий - терминология проекта

🛠️ Инструменты разработчика

Документация gems

Структура:

  • docs/gems/telegram-bot/ - Telegram интеграция
  • docs/gems/ruby_llm/ - AI/LLM интеграция
  • Каждый gem: README, API reference, patterns, examples

Development команды

Docker (dip)

# Инфраструктура
dip up                     # Поднять postgres + redis
dip down                   # Остановить всё

# Разработка
dip dev                    # Полный стек (server + css + bot)
dip rails s                # Только Rails server
dip rails c                # Console
dip test                   # Тесты
dip rubocop                # Code style
dip ci                     # Все проверки

# База данных
dip migrate                # Миграции
dip psql                   # PostgreSQL console

# Telegram Bot
dip bot                    # Polling режим

Локально (без Docker)

# Разработка
bin/dev                    # Dev сервер
bin/rails console          # Console
bin/rails test             # Тесты
bin/rubocop               # Code style
bin/rubocop -a            # Auto-fix
bin/brakeman              # Security
bin/ci                    # Все проверки

# База данных
bin/rails db:migrate      # Миграции
bin/rails db:rollback     # Откат
bin/rails db:reset        # Пересоздать

# Telegram Bot
bin/rails telegram:bot:poller  # Polling режим (dev)

Интеграция с Claude AI

Автоматическое обучение:

  • Telegram задачи → изучает telegram-bot docs
  • LLM задачи → изучает ruby_llm docs
  • Features → изучает requirements/, FLOW.md

Ручной запуск:

ruby .claude/pre-work-hook.rb "your task description"

См. подробнее:

📋 Процесс разработки

Подробный процесс разработки: ../FLOW.md

Краткий workflow:

  1. User Story + Technical Design (согласно шаблонов)
  2. Реализация (следовать Product Constitution)
  3. Code Review (bin/ci)

См. подробнее: ../FLOW.md

🧪 Testing

Запуск тестов

# Все
bin/rails test

# Файл
bin/rails test test/models/chat_test.rb

# Конкретный тест
bin/rails test test/models/chat_test.rb:12

Критические правила разработки

🚨 КРИТИЧЕСКИ ВАЖНО:

  • Models: ВСЕГДА используй rails generate model для создания моделей и миграций одновременно
  • Error Handling: Используй ErrorLogger вместо Bugsnag.notify()
  • Configuration: Не использовать .env* файлы, только anyway_config
  • Testing: В тестах не использовать File.write/File.delete и не изменять ENV
  • Documentation: Документация создается для AI-агентов в первую очередь
  • AI Architecture: User Stories разделяются по уровням system prompt, не по бизнес-функциям

Подробнее об ErrorLogger: docs/patterns/error-handling.md

Правила тестирования

⚠️ ВАЖНО:

  • ❌ НЕ использовать File.write, File.delete
  • ❌ НЕ изменять ENV переменные
  • ❌ Логирование НЕ мокается и НЕ проверяется

Подробнее: ../../CLAUDE.md

🤖 AI Development с Claude

Workflow с Claude Code

  1. Задать задачу Claude
  2. Claude изучает документацию (авто)
  3. Claude создает план → .protocols/
  4. Реализация с паттернами
  5. Code review и тесты

Оптимизация:

  • Автообучение при Telegram/LLM работе
  • Готовые паттерны в docs/gems/
  • Примеры кода для быстрого старта

📚 Полезные ссылки

🔧 Troubleshooting

Зависимости:

bundle install
bin/rails db:reset

Тесты:

RAILS_ENV=test bin/rails db:reset
bin/rails test

Telegram Bot:

  • Проверить config/configs/application_config.rb

Версия: 1.0 Дата создания: 26.10.2025 Последнее обновление: 26.10.2025 Ответственный: Development Team