AGENTS.md: как объяснить ИИ-агенту правила своего проекта

AGENTS.md помогает объяснить ИИ-агенту, как работать именно в вашем проекте: где искать код, чем запускать проверки и какие изменения требуют особой осторожности. Вместо повторения одних правил в каждом запросе вы храните их рядом с исходниками.

Но файл не исправляет ошибку самостоятельно. Проверим его пользу на маленькой библиотеке задач: сформулируем правила, найдём дефект и закрепим исправление тестом. Все примеры рассчитаны на Node.js 22 или новее, установка пакетов не нужна.

Это учебный разбор кода с воспроизводимыми командами. Мы не сравнивали качество ответов разных агентов и не измеряли, насколько файл улучшает результат. Такой эксперимент вы сможете провести отдельно.

Что записывать в AGENTS.md

Это обычный Markdown-файл с инструкциями для программирующего агента. В нём удобно хранить сведения о проекте, команды и рабочие ограничения. Формат поддерживают разные инструменты, перечисленные на сайте AGENTS.md.

Это полезное разделение обязанностей, а не требование к названиям всех файлов. Для нашей библиотеки достаточно README.md с запуском и короткого AGENTS.md. Не переносите туда всю документацию: агенту нужны решения, которые влияют на текущую работу.

Как определить область действия правил

Учитывайте конкретный инструмент. Codex при запуске собирает инструкции по цепочке от глобального уровня через корень проекта к текущему каталогу. Более глубокие правила уточняют общие; AGENTS.override.md заменяет AGENTS.md в той же папке. Это не автоматическое чтение всех подобных файлов во всём репозитории. Порядок описан в документации Codex.

В GitHub Copilot поддержка инструкций зависит от используемой возможности: не переносите поведение Codex на все режимы другого продукта. Проверьте таблицу поддержки Copilot перед настройкой.

Соберите мини-проект и добавьте шаблон

Создайте отдельную папку tasks-lab. В ней будут tasks.mjs, tasks.test.mjs и приведённый ниже AGENTS.md. Если повторяете пример в существующем проекте, согласуйте текст с его действующими правилами, не заменяйте корневой файл вслепую.

# Правила проекта Tasks

## Назначение
Мини-библиотека задач. Node.js 22+, модули .mjs.
Runtime-зависимостей нет. Сохраняй createTask(title).

## Перед изменением
Прочитай tasks.mjs и tasks.test.mjs.
Меняй только файлы, необходимые для текущей задачи.
Не отменяй чужие изменения и не устанавливай зависимости.

## Исправление ошибок
Сначала добавь тест, воспроизводящий ошибку, и запусти его.
Убедись, что он падает по ожидаемой причине.
Затем исправь код и выполни node --test tasks.test.mjs.
Название задачи после trim() не может быть пустым.

## Перед ответом
Просмотри git diff, если каталог находится в Git.
Перечисли изменённые файлы, команды и фактические результаты.
Если проверка не запускалась, скажи об этом прямо.

Здесь каждое правило можно проверить. Просьба писать хороший код не задаёт наблюдаемого результата. Точная команда проверки позволяет сверить запуск и вывод. Ограничение зависимостей защищает учебную задачу от ненужного усложнения.

Для большого проекта добавьте карту важных папок и точные команды отдельных подсистем. Убирайте устаревшие пункты вместе с изменением сборки. Инструкция, которая просит запустить удалённый скрипт, мешает больше, чем отсутствие этого пункта.

Отделяйте постоянное правило от задания на сегодня. Ограничение внешних пакетов пригодится следующей сессии. Исправление пустого названия относится к текущему запросу. Если записывать в общий файл каждую временную цель, следующему агенту придётся угадывать, какие пункты ещё действуют.

Проверяйте и область запрета. Полный запрет менять тесты противоречит нашему процессу исправления ошибок. Точнее запретить удаление проверок существующего поведения и разрешить добавление регрессионных тестов для новых дефектов. Так ограничение сохраняет смысл и оставляет агенту путь к завершению задачи.

Найдите ошибку раньше исправления

Начальный tasks.mjs проверяет длину исходной строки, а обрезает пробелы уже после проверки:

export function createTask(title) {
  if (typeof title !== 'string' || title.length === 0) {
    throw new Error('Название обязательно');
  }
  return { title: title.trim(), done: false };
}

Сохраните первый тест в tasks.test.mjs. Он подтверждает полезное поведение, но пока не покрывает ошибку:

import test from 'node:test';
import assert from 'node:assert/strict';
import { createTask } from './tasks.mjs';

test('убирает пробелы вокруг названия', () => {
  assert.deepEqual(createTask('  Купить хлеб  '), {
    title: 'Купить хлеб', done: false,
  });
});

Запустите node --test tasks.test.mjs. Встроенный модуль node:test и флаг --test описаны в документации Node.js. Один зелёный тест ещё не доказывает правильность всех входных данных.

Добавьте регрессионный тест в тот же файл. Он фиксирует конкретный дефект, чтобы следующая правка не вернула его:

test('отклоняет название из пробелов', () => {
  assert.throws(() => createTask('   '), /Название обязательно/);
});

Замените функцию: сначала убедитесь, что пришла строка, затем нормализуйте её и проверьте результат.

export function createTask(title) {
  if (typeof title !== 'string') {
    throw new Error('Название обязательно');
  }
  const normalizedTitle = title.trim();
  if (normalizedTitle.length === 0) {
    throw new Error('Название обязательно');
  }
  return { title: normalizedTitle, done: false };
}

Проверьте работу агента по следам

Для собственного сравнения сделайте две копии исходного проекта. Во вторую добавьте AGENTS.md. В отдельных новых сессиях одного инструмента и одной модели отправьте одинаковый запрос: «Исправь создание задач с названием из пробелов, сохрани остальное поведение».

Зафиксируйте условия и сравните diff, наличие регрессионного теста, порядок команд и честность итогового отчёта. Проверяйте команды из того же каталога, который указали агенту. Не добавляйте подсказки только одной сессии. Один повтор покажет наблюдение для двух запусков, но не установит общее преимущество: ответы могут различаться между повторами.

Полезно заранее завести короткую запись результата: рабочая папка, версия инструмента, модель, текст запроса, найденные инструкции, изменённые файлы и команды. Сохраняйте также неудачные попытки. Иначе легко принять удачный второй ответ за эффект файла, хотя вы уже уточнили задачу или дали агенту сообщение об ошибке.

Если агент сразу исправил функцию без теста, различайте два вывода: программная ошибка могла исчезнуть, а заданный процесс не был выполнен. Проверьте итоговый код и отдельно уточните причину пропуска. Такая запись помогает улучшать конкретную инструкцию без обещаний, что любой следующий запуск будет ей следовать.

• В изменениях нет посторонних файлов и зависимостей.
• Тест падает на старой реализации и проходит на новой.
• Исходное поведение осталось проверено.
• Агент сообщил реальные команды и ограничения проверки.