README для людей, AGENTS.md для агентов
Почему в каждом моём репозитории четыре документа и почему человеку и исполнителю нельзя писать один и тот же текст.
В каждом моём репозитории — от библиотеки на Go до обёртки над чужим образом —
лежат четыре файла: README.md, CONTRIBUTING.md, CHANGELOG.md и
AGENTS.md. Обязательны все четыре, исключений по типу репозитория нет.
Главное правило одно: README, CONTRIBUTING и CHANGELOG пишет человек человеку. AGENTS.md пишет агент агенту. Смешивать нельзя в обе стороны.
Почему нельзя одним текстом
Документ, адресованный сразу двоим, не служит никому. Человеку мешает машинная плотность: списки команд, инварианты, запреты без объяснений. Исполнителю мешает всё остальное: вводные, причины, приглашения «почитать, чтобы проникнуться». В итоге каждый читает половину и пропускает важное.
Отсюда следствия, которые проверяются взглядом:
- в человеческих файлах нет слов «агент» и «ИИ» — они написаны так, будто агентов не существует;
- человеческие файлы не ссылаются на AGENTS.md: для их читателя его нет;
- AGENTS.md не здоровается и не объясняет «зачем это людям», он перечисляет факты, команды и запреты;
- AGENTS.md самодостаточен и повторяет нужные факты у себя. Это единственное разрешённое дублирование, и оно намеренное.
Четыре файла — четыре вопроса
| файл | читатель | вопрос |
|---|---|---|
| README | тот, кто впервые открыл репозиторий | что это и как этим пользоваться |
| CONTRIBUTING | тот, кто собрался что-то менять | как менять и что проверят |
| CHANGELOG | тот, кто обновляет версию у себя | что изменилось и что сломается |
| AGENTS.md | исполнитель, начинающий работу | что где лежит, что обязано быть истинным, что запрещено |
«Но у меня тут нечего писать»
Самые частые возражения, и почему я с ними не согласен:
- «В репозитории один человек, договариваться не с кем». Договариваешься с собой через год. CONTRIBUTING — единственное место, где записано, почему здесь так, а не иначе.
- «Исполнитель разберётся по коду». Разберётся и сделает по-своему: по коду не видно ни запретов, ни того, что сгенерировано, ни того, какая проверка обязана быть зелёной.
- «Там три строки, какой стиль кода». Три строки тоже пишутся по правилам: один источник истины, сгенерированное руками не правят, сборка идёт в конвейере.
Отсутствие любого из четырёх файлов для меня такой же дефект, как красная сборка. Звучит строго, но на деле экономит время: и людям, и агентам больше не приходится угадывать.