04. Правила проекта в AGENTS.md

← Предыдущий модуль · Оглавление · Следующий модуль →

Если сейчас только читаете: русский разбор ситуации без запуска программ. После него ответьте на вопросы самопроверки модуля; практическое упражнение можно отложить.

Результат модуля: вы подготовили короткие правила с проверенными командами и понимаете область их действия.

Codex собирает инструкции при старте запуска. В Codex home, обычно ~/.codex, сначала учитывается непустой AGENTS.override.md, иначе AGENTS.md. В проекте проверяются каталоги от корня к текущему: сначала override, затем обычный файл и настроенные резервные имена. Из одного каталога берётся не более одного файла. Более близкие к текущему каталогу инструкции добавляются позже и могут переопределять ранние. По умолчанию общий объём ограничен 32 КиБ. Правила обнаружения AGENTS.md.

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

Хороший AGENTS.md хранит специфические сведения проекта: где проходят границы модулей, какие команды считаются обязательными, какие файлы генерируются, как оформляется завершение работы. Общие советы вроде «пиши хороший код» редко помогают выбрать действие. Длинное объяснение архитектуры удобнее хранить отдельно, оставив короткую ссылку и указание, когда его читать.

Пример содержимого для учебного проекта:

# Правила репозитория

## Контекст
- Перед изменением проверь ветку и git status.
- src/import отвечает за чтение и проверку входных файлов.
- docs/decisions содержит объяснения архитектурных решений.

## Проверки
- Команды запускай из корня проекта в PowerShell.
- Для Python используй существующее виртуальное окружение проекта.
- Точные команды тестов возьми из README; при расхождении сообщи об этом.

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

## Завершение
- Укажи изменённое поведение, выполненные проверки и ограничения.

Пути в примере условные. Перед сохранением замените их реальной структурой. Фраза «команды из README» тоже не вечное решение: если команда стабильна и проверена, укажите её прямо. Правило должно уменьшать неопределённость, а не перенаправлять читателя по кругу.

На Windows различайте путь и строку. Если в проекте допустимы пробелы, используйте -LiteralPath при файловых операциях. Для одинаковой записи русского текста в Windows PowerShell 5.1 и PowerShell 7 можно использовать .NET с явным UTF-8. Пример ниже создаёт только учебную заметку; не перезаписывает существующий AGENTS.md:

$notePath = Join-Path (Get-Location) 'agents-draft.txt'
if (Test-Path -LiteralPath $notePath) {
    throw 'Учебная заметка уже существует: выберите другое имя.'
}
$noteText = @'
# Черновик правил
Пиши по-русски. Перед изменением проверяй ветку и состояние Git.
Указывай только реально выполненные проверки.
'@
$utf8 = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($notePath, $noteText, $utf8)
Get-Content -LiteralPath $notePath -Encoding UTF8

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

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

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

Самопроверка:

Чем AGENTS.override.md отличается от ещё одного обычного файла инструкций?
Почему нужно знать текущий каталог запуска?
Как отличить полезное правило от инструкции, которую уже обеспечивает линтер?

Структурная основа: upstream, модуль 04. Проверено 24 октября 2026 года.

← Предыдущий модуль · Оглавление · Следующий модуль →