Практика -- настраиваем автономную рабочую среду с нуля

Цель

За этот урок вы создадите фундамент автономной среды:

• Единый источник правды о проекте (PROJECT.md)
• Система памяти агента (.memory/)
• Автоматическая генерация конфигов для всех сред

В следующем уроке мы настроим CI/CD, мультиагентную работу и мониторинг.

Шаг 1: Единый источник правды

Создайте PROJECT.md — главный файл, из которого генерируются конфиги для всех агентов. Это не README для людей, а операционная инструкция для AI. Агент читает этот файл при каждом запуске и принимает решения на его основе: какой стиль кода использовать, какие тесты запускать, что запрещено.

# PROJECT.md

## Проект
Название: [ваш проект]
Описание: [что делает]
Команда: [сколько человек, роли]

## Стек
- Язык: Python 3.11
- Фреймворк: FastAPI
- БД: PostgreSQL 15
- Кеш: Redis
- Контейнеры: Docker Compose (dev), Kubernetes (prod)
- CI/CD: GitHub Actions
- Тесты: pytest + playwright

## Архитектура
- Модульная структура: src/modules/{name}/
- Каждый модуль: routes.py, service.py, models.py, schemas.py
- Зависимости через DI
- Миграции: alembic

## Конвенции
- Стиль: PEP 8 + black + ruff
- Типизация: mypy --strict
- Коммиты: conventional commits (feat:, fix:, docs:, refactor:)
- PR: обязательное ревью, минимум 1 approve
- Тесты: покрытие > 80%, обязательные для новых эндпоинтов

## Запреты
- Прямой SQL без параметризации
- f-strings в SQL
- Коммиты без тестов
- Push в main без PR
- Хардкод credentials

## Текущие приоритеты
- Рефакторинг модуля orders (техдолг)
- Миграция с Redis на Valkey
- Подготовка к нагрузочному тестированию

Секция «Запреты» критична: без нее агент может, например, использовать f-strings в SQL (привет, SQL injection) или запушить прямо в main. Секция «Текущие приоритеты» направляет агента при неоднозначных решениях — если он видит два варианта рефакторинга, он выберет тот, что ближе к приоритетам.

Генерация конфигов для разных сред

Скрипт ниже берет PROJECT.md как источник и создает конфиги для каждой среды. Cursor, Copilot и Claude используют разные форматы и имена файлов — скрипт решает эту проблему. Запускайте его после каждого обновления PROJECT.md.

Шаг 2: Система памяти

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

mkdir -p .memory

.memory/decisions.md

Этот файл — лог архитектурных решений (ADR в миниатюре). Когда агент видит код, использующий Valkey, и не понимает, почему не Redis, — он найдет ответ здесь. Формат жесткий: решение, причина, влияние, статус. Без причины решение бесполезно — через месяц никто не вспомнит, почему так сделали.

# Архитектурные решения

## 2025-03-10: Redis -> Valkey
**Решение:** Мигрируем с Redis на Valkey (open-source fork)
**Причина:** Лицензионные изменения Redis 7.4+
**Влияние:** Совместимость 99%, нужно поменять docker-образ
**Статус:** В процессе

## 2025-02-20: Монолит -> модули
**Решение:** Разбить app.py на модульную структуру
**Причина:** Файл вырос до 3000 строк, невозможно поддерживать
**Паттерн:** src/modules/{name}/ с четырьмя файлами
**Статус:** Завершено

.memory/learnings.md

Технические инсайты, которые были получены опытным путем. Не теория из документации, а конкретные выводы вашей команды: «мы попробовали X, и вот что выяснили». Агент использует эти знания, чтобы не наступать на те же грабли — например, не предлагать pgvector для таблицы с 5 миллионами записей, если вы уже выяснили, что порог — миллион.

# Что мы узнали

## PostgreSQL + pgvector
- Для векторного поиска на < 1M записей pgvector достаточен
- IVFFlat индекс с lists=100 дает оптимальный balance recall/speed
- Для > 1M записей рассмотреть Qdrant

## GitHub Actions
- Матричные билды экономят время: тестируй Python 3.10 и 3.11 параллельно
- Кеширование pip: actions/cache@v3 с hashFiles('**/requirements*.txt')
- Self-hosted runners для тяжелых тестов (playwright)

.memory/patterns.md

Пошаговые рецепты для типовых задач проекта. Это ваш внутренний «кулинарный сборник»: агент читает его, когда ему нужно создать новый модуль или добавить эндпоинт, и следует именно вашему шаблону, а не своим представлениям о «правильной» структуре. Чем конкретнее шаги — тем точнее результат.

# Паттерны проекта

## Создание нового модуля
1. mkdir src/modules/{name}
2. Создать: __init__.py, routes.py, service.py, models.py, schemas.py
3. Зарегистрировать router в src/app.py
4. Создать tests/test_{name}.py
5. Добавить alembic миграцию если нужны таблицы

## Добавление API-эндпоинта
1. Схема в schemas.py (Pydantic v2)
2. Модель в models.py (SQLAlchemy)
3. Логика в service.py
4. Роут в routes.py (FastAPI)
5. Тест в tests/
6. Документация обновляется автоматически (FastAPI OpenAPI)

Что дальше

Вы создали фундамент: PROJECT.md как единый источник правды, систему памяти для накопления знаний и скрипт генерации конфигов. Агент теперь знает все о проекте.

В следующем уроке мы настроим CI/CD с AI-ревью, мультиагентную работу и мониторинг — чтобы агент не просто знал о проекте, а активно в нем работал.