Проектирование технической архитектуры: полное руководство по этапу Tech

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

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

Понимать, как Tech Agent проектирует техническую архитектуру на основе PRD
Освоить методы проектирования и ограничения Prisma Schema
Понимать принципы принятия решений при выборе технологического стека
Уметь разрабатывать разумную модель данных и API для MVP
Понимать стратегию миграции между средой разработки SQLite и производственной средой PostgreSQL

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

PRD уже написан, вы четко понимаете, какие функции нужно реализовать, но не знаете:

Какой технологический стек выбрать? Node.js или Python?
Как спроектировать таблицы данных? Как определить отношения?
Какие конечные точки API должны быть? Каким стандартам следовать?
Как обеспечить проектирование, которое позволит быстро доставить продукт и поддерживать будущее расширение?

Этап Tech решает именно эти проблемы — он автоматически генерирует техническую архитектуру и модель данных на основе PRD.

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

Этап Tech является 4-м этапом конвейера, следующим сразу после этапа UI и предшествующим этапу Code.

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

Сценарий	Описание
Запуск нового проекта	После подтверждения PRD необходимо спроектировать техническое решение
Быстрый прототип MVP	Необходима минимально жизнеспособная техническая архитектура, избегая избыточного проектирования
Принятие решения о технологическом стеке	Не уверены, какая комбинация технологий наиболее подходящая
Проектирование модели данных	Необходимо четко определить сущности, отношения и поля

Неподходящие сценарии:

Проекты с уже определенной технической архитектурой (этап Tech перепроектирует её)
Проекты только с фронтендом или только с бэкендом (этап Tech проектирует полноценную архитектуру)
Проекты, требующие микросервисной архитектуры (не рекомендуется на этапе MVP)

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

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

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

Завершили этап PRD: файл artifacts/prd/prd.md должен существовать и пройти валидацию
Понимаете требования продукта: четко знаете основные функции, пользовательские истории и рамки MVP
Знакомы с базовыми концепциями: понимаете RESTful API, реляционные базы данных и основы ORM

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

Что такое Prisma?

Prisma — это современный инструмент ORM (объектно-реляционное отображение) для работы с базами данных в TypeScript/Node.js.

Основные преимущества:

Типовая безопасность: автоматическая генерация типов TypeScript с полной поддержкой IDE
Управление миграциями: команда prisma migrate dev автоматически управляет изменениями базы данных
Удобство разработки: Prisma Studio для визуального просмотра и редактирования данных

Базовый рабочий процесс:

Определить schema.prisma → Запустить миграцию → Сгенерировать Client → Использовать в коде

Почему MVP использует SQLite, а производство — PostgreSQL?

SQLite (среда разработки):

Нулевая конфигурация, файловая база данных (dev.db)
Легковесная и быстрая, подходит для локальной разработки и демонстраций
Не поддерживает параллельную запись

PostgreSQL (производственная среда):

Полный функционал, поддержка параллельности и сложных запросов
Отличная производительность, подходит для производственного развертывания
Бесшовное переключение миграций Prisma: достаточно изменить DATABASE_URL

Стратегия миграции: Prisma автоматически адаптируется к провайдеру базы данных на основе DATABASE_URL, без необходимости ручного изменения Schema.

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

Суть этапа Tech — преобразование требований продукта в техническое решение, следуя принципу «MVP в первую очередь».

Фреймворк мышления

Tech Agent следует следующему фреймворку мышления:

Принцип	Описание
Соответствие целям	Техническое решение должно служить основной ценности продукта
Простота в первую очередь	Выбирать простой и зрелый технологический стек для быстрой доставки
Масштабируемость	Предусматривать точки расширения в проектировании для поддержки будущей эволюции
Ориентация на данные	Выражать сущности и отношения через четкую модель данных

Дерево решений по выбору технологий

Бэкенд технологический стек:

Компонент	Рекомендуется	Альтернатива	Описание
Среда выполнения	Node.js + TypeScript	Python + FastAPI	Node.js имеет богатую экосистему, единый стек для фронтенда и бэкенда
Веб-фреймворк	Express	Fastify	Express зрелый и стабильный, богатый выбор middleware
ORM	Prisma 5.x	TypeORM	Prisma обеспечивает типовую безопасность и отличное управление миграциями
База данных	SQLite (разработка) / PostgreSQL (производство)	-	SQLite без конфигурации, PostgreSQL готов к производству

Фронтенд технологический стек:

Сценарий	Рекомендуется	Описание
Только мобильное	React Native + Expo	Кроссплатформенность, горячее обновление
Мобильное + Web	React Native Web	Один код для нескольких платформ
Только Web	React + Vite	Отличная производительность, зрелая экосистема

Управление состоянием:

Сложность	Рекомендуется	Описание
Простая (< 5 глобальных состояний)	React Context API	Нулевые зависимости, низкий порог входа
Средняя сложность	Zustand	Легковесный, простой API, хорошая производительность
Сложное приложение	Redux Toolkit	⚠️ Не рекомендуется на этапе MVP, слишком сложный

Принципы проектирования модели данных

Идентификация сущностей:

Извлечь существительные из пользовательских историй PRD → кандидаты на сущности
Различать основные сущности (обязательные) и вспомогательные сущности (опциональные)
Каждая сущность должна иметь четкое бизнес-значение

Проектирование отношений:

Тип отношения	Пример	Описание
Один-ко-многим (1:N)	User → Posts	У пользователя много статей
Многие-ко-многим (M:N)	Posts ↔ Tags	Статьи и теги (через промежуточную таблицу)
Один-к-одному (1:1)	User → UserProfile	⚠️ Использовать редко, обычно можно объединить

Принципы полей:

Обязательные поля: id, createdAt, updatedAt
Избегать избыточности: поля, которые можно получить через вычисление или связь, не хранить
Подходящие типы: String, Int, Float, Boolean, DateTime
Пометка чувствительных полей: пароли и т.п. не должны храниться напрямую

⚠️ Ограничения совместимости SQLite

Tech Agent при генерации Prisma Schema должен соблюдать требования совместимости с SQLite:

Запрет использования Composite Types

SQLite не поддерживает определения type в Prisma, необходимо использовать String для хранения JSON-строк.

prisma

// ❌ Ошибка - SQLite не поддерживает
type UserProfile {
  identity String
  ageRange String
}

model User {
  id      Int        @id @default(autoincrement())
  profile UserProfile
}

// ✅ Правильно - использование String для хранения JSON
model User {
  id      Int    @id @default(autoincrement())
  profile String // JSON: {"identity":"student","ageRange":"18-25"}
}

Спецификация комментариев для JSON-полей

В Schema используйте комментарии для описания структуры JSON:

prisma

model User {
  id      Int    @id @default(autoincrement())
  // JSON формат: {"identity":"student","ageRange":"18-25"}
  profile String
}

В коде TypeScript определите соответствующий интерфейс:

typescript

// src/types/index.ts
export interface UserProfile {
  identity: string;
  ageRange: string;
}

Фиксация версии Prisma

Необходимо использовать Prisma 5.x, не использовать 7.x (есть проблемы совместимости):

json

{
  "dependencies": {
    "@prisma/client": "5.22.0",
    "prisma": "5.22.0"
  }
}

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

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

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

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

Файл	Описание	Расположение
`prd.md`	Документ требований к продукту	`artifacts/prd/prd.md`

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

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

Файл	Описание	Расположение
`tech.md`	Документ технического решения и архитектуры	`artifacts/tech/tech.md`
`schema.prisma`	Определение модели данных	`artifacts/backend/prisma/schema.prisma`

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

Чтение PRD: идентификация основных функций, потоков данных и ограничений
Выбор технологического стека: на основе skills/tech/skill.md выбрать язык, фреймворк и базу данных
Проектирование модели данных: определить сущности, атрибуты и отношения, выразить через Prisma schema
Написание технической документации: в tech.md объяснить обоснование выбора, стратегию расширения и нецели
Генерация выходных файлов: записать проект в указанные пути, не изменяя восходящие файлы

Условия выхода

Планировщик Sisyphus проверяет, соответствует ли Tech Agent следующим условиям:

✅ Технологический стек четко объявлен (бэкенд, фронтенд, база данных)
✅ Модель данных соответствует PRD (все сущности из PRD)
✅ Нет преждевременной оптимизации или избыточного проектирования

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

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

Почему

Tech Agent должен прочитать artifacts/prd/prd.md, если файл не существует, этап Tech не может быть выполнен.

Действие

bash

# Проверить существование файла PRD
cat artifacts/prd/prd.md

Вы должны увидеть: структурированный документ PRD, содержащий целевых пользователей, список функций, нецели и т.д.

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

Почему

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

Действие

bash

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

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

✓ Текущий этап: tech
✓ Загрузка документа PRD: artifacts/prd/prd.md
✓ Запуск Tech Agent

Tech Agent проектирует техническую архитектуру...

[AI-ассистент выполнит следующие действия]
1. Анализ PRD, извлечение сущностей и функций
2. Выбор технологического стека (Node.js + Express + Prisma)
3. Проектирование модели данных (сущности User, Post и т.д.)
4. Определение конечных точек API
5. Генерация tech.md и schema.prisma

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

Шаг 3: Просмотр сгенерированной технической документации

Почему

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

Действие

bash

# Просмотр технической документации
cat artifacts/tech/tech.md

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

markdown

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

**Бэкенд**
- Среда выполнения: Node.js 20+
- Язык: TypeScript 5+
- Фреймворк: Express 4.x
- ORM: Prisma 5.x
- База данных: SQLite (разработка) / PostgreSQL (производство)

**Фронтенд**
- Фреймворк: React Native + Expo
- Язык: TypeScript
- Навигация: React Navigation 6
- Управление состоянием: React Context API
- HTTP-клиент: Axios

## Архитектурное проектирование

**Многоуровневая структура**
- Уровень маршрутов (routes/): определение конечных точек API
- Уровень контроллеров (controllers/): обработка запросов и ответов
- Уровень сервисов (services/): бизнес-логика
- Уровень доступа к данным: Prisma ORM

**Поток данных**
Client → API Gateway → Controller → Service → Prisma → Database

## Проектирование конечных точек API

| Конечная точка | Метод | Описание | Тело запроса | Ответ |
|------|------|------|--------|------|
| /api/items | GET | Получить список | - | Item[] |
| /api/items/:id | GET | Получить детали | - | Item |
| /api/items | POST | Создать | CreateItemDto | Item |
| /api/items/:id | PUT | Обновить | UpdateItemDto | Item |
| /api/items/:id | DELETE | Удалить | - | { deleted: true } |

## Модель данных

### User
- id: первичный ключ
- email: email (обязательно)
- name: имя (обязательно)
- createdAt: время создания
- updatedAt: время обновления

**Отношения**:
- posts: один-ко-многим (у пользователя много статей)

## Переменные окружения

**Бэкенд (.env)**
- PORT: порт сервиса (по умолчанию 3000)
- DATABASE_URL: строка подключения к базе данных
- NODE_ENV: окружение (development/production)
- CORS_ORIGINS: разрешенные источники CORS

**Фронтенд (.env)**
- EXPO_PUBLIC_API_URL: адрес бэкенд API

## Точки будущего расширения

**Краткосрочные (v1.1)**
- Добавление пагинации и фильтрации
- Реализация функции экспорта данных

**Среднесрочные (v2.0)**
- Миграция на PostgreSQL
- Добавление аутентификации пользователей

**Долгосрочные**
- Разделение на микросервисы
- Добавление уровня кэширования (Redis)

Шаг 4: Просмотр сгенерированного Prisma Schema

Почему

Проверьте, соответствует ли модель данных PRD, соблюдаются ли ограничения совместимости SQLite.

Действие

bash

# Просмотр Prisma Schema
cat artifacts/backend/prisma/schema.prisma

Вы должны увидеть: Schema, соответствующий синтаксису Prisma 5.x, содержащий полные определения сущностей и отношений

prisma

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite" // среда разработки
  url      = "file:./dev.db"
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  posts     Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String
  published Boolean  @default(false)
  authorId  Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  author    User     @relation(fields: [authorId], references: [id])
}

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

Почему

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

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

Проверка	Описание	Пройдено/Не пройдено
Технологический стек четко объявлен	Бэкенд, фронтенд, база данных четко определены	[ ]
Модель данных соответствует PRD	Все сущности из PRD, нет лишних полей	[ ]
Нет преждевременной оптимизации или избыточного проектирования	Соответствует рамкам MVP, нет непроверенных функций	[ ]

В случае неудачи:

bash

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

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

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

[ ] Этап Tech успешно выполнен
[ ] Файл artifacts/tech/tech.md существует и содержит полный контент
[ ] Файл artifacts/backend/prisma/schema.prisma существует и имеет правильный синтаксис
[ ] Выбор технологического стека обоснован (Node.js + Express + Prisma)
[ ] Модель данных соответствует PRD, нет лишних полей
[ ] Schema соблюдает ограничения совместимости SQLite (нет Composite Types)

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

⚠️ Ловушка 1: Избыточное проектирование

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

Симптомы: В tech.md содержатся «микросервисная архитектура», «Redis кэш», «очереди сообщений» и т.д.

Решение: У Tech Agent есть список NEVER, четко запрещающий избыточное проектирование. Если вы видите такой контент, перезапустите.

markdown

## Не делайте (NEVER)
* **NEVER** избыточно проектируйте, например, вводя микросервисы, сложные очереди сообщений или высокопроизводительный кэш на этапе MVP
* **NEVER** пишите избыточный код для еще не определенных сценариев

⚠️ Ловушка 2: Ошибки совместимости SQLite

Проблема: Prisma Schema использует функции, не поддерживаемые SQLite.

Симптомы: Ошибка на этапе Validation или сбой npx prisma generate.

Распространенные ошибки:

prisma

// ❌ Ошибка - SQLite не поддерживает Composite Types
type UserProfile {
  identity String
  ageRange String
}

model User {
  profile UserProfile
}

// ❌ Ошибка - использование версии 7.x
{
  "prisma": "^7.0.0"
}

Решение: Проверьте Schema, убедитесь в использовании String для хранения JSON, зафиксируйте версию Prisma на 5.x.

⚠️ Ловушка 3: Модель данных выходит за рамки MVP

Проблема: Schema содержит сущности или поля, не определенные в PRD.

Симптомы: Количество сущностей в tech.md значительно превышает количество основных сущностей в PRD.

Решение: Tech Agent ограничен «модель данных должна охватывать все сущности и отношения, необходимые для функций MVP, не следует заранее добавлять непроверенные поля». Если обнаружены дополнительные поля, удалите их или пометьте как «точки будущего расширения».

⚠️ Ловушка 4: Ошибки в проектировании отношений

Проблема: Определение отношений не соответствует реальной бизнес-логике.

Симптомы: Один-ко-многим записано как многие-ко-многим, или отсутствуют необходимые отношения.

Пример ошибки:

prisma

// ❌ Ошибка - пользователь и статья должны быть один-ко-многим, не один-к-одному
model User {
  id   Int    @id @default(autoincrement())
  post Post?  // отношение один-к-одному
}

model Post {
  id      Int    @id @default(autoincrement())
  author  User?  // должно использовать @relation
}

Правильный вариант:

prisma

// ✅ Правильно - отношение один-ко-многим
model User {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  authorId Int
  author   User @relation(fields: [authorId], references: [id])
}

Резюме урока

Этап Tech является мостом в конвейере, соединяющим «требования продукта» и «реализацию кода». На основе PRD он автоматически проектирует:

Технологический стек: Node.js + Express + Prisma (бэкенд), React Native + Expo (фронтенд)
Модель данных: Prisma Schema, соответствующий требованиям совместимости SQLite
Архитектурное проектирование: многоуровневая структура (маршруты → контроллеры → сервисы → данные)
Определение API: RESTful конечные точки и потоки данных

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

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

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

✅ Полный документ технического решения (tech.md)
✅ Модель данных, соответствующая спецификации Prisma 5.x (schema.prisma)
✅ Четкое проектирование API и конфигурация окружения

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

В следующем уроке мы изучим Этап Code: генерация работающего кода.
Вы узнаете:
Как Code Agent генерирует фронтенд и бэкенд код на основе UI Schema и Tech проектирования
Какие функции содержит сгенерированное приложение (тесты, документация, CI/CD)
Как проверить качество сгенерированного кода
Специальные требования и спецификации вывода Code Agent

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

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

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

Функция	Путь к файлу	Номер строки
Определение Tech Agent	`source/hyz1992/agent-app-factory/agents/tech.agent.md`	1-63
Руководство по навыкам Tech	`source/hyz1992/agent-app-factory/skills/tech/skill.md`	1-942
Конфигурация Pipeline	`source/hyz1992/agent-app-factory/pipeline.yaml`	49-62
Ограничения совместимости SQLite	`source/hyz1992/agent-app-factory/agents/tech.agent.md`	28-56

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

Запрет использования Composite Types: SQLite не поддерживает, необходимо использовать String для хранения JSON
Фиксация версии Prisma: необходимо использовать 5.x, не использовать 7.x
Рамки MVP: модель данных должна охватывать все сущности, необходимые для функций MVP, не следует заранее добавлять непроверенные поля

Принципы принятия решений о технологическом стеке:

Приоритет отдается языкам и фреймворкам с активным сообществом и полной документацией
На этапе MVP выбирать легковесную базу данных (SQLite), в дальнейшем можно мигрировать на PostgreSQL
Системное многоуровневое разделение следует принципу уровень маршрутов → уровень бизнес-логики → уровень доступа к данным

Не делайте (NEVER):

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

Проектирование технической архитектуры: полное руководство по этапу Tech ​

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

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

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

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

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

Фреймворк мышления ​

Дерево решений по выбору технологий ​

Принципы проектирования модели данных ​

⚠️ Ограничения совместимости SQLite ​

Запрет использования Composite Types ​

Спецификация комментариев для JSON-полей ​

Фиксация версии Prisma ​

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

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

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

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

Условия выхода ​

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

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

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

Шаг 3: Просмотр сгенерированной технической документации ​

Шаг 4: Просмотр сгенерированного Prisma Schema ​

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

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

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

⚠️ Ловушка 1: Избыточное проектирование ​

⚠️ Ловушка 2: Ошибки совместимости SQLite ​

⚠️ Ловушка 3: Модель данных выходит за рамки MVP ​

⚠️ Ловушка 4: Ошибки в проектировании отношений ​

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

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

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

Проектирование технической архитектуры: полное руководство по этапу Tech

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

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

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

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

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

Фреймворк мышления

Дерево решений по выбору технологий

Принципы проектирования модели данных

⚠️ Ограничения совместимости SQLite

Запрет использования Composite Types

Спецификация комментариев для JSON-полей

Фиксация версии Prisma

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

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

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

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

Условия выхода

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

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

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

Шаг 3: Просмотр сгенерированной технической документации

Шаг 4: Просмотр сгенерированного Prisma Schema

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

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

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

⚠️ Ловушка 1: Избыточное проектирование

⚠️ Ловушка 2: Ошибки совместимости SQLite

⚠️ Ловушка 3: Модель данных выходит за рамки MVP

⚠️ Ловушка 4: Ошибки в проектировании отношений

Резюме урока

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

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