Skip to content

CUSTOM_SYSTEM_PROMPTS.md

Latest commit

 

History

History
327 lines (223 loc) · 21.1 KB

CUSTOM_SYSTEM_PROMPTS.md

File metadata and controls

327 lines (223 loc) · 21.1 KB
Raw

Пользовательские системные подсказки

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

Это руководство объясняет, как настроить системную подсказку, которую GAC использует для генерации сообщений коммитов, позволяя вам определить свой собственный стиль и соглашения для сообщений коммитов.

Содержание

Что такое системные подсказки?

GAC использует две подсказки при генерации сообщений коммитов:

  1. Системная подсказка (настраиваемая): Инструкции, которые определяют роль, стиль и соглашения для сообщений коммитов
  2. Пользовательская подсказка (автоматическая): Данные git diff, показывающие что изменилось

Системная подсказка говорит AI КАК писать сообщения коммитов, в то время как пользовательская подсказка предоставляет ЧТО (фактические изменения кода).

Зачем использовать пользовательские системные подсказки?

Вам может понадобиться пользовательская системная подсказка, если:

  • Ваша команда использует другой стиль сообщений коммитов, чем обычные коммиты
  • Вы предпочитаете эмодзи, префиксы или другие пользовательские форматы
  • Вы хотите больше или меньше деталей в сообщениях коммитов
  • У вас есть специфичные для компании руководства или шаблоны
  • Вы хотите соответствовать голосу и тону вашей команды
  • Вы хотите сообщения коммитов на другом языке (смотрите Конфигурацию языка ниже)

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

  1. Создайте ваш файл пользовательской системной подсказки:

    # Скопируйте пример как отправную точку
cp custom_system_prompt.example.txt ~/.config/gac/my_system_prompt.txt

# Или создайте свой с нуля
vim ~/.config/gac/my_system_prompt.txt

  2. Добавьте в ваш файл .gac.env:

    # В ~/.gac.env или проектном уровне .gac.env
GAC_SYSTEM_PROMPT_PATH=/path/to/your/custom_system_prompt.txt

  3. Протестируйте:

    uvx gac --dry-run

Вот и всё! GAC теперь будет использовать ваши пользовательские инструкции вместо стандартных.

Написание вашей пользовательской системной подсказки

Ваша пользовательская системная подсказка может быть простым текстом - специальный формат или XML-теги не требуются. Просто напишите чёткие инструкции о том, как AI должен генерировать сообщения коммитов.

Ключевые вещи, которые стоит включить:

  1. Определение роли - Что должен делать AI
  2. Требования к формату - Структура, длина, стиль
  3. Примеры - Покажите, как выглядят хорошие сообщения коммитов
  4. Ограничения - Чего избегать или требования к выполнению

Пример структуры:

Вы - автор сообщений коммитов для [вашего проекта/команды].

При анализе изменений кода, создайте сообщение коммита, которое:

1. [Первое требование]
2. [Второе требование]
3. [Третье требование]

Пример формата:
[Покажите пример сообщения коммита]

Ваш весь ответ будет использован непосредственно как сообщение коммита.

Примеры

Стиль коммитов на основе эмодзи

Смотрите custom_system_prompt.example.txt для полного примера на основе эмодзи.

Быстрый фрагмент:

Вы - автор сообщений коммитов, который использует эмодзи и дружелюбный тон.

Начинайте каждое сообщение с эмодзи:
- 🎉 для новых функций
- 🐛 для исправлений ошибок
- 📝 для документации
- ♻️ для рефакторинга

Держите первую строку под 72 символами и объясняйте ПОЧЕМУ изменение важно.

Командно-специфичные соглашения

Вы пишете сообщения коммитов для корпоративного банковского приложения.

Требования:
1. Начинайте с номера билета JIRA в скобках (например, [BANK-1234])
2. Используйте формальный, профессиональный тон
3. Включите последствия для безопасности, если релевантно
4. Ссылайтесь на любые требования соответствия (PCI-DSS, SOC2 и т.д.)
5. Держите сообщения краткими, но полными

Формат:
[TICKET-123] Краткое описание изменения

Подробное объяснение того, что изменилось и почему. Включите:
- Бизнес-обоснование
- Технический подход
- Оценку рисков (если применимо)

Пример:
[BANK-1234] Реализация ограничения скорости для конечных точек входа

Добавлено ограничение скорости на основе Redis для предотвращения атак грубой силы.
Ограничивает попытки входа до 5 на IP за 15 минут.
Соответствует требованиям безопасности SOC2 для контроля доступа.

Детальный технический стиль

Вы - технический автор сообщений коммитов, который создаёт всестороннюю документацию.

Для каждого коммита предоставьте:

1. Чёткое, описательное название (под 72 символами)
2. Пустую строку
3. ЧТО: Что было изменено (2-3 предложения)
4. ПОЧЕМУ: Почему изменение было необходимо (2-3 предложения)
5. КАК: Технический подход или ключевые детали реализации
6. ВОЗДЕЙСТВИЕ: Файлы/компоненты, на которые повлияло, и потенциальные побочные эффекты

Используйте техническую точность. Ссылайтесь на конкретные функции, классы и модули.
Используйте настоящее время и активный залог.

Пример:
Рефакторинг промежуточного ПО аутентификации для использования внедрения зависимостей

ЧТО: Заменено глобальное состояние аутентификации на внедряемый AuthService. Обновлены все обработчики маршрутов для принятия AuthService через внедрение конструктора.

ПОЧЕМУ: Глобальное состояние затрудняло тестирование и создавало скрытые зависимости.
Внедрение зависимостей улучшает тестируемость и делает зависимости явными.

КАК: Создан интерфейс AuthService, реализованы JWTAuthService и MockAuthService.
Модифицированы конструкторы обработчиков маршрутов для требования AuthService.
Обновлена конфигурация контейнера внедрения зависимостей.

ВОЗДЕЙСТВИЕ: Влияет на все аутентифицированные маршруты. Нет изменений в поведении для пользователей.
Тесты теперь работают в 3 раза быстрее с MockAuthService. Требуется миграция для routes/auth.ts, routes/api.ts и routes/admin.ts.

Рекомендации

Делайте

  • ✅ Будьте конкретны - Чёткие инструкции дают лучшие результаты
  • ✅ Включайте примеры - Покажите AI, как выглядит хорошее сообщение
  • ✅ Тестируйте итеративно - Попробуйте вашу подсказку, уточняйте на основе результатов
  • ✅ Держите сфокусированным - Слишком много правил могут запутать AI
  • ✅ Используйте последовательную терминологию - Придерживайтесь одних и тех же терминов на протяжении всего текста
  • ✅ Заканчивайте напоминанием - Подтвердите, что ответ будет использован как есть

Не делайте

  • ❌ Используйте XML-теги - Простой текст работает лучше (если вы не хотите именно такую структуру)
  • ❌ Делайте слишком длинным - Стремитесь к 200-500 словам инструкций
  • ❌ Противоречьте себе - Будьте последовательны в своих требованиях
  • ❌ Забывайте о конце - Всегда напоминайте: "Ваш весь ответ будет использован непосредственно как сообщение коммита"

Советы

  • Начните с примера - Скопируйте ../../examples/custom_system_prompt.example.txt и измените его
  • Тестируйте с --dry-run - Увидьте результат без создания коммита
  • Используйте --show-prompt - Увидите, что отправляется в AI
  • Итерируйте на основе результатов - Если сообщения не совсем такие, как надо, отрегулируйте ваши инструкции
  • Контролируйте версию вашей подсказки - Храните вашу пользовательскую подсказку в репозитории вашей команды
  • Специфичные для проекта подсказки - Используйте проектный уровень .gac.env для специфичных для проекта стилей

Устранение неполадок

Сообщения всё ещё имеют префикс "chore:"

Проблема: Ваши пользовательские сообщения с эмодзи получают добавление "chore:".

Решение: Этого не должно происходить - GAC автоматически отключает принуждение обычных коммитов при использовании пользовательских системных подсказок. Если вы видите это, пожалуйста, создайте заявку.

AI игнорирует мои инструкции

Проблема: Сгенерированные сообщения не следуют вашему пользовательскому формату.

Решение:

  1. Сделайте ваши инструкции более явными и конкретными
  2. Добавьте чёткие примеры желаемого формата
  3. Закончите: "Ваш весь ответ будет использован непосредственно как сообщение коммита"
  4. Уменьшите количество требований - слишком многие могут запутать AI
  5. Попробуйте использовать другую модель (некоторые следуют инструкциям лучше, чем другие)

Сообщения слишком длинные/короткие

Проблема: Сгенерированные сообщения не соответствуют вашим требованиям к длине.

Решение:

  • Будьте явными о длине (например, "Держите сообщения под 50 символов")
  • Покажите примеры точной длины, которую вы хотите
  • Рассмотрите использование флага --one-liner также для коротких сообщений

Пользовательская подсказка не используется

Проблема: GAC всё ещё использует стандартный формат коммитов.

Решение:

  1. Проверьте, что GAC_SYSTEM_PROMPT_PATH установлен правильно:

    uvx gac config get GAC_SYSTEM_PROMPT_PATH

  2. Проверьте, что путь к файлу существует и читаем:

    cat "$GAC_SYSTEM_PROMPT_PATH"

  3. Проверьте файлы .gac.env в этом порядке:

    • Уровень проекта: ./.gac.env
    • Уровень пользователя: ~/.gac.env

  4. Попробуйте абсолютный путь вместо относительного

Конфигурация языка

Примечание: Вам не нужна пользовательская системная подсказка, чтобы изменить язык сообщений коммитов!

Если вы хотите изменить только язык ваших сообщений коммитов (сохраняя стандартный формат обычных коммитов), используйте интерактивный селектор языка:

uvx gac language

Это покажет интерактивное меню с 25+ языками в их родных сценариях (Español, Français, 日本語 и т.д.). Выберите ваш предпочтительный язык, и он автоматически установит GAC_LANGUAGE в вашем файле ~/.gac.env.

Альтернативно, вы можете вручную установить язык:

# В ~/.gac.env или проектном уровне .gac.env
GAC_LANGUAGE=Spanish

По умолчанию, префиксы обычных коммитов (feat:, fix: и т.д.) остаются на английском для совместимости с инструментами changelog и конвейерами CI/CD, в то время как весь остальной текст на вашем указанном языке.

Хотите перевести префиксы тоже? Установите GAC_TRANSLATE_PREFIXES=true в вашем .gac.env для полной локализации:

GAC_LANGUAGE=Spanish
GAC_TRANSLATE_PREFIXES=true

Это переведёт всё, включая префиксы (например, corrección: вместо fix:).

Это проще, чем создание пользовательской системной подсказки, если язык - ваша единственная потребность в настройке.

Хочу вернуться к стандартной

Проблема: Хочу временно использовать стандартные подсказки.

Решение:

# Вариант 1: Снять установку переменной окружения
uvx gac config unset GAC_SYSTEM_PROMPT_PATH

# Вариант 2: Закомментировать в .gac.env
# GAC_SYSTEM_PROMPT_PATH=/path/to/custom_prompt.txt

# Вариант 3: Использовать другой .gac.env для конкретных проектов

Связанная документация

  • USAGE.md - Флаги и опции командной строки
  • README.md - Установка и базовая настройка
  • TROUBLESHOOTING.md - Общее устранение неполадок

Нужна помощь?

  • Сообщайте о проблемах: GitHub Issues
  • Делитесь вашими пользовательскими подсказками: Взносы приветствуются!