01 Why.ru

Зачем это нужно

Репозиторий проваливается не на коде, а на документации. git push проходит, тесты зелёные, а читатель не понимает, как проект запустить. Дефект живёт годами, потому что его не видно: ни компилятор, ни CI о нём не сообщают.

Пять дефектов, которые встречаются чаще всего

Дефект	Как выглядит	Чем опасен
README без установки	сразу архитектура и философия	читатель уходит на втором абзаце
Журнал изменений без дат	## 1.1.0 и всё	версии нельзя сравнить и связать
Вики без навигации	десять страниц, ссылок нет	страницы существуют, но не находятся
Ссылка в никуда	[API](docs/api.md) при docs/API.md	документация «есть», но не открывается
Описание из трёх слов	«panel», «tools»	поиск не показывает проект

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

Почему это работа для агента

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

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

Что считается провалом

Ситуация	Почему провал
Проверка осмотрела ноль файлов и вернула «успех»	зелёный результат ничего не значит
Ссылка на несуществующую страницу вики	читатель считает, что документация есть
Публикация вики удалила чужую страницу	потеря данных без предупреждения
Выпуск версии без записей	журнал перестаёт что-либо значить
Число в README без источника	проверить нельзя, доверять нельзя

Дальше

• Установка — поставить и проверить.
• Ловушки платформы — места, где поведение GitHub отличается от ожидаемого.
• Контракты файлов — что именно проверяется.