Skip to content

AGENTS.md

Latest commit

 

History

History
172 lines (110 loc) · 14.6 KB

AGENTS.md

File metadata and controls

172 lines (110 loc) · 14.6 KB
Raw

AGENTS.md — как работать с платформой Доки

Инструкция для ИИ-агентов: Codex, Cursor, Copilot, Gemini CLI читают этот файл напрямую, Claude Code — через CLAUDE.md, который на него ссылается. Здесь только то, что нужно, чтобы начать работать и не сломать ничего по дороге. Подробное устройство сборки — в docs/how-its-work.md.

1. Правила работы

Правила смещают баланс в сторону осторожности, а не скорости. На мелких задачах включайте здравый смысл.

Сначала подумай, потом пиши

  • Назови свои допущения вслух. Если не уверен — спроси.
  • Если задачу можно понять двумя способами — покажи оба, не выбирай молча.
  • Если есть решение проще — скажи об этом. Возражать можно и нужно.
  • Если что-то непонятно — остановись и назови, что именно непонятно.

Минимум кода

  • Ничего сверх того, о чём попросили.
  • Никаких абстракций ради одного вызова.
  • Никакой «гибкости» и «настраиваемости», которую не заказывали.
  • Никакой обработки ошибок для невозможных ситуаций.
  • Если получилось 200 строк там, где хватило бы 50, — перепиши.

Проверка: сказал бы опытный разработчик, что здесь переусложнено? Если да — упрощай.

Правки хирургические

  • Не «улучшай» соседний код, комментарии и форматирование заодно.
  • Не рефактори то, что не сломано.
  • Держись существующего стиля, даже если сам написал бы иначе.
  • Заметил не связанный с задачей мёртвый код — скажи о нём, но не удаляй.
  • Убирай за собой только то, что осиротело из-за твоих же правок.

Проверка: каждая изменённая строка должна прослеживаться до запроса пользователя.

Цель должна быть проверяемой

Формулируй задачу так, чтобы результат можно было проверить командой:

  • «добавь валидацию» → «напиши тест на неверный ввод, потом сделай, чтобы он проходил»;
  • «почини баг» → «напиши тест, который его воспроизводит, потом сделай, чтобы он проходил»;
  • «отрефактори X» → «убедись, что тесты зелёные до и после».

Для многошаговых задач сначала напиши короткий план: шаг → чем проверяю.

Тест обязателен

Не «желательно» и не «если останется время».

  • Чиним баг — сначала тест, который его воспроизводит. Он должен падать до правки и проходить после. Если тест зелёный до правки — вы починили не то, что сломано.
  • Добавляем функциональность — тест на неё в том же пулреквесте, вместе с кодом.
  • Правка без теста не считается сделанной. Не откладывайте его «на потом» и не предлагайте написать отдельно.

Тестируемого места нет — сделайте его: вынесите логику из шаблона или обработчика в чистую функцию и покройте её. Если это невозможно (шаблоны Nunjucks, CSS, вёрстка), скажите об этом прямо и напишите, чем проверяли вместо теста — какую страницу открывали и что на ней смотрели.

Правка не заканчивается на коде

Изменили поведение — пройдитесь по тому, что вокруг него написано, и приведите в соответствие:

  • Документация. AGENTS.md, README.md, CONTRIBUTING.md, docs/ — если поменялись команды, шаги запуска, требования к окружению или то, как что-то устроено, правьте текст в том же пулреквесте. Устаревшая документация хуже отсутствующей: по ней принимают решения.
  • Соседние тесты. Найдите тесты, которые относятся к тронутому коду, и прочитайте их — не только те, что упали. Тест мог остаться зелёным, но проверять уже не то поведение: устаревшие ожидания, отсылки к переименованному, покрытие ветки, которой больше нет. Такой тест поправьте вместе с кодом.

Проверка: если после ваших правок в репозитории остался текст, который теперь врёт, — работа не закончена.

Чего делать нельзя

  • Не запускать npm run deploy. Это не проверка сборки, а реальный rsync на dev.doka.guide.
  • Не читать и не печатать .env — там боевой GITHUB_TOKEN.
  • Не коммитить симлинки на контент (src/html, src/css, src/js и остальные из .gitignore), .issues.json, dist и bin.
  • Не пушить в main. Работа идёт по GitHub Flow: ветка → пулреквест → ревью.

2. Что это за репозиторий

Движок сайта doka.guide — статический генератор на Eleventy. Берёт Markdown из отдельного репозитория doka-guide/content и рендерит через Nunjucks-шаблоны.

Контент и платформа живут в разных репозиториях намеренно: авторы работают с материалами без знания сборки, платформа развивается независимо. Для 11ty это нестандартно — отсюда симлинки, .11tydata.js и ручные коллекции.

Рядом в экосистеме: api (Go-бэкенд форм и рассылок) и search (движок поиска по инвертированному индексу).

3. Запуск

npm i
cp .env.example .env
npm start          # http://localhost:8080

Версия ноды — из .nvmrc. По умолчанию PATH_TO_CONTENT=../content: репозиторий с контентом должен лежать рядом. При первом npm start скрипт make-links.js спросит путь и создаст симлинки.

Сборка всего контента идёт долго. Что подключается симлинками, задаёт CONTENT_REP_FOLDERS в .env: сборка учитывает только материалы из перечисленных папок, а папки могут быть и пустыми. Для быстрых итераций оставьте нужный раздел и обязательную settings. Подробности — в docs/how-its-work.md.

Файл .issues.json (статистика вкладов из репозитория doka-guide/cache) для разработки не нужен: без него npm start печатает предупреждение и собирает страницы участников с пустой статистикой. Для npm run build он обязателен — сборка упадёт с внятным сообщением. Как его получить, написано в docs/how-to-run.md.

4. Как проверять работу

От быстрого к медленному. Первый шаг закрывает почти всё:

npm run check                         # тесты + editorconfig + stylelint + eslint, ~5 с
npx eslint <изменённые файлы>         # точечно, без шума от чужих ошибок
npm start                             # если трогали шаблоны или трансформации — посмотреть глазами
npm run build && npm run lint:html    # валидация разметки, нужна Java 17+

npm run check доводит до конца все проверки и печатает итоговую таблицу. Не используйте вместо него npm run lint-check: там шаги склеены через &&, поэтому падение editorconfig прячет отчёты stylelint и eslint, и вы чините переводы строк вместо настоящей ошибки.

lint:html проверяет по одной странице каждого типа, а не весь сайт: за разметку статей отвечает один шаблон doc.njk, и тысячная статья не скажет ничего, чего не сказала первая. Список страниц — в scripts/lint-html.js, при добавлении нового типа страницы его нужно пополнить.

editorconfig-checker при каждом запуске качает свой бинарник в ./bin/latest/. Папка в .gitignore.

Тесты лежат в __tests__/ рядом с кодом, общие помощники — в test/helpers/. Покрытие пока тонкое, самое ценное место для новых тестов — трансформации: это чистые функции, html на входе и html на выходе.

5. Карта репозитория

Где Что
.eleventy.js Главный конфиг: коллекции, фильтры, трансформации, плагины
gulpfile.js Продакшн-пайплайн: бандл CSS/JS, кеш-хэши
make-links.js Симлинки src/{раздел} → content/{раздел}
config/ Константы, окружение, цвета разделов
src/data/ Глобальные данные 11ty
src/layouts/, src/includes/ Базовый шаблон и блоки
src/views/ Страницы: *.njk плюс *.11tydata.js с данными
src/transforms/ Постобработка готового HTML
src/libs/ Утилиты сборки (Node)
src/scripts/ Клиентский JS, точка входа index.js, бандлится esbuild
src/styles/ CSS по блокам, точка входа index.css
.github/workflows/ CI: линтеры, тесты, сборка, превью, деплой

Ключевые коллекции в шаблонах: docs, docsById, разделы (html, css, js, a11y, tools, recipes), articleIndexes, people, practice, question, answer, webFeatures, posts.

Данные страницы статьи собираются в src/views/doc.11tydata.js, общие для всех страниц — в src/views/views.11tydata.js.

6. Соглашения

Код. semi: never, одинарные кавычки, ширина 120 — всё это чинится автоматически, prettier подключён правилом eslint. Отступ 2 пробела, LF, финальная новая строка.

Комментарии на русском и объясняют «почему», а не «что». В этом репозитории комментарий — это место для решения и его причины: почему arm64 собирается на нативном раннере, почему глоб в кавычках, почему linkify выключен. Пересказ кода словами не нужен.

Коммиты на русском, в третьем лице настоящего времени, номер пулреквеста в конце:

Убирает пустые строки в выдаче поиска (#1366)
Чинит сборку arm64, добавляет тесты в CI и убирает мёртвый GITHUB_TOKEN (#1365)

Пулреквесты — в main, ревью по CODEOWNERS. Перед пушем прогоните npm run check: тесты в pre-commit хук не входят, а CI гоняет их отдельным воркфлоу.

Pre-commit хук (simple-git-hooks + nano-staged) чинит только файлы в индексе: eslint --fix для JS, stylelint --fix для CSS. До нетронутых файлов он не доходит — поэтому долг по линтерам копится сам собой.

7. Где читать дальше