Урок 1: Зачем документировать проект для AI

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

• Понимать, почему AI-агент нуждается в документации (как новый разработчик в команде)
• Различать типы memory-файлов для агентов: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules
• Видеть различие в качестве результатов между документированным и недокументированным проектом
• Планировать документацию как часть разработки, а не бонус

Проблема: AI как новый разработчик

Представьте: вы передали свой проект новому разработчику в команде. Он приходит в первый день и…

Без информации агент сталкивается с:

[-] "Какая архитектура проекта?"
[-] "Какие соглашения кодирования?"
[-] "Какие зависимости я могу использовать?"
[-] "Как запустить тесты?"
[-] "Какой style guide нужно соблюдать?"
[-] "Какие ошибки часто случаются?"

Результат:

• Агент делает догадки
• Генерирует код, не соответствующий стилю проекта
• Пропускает важные соглашения
• Требует многочисленных итераций для исправления
• Тратит контекст на уточнения вместо полезной работы

С информацией:

[+] AGENTS.md содержит все соглашения
[+] CLAUDE.md объясняет особенности проекта
[+] .cursorrules содержит запреты и best practices
[+] Агент знает, что и как делать с первого раза

Аналогия: онбординг нового разработчика

Решение: Memory-файлы для AI

Существует несколько стандартов инструктирования AI-агентов:

AGENTS.md
├─ Открытый стандарт (Linux Foundation)
├─ Поддержка: все CLI инструменты
└─ Для: документирования проекта под все AI-инструменты

CLAUDE.md
├─ Специфичен для Anthropic Claude
├─ Рекомендуемый размер: <300 строк
└─ Для: интеграции с Claude Code

GEMINI.md
├─ Специфичен для Google Gemini
└─ Для: интеграции с Gemini CLI

.cursorrules
├─ Для Cursor IDE
└─ Просто текстовый файл с инструкциями

Статистика использования

Проекты, использующие AGENTS.md:

Середина 2025: стандарт опубликован
Конец 2025: 30,000+ проектов
Начало 2026: 60,000+ проектов

Почему растёт?

• Разработчики видят улучшение качества AI-генерируемого кода
• Документирование проекта полезно не только для AI, но и для людей
• Становится проще писать issue и код review для других разработчиков

До и после: качество работы агента

Сценарий: добавить функцию аутентификации в React приложение

До (без документации):

Запрос: "Добавь логин на странице"

Агент генерирует:
[-] React class component (vs функциональные компоненты в проекте)
[-] localStorage для хранения токена (vs httpOnly cookies)
[-] console.log для отладки (vs структурированное логирование)
[-] CSS-in-JS (vs Tailwind CSS как в проекте)
[-] fetch API (vs axios как в проекте)

Результат: 5-7 итераций переписывания
Время: 2+ часа
Контекст израсходован

После (с CLAUDE.md):

CLAUDE.md содержит:
[+] "Используем функциональные компоненты с hooks"
[+] "Стиль кода: Tailwind CSS"
[+] "HTTP клиент: axios"
[+] "Аутентификация: JWT в httpOnly cookies"
[+] "Не используем: localStorage, class components"

Агент генерирует:
[+] Функциональный компонент с hooks
[+] Правильное хранилище токена
[+] Структурированное логирование
[+] Tailwind для стилей
[+] axios для запросов

Результат: код уходит в PR с первого раза
Время: 15-30 минут
Контекст сэкономлен для сложной логики

Диаграмма: с контекстом vs без

graph TD
    A["Агент начинает задачу"] --> B{Есть ли AGENTS.md?}

    B -->|НЕТ| C["Агент не знает:<br/>- архитектуру<br/>- соглашения<br/>- запреты"]
    C --> D["Генерирует код на основе<br/>общих знаний"]
    D --> E["[-] Не соответствует<br/>стилю проекта"]
    E --> F["Итерация 1:<br/>Fix стиль кода"]
    F --> G["Итерация 2:<br/>Fix зависимости"]
    G --> H["Итерация 3:<br/>Fix архитектуру"]
    H --> I["3+ часа<br/>контекст израсходован"]

    B -->|ДА| J["Агент знает:<br/>- архитектуру<br/>- соглашения<br/>- запреты"]
    J --> K["Генерирует код<br/>сразу правильный"]
    K --> L["[+] Соответствует<br/>проекту"]
    L --> M["1-2 итерации<br/>для деталей"]
    M --> N["30 минут<br/>контекст сэкономлен"]

    style E fill:#ffcccc
    style I fill:#ffcccc
    style L fill:#ccffcc
    style N fill:#ccffcc

Практика: оцените свой проект

Ответьте на вопросы про ваш проект:

1. Архитектура:

   • Документирована ли структура папок?
   • Ясна ли цель каждого модуля?

2. Соглашения кодирования:

   • Написаны ли стандарты именования переменных?
   • Зафиксирован ли style guide?
   • Есть ли примеры правильного и неправильного кода?

3. Запреты:

   • Понятно ли, какие паттерны НЕЛЬЗЯ использовать?
   • Описаны ли антипаттерны?

4. Тестирование:

   • Понятно ли, как запустить тесты?
   • Ясно ли целевое покрытие?

5. Сборка и деплой:

   • Задокументированы ли команды build?
   • Ясна ли процедура развёртывания?

Если ответов “нет” больше 3 — пора создавать AGENTS.md / CLAUDE.md.

Попробуйте сами

Задание: найдите проблему в AI-генерируемом коде

Вот фрагмент, сгенерированный AI для React-проекта без документации:

// Без CLAUDE.md агент не знает о требованиях

class LoginComponent extends React.Component {
  constructor(props) {
    super(props);
    this.state = { token: null };
  }

  handleLogin = async (username, password) => {
    const response = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ username, password })
    });
    const data = await response.json();
    localStorage.setItem('token', data.token);  // [-] Небезопасно!
    this.setState({ token: data.token });
  }

  render() {
    return (
      <div style={{ color: 'blue', padding: '20px' }}>  // [-] Inline styles!
        <input type="text" />
        <button onClick={this.handleLogin}>Вход</button>
        {console.log('Debug:', this.state)}  // [-] console.log!
      </div>
    );
  }
}

Проблемы:

1. Class component вместо functional
2. localStorage вместо httpOnly cookies
3. Inline styles вместо Tailwind
4. console.log вместо структурированного логирования
5. Нет обработки ошибок
6. Нет валидации

С CLAUDE.md:

## Технический стек

- React 18+
- Функциональные компоненты с hooks
- TypeScript
- Tailwind CSS для стилей
- axios для HTTP
- JWT в httpOnly cookies
- Структурированное логирование через winston

## Development conventions

### Компоненты
- [+] Используйте функциональные компоненты
- [-] НЕ используйте class components
- [+] Применяйте TypeScript для типизации
- [-] НЕ пишите console.log — используйте logger

### Стили
- [+] Tailwind CSS классы
- [-] НЕ используйте inline styles
- [+] При необходимости CSS-модули

Агент с таким файлом напишет правильно с первого раза.

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

1. AI-агент как новый разработчик: ему нужна документация для работы на максимуме. Без неё — много итераций и ошибок.

2. Memory-файлы экономят контекст: вместо уточнений агент сразу пишет правильный код. Это означает больше полезной работы в одном запросе.

3. Существует несколько стандартов:

   • AGENTS.md (универсальный, Linux Foundation)
   • CLAUDE.md (для Claude Code)
   • GEMINI.md (для Google Gemini)
   • .cursorrules (для Cursor IDE)

4. Документация полезна не только для AI: она помогает людям, новым разработчикам, и вам самим через месяц.

5. Начните с малого: даже простой CLAUDE.md в 50-100 строк улучшит качество результатов в 5+ раз.

Следующий урок

Урок 2: AGENTS.md — открытый стандарт

Узнаете:

• Полная структура AGENTS.md по spec
• Как заполнить каждую секцию
• Готовые примеры для разных типов проектов
• Как инструменты находят и используют AGENTS.md