Подробное руководство по структуре директорий: полное руководство по проекту Factory

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

✅ Познакомитесь с полной структурой директорий проекта Factory
✅ Узнаете назначение каждой директории и файла
✅ Поймёте, как хранятся артефакты (artifacts)
✅ Освоите роль конфигурационных файлов и методы их изменения

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

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

Проект Factory имеет две формы:

Форма 1: Репозиторий исходного кода (клонированный с GitHub) Форма 2: Проект после инициализации (сгенерированный командой factory init)

Это руководство фокусируется на Форме 2 — структуре проекта Factory после инициализации, так как это рабочая директория вашей повседневной работы.

Полная структура проекта Factory

my-app/                          # Корневая директория вашего проекта Factory
├── .factory/                    # Основная конфигурационная директория Factory (не изменять вручную)
│   ├── pipeline.yaml             # Определение конвейера (7 этапов)
│   ├── config.yaml               # Конфигурационный файл проекта (стек технологий, ограничения MVP и т.д.)
│   ├── state.json                # Состояние выполнения конвейера (текущий этап, завершённые этапы)
│   ├── agents/                   # Определения агентов (описания задач ИИ-ассистентов)
│   ├── skills/                   # Модули навыков (многократно используемые знания)
│   ├── policies/                 # Документы политик (права доступа, обработка ошибок, стандарты кода)
│   └── templates/                # Шаблоны конфигураций (CI/CD, Git Hooks)
├── .claude/                      # Конфигурационная директория Claude Code (автоматически генерируется)
│   └── settings.local.json       # Конфигурация прав Claude Code
├── input/                        # Директория пользовательского ввода
│   └── idea.md                   # Структурированная идея продукта (генерируется Bootstrap)
└── artifacts/                    # Директория артефактов конвейера (вывод всех 7 этапов)
    ├── prd/                      # Артефакты PRD
    │   └── prd.md                # Документ требований к продукту
    ├── ui/                       # Артефакты UI
    │   ├── ui.schema.yaml        # Определение структуры UI
    │   └── preview.web/          # Предпросмотр HTML-прототипа
    │       └── index.html
    ├── tech/                     # Артефакты Tech
    │   └── tech.md               # Документ архитектуры технологий
    ├── backend/                  # Код бэкенда (Express + Prisma)
    │   ├── src/                  # Исходный код
    │   ├── prisma/               # Конфигурация базы данных
    │   │   ├── schema.prisma     # Модель данных Prisma
    │   │   └── seed.ts           # Начальные данные
    │   ├── tests/                # Тесты
    │   ├── docs/                 # Документация API
    │   ├── package.json
    │   ├── tsconfig.json
    │   └── README.md
    ├── client/                   # Код фронтенда (React Native)
    │   ├── src/                  # Исходный код
    │   ├── __tests__/            # Тесты
    │   ├── app.json
    │   ├── package.json
    │   └── README.md
    ├── validation/               # Артефакты валидации
    │   └── report.md             # Отчёт о качестве кода
    ├── preview/                  # Артефакты Preview
    │   ├── README.md             # Руководство по развёртыванию и запуску
    │   └── GETTING_STARTED.md    # Руководство по быстрому запуску
    ├── _failed/                  # Архив артефактов ошибок
    │   └── <stage-id>/           # Артефакты этапа с ошибкой
    └── _untrusted/               # Изоляция несанкционированных артефактов
        └── <stage-id>/           # Файлы, записанные агентом без разрешения

Подробное описание директории .factory/

Директория .factory/ — это ядро проекта Factory, содержащее определение конвейера, конфигурации агентов и документы политик. Эта директория создаётся автоматически командой factory init, обычно не требует ручного изменения.

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

Назначение: определяет порядок выполнения 7 этапов, входы/выходы и условия завершения.

Основное содержание:

7 этапов: bootstrap, prd, ui, tech, code, validation, preview
Агент, входные и выходные файлы для каждого этапа
Условия завершения (exit_criteria): стандарты проверки завершения этапа

Пример:

yaml

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

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

config.yaml — конфигурационный файл проекта

Назначение: настройка технологического стека, ограничений MVP, предпочтений UI и других глобальных настроек.

Основные параметры конфигурации:

preferences: предпочтения технологического стека (язык бэкенда, база данных, фреймворк фронтенда и т.д.)
mvp_constraints: контроль рамок MVP (максимальное количество страниц, максимальное количество моделей и т.д.)
ui_preferences: предпочтения дизайна UI (направление эстетики, цветовая схема)
pipeline: поведение конвейера (режим контрольных точек, обработка ошибок)
advanced: расширенные опции (таймаут агента, контроль параллелизма)

Пример:

yaml

preferences:
  backend:
    language: typescript
    framework: express
    database: sqlite
  mvp_constraints:
    max_pages: 3
    enable_auth: false

Когда изменять: когда вы хотите изменить технологический стек или рамки MVP.

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

Назначение: записывает состояние выполнения конвейера, поддерживает возобновление работы с точки прерывания.

Основное содержание:

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

Когда изменять: обновляется автоматически, не изменяйте вручную.

agents/ — директория определений агентов

Назначение: определение обязанностей, входов/выходов и ограничений выполнения каждого агента.

Список файлов:

Файл	Описание
`orchestrator.checkpoint.md`	Основное определение оркестратора (координация конвейера)
`orchestrator-implementation.md`	Руководство по реализации оркестратора (справочник для разработки)
`bootstrap.agent.md`	Агент Bootstrap (структурирование идеи продукта)
`prd.agent.md`	Агент PRD (генерация документа требований)
`ui.agent.md`	Агент UI (проектирование UI-прототипа)
`tech.agent.md`	Агент Tech (проектирование технической архитектуры)
`code.agent.md`	Агент Code (генерация кода)
`validation.agent.md`	Агент Validation (проверка качества кода)
`preview.agent.md`	Агент Preview (генерация руководства по развёртыванию)

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

skills/ — директория модулей навыков

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

Структура директории:

skills/
├── bootstrap/skill.md         # Структурирование идеи продукта
├── prd/skill.md               # Генерация PRD
├── ui/skill.md                # Проектирование UI
├── tech/skill.md              # Техническая архитектура + миграция базы данных
├── code/skill.md              # Генерация кода + тестирование + логирование
│   └── references/            # Шаблоны для генерации кода
│       ├── backend-template.md   # Производственный шаблон бэкенда
│       └── frontend-template.md  # Производственный шаблон фронтенда
└── preview/skill.md           # Конфигурация развёртывания + руководство по быстрому запуску

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

policies/ — директория документов политик

Назначение: определение политик, таких как разрешения, обработка ошибок, стандарты кода и т.д.

Список файлов:

Файл	Описание
`capability.matrix.md`	Матрица границ возможностей (права на чтение/запись агентов)
`failure.policy.md`	Политика обработки ошибок (повторные попытки, откат, ручное вмешательство)
`context-isolation.md`	Политика изоляции контекста (экономия токенов)
`error-codes.md`	Спецификация унифицированных кодов ошибок
`code-standards.md`	Стандарты кода (стиль кодирования, структура файлов)
`pr-template.md`	Шаблон PR и контрольный список code review
`changelog.md`	Спецификация генерации Changelog

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

templates/ — директория шаблонов конфигураций

Назначение: шаблоны конфигураций, такие как CI/CD, Git Hooks и т.д.

Список файлов:

Файл	Описание
`cicd-github-actions.md`	Конфигурация CI/CD (GitHub Actions)
`git-hooks-husky.md`	Конфигурация Git Hooks (Husky)

Когда изменять: обычно не требует изменения, только если вы хотите настроить процесс CI/CD.

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

1. Могу ли я вручную изменять файлы в директории .factory/?

Осторожно при изменении

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

Если вам нужно настроить конфигурацию, рекомендуется в первую очередь изменить файл config.yaml.

2. Могу ли я вручную изменять файлы в директории artifacts/?

Можно. Файлы в директории artifacts/ — это выходные артефакты конвейера, вы можете:

Изменять input/idea.md или artifacts/prd/prd.md для корректировки направления продукта
Вручную исправлять код в artifacts/backend/ или artifacts/client/
Корректировать стили в artifacts/ui/preview.web/index.html

После изменений можно перезапустить конвейер с соответствующего этапа.

3. Как обрабатывать файлы в директориях _failed/ и _untrusted/?

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

4. Что делать, если файл state.json повреждён?

Если файл state.json повреждён, вы можете сбросить его, выполнив следующую команду:

bash

factory reset

5. Как проверить текущее состояние конвейера?

Выполните следующую команду для просмотра текущего состояния:

bash

factory status

Резюме урока

В этом уроке мы подробно разобрали полную структуру директорий проекта Factory:

✅ .factory/: основная конфигурация Factory (pipeline, agents, skills, policies)
✅ .claude/: конфигурация прав Claude Code
✅ input/: пользовательский ввод (idea.md)
✅ artifacts/: артефакты конвейера (prd, ui, tech, backend, client, validation, preview)
✅ _failed/ и _untrusted/: архивы артефактов ошибок и изоляции несанкционированных артефактов

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

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

В следующем уроке мы изучим стандарты кода.
Вы узнаете:
Стандарты кодирования TypeScript
Структуру файлов и соглашения об именовании
Требования к комментариям и документации
Спецификацию сообщений Git commit

Начало работы

Платформы и интеграции

Продвинутый: Конвейер

FAQ

Приложение

Журнал изменений

Подробное руководство по структуре директорий: полное руководство по проекту Factory

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

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

Полная структура проекта Factory

Подробное описание директории .factory/

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

config.yaml — конфигурационный файл проекта

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

agents/ — директория определений агентов

skills/ — директория модулей навыков

policies/ — директория документов политик

templates/ — директория шаблонов конфигураций

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

1. Могу ли я вручную изменять файлы в директории .factory/?

2. Могу ли я вручную изменять файлы в директории artifacts/?

3. Как обрабатывать файлы в директориях _failed/ и _untrusted/?

4. Что делать, если файл state.json повреждён?

5. Как проверить текущее состояние конвейера?

Резюме урока

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

Подробное руководство по структуре директорий: полное руководство по проекту Factory ​

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

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

Полная структура проекта Factory ​

Подробное описание директории .factory/ ​

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

config.yaml — конфигурационный файл проекта ​

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

agents/ — директория определений агентов ​

skills/ — директория модулей навыков ​

policies/ — директория документов политик ​

templates/ — директория шаблонов конфигураций ​

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

1. Могу ли я вручную изменять файлы в директории .factory/? ​

2. Могу ли я вручную изменять файлы в директории artifacts/? ​

3. Как обрабатывать файлы в директориях _failed/ и _untrusted/? ​

4. Что делать, если файл state.json повреждён? ​

5. Как проверить текущее состояние конвейера? ​

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

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

Подробное руководство по структуре директорий: полное руководство по проекту Factory

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

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

Полная структура проекта Factory

Подробное описание директории .factory/

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

config.yaml — конфигурационный файл проекта

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

agents/ — директория определений агентов

skills/ — директория модулей навыков

policies/ — директория документов политик

templates/ — директория шаблонов конфигураций

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

1. Могу ли я вручную изменять файлы в директории .factory/?

2. Могу ли я вручную изменять файлы в директории artifacts/?

3. Как обрабатывать файлы в директориях _failed/ и _untrusted/?

4. Что делать, если файл state.json повреждён?

5. Как проверить текущее состояние конвейера?

Резюме урока

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