Лучшие практики: четкое описание, использование контрольных точек, контроль объема и техники итераций

Что вы сможете сделать после этого курса

После прохождения этого курса вы освоите:

• Как написать качественное описание продукта, чтобы AI понял ваши идеи
• Как использовать механизм контрольных точек для управления качеством вывода на каждом этапе
• Как через нефункциональные требования четко определить границы объема и предотвратить разрастание проекта
• Как через пошаговые итерации быстро проверять идеи и постоянно оптимизировать

Ваша текущая проблема

Вы тоже сталкивались с такими ситуациями:

• "Я всё объяснил понятно, почему сгенерировано не то, что я хотел?"
• "В одном месте не понравилось, дальше всё неверно, исправлять очень больно"
• "В процессе работы функций становится всё больше, завершить невозможно"
• "Хочу сделать все функции сразу, в итоге ничего не сделал"

Когда применять этот метод

Независимо от того, впервые ли вы используете AI App Factory или уже имеете опыт, эти лучшие практики помогут вам:

• Повысить качество вывода: сгенерированные приложения будут больше соответствовать ожиданиям
• Сэкономить время на изменения: избежать накопления ошибок, выявлять проблемы на ранней стадии
• Контролировать объем проекта: сосредотачиваться на MVP, быстро доставлять
• Снизить затраты на разработку: поэтапная проверка, избегать бесполезных вложений

🎒 Подготовка перед началом

Предварительные требования

• Прочитали Быстрый старт для понимания основных концепций AI App Factory
• Прочитали Обзор конвейера из 7 этапов для понимания полного процесса
• Выполнили хотя бы один полный запуск конвейера (так у вас будет интуитивное понимание вывода каждого этапа)

Основная идея

Лучшие практики AI App Factory строятся вокруг четырех основных принципов:

1. Качество ввода определяет качество вывода: четкое и подробное описание продукта — первый шаг к успеху
2. Контрольные точки — линия защиты качества: после завершения каждого этапа внимательно проверяйте, избегайте накопления ошибок
3. Фокус на MVP: четко определите нефункциональные требования, контролируйте объем, быстро доставляйте ключевые функции
4. Непрерывная итерация: сначала проверяйте ключевую идею, затем постепенно расширяйте функциональность

Эти принципы основаны на анализе исходного кода и практического опыта, следование им может повысить вашу эффективность разработки в несколько раз.

Делайте вместе со мной

Техника 1: предоставьте четкое описание продукта

Зачем

Когда AI понимает ваши идеи, он может полагаться только на предоставленную текстовую информацию. Чем четче описание, тем больше сгенерированный результат соответствует ожиданиям.

Как делать

Хорошее описание продукта включает следующие элементы:

• Целевая аудитория: кто будет использовать этот продукт?
• Ключевая проблема: какие трудности возникают у пользователей?
• Решение: как продукт решает эту проблему?
• Ключевые функции: какие функции обязательно должны быть включены?
• Сценарии использования: в каких ситуациях пользователи используют продукт?
• Ограничения: есть ли какие-то ограничения или специальные требования?

Примеры сравнения

❌ Плохое описание	✅ Хорошее описание
Сделайте фитнес-приложение	Приложение для записи тренировок для новичков в фитнесе, поддерживает запись типа тренировки, продолжительности, сжигаемых калорий и просмотр статистики тренировок за неделю. Целевая аудитория — молодые люди, которые только начинают заниматься фитнесом, ключевые функции — быстрое заполнение и просмотр прогресса, не включает социальные функции или платные функции
Сделайте приложение для учета расходов	Мобильное приложение для быстрой записи ежедневных расходов для молодых людей, основная функция — запись суммы, выбор категории (еда, транспорт, развлечения, другие), просмотр общих расходов за месяц и статистики по категориям. Поддерживает автономное использование, данные сохраняются только локально
Сделайте инструмент управления задачами	Простой инструмент для управления задачами в малых командах, поддерживает создание задач, назначение участников, установку сроков, просмотр списка задач. Члены команды могут обмениваться статусами задач. Не требует сложных рабочих процессов или управления правами доступа

Контрольная точка ✅

• [ ] В описании четко определена целевая аудитория
• [ ] В описании объясняется ключевая проблема, с которой сталкиваются пользователи
• [ ] В описании перечислены ключевые функции (не более 5)
• [ ] В описании включены ограничения или нефункциональные требования

---

Техника 2: внимательно подтверждайте в контрольных точках

Зачем

После завершения каждого этапа конвейера происходит пауза в контрольной точке, ожидая вашего подтверждения. Это линия защиты качества, позволяющая рано выявлять проблемы и избегать их распространения на последующие этапы.

Если проблема обнаруживается на этом этапе, достаточно перезапустить только текущий этап; если обнаружить в самом конце, может потребоваться откат нескольких этапов, что приведет к потере большого количества времени и Token.

Как делать

При каждом подтверждении в контрольной точке проверяйте следующее:

Контрольная точка этапа Bootstrap:

• [ ] Определение проблемы в input/idea.md точное
• [ ] Портрет целевой аудитории четкий и конкретный
• [ ] Ключевое ценностное предложение четкое
• [ ] Условия гипотезы разумные

Контрольная точка этапа PRD:

• [ ] Пользовательские истории ясны, включают условия приема
• [ ] Список функций не превышает 7 (принцип MVP)
• [ ] Четко перечислены нефункциональные требования (Non-Goals)
• [ ] Не включены технические детали (например, React, API, база данных)

Контрольная точка этапа UI:

• [ ] Структура страниц разумная, не более 3 страниц
• [ ] Можно предварительно просмотреть прототип в браузере
• [ ] Поток взаимодействия ясный
• [ ] Стиль выражен ярко (избегайте общего AI-стиля)

Контрольная точка этапа Tech:

• [ ] Выбор технологического стека разумен, соответствует принципу MVP
• [ ] Дизайн модели данных простой, количество таблиц не превышает 10
• [ ] Список API-эндпоинтов полный
• [ ] Не введены избыточные проектирования, такие как микросервисы, кеширование

Контрольная точка этапа Code:

• [ ] Структура кода интерфейса и бэкенда полная
• [ ] Включены тестовые случаи
• [ ] Нет очевидных типов any
• [ ] Включен README.md с объяснением, как запустить

Контрольная точка этапа Validation:

• [ ] В отчете о проверке нет серьезных проблем безопасности
• [ ] Покрытие тестами > 60%
• [ ] Установка зависимостей без конфликтов
• [ ] Проверка типов TypeScript пройдена

Контрольная точка этапа Preview:

• [ ] README.md содержит полные инструкции по запуску
• [ ] Конфигурация Docker успешно собирается
• [ ] Локально можно запустить службы интерфейса и бэкенда
• [ ] Включены инструкции по настройке переменных окружения

Процесс подтверждения в контрольных точках

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

• Продолжить: если вывод соответствует ожиданиям, перейдите к следующему этапу
• Повторить: если в выводе есть проблемы, предоставьте исправления и перезапустите текущий этап
• Пауза: если нужна дополнительная информация или хотите скорректировать идею, приостановите конвейер

Принципы принятия решений:

• ✅ Продолжить: все контрольные пункты соответствуют требованиям
• ⚠️ Повторить: мелкие проблемы (формат, упущения, детали), можно немедленно исправить
• 🛑 Пауза: серьезные проблемы (ошибочное направление, потеря контроля над объемом, невозможно исправить), требуется повторное планирование

Предупреждение о подводных камнях

Частые ошибки

Не пропускайте подтверждение в контрольных точках ради того, чтобы "быстро закончить"!

Конвейер спроектирован как "пауза и подтверждение на каждом этапе" именно для того, чтобы вы вовремя выявляли проблемы. Если вы привыкаете нажимать "Продолжить", и в самом конце обнаруживаются проблемы, может потребоваться:

• Откат нескольких этапов
• Повторное выполнение большого объема работы
• Потеря большого количества Token

Помните: временные затраты на подтверждение в контрольных точках намного меньше временных затрат на откат и переделку.

---

Техника 3: используйте нефункциональные требования для контроля объема

Зачем

Нефункциональные требования (Non-Goals) — это ключевое оружие разработки MVP. Четкое перечисление "что не делать" может эффективно предотвратить разрастание объема.

Корень многих неудач проектов — не в том, что функций слишком мало, а в том, что их слишком много. Каждая новая функция увеличивает сложность, время разработки и затраты на обслуживание. Только четкое определение границ и фокус на ключевой ценности позволят быстро доставить.

Как делать

На этапе Bootstrap четко перечислите нефункциональные требования:

## Нефункциональные требования (функции, не выполняемые в этой версии)

1. Не поддерживает многопользовательское сотрудничество
2. Не поддерживает синхронизацию в реальном времени
3. Не поддерживает интеграцию сторонних сервисов (например, оплата, карты)
4. Не предоставляет аналитики данных или отчетов
5. Не включает функции социального шеринга
6. Не требует аутентификации пользователя или функции входа

На этапе PRD сделайте нефункциональные требования отдельным разделом:

## Нефункциональные требования (функции, которые явно не выполняются в этой версии)

Следующие функции имеют ценность, но не входят в объем этого MVP:

| Функция | Причина | Будущее планирование |
| --- | --- | --- |
| Многопользовательское сотрудничество | Фокус на индивидуальных пользователях | Рассмотреть в v2.0 |
| Синхронизация в реальном времени | Увеличивает техническую сложность | Рассмотреть при сильной обратной связи пользователей |
| Интеграция оплаты | Не является ключевой ценностью | Рассмотреть в v1.5 |
| Аналитика данных | MVP не требует | Рассмотреть в v2.0 |

Критерии оценки нефункциональных требований

Как определить, следует ли считать функцию нефункциональным требованием:

• ❌ Эта функция не является обязательной для проверки ключевой идеи → как нефункциональное требование
• ❌ Эта функция значительно увеличивает техническую сложность → как нефункциональное требование
• ❌ Эту функцию можно заменить вручную → как нефункциональное требование
• ✅ Эта функция — причина существования продукта → обязательно включить

Предупреждение о подводных камнях

Ловушка разрастания объема

Частые сигналы разрастания объема:

1. "Все равно очень просто, заодно добавим еще одну..."
2. "У конкурентов есть эта функция, нам тоже нужно..."
3. "Возможно, пользователям понадобится,不如 сначала сделать..."
4. "Эта функция интересная, может улучшить яркие стороны продукта..."

При возникновении таких идей спросите себя три вопроса:

1. Эта функция полезна для проверки ключевой идеи?
2. Если не делать эту функцию, продуктом можно пользоваться?
3. Добавление этой функции задержит доставку?

Если ответы: "не нужно", "можно", "задержит", то решительно отнесите к нефункциональным требованиям.

---

Техника 4: пошаговая итерация, быстрая проверка

Зачем

Ключевая идея MVP (минимально жизнеспособного продукта) — быстро проверить идеи, а не сразу сделать идеально.

Через итерационную разработку вы можете:

• Рано получить обратную связь от пользователей
• Своевременно корректировать направление
• Снизить невозвратные затраты
• Поддерживать мотивацию разработки

Как делать

Шаги итерационной разработки:

Первый раунд: проверка ключевых функций

1. Используйте AI App Factory для генерации первого приложения
2. Включайте только 3-5 самых ключевых функций
3. Быстро запустите и протестируйте
4. Покажите прототип реальным пользователям, соберите обратную связь

Второй раунд: оптимизация на основе обратной связи

1. На основе обратной связи пользователей определите точки с наивысшим приоритетом
2. Измените input/idea.md или artifacts/prd/prd.md
3. Используйте factory run <stage> для повторного выполнения с соответствующего этапа
4. Сгенерируйте новую версию и протестируйте

Третий раунд: расширение функциональности

1. Оцените, достигнута ли ключевая цель
2. Выберите 2-3 функции с высокой ценностью
3. Сгенерируйте и интегрируйте через конвейер
4. Постоянно итерируйте, постепенно улучшайте

Пример итерации в реальном проекте

Сценарий: вы хотите сделать приложение для управления задачами

Первый раунд MVP:

• Ключевые функции: создание задач, просмотр списка, отметка о выполнении
• Нефункциональные требования: управление участниками, контроль доступа, напоминания и уведомления
• Время доставки: 1 день

Второй раунд оптимизации (на основе обратной связи):

• Обратная связь пользователей: хотят добавлять теги к задачам
• Измените PRD, добавьте функцию "классификация тегами"
• Повторно выполните конвейер с этапа UI
• Время доставки: полдня

Третий раунд расширения (после успешной проверки):

• Добавьте функцию управления участниками
• Добавьте напоминания о сроках
• Добавьте функцию комментариев к задачам
• Время доставки: 2 дня

Контрольная точка ✅

Перед каждой итерацией проверьте:

• [ ] Соответствует ли новая функция ключевой цели
• [ ] Поддерживается ли новая функция спросом пользователей
• [ ] Значительно ли увеличивает новую функция сложность
• [ ] Есть ли четкие критерии приемки

---

Продвинутые техники

Техника 5: используйте разделение сеансов для экономии Token

Зачем

Длительное выполнение конвейера приводит к накоплению контекста и потреблению большого количества Token. Разделение сеансов на выполнение позволяет каждому этапу иметь чистый контекст, значительно снижая затраты на использование.

Как делать

В каждой контрольной точке выберите "Новый сеанс для продолжения":

# Выполните в новом окне командной строки
factory continue

Система автоматически:

1. Прочтет .factory/state.json для восстановления состояния
2. Запустит новое окно Claude Code
3. Продолжит со следующего этапа, ожидающего выполнения
4. Загрузит только входные файлы, необходимые для этого этапа

Сравнение:

Способ	Преимущества	Недостатки
Продолжение в том же сеансе	Просто, не нужно переключать окна	Контекст накапливается, большой расход Token
Продолжение в новом сеансе	Каждый этап имеет чистый контекст, экономия Token	Нужно переключать окна

Рекомендуемый подход

Для крупных проектов или ограниченного бюджета Token настоятельно рекомендуется использовать "Новый сеанс для продолжения".

Подробное описание см. в руководстве Оптимизация контекста.

---

Техника 6: обработка сбоев и повторов

Зачем

В процессе выполнения конвейера могут возникнуть сбои (недостаточный ввод, проблемы с правами доступа, ошибки кода и т. д.). Понимание того, как обрабатывать сбои, позволит вам быстрее восстановить прогресс.

Как делать

Лучшие практики обработки сбоев (ссылка на failure.policy.md:267-274):

1. Ранний сбой: раннее выявление проблем, избегание потерь времени на последующих этапах
2. Детальное логирование: запись достаточной контекстной информации для облегчения устранения проблем
3. Атомарные операции: вывод каждого этапа должен быть атомарным, удобным для отката
4. Сохранение доказательств: архивация продуктов сбоев перед повтором для облегчения сравнительного анализа
5. Постепенный повтор: при повторе предоставляйте более конкретные инструкции, а не просто повторяйте

Частые сценарии сбоев:

Тип сбоя	Симптомы	Решение
Отсутствие вывода	input/idea.md не существует	Повторите, проверьте путь записи
Разрастание объема	Количество функций > 7	Повторите, требуйте упростить до MVP
Техническая ошибка	Ошибка компиляции TypeScript	Проверьте определения типов, повторите
Проблема с правами доступа	Agent пишет в неавторизованный каталог	Проверьте матрицу границ возможностей

Чек-лист восстановления после сбоя:

• [ ] Причина сбоя определена четко
• [ ] Решение по исправлению реализовано
• [ ] Связанные конфигурации обновлены
• [ ] Перезапуск с этапа, где произошел сбой

Сбои — это нормально

Не бойтесь сбоев! AI App Factory спроектирован с совершенным механизмом обработки сбоев:

• Каждый этап позволяет автоматически повториться один раз
• Продукты сбоев автоматически архивируются в artifacts/_failed/
• Можно откатиться к последней успешной контрольной точке

При возникновении сбоев спокойно проанализируйте причину и обрабатывайте согласно стратегии сбоев.

---

Итоги курса

В этом курсе представлены шесть лучших практик AI App Factory:

1. Четкое описание продукта: подробное описание целевой аудитории, ключевых проблем, ключевых функций и ограничений
2. Внимательное подтверждение в контрольных точках: проверка качества вывода после завершения каждого этапа, избежание накопления ошибок
3. Использование нефункциональных требований для контроля объема: четкое перечисление функций, которые не будут выполняться, предотвращение разрастания объема
4. Пошаговая итерация: сначала проверка ключевых идей, затем постепенное расширение на основе обратной связи пользователей
5. Разделение сеансов для экономии Token: создание нового сеанса в каждой контрольной точке, снижение затрат на использование
6. Правильная обработка сбоев: использование механизма обработки сбоев для быстрого восстановления прогресса

Следование этим лучшим практикам сделает опыт использования AI App Factory более плавным, повысит качество генерируемых приложений и увеличит эффективность разработки в несколько раз.

---

Предварительный обзор следующего курса

В следующем курсе мы изучим Справочник команд CLI.

Вы узнаете:

• Все параметры и варианты команды factory init
• Как команда factory run начинает с указанного этапа
• Как команда factory continue создает новый сеанс для продолжения
• Как factory status и factory list просматривают информацию о проекте
• Как factory reset сбрасывает состояние проекта

---

Приложение: ссылки на исходный код

Нажмите для просмотра расположения исходного кода

Обновлено: 2026-01-29

Функция	Путь к файлу	Номер строки
Техники описания продукта	README.md	186-210
Механизм контрольных точек	agents/orchestrator.checkpoint.md	98-112
Контроль нефункциональных требований	README.md	199-203
Стратегия обработки сбоев	policies/failure.policy.md	267-274
Изоляция контекста	policies/context-isolation.md	10-42
Стандарты кода	policies/code-standards.md	Весь текст

Ключевые константы:

• MAX_RETRY_COUNT = 1: каждый этап по умолчанию позволяет автоматически повториться один раз

Ключевые правила:

• Количество функций Must Have ≤ 7 (принцип MVP)
• Количество страниц ≤ 3 (этап UI)
• Количество моделей данных ≤ 10 (этап Tech)
• Покрытие тестами > 60% (этап Validation)