| name | db-schema-keeper |
| description | Протокол для любых задач, связанных с базой данных. Использовать этот навык когда пользователь просит создать миграцию, добавить/изменить/удалить колонку, таблицу, индекс или внешний ключ, а также когда задаёт вопрос о структуре БД. Триггерные слова: таблица, колонка, индекс, миграция, схема БД, foreign key, ALTER TABLE, CREATE TABLE. |
| allowed-tools | Read, Write, Edit, Bash |
db-schema-keeper
Навык обеспечивает единый протокол работы со схемой базы данных проекта. Файл docs/database/schema.sql является единственным источником истины о структуре БД. Читать его до выполнения любого действия, обновлять после каждого изменения структуры.
Протокол выполнения
Строго соблюдать следующий порядок шагов при каждом обращении к задаче, связанной с БД:
Шаг 1. Прочитать схему
Всегда читать docs/database/schema.sql первым действием — до ответа на любой вопрос и до любых изменений:
Read: docs/database/schema.sql
Это обязательный шаг даже для вопросов только на чтение (read-only). Схема содержит актуальное состояние всех таблиц, колонок, индексов, внешних ключей и связей.
Шаг 2. Выполнить задачу
После прочтения схемы выполнить то, о чём просит пользователь:
- Вопрос о структуре — ответить на основе прочитанного
schema.sql.
- Создание миграции — написать SQL-миграцию в соответствии с существующей схемой. Файлы миграций размещать в
migrations/sql/ с именем вида VersionYYYYMMDDHHmmss_<описание>.sql.
- Изменение структуры — внести изменения в
docs/database/schema.sql через инструмент Edit, отражая реальное новое состояние схемы.
Шаг 3. Обновить schema.sql (только при изменении структуры)
Если задача изменяла структуру БД (добавление, изменение или удаление таблицы, колонки, индекса, внешнего ключа, ограничения), обновить docs/database/schema.sql инструментом Edit, чтобы файл отражал актуальное состояние.
Для вопросов только на чтение этот шаг пропускать.
Шаг 4. Дописать строку в changelog (только при изменении структуры)
После обновления schema.sql добавить строку changelog в конец файла.
Перед записью получить имя автора из git:
git config user.name
Затем дописать строку:
Если секции changelog в файле ещё нет, создать её перед записью:
Правила changelog
- Формат строго:
-- YYYY-MM-DD | <git user.name> | <description>
- Автор: всегда брать из
git config user.name, не подставлять имя вручную
- Дата: текущая дата в формате YYYY-MM-DD
- Описание: кратко на английском, например:
added deleted_at (timestamptz) to userscreated table core.orders with FK to core.usersadded index idx_tasks_assignee on core.tasks(assignee_id)
- Запись добавляется ТОЛЬКО при изменении структуры, не для read-only запросов
Примеры
Пример 1: изменение структуры таблицы
Запрос: "Добавь колонку deleted_at в таблицу core.tasks"
- Read
docs/database/schema.sql
- Найти определение
core.tasks, добавить колонку через Edit
- Обновить
docs/database/schema.sql — дописать deleted_at TIMESTAMPTZ NULL в определение таблицы
- Добавить в changelog:
Пример 2: создание новой таблицы и миграции
Запрос: "Напиши миграцию для новой таблицы core.comments"
- Read
docs/database/schema.sql
- Написать SQL-миграцию, создать файл
migrations/sql/Version20260416000001_create_core_comments.sql
- Добавить определение таблицы в
docs/database/schema.sql через Edit
- Добавить в changelog:
Пример 3: вопрос только на чтение
Запрос: "Какие индексы есть на таблице core.tasks?"
- Read
docs/database/schema.sql
- Найти и перечислить все индексы на
core.tasks
- Шаг 3 и Шаг 4 пропустить — schema.sql не обновляется, changelog не пишется
Частые ошибки
Ошибка: приступать к задаче без чтения schema.sql.
Решение: всегда начинать с Read docs/database/schema.sql, даже если структура кажется очевидной.
Ошибка: обновить schema.sql, но забыть дописать changelog.
Решение: changelog — обязательная часть протокола при любом изменении структуры.
Ошибка: писать changelog на русском языке.
Решение: описание в changelog всегда на английском языке, кратко и конкретно.
Ошибка: добавить запись в changelog при read-only запросе.
Решение: changelog пишется только при фактическом изменении структуры БД.
