Конфигурация Cursor живёт не в одном файле, а в семействе файлов с разными областями действия: разрешения, песочница, навыки, роли, обработчики событий, внешние серверы, плагины, деревья и облачное окружение. Главная ошибка в работе с ними - не незнание поля, а правильное поле в неправильном файле. Поэтому в справочнике первым столбцом стоит именно область, а не название параметра: без области имя поля почти бесполезно, ведь одинаковые по смыслу ключи встречаются в нескольких механизмах и означают в них разное.
Полезно один раз свести файлы и их предметы в таблицу. Ниже такая карта: что именно описывает каждый файл, где он лежит и что важно помнить про его слои. Это тот случай, когда обзорная картина полезнее подробностей: зная, какой файл за что отвечает, вы найдёте нужный ключ за минуту, а не будете искать его в четырёх местах.
| Файл | Что описывает | Что помнить |
|---|---|---|
| Файл разрешений | Команды терминала, инструменты серверов, указания проверке | Слои объединяются, но командная настройка в панели их перекрывает |
| Файл песочницы | Файловые и сетевые границы выполнения | Проектный слой важнее пользовательского |
| Правила проекта | Постоянные инструкции с областью применения | Требуют заголовка; обычный markdown игнорируется |
| Навыки | Процедуры со скриптами и материалами | Скрипты - исполняемый код, нужен ревью |
| Роли | Отдельные контексты с моделью и правами | Признак только для чтения несёт основную нагрузку |
| Обработчики событий | Реакции жизненного цикла | Исполняемая политика с приоритетом источников |
| Внешние серверы | Транспорт, адрес, авторизация, инструменты | Секреты подставляют из окружения |
| Плагины | Переносимый набор компонентов | Манифест и состав ревьюят перед установкой |
| Деревья | Подготовка изолированного checkout | Скрипты подготовки исполняются при создании |
| Облачное окружение | Сборка, установка, запуск | Установка идемпотентна; процессы не переживают этап |
Особое внимание стоит уделить приоритетам. У разных механизмов они разные: где-то проектный файл сильнее пользовательского, где-то массивы объединяются, где-то административный слой нельзя ослабить снизу. Единого правила нет, и это нормально - разные механизмы решают разные задачи. Но это значит, что приоритет проверяют в документации конкретного механизма, а не выводят по аналогии с соседним.
Как именно разрешается конфликт, лучше всего видно на сетевой политике песочницы. Там есть три части: список разрешённого, список запрещённого и действие по умолчанию, когда не подошло ни одно правило. Запрет имеет высший приоритет и блокирует даже то, что одновременно указано в разрешениях, а по умолчанию действие - запретить. Такая схема выбрана не случайно: она делает результат предсказуемым при добавлении правил, потому что новое разрешающее правило никогда не ослабляет уже написанный запрет. Проверяя чужую конфигурацию, начинают с запрещающего списка и значения по умолчанию, а не с разрешающего - именно они определяют форму границы.
Отдельная группа - файлы, которые содержат исполняемое содержимое: обработчики событий, скрипты навыков, скрипты подготовки деревьев, описания внешних серверов. Их отличает не формат, а последствия: они запускают код с вашими правами. К ним применяется правило ревью как к коду, а не как к настройкам. Практическая проверка: если файл может запустить процесс, он относится к этой группе, даже когда выглядит как безобидный список путей.
Есть и полезный организационный приём: разделить файлы по тому, кто их владелец. Личные предпочтения - в пользовательском слое, командные границы - в репозитории, обязательные требования - в административной политике. Когда это разделение соблюдено, вопрос кто может это изменить имеет очевидный ответ, а споры о конфигурации превращаются в обсуждение слоя, а не намерений.
Общий признак неправильно положенного ключа один: тишина. Неизвестное поле обычно не вызывает ошибку, файл читается, механизм работает по значениям по умолчанию, и снаружи всё выглядит настроенным. Отсюда набор частых случаев: файл навыка без заголовка воспринимается как обычный markdown и не подключается; имя навыка, не совпадающее с именем папки, ломает опознание; правило без описания и без шаблонов путей не имеет причины быть выбранным. Вывод практический: после правки конфигурации проверяют не то, что файл сохранился, а то, что механизм увидел изменение - через список загруженного или через попытку, которая раньше проходила, а теперь должна блокироваться.
Практическая проверка карты простая: возьмите любое требование из вашей политики и назовите файл, в котором оно живёт. Если такого файла нет или их несколько, требование существует только в головах. Это упражнение занимает полчаса и обычно находит два-три требования, которые все считали настроенными.
Инженерный вывод простой: карта файлов важнее списка полей. Поля меняются, а структура ответственности остаётся: границы - в одном месте, процедуры - в другом, исполняемое - в третьем и под ревью. Держа эту карту в голове, вы перестаёте искать ключ наугад и начинаете искать его там, где он должен быть.
Типичные провалы предсказуемы. Написать правильный ключ в неправильном файле. Вывести приоритет по аналогии с другим механизмом. Читать сетевую политику с разрешающего списка вместо запрещающего. Принять файл с исполняемым содержимым за обычную настройку. И иметь требование без файла, в котором оно живёт.