---
name: architecture-new-project
description: Воркфлоу инициализации нового проекта — структура, конфиги, документация, первый коммит. Используй при создании проекта с нуля. Триггеры: пользователь говорит «создай проект», «новый проект», «init», «начни с нуля», «инициализация».
---

# Новый проект — Воркфлоу инициализации

Инициализация проходит 5 шагов:
1. Требования → что строим, какой стек
2. Scaffold → создать проект средствами фреймворка
3. Конфигурация → структура, git, env, .ai/
4. Документация → INDEX.md, RULES.md, ARCHITECTURE.md, SNAPSHOT.md, BACKLOG.md, README.md, EVOLUTION.md
5. Первый коммит → чистая точка старта

## Шаг 1: Требования

Уточнить у пользователя до начала работы:

```
Что строим: [тип — веб-приложение, API, лендинг, дашборд]
Стек: [фреймворк, язык, БД — или предложить]
Ключевой функционал: [3–5 главных фич]
Деплой: [Vercel, VPS, Docker — или решить позже]
```

**Если стек не указан** — предложить:
- Веб-приложение → Next.js + TypeScript + Tailwind + Prisma
- API → Next.js API Routes или Express + TypeScript
- Лендинг → Next.js + TypeScript + Tailwind

**Не начинать scaffold до подтверждения стека.**

## Шаг 2: Scaffold

```bash
npx create-next-app@latest [имя] --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd [имя]
npm run dev
```

Проект запускается → переходить дальше.

## Шаг 3: Конфигурация

### Структура кода (создать если scaffold не создал)

```
src/
  app/            — страницы и layouts
  components/
    ui/           — базовые UI-компоненты
  lib/            — утилиты, хелперы
  hooks/          — кастомные хуки
  types/          — TypeScript типы
  services/       — работа с API и внешними сервисами
```

### Структура .ai/ и .cursor/

```bash
mkdir -p .ai/templates .cursor/skills .cursor/rules
```

```
.ai/                — проектная документация
  INDEX.md          — навигация (точка входа)
  RULES.md          — единый свод правил
  ARCHITECTURE.md   — архитектура системы
  SNAPSHOT.md       — текущее состояние
  BACKLOG.md        — roadmap и задачи
  EVOLUTION.md      - динамика роста ценности
  templates/        — шаблоны ADR / RFC / Runbook
.cursor/
  skills/           — workflow-скиллы
  rules/            — правила проекта (.mdc файлы)
```

### Git

```bash
git init
git checkout -b main
```

Проверить `.gitignore`: `node_modules/`, `.next/`, `.env`, `.env.local`

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

Создать `.env.example` с пустыми значениями. НЕ создавать `.env` — попросить пользователя заполнить.

### Проверка

```bash
npm run dev    # работает
npm run build  # собирается
```

## Шаг 4: Документация

Все файлы для AI-агента живут в `.ai/`. В корне — CLAUDE.md и .cursorrules (bootstrap), README.md для людей.

Принцип: каждый файл < 50 строк на старте. Растёт с проектом.

Также создать bootstrap-файлы:
- `CLAUDE.md` — START PROTOCOL (прочитай INDEX → RULES → SNAPSHOT) + NAVIGATION ссылки
- `.cursorrules` — то же самое для Cursor

---

### .ai/INDEX.md — Навигация (точка входа)

Главный файл. Агент читает ПЕРВЫМ при входе в проект. Только навигация и триггеры — не правила, не архитектура.

```markdown
# [Название]
[Одно предложение — что делает проект]

## Навигация
| Документ | Содержание |
|----------|-----------|
| RULES.md | Единый свод правил |
| ARCHITECTURE.md | Архитектура системы |
| SNAPSHOT.md | Текущий статус |
| BACKLOG.md | Roadmap |

## Триггерные команды
| Команда | Действие |
|---------|---------|
| старт | Читать SNAPSHOT, показать состояние |
| план | Читать BACKLOG, показать этап |
| статус | Краткая сводка |
| финиш | Обновить SNAPSHOT, предложить commit |

## Структура
[дерево проекта]
```

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

---

### .ai/RULES.md — Единый свод правил

Все правила в одном месте: роль, протокол выполнения, скиллы, принципы кода, безопасность, автономность, запреты.

**Когда обновлять:** при изменении процессов или правил.

---

### .ai/ARCHITECTURE.md — Архитектура системы

Философия проекта, стек, компоненты, data flows, уровни системы.

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

---

### .ai/SNAPSHOT.md — Текущее состояние

Память между сессиями. Без него агент начинает с нуля.

```markdown
# Состояние
Последний коммит: [дата] — [сообщение]
Что работает: [список]
В процессе: [что начато, где остановились]
Проблемы: [баги, техдолг]
Следующий шаг: [задача из BACKLOG]
```

**Когда обновлять:** после каждого коммита (автоматически через workflow-commit).

---

### .ai/BACKLOG.md — План задач

```markdown
# Бэклог
## Готово
- [x] Инициализация проекта
## В работе
- [ ] [задача]
## Запланировано
- [ ] [задача]
```

**Когда обновлять:** завершение задач, новые задачи, переприоритизация.

---

### .ai/EVOLUTION.md — Журнал эволюции и ценности

Фиксирует не технические изменения, а **ценность** — что проект делает вместо тебя, от каких рутин освободил.

```markdown
# EVOLUTION.md — Эволюция [Название]

## Уровни зрелости
| Уровень | Описание | Статус |
| --- | --- | --- |
| 0 — Инструмент | Выполняет команды, требует управления | 🔄 В процессе |
| 1 — Рутины | Автоматически выполняет повторяющиеся задачи | ⏳ Впереди |
| 2 — Наблюдатель | Сам замечает важное, сигнализирует | ⏳ Впереди |
| 3 — Советник | Участвует в решениях, знает контекст | ⏳ Впереди |
| 4 — Автономия | Действует проактивно | ⏳ Впереди |

## Что проект снял с меня — по категориям

### 1. [Название категории]
**Проблема до:** [что делал вручную]
**Что делает проект:** [список действий]
**Что снял с меня:** [рутина/тревога → результат]

## Хронологический журнал
| Дата | Изменение | Категория |
| --- | --- | --- |
| YYYY-MM-DD | Инициализация проекта | #init |
```

**Когда обновлять:** когда проект берёт на себя новую задачу или решает новую проблему (триггер: workflow-done Шаг 5.5).

---

### .ai/templates/ — Шаблоны

```bash
mkdir -p .ai/templates
```

Создать шаблоны: ADR_TEMPLATE.md, RFC_TEMPLATE.md, RUNBOOK_TEMPLATE.md.

---

### deployment/RECOVERY.md — Операционный runbook

**Когда создавать:** если в проекте есть сервер/VPS, бот, cron jobs.
**Кто использует:** человек (владелец) — когда система недоступна.
**Шаблон:** скопировать из `.ai/templates/RUNBOOK_TEMPLATE.md`.

---

### README.md (корень) — Для людей

```markdown
# [Название]
[Описание — 2-3 предложения]

## Установка
git clone [url] && cd [имя] && cp .env.example .env && npm install && npm run dev

## Стек
[список технологий]
```

## Шаг 5: Первый коммит

```bash
git add .
git commit -m "chore: инициализация проекта — [стек]"
```

**Исключение:** `git add .` допустим — первый коммит, все файлы наши.

```
✅ Проект: [имя] | Стек: [перечень]
✅ Документация: .ai/ (INDEX, RULES, ARCHITECTURE, SNAPSHOT, BACKLOG, templates/) + README.md
✅ Bootstrap: CLAUDE.md + .cursorrules → .ai/INDEX.md
✅ Если есть сервер/бот/cron: deployment/RECOVERY.md
✅ Первый коммит: main | npm run dev → localhost:3000
Следующий шаг: [первая задача из BACKLOG]
```