Перейти к основному содержимому

Инструкции ИИ для обновления репозитория

Этот документ содержит инструкции для агентов ИИ (и участников из числа людей) о том, как управлять и обновлять вопросы в этом репозитории.

Структура проекта​

  • docs/docs/questions/: Содержит все модульные вопросы.
    • Поддиректории именуются как {Category_ID}-{Category_Slug}.
    • В каждой категории есть поддиректории уровней: junior, middle, senior, expert.
    • Отдельные вопросы хранятся как 00X-{slug}.mdx.
  • docs/docs/answers/: Содержит подробные развернутые ответы и руководства.
  • QUESTIONS.md: Устаревший исходный файл (поддерживайте его в синхронизации, если необходимо, но основным источником истины для фронтенда является docs/docs/questions/).

Как добавить новый вопрос​

  1. Определите категорию: Выберите соответствующую категорию в docs/docs/questions/.
  2. Выберите уровень: Поместите новый файл в правильную папку уровня.
  3. Соглашение об именовании: Используйте следующий доступный трехзначный номер, за которым следует слаг (slug), например, 016-new-feature.mdx.
  4. Содержимое файла:
    • Используйте frontmatter для определения заголовка (включая глобальный номер вопроса).
    • Используйте заголовок 1-го уровня для названия вопроса.
    • Используйте блок :::info внизу, чтобы указать категорию и уровень.

Пример шаблона:​

---
title: '145. Что такое [Тема]?'
---

# 145. Что такое [Тема]?

[Здесь идет ответ]

---

:::info
Категория: [Название категории] | Уровень: [Уровень]
:::

Как обновить существующие вопросы​

  1. Найдите файл в docs/docs/questions/.
  2. Внесите изменения непосредственно в файл .mdx.
  3. Если ответ ссылается на подробное руководство, убедитесь, что ссылка указывает на ../answers/guide-name.md.

Разработка и сборка​

Чтобы убедиться, что фронтенд корректен, выполните следующие шаги:

Линтинг и форматирование​

Перед отправкой любых изменений запустите линтер и форматировщик:

cd docs
npm run format
npm run lint

Это проверит наличие проблем со стилем кода, битый React/JSX и распространенные ошибки Markdown.

Сборка Docker​

Чтобы протестировать сборку локально с помощью Docker:

docker compose up --build

Это соберет сайт Docusaurus и запустит его на http://localhost:8080.

Автоматизация​

Если вам нужно заново сгенерировать структуру из QUESTIONS.md, используйте скрипт extract_questions.py в корневом каталоге. Однако предпочтительнее вносить изменения в модульные файлы вручную для более тонкой настройки.

Перевод и Локализация (Русский язык)​

  • При переводе контента на русский язык (например, в docs/i18n/ru/) поддерживайте уровень Native Russian Speaking C1.
  • Применяйте профессиональные знания в области Software Engineering, Software Development и DevOps:
    • Используйте правильную техническую терминологию и профессиональный сленг, распространенный в русскоязычном IT-сообществе (например, «деплоить», «мержить», «прод», «стейджинг»).
    • Правильно переводите и используйте «рунглиш», где он является стандартом индустрии, сохраняя при этом общее качество профессионального языка.
    • Убедитесь, что тон изложения профессиональный, технически точный и доступный для целевой аудитории (от Junior до Senior уровней).
  • Синхронизируйте все изменения контента между основным англоязычным источником и русским переводом.