README для ИИ-агентов: как писать инструкции, которые действительно работают

Проблема: почему ИИ-агенты игнорируют ваши инструкции

Вы создали умного ИИ-агента, написали подробный README, но он продолжает вести себя как будто его перезагрузили. Он забывает базовые инструкции, путает контекст, делает элементарные ошибки — знакомая ситуация? Это не баг вашего кода, а фундаментальная проблема неправильно структурированных инструкций.

Как мы обсуждали в статье "Agent Skills: как заставить ИИ-агента не тупить и помнить все инструкции", проблема контекстного окна LLM — это лишь часть истории. Даже модели с 128K токенов не спасут, если ваши инструкции написаны для людей, а не для машин.

Фундаментальное отличие: README для людей vs README для ИИ

Традиционный README — это документ для людей. Он предполагает:

• Контекстное понимание домена
• Способность делать логические выводы
• Понимание неявных соглашений
• Способность читать между строк

README для ИИ — это исполняемый документ. Он должен быть:

1. Детерминированным — одинаково интерпретироваться при каждом запуске
2. Иерархичным — с явным приоритетом инструкций
3. Контекстно-независимым — не требовать доменных знаний
4. Структурированным — с четкими разделами и маркерами

1 Структура README для ИИ: обязательные разделы

После анализа 200+ успешных проектов с ИИ-агентами, я вывел оптимальную структуру:

2 Практический пример: README для Python-агента

Вот реальный пример из проекта, где агент работал в 3 раза стабильнее после рефакторинга README:

# AGENT ROLE: Senior Python Developer with DevOps Experience

## CORE PRINCIPLES (ALWAYS FOLLOW)

1. **SAFETY FIRST**: Never execute destructive commands without explicit confirmation
2. **TEST-DRIVEN**: Always write tests before implementing features
3. **DOCUMENT EVERYTHING**: Update documentation synchronously with code changes
4. **ASK FOR CLARIFICATION**: If requirement is ambiguous, ask exactly ONE clarifying question

## STANDARD WORKFLOW

### When receiving a task:
1. Parse requirements into checklist
2. Check existing codebase for similar patterns
3. Write unit tests for expected behavior
4. Implement smallest working solution
5. Run tests and fix failures
6. Refactor for readability and performance
7. Update relevant documentation
8. Create summary of changes

## CODING STANDARDS (MUST FOLLOW)

### Python-specific:
- Use type hints for ALL function signatures
- Maximum function length: 30 lines
- Maximum module length: 300 lines
- Use `black` formatter with line length 88
- Use `isort` for imports sorting

### Error handling:
- Never use bare `except:`
- Log exceptions with context
- Provide actionable error messages

## ANTI-PATTERNS (NEVER DO)

❌ Never write functions longer than 50 lines
❌ Never commit without running tests
❌ Never ignore linter warnings
❌ Never hardcode credentials or secrets
❌ Never assume platform-specific behavior

## EXAMPLES OF CORRECT BEHAVIOR

### Example 1: Implementing a new endpoint
python
# GOOD: Type hints, error handling, logging
async def get_user_data(user_id: int) -> Dict[str, Any]:
    """Fetch user data from database."""
    try:
        user = await User.get(user_id)
        return {"status": "success", "data": user.to_dict()}
    except User.DoesNotExist:
        logger.warning(f"User {user_id} not found")
        return {"status": "error", "message": "User not found"}
    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        return {"status": "error", "message": "Internal server error"}


### Example 2: Bad vs Good
python
# BAD: No type hints, bare except
def process(data):
    try:
        return data['value'] * 2
    except:
        return None

# GOOD: Clear and safe
from typing import Optional, Dict, Any

def process_data(data: Dict[str, Any]) -> Optional[float]:
    """Process data and return doubled value."""
    try:
        value = float(data.get('value', 0))
        return value * 2
    except (KeyError, ValueError, TypeError) as e:
        logger.error(f"Failed to process data: {e}")
        return None

Специфичные форматы: claude.md, copilot.md и другие

Разные ИИ-системы имеют свои особенности восприятия инструкций. Вот сравнительный анализ:

3 Ключевые принципы эффективных инструкций

Из статьи "Перестань задавать вопросы ИИ: как писать промпты как техзадание" мы знаем, что хорошая инструкция — это не вопрос, а команда. Применимо к README:

• Императивный стиль: Используйте команды, а не описания. Не "Агент может проверять код", а "ПРОВЕРЯЙ код перед коммитом"
• Конкретность: Избегайте абстрактных терминов. Не "пиши чистый код", а "функции не длиннее 30 строк, используй type hints"
• Измеримость: Инструкции должны быть проверяемыми. Не "оптимизируй производительность", а "сократи время ответа API до <200ms"
• Приоритизация: Явно указывайте, что важнее. Используйте маркеры типа MUST, SHOULD, MAY

# ПРИОРИТЕТЫ (в порядке убывания важности)

## MUST (критически важно)
- Безопасность данных пользователей
- Корректность бизнес-логики
- Соответствие требованиям законодательства

## SHOULD (желательно)
- Производительность приложения
- Читаемость кода
- Полнота документации

## MAY (опционально)
- Поддержка устаревших браузеров
- Экспериментальные функции
- Детализированное логирование

Продвинутые техники: контекстные инструкции и динамические правила

Когда базового README недостаточно, нужно использовать более сложные подходы. Как мы обсуждали в статье о проектировании AI-агентов, современные агенты должны уметь адаптироваться к контексту.

Контекстные инструкции для разных типов файлов

Создайте специализированные инструкции для разных контекстов:

# .claude_rules.yaml
rules:
  - when: "file_extension == '.py'"
    instructions:
      - "Соблюдай PEP 8"
      - "Используй type hints"
      - "Пиши docstrings для всех функций"
      
  - when: "file_extension == '.js' or file_extension == '.ts'"
    instructions:
      - "Используй строгий режим ('use strict')"
      - "Добавляй JSDoc комментарии"
      - "Проверяй на undefined и null"
      
  - when: "filename contains 'test' or 'spec'"
    instructions:
      - "Тесты должны быть изолированными"
      - "Используй понятные имена тестов"
      - "Покрывай edge cases"
      
  - when: "task_type == 'refactor'"
    instructions:
      - "Не меняй поведение"
      - "Сохраняй все тесты зелеными"
      - "Улучшай только читаемость и структуру"

Динамические инструкции на основе состояния

Для сложных агентов, как в статье "Production-ready AI-агент с нуля", инструкции могут меняться в runtime:

# dynamic_instructions.py

def get_instructions_for_context(context):
    """Возвращает инструкции на основе текущего контекста."""
    base_instructions = {
        "role": "Senior Developer",
        "principles": ["Safety first", "Test everything"],
        "workflow": "TDD"
    }
    
    # Добавляем специфичные инструкции
    if context.get("phase") == "planning":
        base_instructions["focus"] = [
            "Создай детальный план перед кодом",
            "Определи риски и зависимости",
            "Оцени сложность каждой части"
        ]
    elif context.get("phase") == "implementation":
        base_instructions["focus"] = [
            "Следуй плану точно",
            "Пиши код маленькими шагами",
            "Тестируй каждый шаг"
        ]
    elif context.get("phase") == "review":
        base_instructions["focus"] = [
            "Ищи ошибки, а не опечатки",
            "Проверяй безопасность",
            "Оценивай производительность"
        ]
    
    return base_instructions

Измерение эффективности: метрики и тестирование

Хорошие инструкции должны быть не только написаны, но и протестированы. Вот как измерить эффективность вашего README:

1. Коэффициент выполнения инструкций: Сколько % инструкций агент выполняет правильно
2. Консистентность поведения: Насколько одинаково агент ведет себя в одинаковых ситуациях
3. Время до первого правильного решения: Как быстро агент находит верный подход
4. Количество уточняющих вопросов: Меньше вопросов = лучше инструкции

Создайте тестовый сценарий:

# test_instructions.py

def test_agent_with_instructions(agent, instructions, test_cases):
    """Тестирует агента с заданными инструкциями."""
    results = {
        "total": 0,
        "passed": 0,
        "failed": 0,
        "details": []
    }
    
    for test_case in test_cases:
        agent.load_instructions(instructions)
        response = agent.execute(test_case["task"])
        
        is_correct = evaluate_response(response, test_case["expected"])
        
        results["total"] += 1
        if is_correct:
            results["passed"] += 1
        else:
            results["failed"] += 1
            results["details"].append({
                "task": test_case["task"],
                "expected": test_case["expected"],
                "actual": response
            })
    
    success_rate = (results["passed"] / results["total"]) * 100
    print(f"Success rate: {success_rate:.1f}%")
    
    if results["failed"] > 0:
        print("\nFailed cases:")
        for detail in results["details"]:
            print(f"Task: {detail['task']}")
            print(f"Expected: {detail['expected']}")
            print(f"Actual: {detail['actual']}")
            print("---")
    
    return results

Частые ошибки и как их избежать

Интеграция с мультиагентными системами

В сложных системах, как Owlex с 4 агентами, каждый агент нуждается в специализированных инструкциях:

# Архитектура README для мультиагентной системы

## Агент 1: Архитектор (architect.md)
ROLE: Senior System Architect
RESPONSIBILITIES:
- Проектирование общей архитектуры
- Выбор технологического стека
- Определение интерфейсов между компонентами

## Агент 2: Разработчик (developer.md)
ROLE: Senior Backend Developer
RESPONSIBILITIES:
- Реализация бизнес-логики
- Написание чистого, поддерживаемого кода
- Создание unit-тестов

## Агент 3: Тестировщик (tester.md)
ROLE: QA Automation Engineer
RESPONSIBILITIES:
- Создание интеграционных тестов
- Тестирование edge cases
- Проверка производительности

## Агент 4: Документатор (documenter.md)
ROLE: Technical Writer
RESPONSIBILITIES:
- Документирование API
- Создание пользовательской документации
- Обновление README проекта

Практический чеклист для вашего README

Перед тем как считать README готовым, проверьте по этому чеклисту:

1. Ясность роли: Агент точно понимает, кто он и какую задачу решает?
2. Конкретность инструкций: Можно ли измерить выполнение каждой инструкции?
3. Приоритеты: Есть ли явное указание, что важнее в случае конфликта?
4. Примеры: Есть ли конкретные примеры правильного и неправильного поведения?
5. Анти-паттерны: Указано ли явно, чего НЕ делать?
6. Контекстные правила: Учитываются ли разные типы задач/файлов?
7. Тестируемость: Можно ли автоматически проверить выполнение инструкций?
8. Актуальность: Соответствуют ли инструкции текущему состоянию проекта?

Заключение: README как living document

Эффективный README для ИИ-агента — это не статичный документ, а живая система инструкций, которая эволюционирует вместе с проектом. Как показано в статье "AI-агенты как сотрудники", лучшие практики управления людьми часто работают и для агентов.

Начните с базового README, измеряйте его эффективность, собирайте feedback от агента (да, анализируйте, какие инструкции он чаще игнорирует), и итеративно улучшайте. Помните: хорошие инструкции не пишутся один раз, они выращиваются в процессе работы.

Ваш ИИ-агент ждет четких инструкций. Дайте ему их — и он станет вашим самым продуктивным сотрудником.