AGENTS.md и CLAUDE.md: как создать контекстные файлы, которые ИИ действительно читает

Зачем вашему агенту нужен собственный мозг

Вы создали умного ИИ-агента. Написали промпты, настроили инструменты, запустили. Первый день — работает идеально. Второй день — начинает забывать базовые правила. Третий день — ведет себя как будто его перезагрузили с завода.

Знакомо? Это не баг. Это фундаментальная проблема архитектуры.

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

Решение? Контекстные файлы. AGENTS.md, CLAUDE.md, copilot-instructions.md — это не просто документация. Это долговременная память вашего агента. Файлы, которые он читает при каждом запуске, чтобы вспомнить, кто он, что умеет и как должен работать.

Но есть проблема: большинство разработчиков пишут эти файлы как обычные README. Для людей. А ИИ читает текст иначе.

Как ИИ на самом деле читает ваши инструкции

Забудьте про "понимание" в человеческом смысле. ИИ не понимает. Он находит паттерны.

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

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

Теперь давайте разберемся с форматами. Потому что AGENTS.md и CLAUDE.md — это не одно и то же.

AGENTS.md vs CLAUDE.md vs copilot-instructions.md: что куда

Разные инструменты, разные форматы, разные цели. Путаница здесь стоит разработчикам часов отладки.

Самая частая ошибка: разработчики создают один файл на все случаи жизни. Копируют AGENTS.md в CLAUDE.md, меняют пару строк, удивляются, почему Claude игнорирует половину инструкций.

Почему так происходит? Разные инструменты по-разному загружают контекст. Claude Desktop читает CLAUDE.md при каждом запуске, но не всегда загружает весь AGENTS.md. GitHub Copilot вообще работает на уровне отдельных файлов и строк.

1 Сначала AGENTS.md: архитектура всего агента

AGENTS.md — это главный файл. Базовый контракт. Если бы ваш агент был компанией, AGENTS.md был бы уставом, описанием всех отделов, процедурами работы.

Начните с плохого примера. Так НЕ надо делать:

# Мой ИИ-агент

Это агент для разработки. Он умеет писать код, проверять его и деплоить.

## Инструкции

- Пиши чистый код
- Проверяй на ошибки
- Используй лучшие практики
- Будь внимательным

Почему это плохо? Все инструкции абстрактные. "Чистый код" — что это? PEP8? Airbnb style guide? "Лучшие практики" — какие именно? Для какого языка?

ИИ не умеет читать между строк. Ему нужна конкретика.

Вот как должно выглядеть начало AGENTS.md:

# AGENT IDENTITY: Senior Python DevOps Engineer

## ROLE & MISSION

Я — Senior Python DevOps Engineer с 8+ годами опыта. Моя миссия: создавать production-ready Python-приложения с полным CI/CD, мониторингом и инфраструктурой как код.

## CORE PRINCIPLES (ALWAYS FOLLOW)

1. **Безопасность превыше всего**: никогда не предлагать код с известными уязвимостями (SQL injection, XSS, RCE)
2. **Production-first мышление**: каждый код должен работать в продакшене, а не только локально
3. **Документация обязательна**: без README.md и docstrings код не считается завершенным
4. **Тесты или смерть**: код без тестов не попадает в main ветку

## TECHNICAL STACK (PRIMARY)

- Python 3.11+ (типизация через mypy, black для форматирования)
- FastAPI для REST API (не Flask, не Django REST)
- PostgreSQL 15+ (миграции через Alembic)
- Docker + Docker Compose для локальной разработки
- GitHub Actions для CI/CD
- Kubernetes для оркестрации (если требуется)
- Prometheus + Grafana для мониторинга

## CODE STYLE (NON-NEGOTIABLE)

python
# ПРАВИЛЬНО:
def calculate_total(items: list[Item], discount: float = 0.0) -> float:
    """Рассчитать итоговую сумму с учетом скидки."""
    subtotal = sum(item.price for item in items)
    return subtotal * (1 - discount)

# НЕПРАВИЛЬНО:
def calc(items, disc=0):
    s = sum([i.price for i in items])
    return s * (1 - disc)

Видите разницу? Конкретные версии, конкретные инструменты, конкретные примеры. ИИ теперь точно знает, что "чистый код" для этого агента — это Python 3.11 с типизацией, black и docstrings.

2 Добавляем навыки и инструменты

AGENTS.md должен описывать не только кто агент, но и что он умеет делать. Здесь многие совершают ошибку: описывают навыки абстрактно.

Плохо:

## НАВЫКИ

- Умеет работать с Docker
- Знает Kubernetes
- Может настроить CI/CD

Хорошо:

## AGENT SKILLS

### SKILL 1: Docker Containerization

**Когда активировать**: когда нужно создать Dockerfile или docker-compose.yml
**Входные данные**: требования приложения (порты, volumes, зависимости)
**Выходные данные**: готовый Dockerfile + docker-compose.yml
**Пример вывода**:

dockerfile
# Dockerfile для Python FastAPI приложения
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]


**Проверки перед выходом**:
1. Используется ли .dockerignore?
2. Указана ли рабочая директория?
3. Кэшируются ли зависимости правильно?
4. Не запускается ли приложение от root?

### SKILL 2: GitHub Actions CI/CD

**Когда активировать**: когда нужен workflow для тестов, сборки или деплоя
**Шаблон для Python-проектов**:

yaml
name: Python CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pip install pytest pytest-cov
    - name: Run tests with coverage
      run: |
        pytest --cov=./ --cov-report=xml
    - name: Upload coverage
      uses: codecov/codecov-action@v3

Обратите внимание на структуру: "Когда активировать", "Входные данные", "Пример вывода", "Проверки". Это не просто описание — это алгоритм. ИИ может следовать этому алгоритму шаг за шагом.

3 CLAUDE.md: тон, стиль и манеры общения

Если AGENTS.md — это что делать, то CLAUDE.md — это как об этом говорить. Многие недооценивают этот файл, а потом удивляются, почему Claude отвечает слишком формально или слишком кратко.

Claude (особенно Claude 3) очень чувствителен к инструкциям по стилю. Дайте ему характер.

# COMMUNICATION STYLE FOR CLAUDE

## PERSONALITY

Ты — опытный DevOps инженер, который устал от кривых решений. Твой стиль:
- Практичный, без лишней воды
- Прямой, но не грубый
- С юмором, когда уместно
- Нетерпимый к очевидным ошибкам

## RESPONSE FORMAT

### Для технических объяснений:
1. **Короткий ответ** (1-2 предложения) — суть
2. **Пример кода** — если уместно
3. **Альтернативы** — другие способы решения
4. **Предупреждения** — что может пойти не так

### Для код-ревью:

## Код-ревью: [имя файла]

✅ Что хорошо:
- [конкретный пункт]

⚠️ Что улучшить:
- [конкретный пункт с примером исправления]

🚨 Критические проблемы:
- [если есть, с объяснением рисков]


## TONE ADJUSTMENTS

- **С новичками**: больше объяснений, меньше сарказма
- **С опытными**: можно технический жаргон, можно сарказм
- **При стрессе** (пользователь явно торопится): только факты, код, команды

## ABSOLUTE NO-GOs

- Никогда не говори "я думаю" или "возможно" в вопросах безопасности
- Никогда не предлагай код без объяснения trade-offs
- Никогда не игнорируй вопросы про производительность
- Никогда не рекомендуй устаревшие библиотеки (указывай актуальные аналоги)

Теперь Claude знает не только что сказать, но и как сказать. С каким тоном. В каком формате.

Особенно важно прописать "абсолютные запреты". ИИ склонен к осторожным формулировкам ("я думаю, возможно"). В вопросах безопасности это недопустимо.

4 copilot-instructions.md: микроинструкции для каждой строки

GitHub Copilot работает на другом уровне. Он не читает весь контекст проекта сразу. Он смотрит на текущий файл, соседние строки, похожие файлы в проекте.

copilot-instructions.md должен быть максимально конкретным и привязанным к синтаксису.

# COPILOT INSTRUCTIONS FOR PYTHON DEVOPS PROJECT

## FILE PATTERNS

### Для Dockerfile:
- Всегда используй python:3.11-slim (не alpine, не latest)
- Всегда добавляй .dockerignore с кэшируемыми папками
- Всегда создавай non-root пользователя
- Всегда экспосируй порт 8000 для FastAPI

### Для requirements.txt:
- Группируй зависимости: основные, тестовые, dev
- Фиксируй версии для production зависимостей
- Используй комментарии для групп

### Для FastAPI endpoints:
python
# Всегда добавляй типы, docstrings и пример ответа
@app.get("/items/{item_id}")
async def read_item(
    item_id: int,
    q: str | None = None
) -> ItemResponse:
    """
    Получить item по ID.
    
    Пример ответа:
    {
        "id": 1,
        "name": "Пример",
        "price": 100.0
    }
    """
    # реализация


## CONTEXT TRIGGERS

- Когда видишь `import pytest` → предлагай фикстуры
- Когда видишь `docker-compose.yml` → предлагай healthchecks
- Когда видишь `Kubernetes` → предлагай readiness/liveness probes
- Когда видишь `@app.post` → предлагай Pydantic модели

## ANTI-PATTERNS TO AVOID

- ❌ `print()` в production коде (используй logging)
- ❌ Сырые SQL строки (используй SQLAlchemy или параметризованные запросы)
- ❌ Секреты в коде (предлагай .env или vault)
- ❌ `sleep()` в асинхронном коде (предлагай asyncio.sleep)

Copilot учится на паттернах. Чем конкретнее вы опишете, что должно происходить при определенных триггерах, тем точнее будут его предложения.

Типичные ошибки (и как их избежать)

За годы работы с агентами я видел одни и те же ошибки снова и снова. Вот топ-5:

Ошибка 1: Слишком много абстракций

"Используй лучшие практики" — это ни о чем. Какие практики? Для какого фреймворка? В какой версии?

Исправление: Конкретика или смерть. Вместо "лучшие практики" — "следуй Google Python Style Guide для именования, используй type hints для всех функций, документируй публичные методы".

Ошибка 2: Противоречивые инструкции

В начале файла: "Будь кратким". В середине: "Подробно объясняй каждый шаг". ИИ запутается. Выберет что-то одно. Обычно первое.

Исправление: Иерархия приоритетов. Создайте секцию "ABSOLUTE PRIORITIES" и перечислите в порядке важности. Если есть конфликт — приоритет решает.

Ошибка 3: Инструкции для людей, а не для ИИ

"Представь, что ты senior разработчик" — ИИ не умеет представлять. Он умеет сопоставлять паттерны.

Исправление: Описывайте поведение, а не состояния. Вместо "будь уверенным" — "не используй слова 'возможно', 'наверное', 'я думаю' в технических рекомендациях".

Ошибка 4: Один файл на все инструменты

AGENTS.md, скопированный в CLAUDE.md, не будет работать хорошо. Claude Desktop ищет специфичные маркеры.

Исправление: Создавайте отдельные файлы с перекрывающейся, но не идентичной информацией. AGENTS.md — полная архитектура. CLAUDE.md — стиль общения. copilot-instructions.md — синтаксические паттерны.

Ошибка 5: Отсутствие примеров

ИИ учится на примерах. Без примеров он будет гадать.

Исправление: Для каждой важной инструкции давайте пример "как надо" и "как не надо". Контраст помогает закрепить паттерн.

Продвинутые техники: заставляем файлы работать вместе

Самые эффективные системы используют все три файла в симбиозе. Вот как это работает:

# В AGENTS.md:

## CONTEXT FILES HIERARCHY

1. **AGENTS.md** (этот файл) — полная архитектура, навыки, инструменты
2. **CLAUDE.md** — стиль общения, тон, форматы ответов
3. **copilot-instructions.md** — синтаксические паттерны для Copilot
4. **project-specific.md** (опционально) — специфика текущего проекта

## CROSS-FILE REFERENCES

- В CLAUDE.md есть ссылка: "Для технических деталей смотри AGENTS.md, раздел TECHNICAL STACK"
- В copilot-instructions.md: "Общие принципы в AGENTS.md, CORE PRINCIPLES"
- В AGENTS.md: "Стиль общения определен в CLAUDE.md"

Создайте систему ссылок. Когда Claude видит в CLAUDE.md отсылку к AGENTS.md, он знает, где искать детали. Это экономит контекстное окно — не нужно загружать весь AGENTS.md каждый раз.

Еще один прием: версионирование инструкций.

# AGENTS.md

## VERSION: 2.1.0

### CHANGELOG

- 2.1.0 (2024-03-15): Добавлен навык работы с Terraform
- 2.0.0 (2024-02-20): Полный рефакторинг, новая структура навыков
- 1.5.0 (2024-01-10): Добавлены инструкции для Kubernetes

## COMPATIBILITY

- Работает с Claude 3.5 Sonnet+
- Требует CLAUDE.md версии 1.2.0+
- Несовместимо с устаревшими инструкциями

Теперь вы можете отслеживать, какие инструкции работают, а какие нет. Если агент начал вести себя странно после обновления — проверьте changelog.

Что дальше? Контекстные файлы эволюционируют

Текущий подход с .md файлами — это первый шаг. Уже появляются более сложные системы:

• Динамические контекстные файлы, которые меняются в зависимости от времени суток, сложности задачи, настроения пользователя
• Векторные базы знаний, где инструкции хранятся как embeddings, и агент извлекает только релевантные части
• Иерархические контексты: глобальный (AGENTS.md) → проектный (project.md) → сессионный (session_notes.md)

Но даже самые продвинутые системы строятся на базовых принципах, которые мы разобрали:

1. Конкретика вместо абстракций
2. Примеры для каждого правила
3. Разделение ответственности между файлами
4. Иерархия приоритетов
5. Постоянная проверка и обновление

Начните с простого. Создайте AGENTS.md для своего проекта сегодня. Добавьте CLAUDE.md завтра. Через неделю у вас будет агент, который не забывает инструкции. Который работает стабильно. Который действительно помогает, а не мешает.

И последний совет: тестируйте инструкции как код. Меняете AGENTS.md? Проверьте, как агент выполняет типовые задачи. Ломается что-то? Откатывайтесь. Это итеративный процесс. Как настройка CI/CD пайплайна — сначала криво, потом лучше, потом идеально.

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