Обзор gstack: /freeze

Команда /freeze из репозитория gstack предназначена для ограничения операций записи (редактирования) искусственного интеллекта строго определенным каталогом. Это обеспечивает, что агент AI будет изменять файлы только внутри указанного пути, предотвращая случайные или нежелательные модификации в других частях файловой системы.

Категория процесса: gstack / Управление файлами.

Кому полезен: Разработчикам, QA-инженерам, менеджерам проектов, всем, кто использует AI-агентов для автоматизированной разработки или модификации кода и хочет обеспечить строгий контроль над зоной их действия.

исходный файл

Что делает команда /freeze

Команда /freeze устанавливает «границу заморозки» (freeze boundary) — конкретный каталог, за пределы которого AI-агент не может вносить изменения или записывать файлы. Любая попытка операции редактирования или записи файла вне этого разрешенного пути будет не просто предупреждена, а заблокирована. Эта функция особенно полезна при работе с большими кодовыми базами, когда необходимо убедиться, что AI-агент взаимодействует только с определенной частью проекта.

Как настроить /freeze:

1. Агент запросит у пользователя путь к каталогу, который необходимо ограничить.
2. Пользователь вводит путь.
3. Система преобразует введенный путь в абсолютный и сохраняет его в файл состояния (freeze-dir.txt), обеспечивая его постоянство в течение текущей сессии.
4. Пользователь получает подтверждение о том, что граница заморозки установлена, и что все операции редактирования/записи вне указанного каталога будут заблокированы.

Принцип работы:

На каждом вызове инструмента редактирования или записи система проверяет путь к файлу, который AI-агент пытается изменить. Если путь не начинается с каталога заморозки, операция блокируется с решением `permissionDecision: "deny"`. Граница заморозки сохраняется в течение сессии с помощью файла состояния, который считывается при каждой попытке операции записи.

/freeze в цикле Think→Plan→Build→Review→Test→Ship

• Think (Мыслить): На этапе планирования, когда определяется область работы AI-агента, /freeze помогает четко обозначить эту область, предотвращая распыление усилий или случайные изменения.
• Plan (Планировать): При разработке конкретного плана действий для AI, использование /freeze является частью стратегии по управлению рисками и обеспечению точности изменений.
• Build (Создавать): В фазе непосредственной генерации кода или внесения изменений, /freeze действует как защитный механизм, гарантируя, что агент создает или модифицирует файлы исключительно в целевом каталоге. Это критически важно для поддержания целостности проекта.
• Review (Просматривать): Во время ревью кода, если /freeze был активен, ревьюер может быть уверен, что изменения агента были ограничены заранее определенной областью, что упрощает проверку и снижает вероятность "побочных эффектов" в неожиданных местах.
• Test (Тестировать): Ограничивая область изменений, /freeze помогает создать более контролируемую тестовую среду, так как другие части системы остаются нетронутыми, уменьшая количество возможных переменных.
• Ship (Выпускать): Уверенность в том, что автоматизированные изменения были строго локализованы, способствует более безопасному и предсказуемому процессу выпуска.

Типичный сценарий использования

Представьте, что вы используете AI-агента для рефакторинга конкретного модуля в вашем большом проекте. Модуль находится в директории src/features/user_dashboard/. Вы хотите, чтобы агент изменил только файлы в этой директории, не затрагивая ничего другого. Вы можете запустить /freeze, указать путь src/features/user_dashboard/. Теперь, даже если AI-агент попытается изменить файл в src/utils/ или public/index.html, операция будет немедленно заблокирована, что предотвратит нежелательные изменения и сохранит фокус агента на поставленной задаче.

Важные примечания:

• Конечный слэш (/) в пути каталога заморозки предотвращает совпадение /src с /src-old.
• Заморозка применяется только к инструментам редактирования и записи; операции чтения, Bash-команды, глобальный поиск и Grep не затрагиваются.
• Это предотвращает случайные изменения, но не является барьером безопасности — Bash-команды, такие как sed, все еще могут модифицировать файлы вне границы.
• Для деактивации выполните команду /unfreeze или завершите текущую сессию.

Сводная таблица

Параметр	Значение
Лицензия	MIT
Исходный файл	freeze/SKILL.md
Репозиторий	gstack (Garry Tan, MIT)

Дисклеймер: Представленный материал является информационным обзором команды /freeze. Для получения наиболее актуальной информации и полного текста навыка рекомендуется обращаться непосредственно к репозиторию gstack на GitHub.

Автор исходного репозитория: Garry Tan, MIT.

Текст skill для копирования (перевод на русский)

# /freeze — Ограничение редактирования каталога

Заблокировать редактирование файлов в определенном каталоге. Любая операция редактирования или записи, направленная на файл вне разрешенного пути, будет заблокирована (а не просто выдаст предупреждение).

bash
mkdir -p ~/.gstack/analytics
echo '{"skill":"freeze","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true

## Настройка

Запросите у пользователя, какой каталог нужно ограничить для редактирования. Используйте AskUserQuestion:

- Вопрос: "Какой каталог мне следует ограничить для редактирования? Файлы вне этого пути будут заблокированы для редактирования."
- Ввод текста (не множественный выбор) — пользователь вводит путь.

Как только пользователь предоставит путь к каталогу:

1. Разрешите его в абсолютный путь:
bash
FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
echo "$FREEZE_DIR"

2. Убедитесь в наличии завершающего слэша и сохраните в файл состояния заморозки:
bash
FREEZE_DIR="${FREEZE_DIR%/}/"
STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
mkdir -p "$STATE_DIR"
echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
echo "Граница заморозки установлена: $FREEZE_DIR"

Сообщите пользователю: "Редактирование теперь ограничено '<путь>/'. Любая операция редактирования или записи вне этого каталога будет заблокирована. Чтобы изменить границу, снова запустите `/freeze`. Чтобы удалить её, запустите `/unfreeze` или завершите сессию."

## Как это работает

Хук считывает `file_path` из входного JSON инструмента редактирования/записи, затем проверяет, начинается ли путь с каталога заморозки. Если нет, он возвращает `permissionDecision: "deny"`, чтобы заблокировать операцию.

Граница заморозки сохраняется для сессии через файл состояния. Скрипт хука считывает его при каждом вызове операции редактирования/записи.

## Примечания

- Завершающий `/` в каталоге заморозки предотвращает совпадение `/src` с `/src-old`.
- Заморозка применяется только к инструментам редактирования и записи — чтение, Bash, Glob, Grep не затрагиваются.
- Это предотвращает случайные изменения, но не является барьером безопасности — Bash-команды, такие как `sed`, все еще могут модифицировать файлы вне границы.
- Для деактивации запустите `/unfreeze` или завершите беседу.