Попросили Claude Code CLI сделать AI-чатбот для нашей платформы. Через 4 часа получили рабочее решение: контекстно-зависимый виджет, база знаний на markdown, эскалация в Telegram, автоматический сбор багов. Работает в production, выложили в open source.

GitHub: github.com/gmen1057/ai-chat-widget
Лицензия: MIT
Demo: studio.jhunterpro.ru (виджет в правом нижнем углу)

Зачем нам понадобился чатбот

У нас несколько платформ.. Пользователи постоянно спрашивают одно и то же: как работает сервис, сколько стоит, почему не пришло письмо, как отменить подписку.

Классический путь — нанять поддержку или написать FAQ на 50 страниц. Оба варианта так себе: поддержка дорогая, FAQ никто не читает.

Решили сделать AI-консультанта. Требования:

• Отвечает на вопросы по платформе

• Понимает, на какой странице находится пользователь

• Если не справляется — зовёт человека

• Автоматически логирует баги, когда пользователь жалуется

• Встраивается одной строкой кода

• Не трогает основной проект — полностью изолированный сервис

Почему Claude Code

Я уже использовал Claude Code для других частей проекта и понимали его сильные стороны: быстрая итерация, понимание контекста, способность держать архитектуру в голове, ну и так далее. А новый opus 4.5 справляется еще лучше.

Для чатбота:

• Типовая задача — тысячи подобных решений существуют, AI знает паттерны

• Чёткие требования — понятно что нужно на входе и выходе

• Изолированный компонент — не нужно разбираться в legacy-коде

• Быстрая обратная связь — можно сразу тестировать и корректировать

Процесс выглядел так: описали требования → Claude Code сгенерировал архитектуру → мы скорректировали → он написал код → мы протестировали → он поправил баги. Четыре итерации, четыре часа.

Архитектура

flowchart LR
    subgraph "Браузер"
        W[Chat Widget]
    end
    
    subgraph "Backend"
        API[FastAPI]
        AI[Claude API]
        DB[(SQLite)]
        KB[База знаний<br/>Markdown]
    end
    
    subgraph "Внешние сервисы"
        TG[Telegram Bot]
    end
    
    W -->|сообщение + контекст страницы| API
    API --> AI
    API <--> DB
    API --> KB
    API -->|эскалация / баги| TG
    API -->|ответ| W

Три слоя:

1. Виджет — vanilla JS, встраивается одним тегом <script>, никаких зависимостей

2. Backend — FastAPI, обрабатывает сообщения, хранит историю, вызывает Claude API

3. Интеграции — Telegram для эскалаций и уведомлений о багах

Ключевые технические решения

Работает без базы данных

По умолчанию история чатов хранится в JSON-файлах — никакой настройки БД не нужно. Запустил и работает. Если проект вырастет, можно переключить на SQLite или PostgreSQL одной переменной:

STORAGE_TYPE=json      # по умолчанию, для разработки
STORAGE_TYPE=sqlite    # для single-server
STORAGE_TYPE=postgres  # для production с нагрузкой

Любой AI-провайдер

Виджет не привязан к конкретной модели. Поддерживаются из коробки: OpenAI, Claude, Gemini, GigaChat, YandexGPT, DeepSeek, Qwen, Ollama и любой OpenAI-compatible API. Переключение — три строки в конфиге:

AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=sk-xxx
AI_MODEL=gpt-4o-mini

Хотите локальную модель через Ollama? Меняете URL на http://localhost:11434/v1 — и всё работает. Хотите GigaChat для российских пользователей? Тоже поддерживается.

Vanilla JS вместо React

Виджет — это один файл. Никаких конфликтов с вашим стеком, никакого бандлинга, работает везде. Встраивание:

<script src="/chat/widget.js"></script>
<script>
  JobHunterChat.init({ apiUrl: '/chat/api' });
</script>

Почему не React? Потому что виджет должен работать на любом сайте — на WordPress, на голом HTML, на Next.js. Фреймворк добавил бы сложности и потенциальные конфликты версий.

Markdown как база знаний

Вместо сложных RAG-систем с векторными базами — папка с markdown-файлами:

knowledge/
├── pricing.md      # Тарифы и цены
├── features.md     # Описание функций
├── faq.md          # Частые вопросы
└── troubleshooting.md

AI получает содержимое этих файлов в system prompt. Для небольшой базы знаний (до 50-100 страниц) этого достаточно. Обновлять легко — просто редактируете markdown.

Контекст страницы

Виджет отправляет не только сообщение, но и URL страницы, на которой находится пользователь. Если пользователь пишет "не работает кнопка" со страницы /balance, AI понимает, что речь о кнопке на странице баланса.

Можно пойти дальше и передавать page_context — JSON с данными о состоянии страницы (баланс пользователя, его тариф, видимые элементы). Тогда AI сможет давать ещё более точные ответы.

Автоматический сбор багов

AI обучен распознавать жалобы на баги. Когда пользователь пишет "страница не грузится" или "кнопка не работает", AI классифицирует это и сохраняет в базу с severity (low/medium/high/critical) и категорией (ui/api/payment/auth).

Разработчик получает структурированный список багов вместо разрозненных сообщений в чате поддержки.

Эскалация в Telegram

Если AI не может помочь или пользователь явно просит человека, происходит эскалация. В Telegram приходит сообщение с контекстом:

? ЭСКАЛАЦИЯ

? Пользователь: user@email.com
? Страница: /balance
? Вопрос: "Платёж прошёл, но баланс не пополнился"

? Контекст:
- Последний платёж: 2499₽ 
- Текущий баланс: 0

Оператор видит всё, что нужно ��ля ответа, не задавая уточняющих вопросов.

Что Claude Code сделал хорошо

Структура проекта. Сразу разложил код по папкам: routes, services, models. Не пришлось потом рефакторить.

Обработка ошибок. Каждый внешний вызов (Claude API, Telegram) обёрнут в try-except с логированием. Мы не просили — он сам добавил.

Rate limiting. Предложил защиту от спама на уровне IP и сессии. Опять же, без явного запроса.

Конфигурация через .env. Все ключи API, настройки CORS, лимиты — в переменных окружения. Правильный подход к деплою.

Что пришлось доработать руками

System prompt. Claude Code написал базовый промпт, но для нашего продукта нужен был специфический тон и знание контекста. Переписали вручную.

Telegram-бот. Базовая отправка сообщений работала, но добавили inline-кнопки для быстрых действий ("Взять в работу", "Ответить").

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

Для кого это решение

Для разработчиков — если нужен AI-чатбот за день, а не за месяц. Форкаете репозиторий, меняете базу знаний, деплоите.

Для продактов — если хотите понять, что реально можно получить от AI-ассистента на сайте. Это не концепт, а работающее решение.

Для тех, кто изучает Claude API — в коде есть примеры: tool use для эскалации и багов, работа с контекстом, structured output.

Ограничения

Это MVP, не enterprise-решение:

• Нет админки для просмотра диалогов (только API)

• Нет аналитики (количество диалогов, satisfaction rate)

• База знаний через prompt, не через RAG (ограничение на объём)

Всё это можно добавить, но мы решили выложить как есть — рабочий минимум, от которого можно отталкиваться.

Как попробовать

Подробная инструкция — в README репозитория.

Выводы

Claude Code справился с задачей за 4 часа. Оставшиеся 20% — настройка под наш продукт, дизайн, документация.

Код открыт, адаптируйте под себя.

GitHub: github.com/gmen1057/ai-chat-widget