[English](/docs/quickstart) | **Русский**

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

<!-- doc-map: reader=user; zone=getting-started -->

TAUSIK — **Т**ехнический **А**гент **У**нифицированного **С**опровождения, **И**нспекции и **К**онтроля.

Пошаговая инструкция: от нуля до первой задачи с ИИ-агентом.
Занимает 10-15 минут. Никакого опыта с ИИ-инструментами не требуется.

> **Вы — агент?** Читайте [agent-quickstart.md](/ru/docs/agent-quickstart) — тот
> же путь точными вызовами, с ответами и отказами, которые вы увидите, для
> каждого хоста, который разворачивает bootstrap.

---

## Шаг 0. Что вам понадобится

Убедитесь, что на вашем компьютере установлены:

1. **Python 3.11 или новее**
   - Windows: скачайте с [python.org](https://www.python.org/downloads/), при установке поставьте галочку "Add to PATH". Альтернатива: `winget install Python.Python.3.13`
   - macOS: `brew install python@3.13`
   - Linux (Ubuntu/Debian): `sudo apt install python3.13` · Fedora: `sudo dnf install python3.13`
   - Проверка: откройте терминал и введите `python --version` (должно показать 3.11+)
   - Bootstrap автоматически создаст изолированное виртуальное окружение (`.tausik/venv/`) и установит все необходимые зависимости. Ваш системный Python не будет изменён. Если подходящий Python не найден, bootstrap покажет инструкцию по установке.

2. **Git**
   - Windows: скачайте с [git-scm.com](https://git-scm.com/downloads)
   - macOS: `brew install git`
   - Linux: `sudo apt install git`
   - Проверка: `git --version`

3. **Visual Studio Code**
   - Скачайте с [code.visualstudio.com](https://code.visualstudio.com/)

4. **ИИ-среда разработки — одна из следующих:**
   - **Claude Code** — расширение VSCode или CLI: `npm install -g @anthropic-ai/claude-code`
   - **Cursor** — скачайте с [cursor.com](https://cursor.com)
   - **Qwen Code (GigaCode)** — установите с [qwen.ai/qwencode](https://qwen.ai/qwencode)
   - **Kilo Code** — дополнение VSCode; работает с моделями z.ai GLM (см. [Kilo + z.ai](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/kilo-zai.md))
   - **OpenCode** — `npm i -g opencode-ai`; bootstrap с `--ide opencode`
   - **Codex CLI** — bootstrap с `--ide codex`; его хуки принуждают только после того, как вы доверили их в Codex (см. [model-providers.md](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/model-providers.md#матрица-принуждения-codex))
   - **Windsurf** — скачайте с [windsurf.com](https://windsurf.com) (ожидается; bootstrap его не разворачивает)
   - Вам понадобится API-ключ или подписка для выбранной среды

## Шаг 1. Создайте репозиторий

Перейдите на [github.com](https://github.com) (или GitLab, Bitbucket — любой Git-хостинг).

1. Нажмите **New Repository**
2. Назовите, например: `my-project`
3. Поставьте галочку "Add a README file"
4. Нажмите **Create Repository**

Теперь склонируйте репозиторий к себе на компьютер:

```bash
git clone https://github.com/your-username/my-project.git
cd my-project
```

> Если у вас уже есть проект — пропустите этот шаг и перейдите в папку вашего проекта.

## Шаг 2. Подключите TAUSIK

> **Уже есть проект с кодом?** Смотрите [Миграция существующего проекта](#миграция-существующего-проекта) ниже — TAUSIK встраивается в ваш проект, ничего не перезаписывая.

Есть два способа — сказать ИИ-агенту или сделать вручную. Рекомендуем первый.

### Вариант А: скажите агенту (проще всего)

Откройте проект в IDE, откройте вашего ИИ-агента (Claude Code, Cursor, Qwen Code, Windsurf) и напишите:

```
Добавь https://github.com/Kibertum/tausik-core как git submodule в .tausik-lib,
запусти python .tausik-lib/bootstrap/bootstrap.py --init,
добавь .tausik/ в .gitignore
```

Агент выполнит все три шага — вам нужно только подтверждать его действия.

### Вариант Б: вручную через терминал

Если предпочитаете делать всё руками:

```bash
# Подключить TAUSIK как Git-подмодуль
# (Подмодуль — это ссылка на другой Git-репозиторий внутри вашего.
#  Код TAUSIK остаётся связанным, но отделённым от вашего проекта)
git submodule add https://github.com/Kibertum/tausik-core .tausik-lib

# Запустить bootstrap (одна команда делает всё)
# Имя проекта определяется автоматически из названия папки
python .tausik-lib/bootstrap/bootstrap.py --init

# Добавить рабочие данные в .gitignore
echo ".tausik/" >> .gitignore
```

### Перезапустите IDE

**После bootstrap перезапустите окно IDE** (Claude Code, Cursor, Qwen Code, Windsurf). Bootstrap генерирует project MCP-конфиги (`.mcp.json` для Claude-экосистемы и `.cursor/mcp.json` для Cursor), а IDE считывают их только при запуске. Без перезапуска агент может уйти в CLI-режим вместо MCP-инструментов.

> **Пользователям Qwen Code:** Bootstrap также создаёт `.qwen/settings.json` с MCP-конфигом и `QWEN.md` с инструкциями проекта. Используйте `--ide qwen` если работаете только в Qwen Code, или `--ide all` для мультисредового сетапа.

### Что произойдёт после bootstrap

Неважно какой вариант вы выбрали — результат одинаковый:

- Появится папка `.tausik/` — база данных, скрипты, конфигурация
- Появится папка `.claude/` — навыки и настройки для Claude Code
- Появится файл `CLAUDE.md` — инструкции для ИИ-агента
- TAUSIK определит технологический стек вашего проекта (Python, React, Go и т.д.) и включит подходящие проверки

**Две директории, которые важно понимать:**

- **`.tausik-lib/`** — исходный код фреймворка (git submodule, отслеживается в git). Это сам TAUSIK.
- **`.tausik/`** — рабочие данные: база, конфиг, виртуальное окружение. Добавлена в `.gitignore` — это локальные данные, они не коммитятся.

Коллеги, склонировавшие репозиторий, выполняют `git submodule update --init` для получения фреймворка, затем `python .tausik-lib/bootstrap/bootstrap.py --init` для настройки локальной `.tausik/`.

`.claude/` и `CLAUDE.md` — оставьте под версионным контролем. Это инструкции
для агента, они должны быть в репозитории.

## Шаг 3. Проверьте установку

```bash
.tausik/tausik status
```

> **Windows:** эта команда требует Git Bash или WSL. Если используете cmd.exe или PowerShell, выполните `.tausik/tausik.cmd status`.

Если видите что-то вроде:

```
Tasks: 0/0 done
Session: none
Epics: 0
```

Всё работает. TAUSIK готов.

## Шаг 4. Откройте проект в VSCode

```bash
code .
```

Откроется VSCode с вашим проектом. В боковой панели или внизу вы увидите
Claude Code — чат с ИИ-агентом.

Если Claude Code не появился — проверьте что расширение установлено (Ctrl+Shift+X → «Claude Code»).

## Шаг 5. Начните сессию

Напишите в чат Claude Code:

```
начинай работу
```

Агент откроет сессию, покажет статус проекта и предложит чем заняться.
При первом запуске проект пустой — это нормально.

## Шаг 6. Поставьте первую задачу

Просто опишите что нужно сделать, своими словами:

```
создай главную страницу с заголовком "Мой проект" и кнопкой "Начать"
```

Агент сам:
1. Создаст задачу в базе данных
2. Сформулирует цель и критерии приёмки (что считается «готово») — **включая хотя бы
   один сценарий ошибки или граничный случай**. Этого требует Context Gate (QG-0), и
   агент добавит его за вас (например, «кнопка неактивна, пока не заполнен заголовок»).
   Писать его вручную не нужно — просто знайте, что агент его добавит.
3. Начнёт работу — напишет код, создаст файлы

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

## Шаг 7. Завершите задачу

Когда агент закончит (или вы решите что результат устраивает), напишите:

```
готово, отправляй
```

Агент:
1. Запустит **`tausik verify`** — это шаг тяжёлой проверки (pytest, tsc, cargo, phpstan и т.д.). Может идти минуты на больших проектах. Результат **кешируется**.
2. Убедится что критерии приёмки выполнены
3. Закроет задачу через **`task done`** — это лёгкий шаг (миллисекунды), ищет свежий verify-кеш.
4. Предложит сохранить изменения в репозитории

Ответьте «да» на предложение — и ваша первая задача завершена.

Если IDE агента обрывает долгие вызовы инструментов (расширение VS Code — примерно через 60 секунд), держите два шага раздельно: сначала `tausik verify --task <slug>`, затем `task done`, который берёт результат из кэша за миллисекунды.

Настройки, меняющие этот процесс, — размер файла правил, сжатый стиль ответа, профиль хоста — в **[Конфигурации](/ru/docs/configuration#настройки-из-быстрого-старта)**.

## Шаг 8. Закончите работу

Когда работать больше не планируете:

```
на сегодня всё
```

Агент сохранит контекст: что сделано, что не закончено, какие решения приняли.
В следующий раз, когда вы скажете "начинай работу" — агент загрузит этот контекст
и продолжит с того же места.

---

## Полный рабочий цикл

Вот как выглядит типичная работа с TAUSIK после настройки:

```
Вы: "начинай работу"                          → агент открывает сессию
Вы: "исправь баг — форма не отправляется"     → агент создаёт задачу, начинает
    ... агент работает ...
Вы: "готово, отправляй"                       → агент проверяет, фиксирует
Вы: "ещё одна — добавь валидацию email"       → следующая задача
    ... агент работает ...
Вы: "готово, отправляй"                       → проверка, фиксация
Вы: "на сегодня всё"                          → агент сохраняет контекст
```

Два-три сообщения на задачу. Всё остальное — автоматически.

---

## Работа в команде

`.tausik/` лежит в gitignore — база ваша. Коллегам нужны не файлы базы, а
*знания* проекта, и они едут в git текстом: задачи, решения и память
выгружаются в читаемое дерево `tausik/`, которое вы коммитите рядом с кодом.

```bash
tausik state export      # БД → tausik/ (выполняется автоматически при любой durable-записи)
git add tausik/ && git commit
```

После того как забрали чужую работу, внесите её в свою базу:

```bash
git pull
tausik sync              # tausik/ → БД, файлы побеждают
```

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

`tausik status` сообщает, когда дерево и база расходятся. Он показывает
количества и называет **оба** направления — `tausik sync` (дерево → БД) и
`tausik state export` (БД → дерево), — не рекомендуя ни одного, потому что
количества доказывают, что стороны *различаются*, а не какая из них свежее.
Единственный однозначный сигнал — строки, которые есть в дереве и которых нет
в базе; именно его вы видите после `git pull`.

**[Полный контракт round-trip →](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/team-state-in-git.md)**

---

## Если что-то пошло не так

**"command not found: .tausik/tausik"**
- На Windows используйте Git Bash или WSL, не cmd.exe
- Или вызывайте напрямую: `.tausik/tausik.cmd status`

**"Python not found"**
- Убедитесь что Python в PATH: `python --version`
- На некоторых системах команда называется `python3`

**"Claude Code не видит навыки"**
- Перезапустите VSCode после bootstrap
- Убедитесь что `.claude/` создана и не пуста

**"База данных заблокирована"**
- Удалите файл `.tausik/tausik.db-wal` и попробуйте снова
- Это случается если предыдущий процесс завершился некорректно

**Агент не создаёт задачи, а просто пишет код**
- Проверьте что `CLAUDE.md` существует в корне проекта
- Проверьте что в нём есть раздел «Ограничения» с правилом «Нет кода без задачи»

---

## Миграция существующего проекта

Если у вас уже есть проект с кодом и вы хотите добавить TAUSIK:

1. **Перейдите в корень проекта** и подключите TAUSIK как подмодуль:
   ```bash
   git submodule add https://github.com/Kibertum/tausik-core .tausik-lib
   python .tausik-lib/bootstrap/bootstrap.py --init
   ```

2. **Bootstrap автоматически определяет окружение:**
   - Распознаёт стек (Python, React, Go и т.д.) и включает соответствующие quality gates
   - Находит существующие конфиги (`.eslintrc`, `pyproject.toml` и т.д.)
   - Сохраняет ваши `.gitignore`, `CLAUDE.md`, `.mcp.json` и `.cursor/mcp.json` — объединяет, а не перезаписывает

3. **Что попадает в git:**
   - `.tausik-lib/` — сам фреймворк (git submodule, отслеживается)
   - `.tausik/` — рабочие данные (база, конфиг, venv) — добавляется в `.gitignore`, не коммитится
   - `.claude/` и `CLAUDE.md` — инструкции агента, отслеживаются

4. **Начать с нуля или импортировать:**
   - TAUSIK начинает с чистой базы задач. Автоматического импорта из других систем нет.
   - Существующие задачи можно создать вручную через `task quick "title"` или спланировать через `/plan`.
   - История кода остаётся в git — TAUSIK управляет только слоем AI-workflow поверх неё.

После настройки проверьте `.tausik/tausik status` и начинайте работу.

---

## Что дальше

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

- **[Рабочий процесс](/ru/docs/workflow)** — быстрый и полный режимы, quality gates, память
- **[Навыки](/ru/docs/skills)** — все фразы, которые понимает агент
- **[CLI-команды](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/cli.md)** — если хотите вызывать TAUSIK из терминала напрямую
