Настройка проекта для ИИ-агента

1. Изоляция — ошибки и мусор остаются внутри учебного репозитория и не касаются рабочих задач.
2. Безопасность — здесь можно ломать, переделывать и пробовать заведомо плохие идеи без последствий.
3. Воспроизводимость — проект можно сбросить в чистое состояние и повторить упражнение с нуля.
4. Управляемость — небольшой код легко читать и проверять, поэтому сразу видно, что агент сделал правильно, а что нет.

Отдельный проект — это ещё и полигон для метрик. Именно на нём удобно замерять стоимость сеансов, сравнивать модели и отрабатывать приёмы управления контекстом, о которых пойдёт речь дальше в курсе. Если что-то пойдёт не так — проект всегда можно удалить и создать заново за пять минут.

Большинство из них уже есть в любой современной системе, но проверить стоит: агент полагается на них при выполнении команд, и пропущенный шаг позже превратится в непонятную ошибку.

Если команда не найдена, установите недостающий инструмент. Точные шаги зависят от вашей ОС: на macOS удобно использовать Homebrew, на Windows — официальные установщики, на Linux — системный пакетный менеджер. Материалы курса не привязываются к конкретному стеку: в примерах используется Node.js, но ровно так же подойдёт Python или любой другой язык, на котором вы пишете.

node --version
git --version
npm --version

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

Создайте папку проекта и инициализируйте репозиторий.

mkdir ai-course
cd ai-course
git init

После выполнения команды в папке появится скрытая директория .git — в ней хранится вся история. С этого момента любые изменения файлов можно фиксировать коммитами и при необходимости возвращаться к любому прошлому состоянию.

Файл .gitignore

Не всё в папке проекта должно попадать в git. Каталоги с зависимостями, временные файлы и переменные окружения раздувают репозиторий и создают конфликты. Список того, что игнорировать, задаётся в файле .gitignore.

node_modules/
.env
.DS_Store

Файл README.md

В README.md коротко опишите, что это за проект и как его запустить. Даже три строки помогут и вам, и агенту быстрее войти в контекст в новой сессии: вместо чтения всего кода агент сначала посмотрит на описание. Это первый шаг к тому, чтобы проект был «дружелюбным» к ИИ-агентам.

Первый коммит

Зафиксируйте стартовое состояние проекта. Первый коммит — точка отсчёта: к ней можно вернуться, если дальнейшие эксперименты заведут в тупик.

git add .
git commit -m "Инициализация учебного проекта"

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

ai-course/
├── src/
│   └── main.js
├── tests/
├── .gitignore
├── package.json
└── README.md

1. src/ — исходный код, с которым работает агент.
2. tests/ — тесты, которые проверяют, что код работает.
3. package.json — описание проекта и его зависимостей.
4. README.md — инструкция, как запускать проект.

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

Зависимости — это готовые библиотеки, которые проект подключает извне. В Node.js их список хранится в файле package.json, а устанавливаются они командой npm install.

{
  "name": "ai-course",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/main.js"
  }
}

Обратите внимание на блок scripts: он позволяет запускать проект одной короткой командой — npm start. Агенту не нужно помнить, какой именно файл запускать: инструкция уже есть в проекте.

npm install

Если вы работаете на Python, аналогичную роль играют pyproject.toml или requirements.txt и виртуальное окружение — изолированный набор пакетов для конкретного проекта. Принцип один: зависимости описаны в файле, устанавливаются одной командой и не мусорят систему.

Что такое lock-файл

После установки появляется файл package-lock.json. В нём зафиксированы точные версии всех пакетов, включая вложенные. Это гарантия воспроизводимости: другой человек или агент установит ровно те же версии, и проект будет работать одинаково у всех.

Обязательно коммитьте lock-файл в репозиторий. Его потеря — одна из самых частых причин «у меня работает, а у тебя нет».

Теперь напишем самую простую программу, которая докажет, что проект собран правильно. Она ничего не делает полезного, но её запуск — критерий того, что окружение, зависимости и структура работают.

const message = "Привет из учебного проекта";
console.log(message);

Запустите программу через команду из package.json:

npm start

Успех — это появление в терминале строки Привет из учебного проекта. Сформулируйте для себя критерий приёмки заранее: в следующих уроках мы будем делать то же самое для каждой задачи — сначала определять «что считается готовым», а потом выполнять работу. Такой порядок радикально повышает качество результата при работе с агентами.

Когда программа запустилась, посмотрите, какие файлы изменились, и зафиксируйте результат. Команда git status показывает состояние рабочей копии, а git log — историю коммитов.

git status
git add .
git commit -m "Добавлено первое упражнение"

Пишите осмысленные сообщения коммитов: они становятся инструкцией для будущих сессий. Когда вы или агент читаете git log, по сообщениям должно быть понятно, что происходило с проектом. Это бесплатная документация, которую вы создаёте автоматически.

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

1. Эксперименты с агентом в рабочем проекте вместо учебного.
2. Пропуск проверки окружения и установки недостающих инструментов.
3. Забытый .gitignore — мусорные файлы попадают в историю.
4. Не закоммиченный lock-файл — проект не воспроизводится у других.
5. Коммит «кучей» одним большим сообщением вместо серии маленьких.
6. Сложная структура проекта на старте, которую не нужно никому объяснять.

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

В следующем уроке установим и настроим ИИ-агента — инструмент, с которым вы будете работать с этим проектом на протяжении всего курса.

1. Git — система контроля версий, хранящая историю изменений.
2. Репозиторий — папка проекта с историей изменений в git.
3. Коммит — зафиксированная точка в истории изменений.
4. Рабочая копия — текущее состояние файлов на диске.
5. .gitignore — файл со списком того, что не попадает в git.
6. README.md — файл с описанием проекта и инструкцией запуска.
7. Зависимость — внешняя библиотека, подключаемая к проекту.
8. Lock-файл — файл с точными версиями всех зависимостей.
9. Рантайм — среда исполнения кода, например Node.js.
10. Node.js — среда исполнения JavaScript вне браузера.
11. Venv — виртуальное окружение Python для изоляции пакетов.
12. Критерий приёмки — условие, по которому задача считается выполненной.
13. git status — команда, показывающая состояние рабочей копии.
14. git log — команда, показывающая историю коммитов.
15. Diff — разница между версиями файлов.