Модуль 2.10 · Урок 1

Урок 1: Настрой проект для AI

ПроектПрактика

2.10 / Урок 1 из 3

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

В этом уроке вы подготовите существующий проект к работе с AI-агентами. Вы создадите необходимые конфигурационные файлы, настроите MCP-серверы и автоматизацию, которые позволят Claude Code эффективно работать с вашим кодом.

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

Содержание

Шаг 1: Выбираем проект для работы

У вас есть три варианта:

Вариант А: Express.js API

Простой REST API на Node.js. Хорошо подходит для новичков.

git clone https://github.com/YOUR-USERNAME/express-api-starter.git
cd express-api-starter

Структура:

express-api/
├── src/
│   ├── server.js
│   ├── routes/
│   │   ├── users.js
│   │   └── items.js
│   └── middleware/
│       └── errorHandler.js
├── package.json
├── .env.example
└── README.md

Вариант Б: FastAPI бэкенд

Современный асинхронный API на Python. Для тех, кто работает с Python.

git clone https://github.com/YOUR-USERNAME/fastapi-backend.git
cd fastapi-backend

Структура:

fastapi-backend/
├── app/
│   ├── main.py
│   ├── routes/
│   │   ├── users.py
│   │   └── items.py
│   └── models/
│       └── schemas.py
├── requirements.txt
├── .env.example
└── README.md

Вариант В: React фронтенд

SPA приложение на React. Для фронтенд-разработчиков.

git clone https://github.com/YOUR-USERNAME/react-app.git
cd react-app

Структура:

react-app/
├── src/
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   └── App.jsx
├── package.json
├── .eslintrc.json
└── vite.config.js

Совет: если у вас нет собственного проекта, используйте учебный репозиторий из Трека 1. Главное — это активный Git-репозиторий с фактическим кодом.

Шаг 2: Создаём AGENTS.md

Этот файл описывает для AI-агента структуру вашего проекта и его особенности.

Создаёте файл: AGENTS.md в корне репозитория

# Агентам о проекте

## Обзор
Это REST API для управления товарами и пользователями. Написан на Express.js + MongoDB.

## Основные компоненты
- **routes/** — все API endpoints
- **models/** — Mongoose-схемы для БД
- **middleware/** — обработчики ошибок, аутентификация
- **tests/** — интеграционные тесты (Jest)

## Стек технологий
- Node.js 18+
- Express 4.18
- MongoDB (используем MongoDB Atlas)
- Jest для тестирования

## Как запустить
```bash
npm install
npm run dev  # запуск на localhost:3000
npm test     # запуск тестов

Важные правила кодирования

Все новые routes должны быть асинхронными (async/await)
Ошибки обрабатываем через middleware errorHandler
Валидация входных данных через express-validator
Коммиты пишем на английском (feat: add user endpoint)
Pull requests: опишите задачу, решение и как тестировать

Конфигурация

PORT: 3000 (из .env)
DB_URL: строка подключения к MongoDB (из .env)
NODE_ENV: development или production

Контакты

Разработчик: your-name (your-email@example.com)


---

### Шаг 3: Создаём CLAUDE.md

Детальная инструкция для Claude Code, как работать с проектом.

**Создаёте файл:** `CLAUDE.md` в корне репозитория

```markdown
# Инструкция для Claude Code

## Перед началом работы

1. **Прочитайте AGENTS.md** — там описана архитектура
2. **Установите зависимости:** `npm install`
3. **Создайте .env файл** на основе .env.example
4. **Запустите dev-сервер:** `npm run dev`
5. **Запустите тесты:** `npm test`

## Как я работаю с кодом

### Создание новых файлов
- Всегда следую структуре проекта
- Новые routes в `src/routes/`, модели в `src/models/`
- Каждый новый файл содержит комментарии

### Редактирование кода
- Проверяю тесты перед изменениями
- Запускаю линтер: `npm run lint`
- Проверяю типы (если используется TypeScript)

### Тестирование
- Для каждой новой фичи пишу тест в `tests/`
- Запускаю полный набор тестов
- Проверяю покрытие: `npm run coverage`

## Команды разработки

```bash
npm install          # установка зависимостей
npm run dev          # запуск в режиме разработки
npm test             # запуск тестов
npm run lint         # проверка линтера (ESLint)
npm run lint:fix     # автоматическое исправление
npm run build        # сборка для production
npm run coverage     # отчёт о покрытии тестами

Структура проекта (важные пути)

src/
├── server.js                 # точка входа
├── routes/                   # API endpoints
│   ├── users.js              # /api/users/*
│   └── items.js              # /api/items/*
├── models/                   # схемы БД
│   ├── User.js
│   └── Item.js
├── middleware/               # обработчики
│   ├── auth.js               # проверка токенов
│   └── errorHandler.js       # обработка ошибок
└── utils/
    └── validators.js         # валидация данных

tests/
├── users.test.js             # тесты для users API
├── items.test.js             # тесты для items API
└── fixtures/                 # тестовые данные

.env.example                  # пример переменных
package.json                  # зависимости

Частые задачи

Добавить новый endpoint

Создать функцию в src/routes/ или src/controllers/
Подключить в src/server.js или в маршрутизаторе
Написать тест в tests/
Запустить npm test для проверки

Исправить баг

Запустить тесты — найти падающий тест
Провести debug через логи
Исправить код
Убедиться, что тест проходит
Запустить полный набор тестов: npm test

Рефакторить код

Убедиться, что есть тесты для модуля
Провести изменения
Запустить: npm test && npm run lint
Если всё зелено — готово!

Общие правила

Никогда не меняю конфиг БД напрямую (только через переменные окружения)
Всегда проверяю, что новый код не ломает тесты
Избегаю удаления или переименования существующих функций без рефакторинга тестов
Документирую сложную логику в комментариях

Если что-то не работает

Проверить логи: npm run dev (скопировать ошибку)
Запустить тесты: npm test (какие упали?)
Проверить версии пакетов: npm list
Переустановить: rm -rf node_modules && npm install


---

### Шаг 4: Настраиваем MCP-серверы

MCP-серверы (Model Context Protocol) позволяют Claude Code читать файловую систему, работать с Git и GitHub.

**Создаёте файл:** `.mcp.json` в корне проекта (или используйте глобальный `~/.claude.json`)

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

⚠️ Пакет @modelcontextprotocol/server-github deprecated — используйте официальный remote-сервер GitHub (https://api.githubcopilot.com/mcp/) с PAT или OAuth. Подробнее: https://github.com/github/github-mcp-server

Управление серверами через CLI:

claude mcp add filesystem  # добавить сервер
claude mcp list            # посмотреть активные
claude mcp remove github   # удалить

Как получить GITHUB_PERSONAL_ACCESS_TOKEN:

Перейдите на https://github.com/settings/tokens
Нажмите “Generate new token” → “Generate new token (classic)”
Выберите минимальные scope: repo, read:org
Скопируйте токен
Добавьте в .env:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Рекомендуется использовать OAuth через официальный remote GitHub MCP server.

Шаг 5: Настраиваем Git-хуки

Автоматизация при коммитах помогает поддерживать качество кода.

Создаёте файл: .husky/pre-commit

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "Запускаю линтер..."
npm run lint || exit 1

echo "[+] Код прошёл проверку!"

Создаёте файл: .husky/post-commit

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "Коммит создан!"
echo "Сообщение: $(git log -1 --pretty=%B)"

Установка Husky:

npm install husky --save-dev
npx husky install
chmod +x .husky/pre-commit
chmod +x .husky/post-commit

Шаг 6: Создаём .cursorrules

Для работы в редакторе Cursor (IDE с встроенным Claude).

Создаёте файл: .cursorrules

# Правила для Cursor AI

## Стиль кода
- Используй async/await вместо Promise chains
- Переменные и функции на английском (camelCase)
- Максимум 100 символов в строке
- Все функции должны иметь JSDoc-комментарии

## Структура проекта
- Новые файлы только в правильных папках (routes/ models/ utils/)
- Не создавай файлы в корне, кроме конфигурационных
- Импорты: сначала внешние пакеты, потом внутренние

## Перед коммитом
- Запусти: npm run lint:fix
- Запусти: npm test
- Обнови CHANGELOG.md если нужно

## Тестирование
- Каждая новая функция должна иметь минимум 2 теста (happy path + error case)
- Используй describe() и it() из Jest
- Mock'и внешних сервисов (БД, API)

## Безопасность
- Никогда не логируй пароли или токены
- Используй переменные окружения для sensitive данных
- Проверяй input от пользователя перед использованием

Практика

Чек-лист готовности проекта

Чек-лист готовности

Перед тем как работать с агентом, убедитесь, что проект готов:

Репозиторий инициализирован: git init (или клонирован)
AGENTS.md создан с описанием стека и структуры
CLAUDE.md создан с инструкциями для AI
Зависимости установлены: npm install или pip install -r requirements.txt
Тесты проходят: npm test возвращает 0 ошибок
Линтер настроен: npm run lint проходит без warning’ов
.env файл создан на основе .env.example
Git-хуки установлены: npx husky install
.cursorrules создан в корне проекта
MCP-токены добавлены в .env (GITHUB_TOKEN и др.)

Если все пункты выполнены — проект готов к работе с агентом.

Пример: готовый репозиторий

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

my-project/
├── .mcp.json                     # конфиг MCP серверов
├── .husky/
│   ├── pre-commit                # линтер перед коммитом
│   └── post-commit               # уведомление после коммита
├── src/
│   ├── server.js
│   ├── routes/
│   ├── models/
│   ├── middleware/
│   └── utils/
├── tests/
│   ├── users.test.js
│   ├── items.test.js
│   └── fixtures/
├── .cursorrules                  # правила для Cursor
├── .env                          # переменные (в .gitignore)
├── .env.example                  # шаблон для других разработчиков
├── .gitignore
├── AGENTS.md                     # описание для AI
├── CLAUDE.md                     # инструкция для Claude Code
├── package.json
├── package-lock.json
└── README.md

Команда для быстрой подготовки проекта:

# 1. Скопируйте шаблоны из этого урока
cp шаблоны/AGENTS.md ./AGENTS.md
cp шаблоны/CLAUDE.md ./CLAUDE.md
cp шаблоны/.cursorrules ./.cursorrules

# 2. Установите Husky
npm install husky --save-dev
npx husky install

# 3. Добавьте хуки
npx husky add .husky/pre-commit "npm run lint"

# 4. Создайте MCP-конфиг
# Скопируйте .mcp.json из Шага 4 в корень проекта
# Либо используйте: claude mcp add <имя>

# 5. Проверьте всё работает
npm test
npm run lint

Ключевые выводы

Вы научились:

Выбирать проект для работы с AI-агентами (Express, FastAPI или React)
Документировать архитектуру через AGENTS.md для понимания AI
Писать инструкции для Claude через CLAUDE.md
Настраивать MCP для работы с файловой системой и GitHub
Автоматизировать качество кода через Git-хуки
Подготавливать IDE через .cursorrules

Следующий шаг: теперь проект готов к Уроку 2, где вы будете решать задачи через агента!

Помните: чем лучше вы подготовите проект, тем эффективнее будет работать AI-агент. Качественная документация (AGENTS.md, CLAUDE.md) экономит время на объяснения.

Прикреплённые файлы:

AGENTS.md.template — готовый шаблон
CLAUDE.md.template — готовый шаблон
.cursorrules.template — готовый шаблон
mcp-servers.json.template — конфиг для MCP

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

Урок 1: Настрой проект для AI

Финальный проект

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

Содержание

Шаг 1: Выбираем проект для работы

Вариант А: Express.js API

Вариант Б: FastAPI бэкенд

Вариант В: React фронтенд

Шаг 2: Создаём AGENTS.md

Важные правила кодирования

Конфигурация

Контакты

Структура проекта (важные пути)

Частые задачи

Добавить новый endpoint

Исправить баг

Рефакторить код

Общие правила

Если что-то не работает

Шаг 5: Настраиваем Git-хуки

Шаг 6: Создаём .cursorrules

Практика

Чек-лист готовности проекта

Пример: готовый репозиторий

Ключевые выводы

Урок 2: Сборка

Урок 3: Финальный проект

Практика: собираем команду агентов

Урок 1: Как писать эффективные промпты для агентов

// Обсуждение

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

Содержание

Шаг 1: Выбираем проект для работы

Вариант А: Express.js API

Вариант Б: FastAPI бэкенд

Вариант В: React фронтенд

Шаг 2: Создаём AGENTS.md

Важные правила кодирования

Конфигурация

Контакты

Структура проекта (важные пути)

Частые задачи

Добавить новый endpoint

Исправить баг

Рефакторить код

Общие правила

Если что-то не работает

Шаг 5: Настраиваем Git-хуки

Шаг 6: Создаём .cursorrules

Практика

Чек-лист готовности проекта

Пример: готовый репозиторий

Ключевые выводы

Связанные уроки

Урок 2: Сборка

Урок 3: Финальный проект

Практика: собираем команду агентов

Урок 1: Как писать эффективные промпты для агентов

// Обсуждение