Codex First — методология работы с ИИ-агентами

Codex First — методология, в которой вы сначала добиваетесь ясности и работающего понимания задачи, и только потом подключаете ИИ-агента к боевым действиям. Этот справочник — про принципы, фазы цикла и про то, как встроить методологию в реальный рабочий процесс с Linear, Notion и GitHub.

Зачем вообще методология

ИИ-агенты быстрые. Они уверенные. Они хотят помочь. И они с лёгкостью разносят прод, если вы спросили их «почини X» без контекста. Codex First — попытка ввести в работу с агентами обычный инженерный цикл: понять, спланировать, сделать, проверить, зафиксировать.

Цель методологии — превратить агента из «болтливого джуна с правом на sudo» в технического партнёра, который сначала разбирается, потом согласовывает, потом действует.

Пять фаз цикла

1. Discover — аудит и evidence

Задача фазы: собрать карту того, что есть на самом деле. Никаких изменений, только чтение, логи, скрины, выводы команд.

Артефакт: evidence-документ или папка с собранными фактами. Обычно — страница в Notion или markdown-файл в репозитории.

Что попадает в evidence:

• Структура проекта, ключевые модули, точки входа.
• Активные сервисы и их состояние.
• Логи за последние N дней по интересующей подсистеме.
• Скриншоты UI до изменений.
• Версии зависимостей.
• Список владельцев и стейкхолдеров.

2. Clarify — формулировка задачи

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

Артефакт: короткий work packet — описание задачи с acceptance-критериями, ограничениями и явными «не делать».

Структура work packet:

• Цель в одном предложении.
• Контекст: что и почему меняем.
• Acceptance: как поймём, что готово.
• Out of scope: что точно не делаем.
• Риски и зависимости.

3. Plan — план изменений

Задача фазы: разложить задачу на шаги, для каждого шага записать ожидаемый результат и rollback.

Артефакт: план в виде нумерованного списка шагов или PR-черновик с описанием изменений.

Каждый шаг плана содержит:

• Что делаем.
• Где (файл, сервис, страница).
• Как проверим, что шаг прошёл успешно.
• Как откатимся, если шаг провалится.

4. Act — действие через коридор

Задача фазы: выполнить план в чистой ветке с активными approval-hooks. Агент работает, человек одобряет ключевые точки.

Артефакт: PR с изменениями, ссылками на evidence и план.

Правила фазы:

• Работа в чистой git-ветке, отдельной для задачи.
• Approval-hooks включены на запись в важные файлы и git-операции.
• Каждые 30–60 минут — checkpoint: что сделано, что осталось, что неожиданно.
• На любом сюрпризе — стоп и возврат к фазе clarify.

5. Record — фиксация в памяти

Задача фазы: записать в проектную память то, что не должно потеряться к следующей сессии.

Артефакт: обновлённые AGENTS.md, SESSION_NOTES.md, ADR (architecture decision records).

Что обычно фиксируется:

• Принятые архитектурные решения и почему.
• Новые конвенции в коде.
• Стоп-линии, которые добавились по итогам инцидентов.
• Обновлённые серверные паспорта.
• Ссылки на PR, evidence и план — чтобы можно было быстро вспомнить.

Целевая архитектура процесса

Вот как Codex First встроен в реальный стек:

Ключевая идея — задача не уходит в действие, пока на ней не появится лейбл Ready for Codex. Этот лейбл означает: discover и clarify пройдены, план есть, риски названы.

Codex readiness labels

Набор лейблов в Linear, который описывает готовность задачи к работе с агентом:

• Needs clarification — задача не понятна, нужны уточнения от автора.
• Needs approval — есть план, нужен человеческий approval по подходу.
• Ready for Codex — discover и clarify пройдены, агент может приступать.
• In progress (Codex) — агент работает, PR в процессе.
• Ready for smoke — изменения сделаны, нужна проверка в реальных условиях.
• Done — задача закрыта, evidence и записи в памяти обновлены.

Лейблы — не украшение. Это коммуникация состояний между людьми, агентами и контекстом задачи.

Чеклист готовности задачи к Codex

Эталонный шаблон work packet

# Work packet: <название задачи>

## Цель
Одно предложение, описывающее результат.

## Контекст
Что сейчас, почему меняем, какие предпосылки.

## Acceptance
- Критерий 1
- Критерий 2
- Критерий 3

## Out of scope
- Что мы точно не делаем в этой задаче

## Риски
- Риск 1 → митигация
- Риск 2 → митигация

## План
1. Шаг 1. Проверка: ... Rollback: ...
2. Шаг 2. Проверка: ... Rollback: ...
3. Шаг 3. Проверка: ... Rollback: ...

## Stop-lines
- Чего агент точно не делает без approval

## Ссылки
- Evidence: ...
- Linear: ...
- PR: ...

Антипаттерны

• ❌ «Сразу в код». Без discover и clarify задача превращается в гадание. Агент выдаст красивый PR, который решает не ту проблему.
• ❌ Evidence «в голове». Если evidence нигде не записан — его нет. К нему нельзя вернуться, его нельзя оспорить.
• ❌ План без rollback. Любой шаг должен иметь обратную операцию или snapshot для отката.
• ❌ Action без approval-hooks. «Я доверяю агенту» — фраза, после которой через две недели в логе появляется инцидент.
• ❌ Record на потом. Если не зафиксировали изменения в памяти — следующая сессия начинается с нуля. Контекстный долг копится быстро.
• ❌ Лейблы на словах. Если процесс не закреплён в Linear явными лейблами — он сначала размывается, потом исчезает.

Когда методология лишняя

Codex First рассчитан на боевые системы и живых пользователей. Есть ситуации, где она избыточна:

• Локальные эксперименты в sandbox.
• Прототипы и скаффолды без рисков для прода.
• Аналитика и поиск по базе знаний.
• Одноразовые скрипты для своих личных задач.

Чем критичнее система и шире круг затронутых людей — тем строже нужно соблюдать цикл.

Если внедряете Codex First в командный процесс или хотите разобрать ваш контур работы с агентами — пишите в Telegram @pimenov