Инициализация проекта Factory: настройка с нуля за 3 минуты

Чему вы научитесь

• Инициализировать проект Factory в любой пустой директории
• Понимать структуру создаваемой директории .factory/
• Настраивать параметры проекта (технологический стек, UI-предпочтения, ограничения MVP)
• Автоматически запускать AI-ассистента и начинать работу конвейера

С чем вы сейчас сталкиваетесь

Хотите попробовать AI App Factory, но не знаете, с чего начать? Смотрите на пустую папку и не понимаете, какие файлы создавать? Или у вас уже есть код, и вы не уверены, можно ли его использовать? Не волнуйтесь — команда factory init всё сделает за вас.

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

• При первом использовании AI App Factory
• При старте нового продукта
• Когда нужна чистая среда для проекта Factory

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

Предварительная проверка

Перед началом убедитесь, что:

• ✅ Выполнена Установка и настройка
• ✅ Установлен AI-ассистент (Claude Code или OpenCode)
• ✅ Есть пустая директория или директория, содержащая только файлы конфигурации Git/редактора

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

Ключевой принцип команды factory init — автономность:

1. Копирование всех необходимых файлов (agents, skills, policies, pipeline.yaml) в директорию .factory/ проекта
2. Генерация файлов конфигурации проекта (config.yaml и state.json)
3. Настройка прав доступа Claude Code (.claude/settings.local.json)
4. Автоматическая установка необходимых плагинов (superpowers, ui-ux-pro-max)
5. Запуск AI-ассистента и начало работы конвейера

Таким образом, каждый проект Factory содержит всё необходимое для работы и не зависит от глобальной установки.

Почему автономность?

Преимущества автономного дизайна:

• Изоляция версий: разные проекты могут использовать разные версии конфигурации Factory
• Переносимость: директорию .factory/ можно закоммитить в Git, и члены команды смогут её использовать
• Безопасность: настройки прав действуют только в директории проекта и не влияют на другие проекты

Пошаговое руководство

Шаг 1: Перейдите в директорию проекта

Зачем: нужна чистая рабочая директория для размещения создаваемого приложения.

# Создание новой директории
mkdir my-app && cd my-app

# Или переход в существующую пустую директорию
cd /path/to/your/project

Ожидаемый результат: директория пуста или содержит только разрешённые файлы: .git/, .gitignore, README.md и т.п.

Шаг 2: Выполните команду инициализации

Зачем: factory init создаст директорию .factory/ и скопирует все необходимые файлы.

factory init

Ожидаемый результат:

Agent Factory - Project Initialization

✓ Factory project initialized!

Project structure created:
  .factory/
    agents/
    skills/
    templates/
    policies/
    pipeline.yaml
    config.yaml
    state.json

Checking and installing required Claude plugins...
Installing superpowers plugin... ✓
Installing ui-ux-pro-max-skill plugin... ✓
Plugins installed!

Starting Claude Code...
✓ Claude Code is starting...
  (Please wait for window to open)

Шаг 3: Настройка с помощью опциональных параметров (необязательно)

Зачем: если у вас есть определённые предпочтения по технологическому стеку, их можно указать при инициализации.

factory init --name "Моё приложение для учёта финансов" --description "Помогает молодым людям отслеживать ежедневные расходы"

Эти параметры записываются в config.yaml и влияют на генерируемый код.

Шаг 4: Проверьте созданную структуру директорий

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

ls -la

Ожидаемый результат:

.claude/              # Директория конфигурации Claude Code
  └── settings.local.json   # Настройки прав доступа

.factory/            # Основная директория Factory
  ├── agents/          # Файлы определения агентов
  ├── skills/          # Модули навыков
  ├── templates/       # Шаблоны конфигурации
  ├── policies/        # Политики и правила
  ├── pipeline.yaml    # Определение конвейера
  ├── config.yaml      # Конфигурация проекта
  └── state.json      # Состояние конвейера

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

Убедитесь, что созданы следующие файлы:

• [ ] .factory/pipeline.yaml существует
• [ ] .factory/config.yaml существует
• [ ] .factory/state.json существует
• [ ] .claude/settings.local.json существует
• [ ] Директория .factory/agents/ содержит 7 файлов .agent.md
• [ ] Директория .factory/skills/ содержит 6 модулей навыков
• [ ] Директория .factory/policies/ содержит 7 документов политик

Подробное описание создаваемых файлов

config.yaml: конфигурация проекта

config.yaml содержит базовую информацию о проекте и состояние конвейера:

project:
  name: my-app                  # Название проекта
  description: ""                # Описание проекта
  created_at: "2026-01-30T00:00:00.000Z"  # Время создания
  updated_at: "2026-01-30T00:00:00.000Z"  # Время обновления

pipeline:
  current_stage: null           # Текущий этап выполнения
  completed_stages: []          # Список завершённых этапов
  last_checkpoint: null         # Последняя контрольная точка

settings:
  auto_save: true               # Автосохранение
  backup_on_error: true        # Резервное копирование при ошибке

Изменение конфигурации

Вы можете редактировать config.yaml напрямую после выполнения factory init, и изменения автоматически применятся при запуске конвейера. Повторная инициализация не требуется.

state.json: состояние конвейера

state.json отслеживает прогресс выполнения конвейера:

{
  "version": 1,
  "status": "idle",
  "current_stage": null,
  "completed_stages": [],
  "started_at": null,
  "last_updated": "2026-01-30T00:00:00.000Z"
}

• status: текущее состояние (при инициализации — idle, во время работы динамически меняется на running, waiting_for_confirmation, paused, failed)
• current_stage: выполняемый этап
• completed_stages: список завершённых этапов

Описание состояний

Конвейер работает как конечный автомат, при инициализации состояние — idle. Другие значения устанавливаются динамически в процессе работы:

• idle: ожидание запуска
• running: выполнение определённого этапа
• waiting_for_confirmation: ожидание ручного подтверждения для продолжения, повтора или паузы
• paused: ручная пауза
• failed: обнаружен сбой, требуется ручное вмешательство

Не редактируйте вручную

state.json автоматически поддерживается конвейером, ручное редактирование может привести к несогласованности состояния. Для сброса используйте команду factory reset.

pipeline.yaml: определение конвейера

Определяет порядок выполнения и зависимости 7 этапов:

stages:
  - id: bootstrap
    description: Инициализация идеи проекта
    agent: agents/bootstrap.agent.md
    inputs: []
    outputs: [input/idea.md]

  - id: prd
    description: Генерация документа требований к продукту
    agent: agents/prd.agent.md
    inputs: [input/idea.md]
    outputs: [artifacts/prd/prd.md]

  # ... остальные этапы

Порядок конвейера

Конвейер выполняется строго последовательно, этапы нельзя пропускать. После завершения каждого этапа происходит пауза для подтверждения.

.claude/settings.local.json: настройки прав доступа

Автоматически генерируемая конфигурация прав Claude Code включает:

• Права на файловые операции: Read/Write/Glob/Edit для директории проекта
• Права на Bash-команды: git, npm, npx, docker и др.
• Права на Skills: superpowers, ui-ux-pro-max и другие необходимые навыки
• Права на WebFetch: доступ к определённым доменам (GitHub, NPM и др.)

Безопасность

Настройки прав применяются только к текущей директории проекта и не влияют на другие части системы. Это один из принципов безопасности Factory.

Типичные проблемы

Ошибка: директория не пуста

Сообщение об ошибке:

Cannot initialize: directory is not empty.
Factory init requires an empty directory or one with only git/config files.

Причина: в директории есть несовместимые файлы или папки (например, artifacts/, input/ и т.п.)

Решение:

1. Удалите конфликтующие файлы:

   rm -rf artifacts/ input/

2. Или используйте новую директорию:

   mkdir my-app-new && cd my-app-new
   factory init

Ошибка: уже является проектом Factory

Сообщение об ошибке:

This directory is already a Factory project:
  Name: my-app
  Created: 2026-01-29T13:00:00.000Z

To reset project, use: factory reset

Причина: директория .factory/ уже существует

Решение:

# Сброс состояния проекта (артефакты сохраняются)
factory reset

# Или полная повторная инициализация (удаление всего содержимого)
rm -rf .factory/
factory init

Ошибка: Claude Code не установлен

Сообщение об ошибке:

Claude CLI not found - skipping plugin installation
Install Claude Code to enable plugins: https://claude.ai/code

Причина: не установлен Claude Code CLI

Решение:

1. Установите Claude Code: https://claude.ai/code
2. Или запустите конвейер вручную (см. Быстрый старт)

Ошибка установки плагина

Сообщение об ошибке:

Installing superpowers plugin... (failed)
Note: superpowers plugin installation failed
The bootstrap stage may prompt you to install it manually

Причина: проблемы с сетью или конфигурацией Claude Code

Решение:

Проигнорируйте предупреждение и продолжайте работу. На этапе Bootstrap вам будет предложено установить плагин вручную.

Итоги урока

В этом уроке вы научились:

1. ✅ Использовать команду factory init для инициализации проекта Factory
2. ✅ Понимать структуру создаваемой директории .factory/
3. ✅ Разбираться в параметрах конфигурации config.yaml
4. ✅ Понимать управление состоянием в state.json
5. ✅ Знать настройки прав доступа в .claude/settings.local.json

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

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

В следующем уроке мы изучим Обзор конвейера.

Вы узнаете:

• Порядок и зависимости 7 этапов
• Входные и выходные данные каждого этапа
• Как механизм контрольных точек обеспечивает качество
• Обработку ошибок и стратегии повторных попыток

---

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

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

Дата обновления: 2026-01-29

Функция	Путь к файлу	Строки
Основная логика init	cli/commands/init.js	220-456
Проверка безопасности директории	cli/commands/init.js	32-53
Генерация конфигурации	cli/commands/init.js	58-76
Настройка прав Claude	cli/utils/claude-settings.js	41-248
Определение конвейера	pipeline.yaml	7-111
Шаблон конфигурации проекта	config.yaml	1-102

Ключевые функции:

• isFactoryProject(): проверка, является ли директория проектом Factory (строки 22-26)
• isDirectorySafeToInit(): проверка безопасности инициализации директории (строки 32-53)
• generateConfig(): генерация конфигурации проекта (строки 58-76)
• generateClaudeSettings(): генерация настроек прав Claude Code (строки 256-275)