MODULE_03 · УРОК 3.4

Контекст проекта

Обвязка у вас одна, а проектов будет много, и живут они по разным законам: здесь тесты гоняют через pytest, там через uv run test, а вот в том репозитории есть папка с миграциями, которую трогать руками категорически нельзя. Зашивать всё это в промпт бессмысленно, угадывать - тем более. Проще положить в корень проекта файл AGENTS.md, обычную записку для того, кто придёт работать с кодом. При старте обвязка прочитает её и вклеит в системный промпт, а дальше правила проекта поедут вместе с проектом.

ЧТО ПОЛУЧИТСЯ В main.py появится пара строк: если в рабочей директории лежит AGENTS.md, читаем его и передаём в build_system_prompt как project_context. Файла нет - всё работает как раньше, без единой ошибки.

Слова, которые встретятся

  • AGENTS.md - markdown-файл в корне проекта с местными правилами: команды, устройство кода, список того, что делать не надо. Идея та же, что у .cursorrules или CLAUDE.md, только имя не привязано к конкретному инструменту.
  • project_context - ключ в вашем PromptContext, куда мы положим текст этого файла. Больше про него знать нечего, вся магия в том, что он опциональный.

Быстрый путь

  1. В main.py перед сборкой промпта проверить cwd / "AGENTS.md".
  2. Если есть - прочитать utf-8 и передать как project_context.
  3. Положить тестовый AGENTS.md и спросить агента про команду тестов.

Какие файлы трогаем

Файл Что делать
main.py Править. Чтение AGENTS.md + передача в билдер.
prompts.py Уже умеет project_context (урок 3.2). Если вырезали - верните блок.
AGENTS.md в cwd проекта Создать для проверки (можно временный).

Шаг 1. Чтение файла в main.py

Читаем диск именно здесь, а не внутри билдера: пусть build_system_prompt остаётся чистой функцией. Код встаёт прямо перед её вызовом:

main.py - фрагмент

from pathlib import Path
from prompts import build_system_prompt

agents_path = cwd / "AGENTS.md"
project_context = (
    agents_path.read_text(encoding="utf-8")
    if agents_path.is_file()
    else None
)

instructions = build_system_prompt({
    "working_directory": str(cwd),
    "sandbox_type": "local",
    "tool_names": ["read", "grep", "bash"],
    **({"project_context": project_context} if project_context else {}),
})

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

ЕСЛИ НЕТ СЕКЦИИ В prompts.py В build_system_prompt должен быть кусок из урока 3.2:
if project := ctx.get("project_context"):
    parts.append(f"""
# Инструкции проекта (из AGENTS.md)
{project}
""")
Без него файл прочитаете, а модель не увидит.

Шаг 2. Что писать в AGENTS.md

Соблазн описать там весь проект велик, но помните: этот текст едет к модели в каждом запросе и стоит токенов. Пишите только то, чего агент не выяснит сам через read и grep:

AGENTS.md - пример

# Инструкции проекта

## Команды
- Тесты: `uv run pytest`
- Не использовать `npm test` - это не Node-проект

## Стиль
- Коммиты: `feat(scope): message`

## Грабли
- Не править файлы миграций руками - только генерировать новые

Проверьте

Положите такой файл в каталог, который передаёте первым аргументом (.), затем:

uv run python main.py . "Какой командой в этом проекте гонять тесты?"

С файлом на месте агент должен уверенно назвать uv run pytest, потому что так написано в записке, а не гадать про npm test по количеству звёзд на небе.

Теперь уберите или переименуйте AGENTS.md и спросите то же самое. Обвязка не должна падать: файла нет, секции в промпте нет, ответ снова «на глаз». Именно поэтому мы и сделали ключ опциональным.

ПОКА ОДИН ФАЙЛ В монорепозиториях принято идти вверх по дереву и склеивать несколько AGENTS.md по пути. Мы так не делаем намеренно: одного файла в рабочей директории достаточно, чтобы идея заработала. Хождение по родительским каталогам добавите, когда эта боль придёт к вам лично.

Готово, если:

  • В main.py проверяется наличие cwd/AGENTS.md
  • Содержимое (если есть) уходит в project_context
  • С файлом агент отвечает на вопрос о тестах по AGENTS.md
  • Без файла агент стартует без ошибки
ЭКСПЕРИМЕНТ Впишите в AGENTS.md заведомую чушь, например «тесты запускаются командой make coffee», и спросите агента про тесты. Он послушно процитирует бред, и это отличный повод задуматься: всё, что лежит в этом файле, модель принимает за истину, а файл приходит из репозитория. Потом верните нормальный текст, пока коллеги не увидели.