---
name: project-guidelines
description: "Конституция разработки Docwise: язык коммуникации, инженерные стандарты, reuse-first подход, правила консистентности UI/анимаций, формат code review и синхронизация skill-файлов. Используйте для любой задачи в репозитории."
---

# Project Guidelines (Constitution)

Этот навык имеет приоритет среди project skills и задаёт единый стандарт качества для всех модулей проекта.

## 1. Язык и коммуникация

- Отвечай пользователю на русском языке.
- Пиши объяснения конкретно: что изменено, зачем, как проверить.
- Используй английские имена сущностей в коде (`variables`, `functions`, `classes`, `types`).
- Пиши комментарии в коде только там, где без них теряется контекст; избегай шумовых комментариев.

## 2. Commit Convention

Используй Conventional Commits:

- `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
- Формулируй сообщение как результат действия (прошедшее время):
  - `feat(auth): добавлен вход через Telegram`
  - `fix(api): исправлена обработка таймаута`

## 3. Reuse-First (обязательно)

Перед созданием нового кода:

1. Найди существующий паттерн в проекте через поиск по модулю.
2. Переиспользуй текущие слои/компоненты/хуки/сервисы.
3. Добавляй новую абстракцию только если:
   - текущая реализация не покрывает задачу;
   - есть минимум два реальных сценария повторного использования.

Запрещено писать кастомную реализацию там, где уже есть проектный или библиотечный стандарт.

## 4. Композиция и размер модулей

- Держи контроллеры/страницы тонкими: оркестрация, а не бизнес-логика.
- Выноси бизнес-правила в service/composable/hook/repository слой.
- Не оставляй «универсальные» файлы-монолиты.
- Если компонент или модуль становится трудно обозримым (ориентир: 200-250+ строк и несколько зон ответственности), разделяй на подкомпоненты/хуки.
- Устраняй повторяющийся код через общие примитивы, а не копипасту.

## 5. Консистентность UI и анимаций

- Соблюдай существующий дизайн-язык проекта (цвета, типографика, отступы, интеракции).
- Используй уже подключённые UI-библиотеки и проектные обёртки, не подменяй их самодельными аналогами.
- Используй существующие animation presets/composables; не дублируй inline-анимации по разным файлам.
- Не добавляй новый визуальный стиль в одном месте без приведения остальных сценариев к тому же паттерну.

## 6. Рабочий цикл

1. Определи границы задачи: затронутые сервисы, API, UI, очереди, БД.
2. Внеси минимально достаточное изменение без побочных рефакторингов.
3. Проверь изменения релевантными командами (lint/test/build/smoke).
4. Зафиксируй ограничения проверки, если что-то не запускалось.
5. Если изменился стек/процессы/контракты модуля — обнови соответствующий `SKILL.md` в `.agents/skills`.

## 7. Формат code review

Если задача связана с ревью:

- Сначала findings по убыванию severity с привязкой к `файл:строка`.
- Для каждого finding укажи: проблема, риск, рекомендация.
- После findings: открытые вопросы/допущения.
- Summary только в конце и только короткий.
- Если проблем не найдено, явно укажи это и перечисли оставшиеся риски/пробелы проверки.

## 8. Запрещённые паттерны

- Бизнес-логика в UI-контроллерах/страницах вместо профильных слоёв.
- Копирование кода между фичами вместо выделения общего примитива.
- Изменение API-контрактов без проверки клиентов, которые от них зависят.
- Закомментированный «мертвый» код, неиспользуемые импорты/функции/файлы.
- Использование путей вне workspace для рабочих артефактов.

## 9. Хранение навыков

Поддерживай навыки только в каталоге:

- `.agents/skills`

Синхронизируй навыки с кодовой базой:

- при добавлении новых ключевых фич (например, новый доменный контур API);
- при изменении обязательных команд проверки/запуска;
- при изменении контрактов между `backend`, `frontend`, `admin`, `rag`, `integrations`.