Самоконфигурация -- память, инструкции, контекст

Проблема: агент забывает все

По умолчанию AI-агент — амнезиак. Каждая новая сессия начинается с чистого листа. Он не помнит:

• Ваши предпочтения (стиль кода, язык, фреймворки)
• Контекст проекта (архитектура, конвенции, зависимости)
• Предыдущие ошибки и решения
• Договоренности с прошлых сессий

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

Стандарт: файлы инструкций

Каждая среда имеет свой формат, но принцип один — текстовый файл в корне проекта, который агент читает автоматически:

Что писать в файл инструкций

Главное правило: файл инструкций — это не документация для людей, а контракт с агентом. Пишите то, что агент должен помнить между сессиями: стек, ограничения, запреты. Начните с минимального набора и расширяйте по мере накопления опыта.

Минимальный набор:

Обратите внимание на секцию «Что НЕ делать». Запреты работают лучше разрешений: агент знает слишком много паттернов и будет применять их по умолчанию, если вы явно не скажете «нет».

Продвинутый файл инструкций

В реальном проекте файл инструкций обрастает бизнес-контекстом, ограничениями версий и процедурами работы. Ключевое отличие от минимального: здесь есть почему (контекст решений), а не только что.

# Проект: E-commerce платформа

## Контекст
Платформа для B2B-продаж строительных материалов.
Пользователи: менеджеры отдела продаж (50 чел.), клиенты (2000+ компаний).
Основная проблема: ручная обработка заказов.

## Стек и версии
- Python 3.11.7 (НЕ обновлять -- совместимость с 1С-модулем)
- FastAPI 0.104.1
- PostgreSQL 15 + pgvector
- Redis для кеша и очередей
- Docker Compose для dev, K8s для prod

## Важные паттерны
- Все запросы к БД через Repository pattern (src/repositories/)
- Бизнес-логика в services (src/services/)
- Валидация через Pydantic v2 models
- Ошибки: кастомные exceptions в src/exceptions.py

## Тестирование
- Перед коммитом: pytest -x --tb=short
- Покрытие: минимум 80%
- Фикстуры: conftest.py в каждом модуле

## Как работать с этим проектом
1. Перед изменением -- прочитай README модуля
2. После изменения -- запусти тесты модуля
3. Если меняешь API -- обнови OpenAPI-схему
4. Если добавляешь endpoint -- добавь тест

## Запрещено
- Любые изменения в src/core/auth.py без ревью
- Прямые SQL-запросы (только через SQLAlchemy)
- Хардкод credentials (используй .env)
- Push в main без PR

Память агента: три подхода

Подход 1: Файловая память (простой)

Агент хранит знания в markdown-файлах, которые читает при старте:

project/
├── CLAUDE.md           # Основные инструкции
├── .memory/
│   ├── decisions.md    # Принятые решения и их причины
│   ├── learnings.md    # Что узнали в процессе
│   └── patterns.md     # Паттерны этого проекта

Как это работает:

1. Агент решает задачу и узнает что-то важное
2. Вы просите (или он сам предлагает): «запиши это в память»
3. Агент добавляет запись в соответствующий файл
4. При следующей сессии он читает эти файлы и помнит контекст

Важно: агент не телепат. Просто создать файл .memory/decisions.md недостаточно — нужно указать в CLAUDE.md (или аналоге), что при старте сессии он должен прочитать эти файлы. Иначе агент про них не узнает.

Пример записи в decisions.md:

## 2024-03-15: Выбор очереди сообщений

**Решение:** Redis Streams вместо RabbitMQ
**Причина:** У нас уже есть Redis для кеша, не хотим добавлять
еще один сервис. Нагрузка < 1000 msg/sec -- Redis справится.
**Альтернативы:** RabbitMQ (отвергнут -- лишний сервис),
Kafka (отвергнут -- overkill для наших объемов)

Подход 2: Структурированная память (средний)

Markdown-файлы хороши для начала, но плохо масштабируются. Когда фактов больше 50, агент начинает путаться в свободном тексте. JSON с четкой структурой позволяет агенту точнее находить нужное:

{
  "project_facts": [
    {
      "fact": "PostgreSQL 15 -- основная БД",
      "confidence": 1.0,
      "source": "docker-compose.yml",
      "added": "2024-03-10"
    },
    {
      "fact": "API rate limit: 100 req/min на пользователя",
      "confidence": 0.9,
      "source": "обсуждение в Slack",
      "added": "2024-03-12"
    }
  ],
  "code_patterns": [
    {
      "pattern": "Все роуты начинаются с /api/v1/",
      "examples": ["src/routes/orders.py:15", "src/routes/products.py:8"],
      "exceptions": ["src/routes/health.py -- /health без версии"]
    }
  ]
}

Поле confidence — не декорация. Агент может использовать его для приоритизации: факт с confidence: 1.0 (из кода) перевешивает факт с confidence: 0.6 (из обсуждения в чате).

Подход 3: Многоуровневая система (продвинутый)

~/.config/agent/           # Глобальные настройки (все проекты)
├── preferences.md         # Стиль кода, язык, привычки
├── tools.md               # Доступные MCP-серверы и инструменты
└── skills/                # Переиспользуемые навыки
    ├── git-workflow/
    ├── code-review/
    └── testing/

project/                   # Настройки проекта
├── CLAUDE.md              # Главный файл инструкций
├── AGENTS.md              # Описание субагентов
├── .memory/               # Память проекта
│   ├── architecture.md
│   └── decisions.md
└── .skills/               # Навыки, специфичные для проекта
    └── deploy/

Порядок загрузки (приоритет):

1. Глобальные настройки (ваши привычки)
2. Файл инструкций проекта (CLAUDE.md / .cursorrules)
3. Контекст текущей задачи
4. Память проекта (если запрошена или автозагрузка)

Агент обновляет свои инструкции: паттерны

Паттерн: «Запомни это»

Самый простой — вы явно просите агента обновить файл инструкций:

Вы: "Мы решили использовать Celery вместо ARQ для фоновых задач.
     Запиши это в CLAUDE.md и в decisions.md"

Агент: [обновляет CLAUDE.md -- добавляет Celery в стек]
       [добавляет запись в .memory/decisions.md с обоснованием]

Паттерн: «Учись на ошибках»

Агент сделал ошибку — вы поправили — агент записывает паттерн:

Вы: "Нет, в этом проекте мы не используем f-strings для SQL-запросов,
     используй параметризованные запросы. Запомни."

Агент: [добавляет в CLAUDE.md / .cursorrules]:
       "## Безопасность
        НИКОГДА не использовать f-strings для SQL.
        Только параметризованные запросы."

Паттерн: «Автоматическое обновление»

Агент обновляет инструкции по триггеру:

# Хук: после каждого успешного деплоя
# Агент обновляет .memory/deploy-history.md
# с версией, датой, и значимыми изменениями

Совместимость между средами

Вы можете использовать одни и те же принципы в разных средах:

# Генерация .cursorrules из CLAUDE.md
# (если вы работаете в обеих средах)

cat CLAUDE.md | head -50 > .cursorrules
# Или наоборот

# Универсальный подход: один source of truth
# CONTRIBUTING.md + project-specific agent config

Но head -50 — грубый подход. В реальных проектах лучше работает генерация из единого источника. Некоторые команды держат единый файл (CONTRIBUTING.md или PROJECT.md), из которого генерируют конфиги для разных агентов:

# scripts/generate_agent_configs.py
import yaml

with open('PROJECT.md') as f:
    project_info = f.read()

# Генерация для разных сред
with open('CLAUDE.md', 'w') as f:
    f.write(project_info)

with open('.cursorrules', 'w') as f:
    # Cursor имеет лимит -- берем только ключевое
    f.write(extract_key_rules(project_info))

with open('.github/copilot-instructions.md', 'w') as f:
    f.write(project_info)

Что дальше

В следующем уроке — CI/CD руками агента: автоматический code review, создание PR, запуск тестов, обновление документации.