README.md не работает как документация для AI-агентов — они не читают между строк, как люди. Решение — AGENTS.md, файл с конкретными правилами и примерами кода вместо описаний. После его внедрения доля задач, сделанных правильно с первой попытки, выросла с 60-70% до 95%, а время на разработку сократилось на 30%. Ниже — структура файла, реальные примеры правил из проекта и что именно сработало.
Стек AI-инструментов
Работал с OpenCode, Cursor и Claude Code — задачи вроде "добавь страницу с блогом" каждый раз возвращались с кодом, который не соответствовал стандартам проекта: импорты в кучу, компоненты то в PascalCase, то в snake_case. Каждый раз требовались правки, уточнения, объяснения заново.
Проблема: README.md не работает для AI
У большинства проектов есть README.md. Это файл, который описывает проект, как его запустить, как тестировать. Но README.md предназначен для людей. Люди умеют читать между строк, интерпретировать контекст, делать выводы. AI модели — нет.
Я создал README.md для проекта landing-79z, но это не помогло. Агенты всё равно делали ошибки: использовали относительные импорты вместо абсолютных, писали компоненты без "use client", не следовали Pip-Boy стилистике. README.md был слишком общим, слишком описательным. AI ассистентам нужны конкретики.
Тогда я создал AGENTS.md.
Решение: AGENTS.md — правила для AI
AGENTS.md — это не просто документация. Это набор правил, которые AI агенты реально следуют. Структура AGENTS.md отличается от README.md:
- Обзор проекта — что это за проект, стек технологий
- Система сборки — пакетный менеджер, команды
- Структура проекта — директории, файлы, назначение
- Конвенции кода — импорты, компоненты, стили, типы
- Именование — PascalCase, camelCase, kebab-case
- UI библиотеки — shadcn/ui, Radix UI, Lucide
- Важные правила — красные флаги, ограничения, критичные требования
Главное отличие — каждое правило сопровождается примером кода. Не просто "используйте абсолютные импорты", а:
// Абсолютные импорты через @/
import { PipBoyTerminal } from "@/components/pip-boy/pip-boy-terminal"
import { cn } from "@/lib/utils"
// Третьесторонние библиотеки
import { useState, useEffect } from "react"Примеры кода критичны. AI модели обучались на миллиардах строк кода, и они понимают паттерны, а не абстрактные инструкции. Показываешь пример — следует шаблону. Описываешь правило — интерпретирует по-разному.
Итог: продуктивность выросла на 40%
После создания AGENTS.md всё изменилось. Я снова дал задачу "добавь страницу с блогом", и агент следовал всем правилам:
- Использовал абсолютные импорты через
@/ - Добавил
"use client"для компонентов с хуками - Следовал Pip-Boy стилистике с неоновым зеленым цветом
#14f686 - Применял PascalCase для компонентов, camelCase для функций
- Использовал
cn()для объединения классов
Я посчитал метрики. До AGENTS.md 60-70% задач требовали правок. После — 95% задач были сделаны правильно с первой попытки. Время на разработку уменьшилось на 30%. Команды вида "просто сделай X" теперь работают без уточнений.
Хорошие правила ловят проблему до того, как код попадёт в репозиторий — но и уже написанный код стоит время от времени проверять на соответствие. Про автоматический аудит соответствия и мёртвого кода — в посте про плагин ponytail.
Реальные примеры из проекта
Вот как выглядит AGENTS.md для проекта landing-79z. Стек: Next.js 16, React 19, TypeScript, Tailwind CSS v4.
// Правило: "use client" для компонентов с хуками
"use client" // Обязательно для компонентов с хуками
import { useState } from "react"
interface ComponentProps {
title: string
children: React.ReactNode
className?: string
}
export function ComponentName({ title, children, className }: ComponentProps) {
const [isActive, setIsActive] = useState(false)
return (
{children}
)
}// Правило: Абсолютные импорты через @/
import type React from "react"
import type { Metadata } from "next"
import { PipBoyTerminal } from "@/components/pip-boy/pip-boy-terminal"
import { cn } from "@/lib/utils"// Правило: Именование
// Компоненты: PascalCase (PipBoyTerminal, BootScreen)
// Функции: camelCase (setActiveTab, cn)
// Переменные: camelCase (bootProgress, activeTab)
// Константы: SCREAMING_SNAKE_CASE или camelCase для объектов
// Типы: PascalCase (TabType, ComponentProps, StatsData)
// CSS классы: kebab-case (pip-box, nav-btn, content-area)Pro Tips: Как получить максимум
- Пишите правила, а не описания — AI модели не умеют читать между строк. Вместо "код должен быть чистым" пишите "используйте абсолютные импорты через @/".
- Добавляйте примеры кода — каждое правило должно быть иллюстрировано. Примеры кода работают лучше, чем тысячи слов описания.
- Используйте ⚠️ для критических правил — визуальные маркеры привлекают внимание, и агенты следуют критическим правилам точнее.
- Обновляйте AGENTS.md регулярно — если проект меняется, правила тоже должны обновляться. Устаревшие правила хуже, чем их отсутствие.
- Тестируйте правила на практике — дайте агенту задачу и посмотрите, где он ошибся. Добавьте правило, которое предотвратит эту ошибку в будущем.
Common Pitfalls: Где люди ошибаются
- Пишут README.md вместо AGENTS.md — это разные цели, разные форматы. README.md для людей, AGENTS.md для AI. Нужны оба.
- Создают слишком общие правила — "код должен быть чистым" не работает. Нужны конкретики: "используйте PascalCase для компонентов, camelCase для функций".
- Не обновляют документацию — если проект эволюционирует, правила тоже должны эволюционировать. Устаревшие правила сбивают агентов с толку.
- Забывают добавить примеры — без примеров AI модели интерпретируют правила по-разному. Примеры кода — это язык, который понимают AI.
- Используют сложный язык — простые правила понятнее, следование точнее. Пишите так, будто объясняете junior-разработчику, а не senior-архитектору.