ai-engineering-process

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: Остановиться и спросить пользователя

После сбора фактов — не двигаться дальше. Показать пользователю:

1. Что нашли (краткий итог research.md)
2. Вопросы которые возникли при анализе

Продолжать только после того как пользователь ответил и подтвердил понимание.

---

Фаза 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 (Реализация)

Цель: написать код строго по плану, проверить каждую часть перед следующей.

Правила написания кода

• Одна функция — одна ответственность. Если функция делает два дела — это два разных места
• Не создавать большие модули которые делают всё сразу
• Не изменять работающий код если он не входит в текущую фазу
• Не добавлять "улучшения" и "рефакторинг" которые не были в плане
• Только то что написано в задаче. Ничего лишнего

Порядок работы над каждой фазой

1. Написать код фазы строго по плану
2. Подготовить тестовые данные (файлы, входные данные, моки)
3. Протестировать эту часть изолированно
4. Проверить quality gates
5. Показать результат пользователю
6. Получить одобрение — только потом переходить к следующей фазе

Тестовые данные

Перед тестированием каждой фазы подготовить:

• входные данные (примеры запросов, файлы, параметры)
• ожидаемые результаты
• граничные случаи (пустые данные, неверный формат, максимальные значения)

Если тестовых данных нет — сгенерировать их. Не тестировать на угад.

Порядок тестирования

Тестировать в том же порядке что и разработка — от основания к верхушке:

1. Сначала базовые части (модели, утилиты)
2. Потом части которые их используют (сервисы)
3. В конце верхний уровень (хендлеры, интеграции)

Нельзя тестировать верхний уровень если базовые части не проверены — такое тестирование бесполезно.

Quality Gates — проверка каждой фазы

Gate	Что проверяем
Build	Код собирается без ошибок
Tests	Тесты этой фазы проходят
Scope	Изменены только файлы из плана этой фазы, ничего лишнего
Size	Нет функций которые делают слишком много (> 30-50 строк — повод задуматься)

Если что-то не прошло — исправить и проверить снова. Не переходить к следующей фазе.

Показ результата пользователю

После каждой фазы показать пользователю:

• что было сделано
• результаты тестов
• что будет в следующей фазе

Продолжать только после одобрения.

---

Специализация по типу задачи

Новая фича

Research → Design → Plan → Implement как описано выше.

Баг

1. Воспроизвести — убедиться что баг воспроизводится стабильно, зафиксировать шаги
2. Найти место — через точки входа найти где именно происходит ошибка
3. Понять причину — только факты из кода, не предположения
4. Спросить пользователя — показать где баг и в чём причина, подтвердить понимание
5. Минимальное исправление — исправить только проблемное место, не трогать остальное
6. Написать тест — тест который воспроизводит баг и проверяет исправление

Рефакторинг

1. Зафиксировать текущее поведение — написать тесты которые описывают что есть сейчас
2. Убедиться что тесты проходят до начала изменений
3. Менять маленькими шагами — один шаг, один коммит, тесты проходят
4. Проверять после каждого шага что поведение не изменилось
5. Если тесты упали — откатить последний шаг, разобраться почему

---

Как выглядит весь процесс

Задача
  → Research: найти точки входа, пройти цепочку, записать факты
  → Спросить пользователя, уточнить непонятное
  → Design: описать решение (минимально необходимо)
  → Показать пользователю, получить одобрение
  → Plan: разбить на фазы от основания к верхушке
  → Implement: фаза за фазой
      → написать код
      → подготовить тестовые данные
      → протестировать
      → quality gates
      → показать пользователю
      → следующая фаза