Issue-трекер с ИИ

Цель проекта

Получить плотный практический опыт работы с Claude Code на нетривиальном продукте: настроить полноценный CLAUDE.md, написать свои скиллы, попробовать команды агентов и встроить AI-фичи в продукт через Anthropic API.

Продукт — это полигон. Главная цель — мастерство приёмов, а не сам трекер.

Что вы строите

Issue-трекер уровня MVP с двумя AI-фичами внутри. Ниже — общая картина домена и сценариев, чтобы на демо у всех был один язык.

Делаем и бекенд и фронтенд.

Домен

Сущности

User — зарегистрированный пользователь. Аутентификация по логину и паролю (без OAuth). Поля: email (уникален, используется как логин), password_hash, name, avatar (опционально). Любой пользователь может создавать projects, issues, брать их в работу и комментировать.

Project — контейнер для issues. Поля: slug, name, description (опционально), owner (User). У project — свой набор labels.

Issue — задача внутри project. Поля:

• title (обязательно, до 200 символов)
• description (markdown, опционально)
• status (enum: backlog | todo | in-progress | in-review | done)
• priority (enum: low | medium | high | urgent)
• assignee (User, опционально)
• reporter (User, заполняется автоматически)
• labels (массив Label)
• acceptance_criteria (markdown, опционально — может быть сгенерирован AI-триажем)
• created_at, updated_at, closed_at (опционально)

Label — метка внутри Project. Поля: name (уникально в рамках project, без учёта регистра), color. Связь Issue ↔ Label — M:N.

Comment — комментарий к Issue. Поля: author (User), body (markdown), created_at, updated_at. Порядок — по created_at asc.

Связи

User    1 —— N   Project   (owner)
User    1 —— N   Issue     (reporter, assignee — две отдельные связи)
Project 1 —— N   Issue
Project 1 —— N   Label
Issue   M —— N   Label
Issue   1 —— N   Comment
User    1 —— N   Comment   (author)

Workflow статусов

Линейный путь: backlog → todo → in-progress → in-review → done. Откат назад разрешён (например, in-review → in-progress). Перепрыгивание через статусы допустимо — это процесс с людьми, а не строгий конечный автомат.

Инварианты

• Issue создаётся в backlog, priority = medium, без assignee.
• reporter заполняется текущим пользователем при создании и не меняется.
• assignee — любой пользователь системы (понятия «участник проекта» нет).
• closed_at ставится автоматически при переходе в done и обнуляется при выходе.
• Label.name уникален в рамках Project (без учёта регистра).
• Comment может редактировать или удалять только автор.
• AI-сгенерированный acceptance_criteria помечается флагом (например, ai_suggested: true) — пользователь может принять, отредактировать или переписать.

Сценарии использования

1. Быстрое создание Issue. Пользователь открывает форму «New issue» в Project, вводит только название, сохраняет. Главный сценарий «приёма входящих» — должен быть мгновенным.
2. AI-триаж backlog. Пользователь открывает свежий Issue без метаданных, нажимает «AI suggest». Агент возвращает priority, labels и черновик acceptance_criteria. Пользователь принимает целиком, частично или переписывает.
3. Триаж + назначение. Пользователь смотрит на Issues в backlog, выставляет priority, labels, acceptance_criteria (вручную или через AI), назначает исполнителя, переводит в todo.
4. Работа над Issue. Исполнитель переводит todo → in-progress, оставляет комментарии о прогрессе, после готовности переводит в in-review и прикрепляет URL пул реквеста на GitHub.
5. AI-ревью PR. В Issue со статусом in-review пользователь добавляет URL PR и запускает «AI review». Агент сам ходит в GitHub за diff'ом и изменёнными файлами, читает их в контексте title / description / acceptance_criteria, оставляет ревью как комментарий с явной привязкой к каждому критерию. После доработки можно перезапустить ревью или закрыть в done.
6. Поиск и фильтры. Пользователь фильтрует Issues по status / assignee / labels, ищет по тексту в title / description. Пагинация по результату.
7. Закрытие Issue. Автор или исполнитель переводит в done. closed_at фиксируется. Закрытые Issues скрыты по умолчанию, показываются по фильтру.

AI-фичи

В проекте две AI-фичи. Одна простая и предсказуемая (триаж), вторая — полноценный агент (ревьюер PR).

AI-триаж

Слово «триаж» пришло из медицины — на полях сражений и в больницах врачи сортируют поступающих пациентов по тяжести состояния, чтобы ограниченный ресурс врачей правильно распределить по входящему потоку. Сначала тех, кому помощь нужна срочно, потом тех, кто может подождать, в самом конце — тех, кому уже не помочь.

В разработке триаж — ровно то же самое для входящих Issues. В бэклог сыплются баги, запросы фич, идеи, жалобы пользователей. Часть из них критична, часть — мусор, часть — что-то посередине. Прежде чем кто-то возьмётся за работу, кто-то другой должен пройти по этому потоку и для каждого Issue:

• выставить приоритет (low / medium / high / urgent)
• навесить метки (bug, feature, frontend, backend, и т.п.)
• понять, к какой части продукта это вообще относится
• сформулировать критерии приёмки — что значит «сделано»

Это нудная, повторяющаяся работа техлида или дежурного по бэклогу. Каждая команда её делает, и почти везде это болезненная точка: новые Issues копятся быстрее, чем их успевают разобрать. Поэтому именно триаж — классический кандидат на автоматизацию через LLM.

Что делает ИИ. Пользователь приносит Issue с одним заголовком и коротким описанием, ИИ-помощник читает контекст проекта (название, описание, набор меток) и предлагает три вещи:

1. Priority — один из четырёх уровней enum'а
2. Labels — подмножество из набора меток проекта (только тех, что в проекте реально существуют — это ограничение зашивается в промпт списком)
3. Acceptance criteria — черновик критериев приёмки чек-листом или в формате «Given / When / Then»

Ключевое слово — предлагает. Пользователь видит результат, принимает целиком, правит любое поле или переписывает с нуля. AI здесь — быстрый первый набросок, а не финальное решение. Поэтому ошибки агента дёшевы: пользователь всё равно проверит перед сохранением.

Почему именно триаж — хорошая первая AI-фича. Это идеальный полигон для практики с LLM:

• Маленькая задача. Заголовок Issue плюс описание плюс список меток проекта — несколько килобайт промпта, не больше. Дёшево, быстро, легко итерировать промпт.
• Лёгкая проверка качества. На 10–20 эталонных Issues за полчаса можно сказать, хороша ли модель, хорош ли промпт, не сломалась ли регрессия после правки.
• Видимые ошибки. Промахнулся с меткой — пользователь увидит и поправит. Это не галлюцинация в коде, которая сломает продакшен через месяц.

Поверх базовой реализации можно навешивать что угодно: учить агента на истории решений по проекту, добавлять «уверенность» по каждому полю, гонять несколько моделей и сравнивать, затачивать промпт под крайние случаи (Issue без описания, Issue на смеси языков, Issue про несколько разных вещей сразу).

AI-ревьюер PR

Пользователь даёт URL пул реквеста на GitHub, агент через кастомные tools (fetch_pr_metadata, fetch_pr_diff, fetch_changed_files, fetch_file_content) сам ходит в репозиторий за нужным контекстом — смотрит метаданные, читает diff, при необходимости подтягивает целые файлы или соседние — и оставляет ревью комментарием к issue, привязанным к acceptance criteria. Многошаговый агент с инструментами — самая сложная и интересная фича.

Стек — свободный

Берите что знаете. Цель — отрабатывать практики Claude Code, а не воевать с незнакомым стеком.

Методика: Spec-Driven Development

Каждый этап делается через цикл из трёх документов, который вы уже разбирали в курсе. Это не ритуал, а способ зафиксировать решения в файлах раньше, чем агент начнёт писать код.

• Design-документ (docs/designs/<дата>-<имя-этапа>.md) — динамический. Что строим на этом этапе и зачем: пользовательские сценарии, бизнес-правила, edge cases, naming, ключевые решения. Создаётся в диалоге с агентом — вы формулируете идею, агент задаёт уточняющие вопросы по одному, на выходе структурированный документ. Например, для AI-триажа: какие поля предлагает агент, что значит «принять предложение», что делать, если LLM не ответил.
• Implementation plan (docs/plans/<дата>-<имя-этапа>.md) — динамический. Пошаговый план с чекбоксами, разбитый на фазы. Каждая задача — атомарная, с указанием файлов.
• Спецификация модуля (docs/specs/<имя-модуля>.md) — статический. Живое описание того, что реально есть в коде: data model, статусная модель, endpoints, key behaviors. Без обоснований и истории решений — только факты. Обновляется после каждого завершённого цикла, чтобы следующий этап начинался с полной картины.

Цикл одного этапа:

1. Создаёте design-документ → ревьюите: всё ли учли.
2. /clear → читаете design, генерируете plan → ревьюите гранулярность задач.
3. /clear → реализуете фазы из плана → коммит → /clear → следующие фазы, если остались.
4. После реализации — обновляете спецификацию модуля, чтобы она отражала текущий код.

Шаг 3 можно делать двумя путями. Базовый — реализовывать план самостоятельно с помощью одного агента, по 1-2 фазы за сессию, контролируя каждый коммит и ревью. Альтернативный — оптимизировать план под команду агентов: просите Claude Code запустить команду агентов с разными ролями (одна делает миграции и модели, другая тесты, третья API endpoints), они координируются через общий task list и обмениваются сообщениями напрямую, проходя независимые куски плана одновременно.

Рекомендация — начинайте с базового пути. На первых этапах вы только нарабатываете скиллы и тюните CLAUDE.md. Каждый параллельный агент в команде читает те же правила из папки .claude/ — если правил ещё нет, каждая агент может делать что-то своё, ухудшая согласованность итогового кода. К середине-концу проекта, когда папка .claude/ уже зрелая и общие правила работают предсказуемо, можно попробовать второй путь. Имейте в виду: команда агентов значительно дороже в токенах, чем последовательная работа — ценность параллелизма должна перевешивать.

Каждый этап оставляет в репозитории свой комплект design + plan + обновлённый spec. Следующий этап стартует с того, что агент читает существующие spec'и и сразу видит, что уже построено. Скиллы и CLAUDE.md, написанные заранее, определяют как агент пишет код. SDD-документы определяют что именно нужно построить.

На созвонах интересно показывать не только итоговый код, но и эволюцию SDD-документов: где design переделывался после трёх вопросов агента, где план разросся из одной фазы в три, где спецификация модуля разошлась с реальностью и пришлось доводить. Это часто рассказывает о работе с агентом больше, чем сам код.

Этапы

Проект разбит на 9 последовательно выполняемых этапов. Каждый — самодостаточный шаг: можно остановиться в любом месте и у вас будет, что показать. Первые этапы намеренно маленькие, чтобы было где спокойно настроить SDD-цикл и почувствовать ритм работы с Claude Code; дальше этапы крупнее.

Сделайте столько этапов, сколько успеете. Но лучше больше. Ожидается, что сеньор сделает больше джуна.

1. Setup и CLAUDE.md. Поднять репо, написать базовый CLAUDE.md (домен + стек + конвенции), подключить пару скиллов из шаблонов как стартовый набор.
2. Auth. Регистрация по email/паролю с хешированием, вход/выход, сессии, защищённые маршруты после логина.
3. Projects. Базовый CRUD проектов: создание, список, удаление. Текущий пользователь автоматически становится owner. Навигация: список проектов → страница проекта.
4. Issues — базовый flow. Создание / просмотр / обновление / удаление Issues внутри Project, статусы и переходы между ними.
5. Issues — комментарии, фильтры, поиск. Полный пользовательский путь по бэклогу: комментарии, фильтрация по status / assignee / labels, поиск по тексту, пагинация.
6. AI-триаж. Первая AI-фича. На вход — сам Issue (title + description) и контекст проекта (name, description, список доступных labels). На выход — priority, labels и черновик acceptance criteria. Записываем в Issue, показываем пользователю.
7. AI-ревьюер PR. Вторая AI-фича, многошаговый агент с tool use. Пользователь даёт URL PR, агент через кастомные tools (fetch_pr_metadata, fetch_pr_diff, fetch_changed_files, fetch_file_content) сам решает, что подтянуть из репозитория и в каком порядке. Tools — обычные функции на бэкенде, которые ходят в GitHub REST API. Ревью оставляет комментарием к Issue.
8. AI-фичи — крайние случаи и валидация. Что если модель вернула мусор. Что если diff пустой или огромный. Что если у проекта нет меток. Что если acceptance criteria противоречат. Защитный промптинг, повторы, явные fallback'и.
9. Свой MCP-сервер наружу. Наш трекер выставляет MCP-сервер, чтобы разработчик из Claude Code мог напрямую работать с Issues и комментариями нашего трекера. Это не «подключи чужой MCP к нашему продукту», а противоположное — наш продукт интегрируется в чужие AI-агенты.

Альтернатива - свой проект

Если строить трекер с нуля не хочется (есть пет-проект или хочется применить Claude Code к существующему коду) — продуктовые этапы не нужны. Берёте сквозную работу с Claude Code (см. ниже) и применяете к своему репо. Из этапов — MCP-сервер (9) тоже можно адаптировать, если в продукте есть что отдать наружу.

Сквозная работа с Claude Code

Это не этап, а параллельный пласт, который растёт вместе с продуктом. Скиллы лучше написать заранее: они закладывают принципы и паттерны разработки, и Claude с первого дня работает по ним, а не по случайным решениям. Команда агентов — инструмент другой природы, появляется ближе к концу проекта, когда у задач есть независимые куски и набор правил в папке .claude/ уже устоялся.

• Кастомные скиллы — заранее. Скиллы фиксируют принципы и паттерны разработки в проекте: «структура вертикального слайса», «как мы обрабатываем ошибки сквозь все слои», «как добавить новое поле в Issue сквозь все слои», «правила написания компонентных тестов». Чем раньше написаны, тем меньше потом переписывать: Claude с первого дня работает по нужным паттернам, и весь накопленный код им соответствует.
• CLAUDE.md растёт по ходу. Начинаете с домена / стека / конвенций. Постепенно добавляете правила работы с AI, edge cases, антипаттерны, журнал решений. Хороший CLAUDE.md — это не то, что вы написали один раз, а то, что переписали 10 раз.
• Команда агентов. Когда у задачи есть независимые куски, которые можно вести параллельно (миграция + тесты + API), запускаете команду параллельных агентов. Координируются через общий task list, могут общаться друг с другом напрямую. Стоит токенов сильно больше, чем последовательная работа, поэтому применяется, когда папка .claude/ уже зрелая и параллелизм действительно экономит время.
• Доп. практика по желанию. Когда руки доходят: нетривиальный хук, автоматизация на plan-mode, реестр промптов, трекер стоимости/задержек на вызовы LLM.

Для вдохновения можете использовать скиллы из нашего демо-репозитория. Особенно важен design-brainstorming — он автоматизирует Specify-фазу SDD: вы формулируете идею этапа, скилл задаёт уточняющие вопросы по одному и собирает структурированный design-документ.

На созвонах одинаково интересно показывать как фичу продукта, так и эволюцию папки .claude/. Иногда выкинутая идея скилла полезнее работающего.

Созвоны

Раз в неделю — общий созвон, ~1 час. Никаких обязательных слотов и заранее назначенных демо: несколько добровольцев показывают, что у них получилось за неделю, остальные смотрят и задают вопросы. Обсуждаем, что сработало, что застряло, чем помочь друг другу.

Хорошо показывать:

• Живой результат — что-то работает (или сломалось) на экране.
• Папку .claude/ — что лежит в CLAUDE.md, какие скиллы родились, что из этого пригодилось, что выкинули.
• Историю одного приёма — где Claude разблокировал, где тормозил, какой промпт переписывали по три раза.

На последнем созвоне — короткое ретро: какие этапы прошли, что забираете с собой, чего не хватает в Claude Code как инструменте.

Что вы заберёте с собой

• Работающий продукт в репозитории
• .claude/ с настройками, которые можно переиспользовать на работе
• Понимание, когда Claude Code ускоряет, а когда мешает