ZAPLAKHOV DENIS

Представьте ситуацию: вы работаете над проектом, даёте задачу AI ассистенту, а в ответ получаете код, который не следует вашим стандартам. Импорты все в кучу, компоненты в PascalCase, а функции в snake_case. Вы объясняете ещё раз, и агенты снова делают по-своему. Круг замыкается.

Так было у меня. Работал я с OpenCode, Cursor, разными AI инструментами, давал задачи вроде "добавь страницу с блогом", а в ответ получал код, который не соответствовал моим правилам. Каждый раз требовались правки, уточнения, объяснения. Это отнимало время, демотивировало.

И тут я вспомнил про AGENTS.md.

>> ПРОБЛЕМА: 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" теперь работают без уточнений.

>> РЕАЛЬНЫЕ ПРИМЕРЫ ИЗ ПРОЕКТА

Вот как выглядит 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-архитектору.