| name | ai-engineering-process |
| description | Инженерный процесс разработки с ИИ по методологии контекстной инженерии: Research → Design → Plan → Implement. Используй этот навык когда нужно добавить новую фичу, исправить баг, спроектировать архитектуру или выстроить правильный процесс работы с ИИ-агентом. Применяй всегда, когда задача сложнее "добавь одну строку" — особенно если касается архитектуры, новых компонентов, интеграций или рефакторинга. |
Инженерный процесс работы с ИИ
Главный принцип: качество определяет не модель, а процесс вокруг неё.
Золотые правила — действуют на всех этапах:
- Только факты. Не додумывать, не предполагать, не фантазировать
- Если чего-то не знаешь или не понял — спроси пользователя
- Не трогать работающий код вне задачи. Никакого "заодно улучшим"
- Работаем только над тем что поставлено в задаче
Структура папок
Все файлы создаются в чётко определённых папках. Ничего не кладётся в корень проекта. Структура одинакова в любом проекте — всегда знаешь где что искать.
Файлы процесса — всегда в одних и тех же папках, каждый этап в своей:
.ai/
research/
<название-задачи>/
research.md — что нашли в коде
design/
<название-задачи>/
architecture.md — как устроено решение
sequence.md — последовательность вызовов
contracts.md — API-контракты (если нужны)
plan/
<название-задачи>/
phase-1.md
phase-2.md
...
tests/
<название-задачи>/
phase-1/ — тестовые данные первой фазы
phase-2/
...
Код — кладётся туда куда принято в этом проекте. Смотри на существующие файлы и следуй той же структуре.
Папка .ai/ всегда в корне проекта. Открыл — сразу видишь 4 папки по этапам. Зашёл в любую — видишь папки по задачам. Одинаково в любом проекте.
Названия подпапок задач — короткие, отражают суть. Не task1, не fix_v2_final.
Процесс: 4 фазы
Фаза 1: Research (Исследование)
Цель: найти в коде только то что относится к задаче.
Шаг 1: Найти точки входа
Точки входа — места где система получает внешние воздействия. С них начинается любой анализ.
| Тип проекта | Где искать |
|---|
| Web-сервис / API | роуты, HTTP-хендлеры |
| CLI | main(), парсинг аргументов |
| Worker / очередь | обработчики сообщений |
| Библиотека | экспортируемые функции и классы |
| Frontend | страницы, роутер, корневые компоненты |
Шаг 2: Пройти по цепочке вызовов
От точки входа идти вглубь: хендлер → сервис → репозиторий → модель.
Останавливаться когда цепочка уходит в части системы не связанные с задачей.
Фиксировать:
- какие файлы и функции участвуют
- какие данные передаются между ними
- какие внешние зависимости вызываются (база, API, очереди)
Шаг 3: Записать факты
Создать docs/<название-задачи>/research.md со структурой:
## Точки входа
- файл.go:42 — `func HandleUpload(w http.ResponseWriter, r *http.Request)` — принимает POST /upload, читает файл из тела запроса
## Цепочка вызовов
- handlers/upload.go:42 HandleUpload
→ services/file.go:18 FileService.Save
→ repositories/storage.go:55 StorageRepo.Put
→ models/file.go:12 File{ID, Name, Size, Path}
## Затронутые модели и данные
- File (models/file.go:12) — поля: ID, Name, Size, Path, CreatedAt
## Внешние зависимости
- S3 (repositories/storage.go:55) — используется для сохранения файла, вызов через AWS SDK
- PostgreSQL (repositories/file.go:30) — хранит метаданные файла
## Вопросы
- всё непонятное что нашли в коде
Для каждой точки входа обязательно:
- файл и номер строки
- первая строка сигнатуры функции
- одна фраза что делает эта часть кода
Только факты. Никаких мнений, советов по рефакторингу и предложений улучшить.
Шаг 4: Остановиться и спросить пользователя
После сбора фактов — не двигаться дальше. Показать пользователю:
- Что нашли (краткий итог research.md)
- Вопросы которые возникли при анализе
Продолжать только после того как пользователь ответил и подтвердил понимание.
Фаза 2: Design (Проектирование)
Цель: решить как будет устроено решение — до написания кода.
Шаг 1: Описать решение
На основе research.md и ответов пользователя описать:
- что добавляется / изменяется в системе
- как новая часть связана с существующими
- какие данные откуда берутся и куда идут
- последовательность вызовов для основного сценария
Минимально необходимые документы:
architecture.md — что и как устроено: текстовое описание + графическая диаграммаsequence.md — последовательность шагов: текстовое описание + графическая диаграмма
Дополнительно, только если меняется интерфейс:
contracts.md — API-контракты
Формат каждого документа — сначала текст, потом графика:
## Название
Текстовое описание что происходит (2-5 предложений простыми словами).
### Диаграмма
<графическое представление доступными средствами текущей среды>
Диаграмма генерируется в виде исходного кода — пользователь редактирует её в своём инструменте самостоятельно.
Использовать только уже установленные инструменты. Не предлагать установить что-то дополнительно.
Шаг 2: Остановиться и показать пользователю
Не писать код пока пользователь не одобрил дизайн.
Показать пользователю дизайн и спросить:
- Всё ли правильно понято?
- Нет ли чего-то что упустили?
Исправить дизайн если пользователь указал на ошибки. Только после одобрения — переходить к плану.
Фаза 3: Plan (Планирование)
Цель: разбить задачу на маленькие части в правильном порядке.
Принцип декомпозиции
Делить на части по принципу от основания к верхушке:
- сначала то от чего всё зависит (модели, базовые структуры данных)
- потом то что использует основание (сервисы, логика)
- в конце то что использует всё остальное (хендлеры, UI, интеграции)
Нельзя тестировать верхние части если нижние не готовы и не проверены.
Шаблон одной фазы
Каждая фаза описывается так:
## Фаза N: <название>
**Что делаем**: одно предложение — суть задачи
**Файлы**:
- создаём: path/to/file.go
- меняем: path/to/other.go (только конкретная функция)
**Тестовые данные**: что нужно подготовить для проверки этой части
**Готово когда**:
- [ ] конкретная проверка 1
- [ ] конкретная проверка 2
Правила планирования
- Каждая фаза — одна маленькая законченная часть работы
- Не смешивать несвязанные изменения в одной фазе
- Если фаза не прошла проверку — не переходить к следующей
- Не планировать изменения в работающих частях которые не нужны для задачи
Фаза 4: Implement (Реализация)
Цель: написать код строго по плану, проверить каждую часть перед следующей.
Правила написания кода
- Одна функция — одна ответственность. Если функция делает два дела — это два разных места
- Не создавать большие модули которые делают всё сразу
- Не изменять работающий код если он не входит в текущую фазу
- Не добавлять "улучшения" и "рефакторинг" которые не были в плане
- Только то что написано в задаче. Ничего лишнего
Порядок работы над каждой фазой
- Написать код фазы строго по плану
- Подготовить тестовые данные (файлы, входные данные, моки)
- Протестировать эту часть изолированно
- Проверить quality gates
- Показать результат пользователю
- Получить одобрение — только потом переходить к следующей фазе
Тестовые данные
Перед тестированием каждой фазы подготовить:
- входные данные (примеры запросов, файлы, параметры)
- ожидаемые результаты
- граничные случаи (пустые данные, неверный формат, максимальные значения)
Если тестовых данных нет — сгенерировать их. Не тестировать на угад.
Порядок тестирования
Тестировать в том же порядке что и разработка — от основания к верхушке:
- Сначала базовые части (модели, утилиты)
- Потом части которые их используют (сервисы)
- В конце верхний уровень (хендлеры, интеграции)
Нельзя тестировать верхний уровень если базовые части не проверены — такое тестирование бесполезно.
Quality Gates — проверка каждой фазы
| Gate | Что проверяем |
|---|
| Build | Код собирается без ошибок |
| Tests | Тесты этой фазы проходят |
| Scope | Изменены только файлы из плана этой фазы, ничего лишнего |
| Size | Нет функций которые делают слишком много (> 30-50 строк — повод задуматься) |
Если что-то не прошло — исправить и проверить снова. Не переходить к следующей фазе.
Показ результата пользователю
После каждой фазы показать пользователю:
- что было сделано
- результаты тестов
- что будет в следующей фазе
Продолжать только после одобрения.
Специализация по типу задачи
Новая фича
Research → Design → Plan → Implement как описано выше.
Баг
- Воспроизвести — убедиться что баг воспроизводится стабильно, зафиксировать шаги
- Найти место — через точки входа найти где именно происходит ошибка
- Понять причину — только факты из кода, не предположения
- Спросить пользователя — показать где баг и в чём причина, подтвердить понимание
- Минимальное исправление — исправить только проблемное место, не трогать остальное
- Написать тест — тест который воспроизводит баг и проверяет исправление
Рефакторинг
- Зафиксировать текущее поведение — написать тесты которые описывают что есть сейчас
- Убедиться что тесты проходят до начала изменений
- Менять маленькими шагами — один шаг, один коммит, тесты проходят
- Проверять после каждого шага что поведение не изменилось
- Если тесты упали — откатить последний шаг, разобраться почему
Как выглядит весь процесс
Задача
→ Research: найти точки входа, пройти цепочку, записать факты
→ Спросить пользователя, уточнить непонятное
→ Design: описать решение (минимально необходимо)
→ Показать пользователю, получить одобрение
→ Plan: разбить на фазы от основания к верхушке
→ Implement: фаза за фазой
→ написать код
→ подготовить тестовые данные
→ протестировать
→ quality gates
→ показать пользователю
→ следующая фаза
