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; содержит требование в первом ответе уточнять предпочтительный грамматический род пользователя.
• local/chat_context.md — заготовка контекста чата для фиксации договорённостей.
• local/project_addenda.md — пустой шаблон для проектных дополнений; заполняется только при наличии специфических правил.
• README_snippet.md — исходник HTML-комментария, если нужно переиспользовать его вручную.
• local/ai/scripts/init.sh — скрипт для развёртывания симлинков и заполнения .git/info/exclude по списку из .gitignore; также обновляет local/ai/bootstrap.ready (первая строка true, дальше только элементы списка).
• local/ai/scripts/bootstrap_check.sh / local/ai/scripts/bootstrap_check.ps1 — проверка, что README содержит скрытый комментарий, симлинки указывают на AGENTS.md, .git/info/exclude содержит список из local/ai/bootstrap.ready, и логи ассистентов используют ISO 8601 UTC.
• local/ai/scripts/ — проектные утилиты (например, сбор открытых пунктов, оркестрация консультаций, тримминг логов); смотрите комментарии внутри скриптов.
• Каталоги local/<assistant>/sessions.log и local/<assistant>/requests.log — JSONL-журналы для всех ассистентов (gemini, qwen, codex, copilot), в них фиксируются timestamp, request_id, assistant, summary/short_context, tools, status.
• local/session_history.md и local/session_summaries/ — рабочий журнал и сводки для передачи контекста.
• local/gemini, local/qwen, local/codex, local/copilot — содержат README и примерные записи, чтобы единообразно оформлять журналы.

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

• local/project_addenda.md. Заполните матрицу окружений (ОС, права, инструменты), правила «можно/нельзя», каталоги токенов и требования к логам. Пока нет фактических значений — оставьте плейсхолдеры, но сохраните двуязычную структуру.
• local/chat_context.md. Укажите рабочий язык, род, краткий профиль окружения, «Разрешённые противоречия», чек-лист закрытия сессии и напоминания по логам. Этот файл первым читают все ассистенты.
• Журналы ассистентов. В local/<assistant>/sessions.log и requests.log оставьте по одной корректной записи JSONL с ISO 8601 таймстемпом (YYYY-MM-DDTHH:MM:SSZ), чтобы показать целевой формат.
• Многоагентные консультации. Используйте проектные скрипты из local/ai/scripts/ (укажите параметры в addenda), храните сырые логи в tmp/ai/consultation_runs/, обработанные — в tmp/ai/assistant_contexts/.
• 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 (строки закомментированы по умолчанию; при ручном копировании в .git/info/exclude уберите префикс # , либо просто запустите ./local/ai/scripts/init.sh).
• .github/copilot-instructions.md, .gemini/GEMINI.md, GEMINI.md, QWEN.md — симлинки на AGENTS.md, чтобы все ассистенты читали единый набор правил без дублирования.

Для работы ассистентов требуется локально доступные CLI (gemini, qwen, codex, copilot). Codex следует запускать через подкоманду codex exec (alias codex e), чтобы выполнять инструкции в неинтерактивном режиме.

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

Ассистент	Локальная установка	Подтверждение	Ссылка	Расположение в репозитории	Примечание
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	—

Содержимое каталога копируется в целевой репозиторий, затем в local/ai/chat_context.md актуализируются дата и договорённости. После этого выполняется ./local/ai/scripts/init.sh, который подготавливает симлинки. В завершение рекомендуется проверить, что README нового репозитория содержит HTML-комментарий для ассистентов (фрагмент можно взять из этого файла).

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

1. Клонировать или скопировать шаблон в целевой репозиторий.
2. Выполнить ./local/ai/scripts/init.sh, чтобы создать симлинки и обновить .git/info/exclude; после запуска убедиться, что строки для AGENTS.md, local/ai/ и симлинков присутствуют в .git/info/exclude.
3. Проверить наличие симлинков в корне: .github/copilot-instructions.md, .gemini/GEMINI.md, GEMINI.md, QWEN.md; каждый из них должен указывать на AGENTS.md.
4. Заполнить актуальные данные в local/chat_context.md (дата, договорённости, проверки); при наличии специфики проекта зафиксировать её в local/project_addenda.md.
5. Убедиться, что README нового репозитория содержит скрытый HTML-комментарий (подсказка расположена в начале файла; при необходимости скопировать фрагмент из README_snippet.md).
6. Ознакомиться с AGENTS.md и согласовать дополнительные правила с командой; при необходимости дополнить их в local/project_addenda.md.
7. После консультаций удалить временные каталоги инструментов ({{TEMP_TOOL_DIRS}}), чтобы не оставлять лишние конфигурации.
8. Если токены/ключи хранились в ~/.<tool>, согласуйте временное копирование или симлинк в {{TOKEN_STORAGE_PATH}}, добавьте путь в .gitignore и опишите процедуру очистки.
9. Если диалог с ассистентом приближается к ~75% от контекстного окна, завершаем работу командой «завершить сессию», чтобы сформировать сводку и продолжить с чистым контекстом; переполнение окна вытесняет ранние сообщения и ломает согласованные договорённости.

Если CLI поддерживает --data-dir или --config-dir, укажите путь внутри {{TEMP_TOOL_DIRS}}, чтобы избежать эскалации при работе с конфигурацией.

После первичной настройки обязательно изучите разделы «Быстрый старт», «Ограничения окружения», «Проверки и инструменты», «Логирование обращений», «Передача контекста» и «Синхронизация с апстримом» в AGENTS.md — они содержат плейсхолдеры, которые нужно адаптировать под ваш проект.

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

1. Сохраните копии текущих файлов инструкций (AGENTS.md, local/chat_context.md, local/project_addenda.md, docs/assistant-*.md и т.п.) и сравните их с шаблоном.
2. Не копируйте и не заменяйте README.md/README.en.md. См. правило в AGENTS.md (P0) и Step 2 в local/ai/agents/01-bootstrap.md.
3. Перенесите действующие договорённости и ограничения в соответствующие плейсхолдеры ({{LEGACY_INSTRUCTIONS}}, {{CHAT_CONTEXT_FILE}}, {{PROJECT_ADDENDA_FILE}}).
4. Просмотрите существующие логи и заметки, чтобы пополнить контекст первой сессии (рабочий язык, режимы песочницы, правила эскалации, список CLI).
5. Убедитесь, что создание временных каталогов ({{TEMP_TOOL_DIRS}}, ~/.<tool>) разрешено или предусмотрены альтернативы; при отсутствии доступа подготовьте план эскалации и перечень параметров --data-dir/--config-dir для переноса конфигурации внутрь репозитория.
6. Если токены/ключи находятся в домашней папке, временно скопируйте их или создайте симлинк в {{TOKEN_STORAGE_PATH}}, добавьте пути в .gitignore и обновите инструкции по очистке.
7. После адаптации повторно проверьте README/CONTRIBUTING и удалите упоминания, которые устарели в новом процессе.
8. Зафиксируйте перемещения и решения в local/session_history.md, чтобы другие ассистенты понимали, какие данные перенесены из старых инструкций.

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