КРАТКО
| Сложность | Средняя |
| Время | 60–90 минут на настройку; недели на полное выполнение проекта |
| Требования | Работа с Git, базовые навыки командной строки, хотя бы один язык программирования |
| Инструменты | ChatGPT+ с доступом к Codex, Claude Pro или Claude+, подписка Gemini Pro (опционально) |
Чему вы научитесь:
- Настраивать файлы agents.md и plans.md, которые держат ИИ-ассистентов в курсе между сессиями
- Выбирать подходящую модель под конкретный тип задачи
- Строить тестовую инфраструктуру, которая ловит регрессии от ИИ-генерации
- Управлять контекстом без потери связности проекта
Этот гайд про координацию нескольких ИИ-ассистентов на проектах, которые не помещаются в одну сессию. Подход обкатан на реальной конвертации библиотеки: работа, которая стоила бы примерно $30 000 разработческого времени, обошлась примерно в $30 подписок за две недели.
Если вы уже пробовали ИИ-кодинг и разочаровались, потому что всё разваливается на чём-то сложнее одного файла, то это для вас. Если вы уже пользуетесь Claude Code ежедневно и хотите добавить другие модели в ротацию, переходите сразу к разделу про выбор моделей.
С чего начать
Нужны активные подписки минимум на две ИИ-платформы для кодинга. Комбинация, которая сработала на этом проекте: ChatGPT+ (для Codex), Claude Pro (для Claude Code и Opus 4.5), Gemini Pro (для фронтенда и задач с большим контекстом). Можно начать с одной, но воркфлоу реально выигрывает от переключения между моделями под разные типы задач.
Создайте директорию проекта с такой структурой:
project/
├── agents.md
├── plans.md
├── src/
├── tests/
└── docs/
└── reference/ # Оригинальный код, спеки, примеры
Файлы agents.md и plans.md — основа всего. Дальше расскажу подробно, что в них писать, но если коротко: agents.md описывает проект и его соглашения; plans.md отслеживает, что сделано и что дальше. Каждая сессия с ИИ начинается с чтения этих файлов.
Настройка документации
agents.md
Этот файл объясняет каждому ИИ-ассистенту, над чем он работает. Начните широко, потом добавляйте детали по мере возникновения проблем. Мой начинался на 200 строк, а закончил примерно на 80 — когда понял, что короче лучше, и вынес детальные спецификации в другое место.
# Project: [Название]
## Overview
[2-3 предложения о том, что это за проект и что вы делаете]
## Architecture
[Где лежит код, как организован, ключевые паттерны]
## Conventions
- Language: TypeScript (strict mode)
- Testing: Jest с покрытием >80%
- Naming: camelCase для функций, PascalCase для классов
[Добавляйте соглашения по мере того, как замечаете неправильные предположения ИИ]
## File Locations
- Source: /src
- Tests: /tests
- Reference implementation: /docs/reference/[оригинальный код]
- Detailed specs: /docs/specs/
## Current Focus
Смотри plans.md для активных задач.
Раздел «Conventions» растёт органически. Каждый раз, когда ИИ пишет код не в вашем стиле — добавляете строчку. Каждый раз, когда делает неправильное предположение о структуре файлов — добавляете строчку.
plans.md
Это ваш трекер задач. У OpenAI есть хорошее описание формата в их cookbook (ищите «codex exec plans»). Структура:
# Implementation Plan
## Completed
- [x] Task 1: Set up project structure
- [x] Task 2: Port core data types
## In Progress
- [ ] Task 3: Port validation logic
- [x] Subtask 3.1: Basic type validation
- [ ] Subtask 3.2: Cross-field validation
## Upcoming
- [ ] Task 4: Port API layer
- [ ] Task 5: Integration tests
После каждой сессии с ИИ обновляйте этот файл. ИИ может помочь, но проверяйте обновления сами. Я это усвоил после того, как одна особо энтузиастичная модель пометила три задачи выполненными, которые на самом деле были наполовину готовы.
Выбор модели под задачу
Не все ИИ-ассистенты одинаковы. Это не исчерпывающий обзор, потому что я не тестировал всё досконально, но вот что заметил.
Codex 5.2 через ChatGPT+ лучше всего справлялся с общим планированием и длинной последовательной работой. Когда у меня был план миграции на 30 шагов и нужно было кому-то методично его выполнять, Codex был тем самым. Похоже, он держит очень большой контекст без деградации, в отличие от других моделей. Нюанс: нужны предельно чёткие спеки. Неоднозначность его убивает.
Opus 4.5 (через Claude Code или просто в интерфейсе Claude) писал самый чистый код для хорошо очерченных задач. Если я мог описать, что нужно, меньше чем в 500 словах, Opus обычно попадал с первого раза. Управление контекстом тут важно. Я старался держать разговоры меньше 30% от окна контекста. После этого качество заметно падало, хотя точных замеров я не делал.
Gemini 3.0 Pro удивил на фронтенд-работе и на задачах, требующих сравнения больших файлов. У него огромное окно контекста, и он его хорошо использует. Когда мне нужно было сравнить Java-файл на 3000 строк с его TypeScript-портом, чтобы найти расхождения, Gemini был быстрее и точнее остальных. Gemini Flash хорош для быстрых проверок, где нельзя ничего сломать, но ошибок у него больше, чем у полных моделей.
Уточню: «лучше всего для X» не значит, что другие не могут делать X. Это значит, что когда у меня были ограничены токены и нужна была надёжность, я тянулся именно к этой модели.
Тестовая инфраструктура
Тесты — это то, что делает ИИ-кодинг работающим на масштабе. Без них вы дебажите ИИ-генерированный код, читая его глазами. Это убивает весь смысл.
Шаг 1: Получите эталонные данные
Если вы портируете существующий код, запустите оригинал и захватите входы и выходы. Для новых проектов напишите спецификации ожидаемого поведения до кодинга.
# Пример: захват тест-кейсов из Java-библиотеки
java -jar original.jar --test-mode > test-cases.json
Это даёт вам эталон для сверки. Храните в /docs/reference/.
Шаг 2: Сгенерируйте каркас тестов
Попросите ИИ сгенерировать тесты на основе эталонных данных, но будьте конкретны:
Read test-cases.json. For each case, generate a Jest test that:
1. Uses the input from the test case
2. Calls the corresponding function in our TypeScript implementation
3. Compares output to expected result
4. Reports which field differs if assertion fails
Проверьте сгенерированные тесты. ИИ склонен писать слишком многословные описания тестов и иногда неправильно понимает assertion'ы. Обрежьте лишнее.
Шаг 3: Добавьте линтинг и проверку типов
Запускайте это при каждом изменении:
// package.json scripts
{
"lint": "eslint src --ext .ts",
"typecheck": "tsc --noEmit",
"test": "jest",
"verify": "npm run lint && npm run typecheck && npm run test"
}
Скажите ИИ запускать npm run verify после каждого изменения. Пропишите это в agents.md. Они всё равно иногда будут забывать.
Шаг 4: Добавьте pre-commit хуки
Это ловит то, что словесные инструкции не ловят:
npx husky install
npx husky add .pre-commit "npm run verify"
Теперь сломанный код не закоммитится вне зависимости от того, что делает ИИ.
Контекст между сессиями
Здесь большинство ИИ-проектов по кодингу проваливается. Вы упираетесь в лимиты контекста, начинаете новый разговор, и ИИ всё забыл.
Документационный слой (agents.md и plans.md) решает часть проблемы. Но есть ещё кое-что.
Паттерн передачи сессии
В конце каждой сессии попросите ИИ подытожить:
Summarize what we accomplished this session and what's left for the next session.
Format as updates to plans.md.
List any new conventions or gotchas for agents.md.
Скопируйте это в свои файлы. Когда начинаете следующую сессию (с той же моделью или другой), начните с:
Read agents.md and plans.md. Confirm you understand the project state and current task.
Дождитесь подтверждения перед тем, как продолжить. Кажется медленным, но экономит время на дебаге.
Поддержание файлов в актуальном состоянии
Тут я поначалу ошибался. Я давал agents.md разрастаться до 500+ строк с детальными спеками, и ИИ терял нить того, что важно. Теперь держу agents.md до 100 строк и выношу детали в файлы /docs/specs/, на которые ссылаюсь по мере необходимости.
Plans.md обновляется после каждой завершённой задачи. Без исключений. Это утомительно, но без этого первые 15 минут каждой сессии уйдут на восстановление состояния.
Работа с существующими кодовыми базами
При портировании или модификации существующего кода:
Положите эталонные файлы в /docs/reference/. Скажите ИИ сверяться с ними перед написанием нового кода. В agents.md напишите:
## Reference Implementation
Original Java code is in /docs/reference/java/
Before implementing any function, read the corresponding Java implementation.
Match behavior exactly unless plans.md specifies a change.
Для проекта конвертации библиотеки я заставлял ИИ сравнивать свой вывод с Java-версией после каждой функции. Это ловило дрифт на ранней стадии.
Решение проблем
ИИ помечает задачи выполненными, хотя они не готовы
Проверяйте завершения сами. Добавьте шаги верификации в plans.md: «Task complete when: all tests pass, types check, matches Java output for test cases 1-15.»
Контекст кончается посреди задачи
Дробите задачи мельче. Если задачу нельзя завершить за одну сессию, она слишком большая. Каждая задача в plans.md должна занимать 15–30 минут ИИ-времени, не часы.
Разные модели делают несовместимые изменения
По возможности придерживайтесь одной модели на файл или модуль. Если приходится переключаться, начните новую сессию с «Read the current state of [file]. Describe what you see before making changes.»
ИИ пишет код, не соответствующий стилю проекта
Добавьте конкретные примеры в agents.md. Не «use consistent naming», а «function names: getUser, validateInput, not get_user, validateUserInput_v2.»
Линтинг/тесты падают после правок ИИ
Такое случается. Воркфлоу на это рассчитан. Для этого verify запускается после каждого изменения, а pre-commit хуки блокируют сломанный код.
Что дальше
Этот воркфлоу справляется с проектами до нескольких тысяч файлов и многонедельными сроками. Для чего-то крупнее, вероятно, нужны нормальные инструменты управления проектами, а не просто markdown-файлы.
Для ближайших шагов: документация Claude Code покрывает конкретные команды, если вы используете этот инструмент.
СОВЕТЫ
Горячие клавиши не так важны, как может показаться, но: в Claude Code /clear сбрасывает контекст без потери сессии. Используйте, когда ответы начинают становиться странными.
Если вы на Mac, broadcast input в iTerm2 позволяет запускать одну команду в нескольких терминалах. Удобно для запуска тестов, пока ИИ работает в другой панели.
Загрузка файлов в Gemini справляется с бо́льшими файлами, чем можно было ожидать. Я загрузил JSON-фикстуру на 15 МБ целиком вместо копирования по кусочкам, и модель корректно ссылалась на неё на протяжении всего разговора.
При переключении между моделями посреди задачи явно формулируйте, что было решено в предыдущих сессиях. «The previous session decided to use a factory pattern for X. Continue with that approach.» ИИ не всегда выводит это из кода.
ЧаВо
Можно использовать бесплатные тарифы вместо платных подписок? Для мелких задач — да. Для многонедельных проектов лимиты запросов делают бесплатные тарифы непрактичными. Воркфлоу предполагает, что вы можете запускать несколько запросов подряд без ожидания.
Как понять, когда переключать модели? Когда текущая модель буксует. Если Opus выдаёт непоследовательные результаты на фронтенд-работе, попробуйте Gemini. Если Codex теряет нить сложного плана, попробуйте сначала разбить его на части, а не переключаться. Формулы нет, только накопление паттернов со временем.
Что если в моём проекте нет тестов? Напишите их сначала. Или пусть ИИ напишет. Серьёзно. Этот воркфлоу завязан на автоматическую верификацию. Без тестов вы вручную ревьюите каждое изменение ИИ, а это плохо масштабируется.
Через сколько ИИ нужны напоминания о соглашениях проекта? По моему опыту, около 20–30 обменов в Claude Code, прежде чем контекст начинает конкурировать с деталями проекта. Короткие разговоры надёжнее. Начинайте свежие сессии для отдельных задач.
Какой расклад по стоимости для проекта типа конвертации библиотеки? ChatGPT+ за $20/месяц, Claude Pro за €20/месяц, Gemini Pro за €20/месяц. Две недели активной работы означают полмесяца каждого, то есть примерно €30 всего. Эквивалентная консалтинговая работа котировалась в $30 000+.
РЕСУРСЫ
- OpenAI Codex Execution Plans: Формат plans.md, который я адаптировал отсюда
- Claude Code documentation: Настройка и команды для CLI Claude Code
