Генерация руководства по развертыванию: полное руководство по этапу Preview

Что вы сможете делать после изучения

Завершив этот урок, вы сможете:

Понимать, как Preview Agent создает инструкции по запуску для сгенерированных приложений
Освоить методы генерации конфигураций Docker для развертывания
Узнать о роли конфигурации сборки Expo EAS
Научиться проектировать краткие демонстрационные процессы для MVP
Понимать лучшие практики конфигурации CI/CD и Git Hooks

Ваша текущая ситуация

Код уже сгенерирован и прошел валидацию, вы хотите быстро показать MVP команде или клиенту, но не знаете:

Какую документацию по запуску написать?
Как позволить другим быстро запустить и использовать приложение?
Какие функции демонстрировать? Каких подводных камней избегать?
Как развернуть в production? Docker или облачная платформа?
Как настроить непрерывную интеграцию и контроль качества кода?

Этап Preview решает именно эти проблемы — он автоматически генерирует полные инструкции по запуску и конфигурации развертывания.

Когда использовать этот подход

Этап Preview — это 7-й и последний этап пайплайна, следующий сразу после этапа Validation.

Типичные сценарии использования:

Сценарий	Описание
Демонстрация MVP	Необходимо показать приложение команде или клиенту, требуется подробное руководство по запуску
Командная работа	Новый участник присоединяется к проекту, нужно быстро освоить среду разработки
Production развертывание	Приложение готовится к запуску, нужны конфигурации Docker и CI/CD пайплайны
Публикация мобильного приложения	Нужно настроить Expo EAS для отправки в App Store и Google Play

Неприменимые сценарии:

Только просмотр кода без запуска (этап Preview обязателен)
Код не прошел этап Validation (сначала исправьте проблемы, затем выполняйте Preview)

🎒 Подготовка к началу

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

Этот урок предполагает, что вы уже:

Завершили этап Validation: файл artifacts/validation/report.md должен существовать и пройти проверку
Понимаете архитектуру приложения: знаете технологический стек backend и frontend, модели данных и API эндпоинты
Знакомы с базовыми концепциями: понимаете основы Docker, CI/CD, Git Hooks

Необходимые концепции:

Что такое Docker?

Docker — это платформа контейнеризации, которая позволяет упаковать приложение и его зависимости в переносимый контейнер.

Ключевые преимущества:

Согласованность окружений: среды разработки, тестирования и production полностью идентичны, исключая "работает на моей машине"
Быстрое развертывание: весь стек приложения запускается одной командой
Изоляция ресурсов: контейнеры не влияют друг на друга, повышая безопасность

Базовые концепции:

Dockerfile → Образ (Image) → Контейнер (Container)

Что такое CI/CD?

CI/CD (Continuous Integration/Continuous Deployment) — это практика автоматизации разработки программного обеспечения.

CI (Continuous Integration):

Автоматический запуск тестов и проверок при каждом коммите
Раннее обнаружение проблем в коде
Повышение качества кода

CD (Continuous Deployment):

Автоматическая сборка и развертывание приложения
Быстрое выведение новых функций в production
Снижение ошибок ручных операций

GitHub Actions — это платформа CI/CD от GitHub, которая определяет автоматизированные процессы через конфигурацию файлов .github/workflows/*.yml.

Что такое Git Hooks?

Git Hooks — это скрипты, автоматически выполняемые в определенные моменты операций Git.

Часто используемые Hooks:

pre-commit: запуск проверок кода и форматирования перед коммитом
commit-msg: валидация формата сообщения коммита
pre-push: запуск полных тестов перед push

Husky — популярный инструмент управления Git Hooks, упрощающий конфигурацию и поддержку Hooks.

Основная концепция

Суть этапа Preview — подготовка полной документации по использованию и развертыванию приложения, следуя принципу "локальный запуск в приоритете, прозрачность рисков".

Концептуальная модель

Preview Agent следует следующей концептуальной модели:

Принцип	Описание
Локальный запуск в приоритете	Обеспечить возможность локального запуска любым пользователем с базовой средой разработки
Готовность к развертыванию	Предоставить все конфигурационные файлы, необходимые для развертывания в production
Пользовательские сценарии	Спроектировать краткие демонстрационные процессы, демонстрирующие основную ценность
Прозрачность рисков	Проактивно перечислить существующие ограничения или известные проблемы текущей версии

Структура выходных файлов

Preview Agent генерирует два типа файлов:

Обязательные файлы (необходимы для каждого проекта):

Файл	Описание	Расположение
`README.md`	Основной документ с инструкциями по запуску	`artifacts/preview/README.md`
`Dockerfile`	Конфигурация Docker для backend	`artifacts/backend/Dockerfile`
`docker-compose.yml`	Docker Compose для среды разработки	`artifacts/backend/docker-compose.yml`
`.env.production.example`	Шаблон переменных окружения production	`artifacts/backend/.env.production.example`
`eas.json`	Конфигурация сборки Expo EAS	`artifacts/client/eas.json`

Рекомендуемые файлы (необходимы для production):

Файл	Описание	Расположение
`DEPLOYMENT.md`	Подробное руководство по развертыванию	`artifacts/preview/DEPLOYMENT.md`
`docker-compose.production.yml`	Docker Compose для production	корень проекта

Структура документа README

Файл artifacts/preview/README.md должен содержать следующие разделы:

markdown

# [Название проекта]

## Быстрый старт

### Требования к окружению
- Node.js >= 18
- npm >= 9
- [Другие зависимости]

### Запуск backend
[Установка зависимостей, настройка окружения, инициализация БД, запуск сервиса]

### Запуск frontend
[Установка зависимостей, настройка окружения, запуск dev-сервера]

### Проверка установки
[Команды тестирования, проверка работоспособности]

---

## Демонстрационный процесс

### Подготовка
### Шаги демонстрации
### Примечания при демонстрации

---

## Известные проблемы и ограничения

### Ограничения функциональности
### Технический долг
### Операции, которых следует избегать при демонстрации

---

## Часто задаваемые вопросы

Рабочий процесс Preview Agent

Preview Agent — это AI Agent, отвечающий за создание инструкций по запуску и конфигураций развертывания для сгенерированных приложений. Его рабочий процесс следующий:

Входные файлы

Preview Agent может читать только следующие файлы:

Файл	Описание	Расположение
Код backend	Проверенное backend-приложение	`artifacts/backend/`
Код frontend	Проверенное frontend-приложение	`artifacts/client/`

Выходные файлы

Preview Agent должен генерировать следующие файлы:

Файл	Описание	Расположение
`README.md`	Основной документ с инструкциями по запуску	`artifacts/preview/README.md`
`Dockerfile`	Конфигурация Docker для backend	`artifacts/backend/Dockerfile`
`docker-compose.yml`	Docker Compose для среды разработки	`artifacts/backend/docker-compose.yml`
`.env.production.example`	Шаблон переменных окружения production	`artifacts/backend/.env.production.example`
`eas.json`	Конфигурация сборки Expo EAS	`artifacts/client/eas.json`

Шаги выполнения

Обзор кода: анализ директорий backend и frontend, определение команд установки зависимостей и запуска
Написание README: создание четких инструкций по установке и запуску согласно руководству skills/preview/skill.md
Генерация конфигурации Docker: создание Dockerfile и docker-compose.yml
Настройка EAS: генерация конфигурации сборки Expo EAS (мобильное приложение)
Подготовка демонстрационного процесса: проектирование краткого сценария демонстрации
Перечисление известных проблем: проактивное перечисление дефектов или ограничений текущей версии

Следуйте за мной: запуск этапа Preview

Шаг 1: Подтвердите завершение этапа Validation

Почему

Preview Agent должен читать artifacts/backend/ и artifacts/client/, если код не прошел валидацию, сгенерированная документация может быть неточной.

Действие

bash

# Проверка отчета о валидации
cat artifacts/validation/report.md

Вы должны увидеть: отчет о валидации показывает, что все проверки backend и frontend пройдены.

✅ Backend Dependencies: OK
✅ Backend Type Check: OK
✅ Prisma Schema: OK
✅ Frontend Dependencies: OK
✅ Frontend Type Check: OK

Шаг 2: Запустите этап Preview

Почему

Используйте AI-ассистента для выполнения Preview Agent, автоматически генерируя инструкции по запуску и конфигурации развертывания.

Действие

bash

# Использование Claude Code для выполнения этапа preview
factory run preview

Вы должны увидеть:

✓ Текущий этап: preview
✓ Загрузка кода backend: artifacts/backend/
✓ Загрузка кода frontend: artifacts/client/
✓ Запуск Preview Agent

Preview Agent генерирует инструкции по запуску и конфигурации развертывания...

[AI-ассистент выполнит следующие действия]
1. Анализ структуры проекта backend и frontend
2. Генерация README.md (установка, запуск, демонстрационный процесс)
3. Создание Dockerfile и docker-compose.yml
4. Настройка файлов сборки Expo EAS
5. Подготовка шаблона переменных окружения production
6. Перечисление известных проблем и ограничений

Ожидание завершения Agent...

Шаг 3: Просмотр сгенерированного README

Почему

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

Действие

bash

# Просмотр руководства по запуску
cat artifacts/preview/README.md

Вы должны увидеть: полное руководство по запуску, содержащее следующие разделы

markdown

# AI-помощник по рекомендации ресторанов

## Быстрый старт

### Требования к окружению

- Node.js >= 18
- npm >= 9
- Docker (опционально, для контейнерного развертывания)

### Запуск backend

```bash
# Переход в директорию backend
cd artifacts/backend

# Установка зависимостей
npm install

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env, введя необходимые настройки

# Инициализация базы данных
npx prisma migrate dev

# (Опционально) Заполнение тестовыми данными
npm run db:seed

# Запуск dev-сервера
npm run dev

Backend работает на: http://localhost:3000 Проверка работоспособности: http://localhost:3000/health API документация: http://localhost:3000/api-docs

Запуск frontend

bash

# Переход в директорию frontend
cd artifacts/client

# Установка зависимостей
npm install

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте API_URL, указав адрес backend

# Запуск dev-сервера
npm start

iOS симулятор: нажмите i
Android симулятор: нажмите a
Веб-браузер: нажмите w

Проверка установки

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

bash

# Тесты backend
cd artifacts/backend && npm test

# Тесты frontend
cd artifacts/client && npm test

# Проверка работоспособности API
curl http://localhost:3000/health

Демонстрационный процесс

Подготовка

Убедитесь, что backend и frontend запущены
Очистка или сброс демонстрационных данных (опционально)

Шаги демонстрации

Представление сценария (30 секунд)
- Представьте целевую аудиторию: пользователи, ищущие новые рестораны
- Представьте основную проблему: трудности с выбором, не знают, что поесть
Демонстрация функций (3-5 минут)
- Шаг 1: Пользователь вводит предпочтения (кухня, вкус, бюджет)
- Шаг 2: AI рекомендует рестораны на основе предпочтений
- Шаг 3: Пользователь просматривает результаты и делает выбор
Технические особенности (опционально, 1 минута)
- Реальные AI-рекомендации (вызов OpenAI API)
- Адаптивный дизайн для мобильных устройств
- Локальное хранение данных в базе данных

Примечания при демонстрации

Убедитесь в нормальном подключении к сети (AI-рекомендации требуют вызова API)
Избегайте ввода слишком длинных или расплывчатых предпочтений (может привести к неточным рекомендациям)
Не изменяйте базу данных во время демонстрации (может повлиять на эффект)

Известные проблемы и ограничения

Ограничения функциональности

[ ] Временно не поддерживается регистрация и вход пользователей
[ ] Временно не поддерживаются избранное и история
[ ] AI-рекомендации поддерживают только текстовый ввод, временно не поддерживается голос или изображения

Технический долг

[ ] Обработка ошибок на frontend недостаточно совершенна
[ ] Необходима оптимизация логирования backend
[ ] Индексы базы данных не оптимизированы (на малых объемах данных не влияет)

Операции, которых следует избегать при демонстрации

Попытка регистрации или входа — может привести к прерыванию демонстрации
Ввод специальных символов или слишком длинного текста — может вызвать ошибку
Быстрые последовательные запросы — может вызвать ограничение API

Часто задаваемые вопросы

В: Что делать, если порт занят?

О: Измените переменную PORT в .env или завершите процесс, занимающий порт.

В: Что делать при ошибке подключения к базе данных?

О: Проверьте правильность настройки DATABASE_URL в .env, убедитесь, что база данных запущена.

В: Что делать, если AI-рекомендации не отвечают?

О: Проверьте действительность OPENAI_API_KEY в .env и нормальность подключения к сети.


### Шаг 4: Просмотр сгенерированной конфигурации Docker

**Почему**

Проверьте правильность конфигурации Docker, убедитесь, что контейнер может быть успешно собран и запущен.

**Действие**

```bash
# Просмотр Dockerfile
cat artifacts/backend/Dockerfile

# Просмотр docker-compose.yml
cat artifacts/backend/docker-compose.yml

Вы должны увидеть: конфигурационные файлы, соответствующие лучшим практикам Docker

Пример Dockerfile:

dockerfile

# Базовый образ
FROM node:20-alpine AS builder

WORKDIR /app

# Копирование файлов зависимостей
COPY package*.json ./
COPY prisma ./prisma/

# Установка зависимостей
RUN npm ci --only=production

# Генерация Prisma Client
RUN npx prisma generate

# Копирование исходного кода
COPY . .

# Сборка
RUN npm run build

# Production образ
FROM node:20-alpine AS production

WORKDIR /app

# Установка production-зависимостей
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/package*.json ./

# Открытие порта
EXPOSE 3000

# Проверка работоспособности
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Команда запуска
CMD ["npm", "start"]

Пример docker-compose.yml:

yaml

version: '3.8'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=file:./dev.db
    volumes:
      - .:/app
      - /app/node_modules
    command: npm run dev
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

Шаг 5: Просмотр конфигурации EAS

Почему

Проверьте правильность конфигурации Expo EAS, убедитесь, что мобильное приложение может быть успешно собрано и опубликовано.

Действие

bash

# Просмотр конфигурации EAS
cat artifacts/client/eas.json

Вы должны увидеть: конфигурацию, содержащую три окружения: development, preview, production

json

{
  "cli": {
    "version": ">= 5.0.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "env": {
        "EXPO_PUBLIC_API_URL": "http://localhost:3000"
      }
    },
    "preview": {
      "distribution": "internal",
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api-staging.your-domain.com"
      }
    },
    "production": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.your-domain.com"
      }
    }
  },
  "submit": {
    "production": {}
  }
}

Шаг 6: Проверка условий выхода

Почему

Sisyphus проверяет, соответствует ли Preview Agent условиям выхода, если нет — требуется повторное выполнение.

Контрольный список

Проверка	Описание	Пройдено/Не пройдено
README содержит шаги установки	Четко перечислены команды установки зависимостей для backend и frontend	[ ]
README содержит команды запуска	Предоставлены отдельные команды для запуска backend и frontend	[ ]
README содержит адреса доступа и демонстрационный процесс	Указаны адреса и порты, используемые при демонстрации	[ ]
Конфигурация Docker может быть собрана	Dockerfile и docker-compose.yml без синтаксических ошибок	[ ]
Шаблон переменных окружения production полный	.env.production.example содержит все необходимые настройки	[ ]

Если не пройдено:

bash

# Повторный запуск этапа Preview
factory run preview

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

Подтвердите, что вы завершили:

[ ] Этап Preview успешно выполнен
[ ] Файл artifacts/preview/README.md существует и содержит полный контент
[ ] Файл artifacts/backend/Dockerfile существует и может быть собран
[ ] Файл artifacts/backend/docker-compose.yml существует
[ ] Файл artifacts/backend/.env.production.example существует
[ ] Файл artifacts/client/eas.json существует (мобильное приложение)
[ ] README содержит четкие шаги установки и команды запуска
[ ] README содержит демонстрационный процесс и известные проблемы

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

⚠️ Ловушка 1: Игнорирование шагов установки зависимостей

Проблема: В README написано только "запустить сервис", без объяснения, как установить зависимости.

Симптом: Новый участник следует README, при запуске npm run dev получает ошибку "модуль не найден".

Решение: Preview Agent ограничивает "README должен содержать шаги установки", обеспечивая четкие команды на каждом шаге.

Правильный пример:

bash

# ❌ Неправильно — отсутствуют шаги установки
npm run dev

# ✅ Правильно — содержит полные шаги
npm install
npm run dev

⚠️ Ловушка 2: Использование тега latest в конфигурации Docker

Проблема: В Dockerfile используется FROM node:latest или FROM node:alpine.

Симптом: При каждой сборке может использоваться разная версия Node.js, что приводит к несогласованности окружений.

Решение: Preview Agent ограничивает "НИКОГДА не используйте latest в качестве тега образа Docker, используйте конкретный номер версии".

Правильный пример:

dockerfile

# ❌ Неправильно — использование latest
FROM node:latest

# ❌ Неправильно — не указана конкретная версия
FROM node:alpine

# ✅ Правильно — использование конкретной версии
FROM node:20-alpine

⚠️ Ловушка 3: Хардкод переменных окружения

Проблема: В конфигурации Docker или EAS жестко закодирована конфиденциальная информация (пароли, API Key и т.д.).

Симптом: Конфиденциальная информация попадает в репозиторий кода, что создает риски безопасности.

Решение: Preview Agent ограничивает "НИКОГДА не хардкодите конфиденциальную информацию в конфигурациях развертывания", используйте шаблоны переменных окружения.

Правильный пример:

yaml

# ❌ Неправильно — хардкод пароля базы данных
DATABASE_URL=postgresql://user:password123@host:5432/database

# ✅ Правильно — использование переменных окружения
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}

⚠️ Ловушка 4: Скрытие известных проблем

Проблема: В README не перечислены известные проблемы и ограничения, преувеличиваются возможности продукта.

Симптом: Во время демонстрации возникают неожиданные ситуации, что приводит к неловкости и снижению доверия.

Решение: Preview Agent ограничивает "НИКОГДА не преувеличивайте функции или скрывайте дефекты", проактивно перечисляйте проблемы текущей версии.

Правильный пример:

markdown

## Известные проблемы и ограничения

### Ограничения функциональности
- [ ] Временно не поддерживается регистрация и вход пользователей
- [ ] AI-рекомендации могут быть неточны (зависит от результатов, возвращаемых OpenAI API)

⚠️ Ловушка 5: Слишком сложный демонстрационный процесс

Проблема: Демонстрационный процесс содержит 10+ шагов, требует более 10 минут.

Симптом: Демонстратор не помнит шаги, аудитория теряет терпение.

Решение: Preview Agent ограничивает "демонстрационный процесс должен занимать 3-5 минут, не более 5 шагов".

Правильный пример:

markdown

### Шаги демонстрации

1. **Представление сценария** (30 секунд)
   - Представьте целевую аудиторию и основную проблему

2. **Демонстрация функций** (3-5 минут)
   - Шаг 1: Пользователь вводит предпочтения
   - Шаг 2: AI рекомендует на основе предпочтений
   - Шаг 3: Пользователь просматривает результаты

3. **Технические особенности** (опционально, 1 минута)
   - Реальные AI-рекомендации
   - Адаптивный дизайн для мобильных устройств

Шаблон конфигурации CI/CD

Preview Agent может ссылаться на templates/cicd-github-actions.md для генерации конфигурации CI/CD, включая:

CI пайплайн для backend

yaml

name: Backend CI

on:
  push:
    branches: [main, develop]
    paths:
      - 'backend/**'
      - '.github/workflows/backend-ci.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'backend/**'

jobs:
  test:
    name: Test & Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: 'npm'
          cache-dependency-path: backend/package-lock.json

      - name: Install dependencies
        working-directory: backend
        run: npm ci

      - name: Run linter
        working-directory: backend
        run: npm run lint

      - name: Run type check
        working-directory: backend
        run: npx tsc --noEmit

      - name: Validate Prisma schema
        working-directory: backend
        run: npx prisma validate

      - name: Generate Prisma Client
        working-directory: backend
        run: npx prisma generate

      - name: Run tests
        working-directory: backend
        run: npm test

CI пайплайн для frontend

yaml

name: Frontend CI

on:
  push:
    branches: [main, develop]
    paths:
      - 'client/**'
      - '.github/workflows/frontend-ci.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'client/**'

jobs:
  test:
    name: Test & Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: 'npm'
          cache-dependency-path: client/package-lock.json

      - name: Install dependencies
        working-directory: client
        run: npm ci

      - name: Run linter
        working-directory: client
        run: npm run lint

      - name: Run type check
        working-directory: client
        run: npx tsc --noEmit

      - name: Run tests
        working-directory: client
        run: npm test -- --coverage

Шаблон конфигурации Git Hooks

Preview Agent может ссылаться на templates/git-hooks-husky.md для генерации конфигурации Git Hooks, включая:

pre-commit Hook

Запуск проверок кода и форматирования перед коммитом.

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

echo "🔍 Запуск pre-commit проверок..."

# Запуск lint-staged
npx lint-staged

# Проверка типов TypeScript
echo "📝 Проверка типов..."
npm run type-check

echo "✅ Pre-commit проверки пройдены!"

commit-msg Hook

Валидация формата сообщения коммита.

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

echo "📋 Валидация сообщения коммита..."

npx --no -- commitlint --edit "$1"

echo "✅ Сообщение коммита валидно!"

Резюме урока

Этап Preview — это последнее звено пайплайна, отвечающее за подготовку полной документации по использованию и развертыванию для сгенерированного приложения. Он автоматически генерирует:

Руководство по запуску: четкие шаги установки, команды запуска и демонстрационный процесс
Конфигурацию Docker: Dockerfile и docker-compose.yml, поддержка контейнерного развертывания
Конфигурацию EAS: конфигурацию сборки Expo EAS, поддержку публикации мобильных приложений
Конфигурацию CI/CD: пайплайны GitHub Actions, поддержку непрерывной интеграции и развертывания
Git Hooks: конфигурацию Husky, поддержку проверок перед коммитом

Ключевые принципы:

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

После завершения этапа Preview вы получите:

✅ Полное руководство по запуску (README.md)
✅ Конфигурацию контейнеризации Docker (Dockerfile, docker-compose.yml)
✅ Шаблон переменных окружения production (.env.production.example)
✅ Конфигурацию сборки Expo EAS (eas.json)
✅ Опциональное подробное руководство по развертыванию (DEPLOYMENT.md)

Анонс следующего урока

Поздравляем! Вы завершили все 7 этапов AI App Factory.
Если вы хотите глубже понять механизм координации пайплайна, можете изучить Подробное руководство по планировщику Sisyphus.
Вы узнаете:
Как планировщик координирует выполнение пайплайна
Механизмы проверки прав и обработки нарушений
Стратегии обработки ошибок и отката
Оптимизацию контекста и техники экономии токенов

Приложение: Справка по исходному коду

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

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

Функция	Путь к файлу	Номер строки
Определение Preview Agent	`source/hyz1992/agent-app-factory/agents/preview.agent.md`	1-33
Руководство по навыкам Preview	`source/hyz1992/agent-app-factory/skills/preview/skill.md`	1-583
Конфигурация Pipeline	`source/hyz1992/agent-app-factory/pipeline.yaml`	98-111
Шаблон конфигурации CI/CD	`source/hyz1992/agent-app-factory/templates/cicd-github-actions.md`	1-617
Шаблон конфигурации Git Hooks	`source/hyz1992/agent-app-factory/templates/git-hooks-husky.md`	1-530

Ключевые ограничения:

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

Обязательные генерируемые файлы:

artifacts/preview/README.md — основной документ с инструкциями по запуску
artifacts/backend/Dockerfile — конфигурация Docker для backend
artifacts/backend/docker-compose.yml — Docker Compose для среды разработки
artifacts/backend/.env.production.example — шаблон переменных окружения production
artifacts/client/eas.json — конфигурация сборки Expo EAS

НЕ делайте (НИКОГДА):

НИКОГДА не игнорируйте шаги установки зависимостей или конфигурации, иначе запуск или развертывание, скорее всего, завершатся ошибкой
НИКОГДА не предоставляйте дополнительные инструкции или маркетинговый текст, не связанные с приложением
НИКОГДА не преувеличивайте возможности продукта, скрывайте дефекты или ограничения
НИКОГДА не хардкодите конфиденциальную информацию (пароли, API Key и т.д.) в конфигурациях развертывания
НИКОГДА не игнорируйте настройку проверки работоспособности, это критически важно для мониторинга production
НИКОГДА не пропускайте инструкции по миграции базы данных, это ключевой шаг для запуска
НИКОГДА не используйте latest в качестве тега образа Docker, используйте конкретный номер версии
НИКОГДА не используйте SQLite в production (следует мигрировать на PostgreSQL)

Генерация руководства по развертыванию: полное руководство по этапу Preview ​

Что вы сможете делать после изучения ​

Ваша текущая ситуация ​

Когда использовать этот подход ​

🎒 Подготовка к началу ​

Основная концепция ​

Концептуальная модель ​

Структура выходных файлов ​

Структура документа README ​

Рабочий процесс Preview Agent ​

Входные файлы ​

Выходные файлы ​

Шаги выполнения ​

Следуйте за мной: запуск этапа Preview ​

Шаг 1: Подтвердите завершение этапа Validation ​

Шаг 2: Запустите этап Preview ​

Шаг 3: Просмотр сгенерированного README ​

Запуск frontend ​

Проверка установки ​

Демонстрационный процесс ​

Подготовка ​

Шаги демонстрации ​

Примечания при демонстрации ​

Известные проблемы и ограничения ​

Ограничения функциональности ​

Технический долг ​

Операции, которых следует избегать при демонстрации ​

Часто задаваемые вопросы ​

В: Что делать, если порт занят? ​

В: Что делать при ошибке подключения к базе данных? ​

В: Что делать, если AI-рекомендации не отвечают? ​

Шаг 5: Просмотр конфигурации EAS ​

Шаг 6: Проверка условий выхода ​

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

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

⚠️ Ловушка 1: Игнорирование шагов установки зависимостей ​

⚠️ Ловушка 2: Использование тега latest в конфигурации Docker ​

⚠️ Ловушка 3: Хардкод переменных окружения ​

⚠️ Ловушка 4: Скрытие известных проблем ​

⚠️ Ловушка 5: Слишком сложный демонстрационный процесс ​

Шаблон конфигурации CI/CD ​

CI пайплайн для backend ​

CI пайплайн для frontend ​

Шаблон конфигурации Git Hooks ​

pre-commit Hook ​

commit-msg Hook ​

Резюме урока ​

Анонс следующего урока ​

Приложение: Справка по исходному коду ​

Генерация руководства по развертыванию: полное руководство по этапу Preview

Что вы сможете делать после изучения

Ваша текущая ситуация

Когда использовать этот подход

🎒 Подготовка к началу

Основная концепция

Концептуальная модель

Структура выходных файлов

Структура документа README

Рабочий процесс Preview Agent

Входные файлы

Выходные файлы

Шаги выполнения

Следуйте за мной: запуск этапа Preview

Шаг 1: Подтвердите завершение этапа Validation

Шаг 2: Запустите этап Preview

Шаг 3: Просмотр сгенерированного README

Запуск frontend

Проверка установки

Демонстрационный процесс

Подготовка

Шаги демонстрации

Примечания при демонстрации

Известные проблемы и ограничения

Ограничения функциональности

Технический долг

Операции, которых следует избегать при демонстрации

Часто задаваемые вопросы

В: Что делать, если порт занят?

В: Что делать при ошибке подключения к базе данных?

В: Что делать, если AI-рекомендации не отвечают?

Шаг 5: Просмотр конфигурации EAS

Шаг 6: Проверка условий выхода

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

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

⚠️ Ловушка 1: Игнорирование шагов установки зависимостей

⚠️ Ловушка 2: Использование тега latest в конфигурации Docker

⚠️ Ловушка 3: Хардкод переменных окружения

⚠️ Ловушка 4: Скрытие известных проблем

⚠️ Ловушка 5: Слишком сложный демонстрационный процесс

Шаблон конфигурации CI/CD

CI пайплайн для backend

CI пайплайн для frontend

Шаблон конфигурации Git Hooks

pre-commit Hook

commit-msg Hook

Резюме урока

Анонс следующего урока

Приложение: Справка по исходному коду