ai-code-assistant-bootstrap

Шаблон для локальных ассистентов

🇬🇧 English version: see README.en.md

Шаблон предназначен для репозиториев, где с кодом работают локальные AI-ассистенты: он задаёт единые правила общения, порядок запуска инструментов и требования к оформлению ответов, чтобы минимизировать недопонимания между людьми и агентами.

Набор ai-code-assistant-bootstrap включает:

• README.md / README.en.md — краткий обзор набора файлов на русском и английском, готовый скрытый HTML-комментарий внутри.
• AGENTS.md — универсальный набор правил с локальными предпочтениями, содержащий инструкции для gemini, qwen, codex, copilot и claude; содержит требование в первом ответе уточнять предпочтительный грамматический род пользователя.
• local/ai/chat_context.md — заготовка контекста чата для фиксации договорённостей.
• local/ai/project_addenda.md — пустой шаблон для проектных дополнений; заполняется только при наличии специфических правил.
• README_snippet.md — исходник HTML-комментария для ручного переиспользования.
• local/ai/scripts/init.sh — скрипт для развёртывания симлинков и применения канонического списка изменяемого локального состояния к .git/info/exclude; также обновляет local/ai/bootstrap.ready (первая строка true, дальше только элементы списка).
• local/ai/scripts/bootstrap_check.sh / local/ai/scripts/bootstrap_check.ps1 — обязательная проверка README, точных целей ссылок, .git/info/exclude и JSONL-журналов.
• local/ai/scripts/ — проектные утилиты (например, сбор открытых пунктов, оркестрация консультаций, тримминг логов); смотрите комментарии внутри скриптов.
• local/ai/<assistant>/sessions.log и local/ai/<assistant>/requests.log — обязательные JSONL-журналы для всех ассистентов (gemini, qwen, codex, copilot, claude).
• local/ai/session_history.md и local/ai/session_summaries/ — рабочий журнал и сводки для передачи контекста.
• local/ai/gemini, local/ai/qwen, local/ai/codex, local/ai/copilot, local/ai/claude — содержат образцы записей для единообразного оформления журналов.

Как адаптировать шаблон

• local/ai/project_addenda.md. Заполните матрицу окружений (ОС, права, инструменты), правила «можно/нельзя», политику аутентификации без значений секретов и требования к логам. При отсутствии данных используйте плейсхолдеры, но сохраните двуязычную структуру.
• local/ai/chat_context.md. Укажите рабочий язык, род, краткий профиль окружения, «Разрешённые противоречия», чек-лист закрытия сессии и напоминания по логам. Этот файл первым читают все ассистенты.
• Журналы ассистентов. Для sessions.log используйте session_id, started_at, assistant, language, gender, logging_precision; для requests.log — timestamp, request_id, assistant, summary, tools, status. Время — ISO 8601 UTC.
• Многоагентные консультации. Используйте проектные скрипты из local/ai/scripts/ (укажите параметры в addenda), храните сырые логи в tmp/ai/consultation_runs/, обработанные — в tmp/ai/assistant_contexts/. Пример запуска: python local/ai/scripts/consult.py execute -a claude,gemini,qwen,codex,copilot -p "Проверьте изменения и риски" python local/ai/scripts/consult.py process <run_id>
• Bootstrap-процедура. После первичного заполнения README, симлинков и логов запустите local/ai/scripts/bootstrap_check.sh/.ps1 и зафиксируйте результат в local/ai/chat_context.md и local/ai/session_history.md, чтобы следующий ассистент видел статус готовности.

⚠️ Windows PowerShell: если политика исполнения блокирует запуск .ps1, временно ослабьте её только для текущей сессии: powershell -NoProfile -ExecutionPolicy Bypass -File local/ai/scripts/bootstrap_check.ps1 После завершения верните прежнее значение или закройте окно. Подпись скриптов не требуется.

• .gitignore — список только изменяемого локального состояния для .git/info/exclude; обязательные инструкции, скрипты и skill не скрываются.
• .github/copilot-instructions.md, .claude/CLAUDE.md, .gemini/GEMINI.md, CLAUDE.md, GEMINI.md, QWEN.md — симлинки на AGENTS.md, чтобы все ассистенты читали единый набор правил без дублирования.

Для работы ассистентов требуется локально доступные CLI (gemini, qwen, codex, copilot, claude). Codex запускать через подкоманду codex exec (alias codex e) для неинтерактивного режима; Claude — через claude -p --output-format json.

Настройки шаблона для ассистентов

Ассистент	Локальная установка	Подтверждение	Ссылка	Расположение в репозитории	Примечание
gemini	☑	☑	google-gemini/gemini-cli	.gemini/GEMINI.md → AGENTS.md; GEMINI.md (корень) → AGENTS.md	—
qwen	☑	☑	QwenLM/qwen-code	QWEN.md (корень) → AGENTS.md	Не выполняет bootstrap/протокол из AGENTS.md автоматически; требует явного промпта с разрешением shell-команд (например: "выполни протокол, используй shell для симлинков и логов").
codex	☑	☑	openai/codex	AGENTS.md (корень)	запускается через codex exec
copilot	☑	☑	github/copilot-cli	.github/copilot-instructions.md → AGENTS.md	—
claude	☑	☑	anthropics/claude-code	.claude/CLAUDE.md → AGENTS.md; CLAUDE.md (корень) → AGENTS.md	Для неинтерактивного режима использовать -p --output-format json.

Применяйте каркас через ai-bootstrap-converge: он приводит целевой репозиторий к обязательному состоянию и сохраняет проектные инструкции. Прямое клонирование или копирование дерева в целевой репозиторий не поддерживается: оно превращает изменяемый контекст и журналы в отслеживаемые Git файлы.

Быстрый старт

1. Вызвать ai-bootstrap-converge и указать целевой репозиторий, источник каркаса и нужный Git ref.
2. Выполнить Audit и Plan, затем Apply и Verify; конфликтующие проектные инструкции не перезаписывать.
3. В целевом репозитории выполнить local/ai/scripts/init.ps1 или local/ai/scripts/init.sh, если готовность ещё не подтверждена.
4. Проверить, что instruction links указывают на AGENTS.md, а .git/info/exclude скрывает только изменяемое локальное состояние.
5. Заполнить неотслеживаемые local/ai/chat_context.md и local/ai/project_addenda.md; сохранить действующие проектные ограничения.
6. Выполнить local/ai/scripts/bootstrap_check.ps1 или local/ai/scripts/bootstrap_check.sh.
7. Использовать штатную аутентификацию подписки или интерактивной сессии, если CLI её поддерживает. API-ключ запрашивать только после одобрения пользователя и только для команды или API, которым он нужен.
8. Не копировать и не связывать симлинком хранилище учётных данных, профиль или токены с репозиторием и tmp/ai.
9. При приближении диалога к ~75% контекстного окна завершить сессию со сводкой.

Если CLI поддерживает --data-dir или --config-dir, направляйте в {{TEMP_TOOL_DIRS}} только несекретные кэши и временные данные. Не перенаправляйте туда аутентифицированный профиль или хранилище токенов.

После первичной настройки выполните протокол начала сессии и изучите правила логирования, песочницы, проверок, передачи контекста и синхронизации.

Интеграция в существующий репозиторий

1. Зафиксируйте исходное состояние через git status и ai-bootstrap-converge Audit; не создавайте копии вне разрешённой рабочей области.
2. Просмотрите Plan: каркас обязателен, но пользовательские инструкции и тело README должны сохраниться.
3. Выполните Apply; при конфликте объедините проектные правила вручную и повторите применение.
4. Перенесите действующие договорённости в неотслеживаемые local/ai/chat_context.md и local/ai/project_addenda.md.
5. Не копируйте и не связывайте симлинком учётные данные. Зафиксируйте только способ аутентификации и порядок отзыва доступа.
6. Выполните Verify и оба доступных bootstrap-check варианта для заявленных платформ.
7. Зафиксируйте решения в local/ai/session_history.md и проверьте итоговый Git diff.

Перед изменениями обязательно изучить CONTRIBUTING.md и CONTRIBUTING.en.md, чтобы поддерживать двуязычную документацию в актуальном состоянии.