AGENTS.md и документация

Описание модуля

Этот модуль учит документировать проекты для AI-агентов (Claude Code, Gemini, Cursor и др.).

Вы узнаете, как создать правильную документацию, которая позволяет AI-инструментам генерировать код высокого качества с первого раза, экономя часы на итерациях.

Структура модуля

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

Файл: урок-01-зачем-документировать.md

Что изучите:

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

Примеры:

• Сценарий: добавить аутентификацию в React без документации vs с документацией
• Диаграмма: сравнение времени и количества итераций

Практика: Оценка вашего проекта с помощью чек-листа

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

Файл: урок-02-agents-md.md

Что изучите:

• Что такое AGENTS.md и стандарт Linux Foundation
• 6 основных секций AGENTS.md:
  • Project overview
  • Development conventions
  • Testing
  • Build & deploy
  • Architecture
  • Do’s and Don’ts
• Как заполнить каждую секцию
• Полный пример для Python Flask API

Практика: Создание AGENTS.md для своего проекта

Урок 3: CLAUDE.md — специфика для Claude

Файл: урок-03-claude-md.md

Что изучите:

• Отличие CLAUDE.md от AGENTS.md
• Оптимальный размер: до 300 строк
• 6 секций CLAUDE.md:
  • Project Description
  • Technology Stack
  • Code Style & Conventions
  • Key Commands
  • Important Rules
  • Examples
• Иерархия файлов (глобальный, корневой, локальный)
• Стратегия итеративного улучшения

Практика: Создание CLAUDE.md и тестирование с Claude Code

Урок 4: GEMINI.md и .cursorrules

Файл: урок-04-gemini-md-cursorrules.md

Что изучите:

• GEMINI.md для Google Gemini CLI
• .cursorrules для Cursor IDE
• Сравнительная таблица всех 4 форматов
• Когда использовать какой файл
• Как избежать дублирования между файлами

Таблица сравнения:

Практика: Создание трёхуровневой документации

Урок 5: Шаблоны для типовых проектов

Файл: урок-05-шаблоны.md

Что изучите:

• 4 готовых шаблона:
  1. React Web App (Next.js + TypeScript)
  2. FastAPI Backend (Python)
  3. Data Pipeline (Python + pandas/dbt)
  4. Mobile App (React Native + Expo)
• 5-шаговая адаптация шаблона под свой проект
• Как тестировать документацию с Claude Code
• Где найти больше примеров

Практика: Выбрать шаблон, адаптировать и использовать

Быстрый старт

За 30 минут

1. Прочитай Урок 1 (зачем нужно)
2. Выбери тип своего проекта из Урока 5
3. Скопируй нужный шаблон
4. Адаптируй за 5 шагов
5. Сохрани как CLAUDE.md

За 2 часа (полный вариант)

1. Прочитай все 5 уроков
2. Выбери тип проекта
3. Создай AGENTS.md (используя структуру из Урока 2)
4. Создай CLAUDE.md (сокращённую версию из Урока 3)
5. Добавь примеры из своего кода
6. Попробуй с Claude Code
7. Улучши на основе результатов

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

Основное

1. Документация = контекст для AI

   • AI-агент как новый разработчик, который нуждается в онбординге
   • Документация позволяет сэкономить 5+ часов на итерациях

2. Выбор формата зависит от инструментов

   • AGENTS.md: универсальный стандарт для всех
   • CLAUDE.md: специфично для Claude Code (до 300 строк)
   • GEMINI.md: для Google Gemini CLI
   • .cursorrules: для Cursor IDE

3. Размер имеет значение

   • AGENTS.md: 300-500 строк (достаточно информации)
   • CLAUDE.md: до 300 строк (быстро читается)
   • Слишком длинные файлы теряют эффективность

4. Примеры важнее описаний

   • AI учится на примерах кода из проекта
   • Даже один пример лучше, чем три параграфа описания

5. Итеративное улучшение

   • После каждой ошибки AI добавляй правило в документацию
   • Используй её как learning feedback loop

Структура файлов в этом модуле

модуль-2.6-agents-md/
├── README.md                          (этот файл)
├── урок-01-зачем-документировать.md   (286 строк)
├── урок-02-agents-md.md               (774 строк)
├── урок-03-claude-md.md               (приблизительно 350 строк)
├── урок-04-gemini-md-cursorrules.md   (приблизительно 400 строк)
└── урок-05-шаблоны.md                 (приблизительно 450 строк)

Итого: ~2250 строк качественного контента на русском языке

Практические задачи по модулю

Обязательные

1. Создать CLAUDE.md для своего проекта

   • Минимум 100 строк
   • Включить все 6 секций
   • Добавить примеры из своего кода

2. Протестировать с Claude Code

   • Попросить выполнить простую задачу
   • Оценить качество результата
   • Если ошибки → добавить правило

Дополнительные

3. Создать полный AGENTS.md

   • Расширенная версия CLAUDE.md
   • 300-500 строк
   • Все 6 основных секций

4. Попробовать другие инструменты

   • Создать GEMINI.md для Gemini CLI
   • Создать .cursorrules для Cursor IDE

5. Поделиться с командой

   • Закоммитить в репо
   • Попросить feedback
   • Улучшить на основе комментариев

Связь с другими модулями

• Трек 2, Модуль 2.1-2.5: Основы работы с Claude Code, практика кодирования
• Модуль 2.6: Документирование для AI (этот модуль)
• Модуль 2.7+: Интеграция AI в рабочий процесс

Модуль 2.6 — важный шаг для перехода от экспериментов к продуктивному использованию AI в разработке.

Рекомендуемый порядок обучения

1. Урок 1: Понимание проблемы      (15 минут)
2. Урок 2: Стандарт AGENTS.md      (30 минут)
3. Урок 3: CLAUDE.md специфика     (25 минут)
4. Урок 4: Другие форматы          (20 минут)
5. Урок 5: Шаблоны + практика      (60+ минут)

Общее время: 2-3 часа обучения + практика

Ресурсы

Официальные источники

• Claude Code Docs: https://claude.ai/help/claude-code
• Awesome Claude Code: https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know

Стандарты

• AGENTS.md Spec: Открытый стандарт Linux Foundation
• CLAUDE.md: Anthropic внутренний стандарт
• GEMINI.md: Google Gemini стандарт
• .cursorrules: Cursor IDE стандарт

Примеры

• Большие open source проекты с AGENTS.md
• Примеры CLAUDE.md в awesome-claude-code
• Примеры .cursorrules в Cursor IDE документации

Часто задаваемые вопросы

Q: Нужна ли мне документация, если я работаю один? A: Да! Даже для одного разработчика документация экономит часы на работе с AI-агентами.

Q: Что выбрать: AGENTS.md или CLAUDE.md? A: Начни с CLAUDE.md (проще, быстрее). Если много разработчиков — создай AGENTS.md.

Q: Как часто обновлять документацию? A: CLAUDE.md → часто (после каждой ошибки AI). AGENTS.md → при больших изменениях проекта.

Q: Можно ли использовать один файл для всех инструментов? A: Да, AGENTS.md поддерживается всеми. Но CLAUDE.md может быть специфичнее для Claude.

Q: Сколько времени займёт создание документации? A: Минимально: 30 минут (CLAUDE.md). Полностью: 2-3 часа (AGENTS.md).

Обратная связь

Если у вас есть вопросы или предложения по модулю:

• Создайте issue в репо
• Поделитесь своей документацией в сообществе
• Дайте feedback на результаты

Для кого: Те, кто хочет максимальную отдачу от AI-ассистентов.

После модуля вы сможете: Создать CLAUDE.md, agents.md, .cursorrules и шаблоны для проектной документации.

Готовы начать? Откройте Урок 1: “Зачем документировать проект для AI”