Initial commit

.template/development/docs/adr/0008-vscode-onboarding.md

@@ -0,0 +1,35 @@
+# ADR-0008: Версионируемая рабочая область VS Code и обучение автора
+
+**Дата**: 2026-08-31  
+**Статус**: Принято
+
+## Контекст
+
+Основные пользователи шаблона пишут документы, но могут никогда не работать с кодом, Git и Typst. Устные инструкции и личные настройки редактора не воспроизводятся в новом форке. Одновременно каталог `.vscode/` не должен отвлекать автора от текста.
+
+Часть расширений доступна в публичном Marketplace, а Typst Typewriter и Zotst распространяются внутри компании как локальные VSIX. Запись идентификатора расширения в рекомендациях VS Code не распространяет сам установочный пакет.
+
+## Рассматриваемые варианты
+
+1. **Не хранить настройки редактора** — корень формально проще, но каждый сотрудник вручную повторяет настройку и получает различное поведение.
+2. **Настроить всё глобально на рабочих станциях** — удобно на одном компьютере, но не переносится вместе с форком и требует администрирования.
+3. **Версионировать `.vscode/` и скрыть его в проводнике** — настройки синхронизируются через Git, оставаясь вне повседневной области автора.
+4. **Положить локальные VSIX в шаблон** — обеспечивает автономную установку, но смешивает бинарные пакеты с исходниками и затрудняет централизованное обновление.
+
+## Решение
+
+Выбран вариант **версионировать `.vscode/`, но скрывать его из Explorer**:
+
+- `extensions.json` содержит десять согласованных идентификаторов, включая два внутренних;
+- `settings.json` включает автосохранение, языки проверки орфографии, TODO-маркеры и защитные настройки Git;
+- `tasks.json` предоставляет обычную и приватную сборку, выбор одного из четырёх публичных примеров и компиляцию учебного каталога;
+- внутренние VSIX хранятся в корпоративном хранилище, а README объясняет их установку;
+- README и видимый `docs/` обучают Git в терминах истории документа, контрольных точек и параллельных версий.
+
+## Последствия
+
+**Становится проще**: первый запуск, одинаковая среда во всех форках, живой предпросмотр, проверка русского текста и совместная работа через Git.
+
+**Становится сложнее**: изменения `.vscode/` требуют такого же review, как изменения шаблона; сопровождающий должен отдельно публиковать совместимые VSIX.
+
+**Закрывает дверь на**: неявные обязательные глобальные настройки и распространение внутренних бинарных расширений внутри Git-шаблона.