Книга про быстро меняющийся продукт устаревает двумя способами. Первый очевиден: выходит новая версия, и конкретная строка перестаёт быть верной. Второй коварнее: читатель принимает удобное обобщение автора за документированное поведение продукта и строит на нём процесс. Первый способ виден сразу - команда не находится, ключ не принимается. Второй молчит: процесс продолжает работать, пока не попадёт в условия, для которых обобщение никогда не было верным. Защита от обоих одна - строго различать, что утверждает производитель, а что выведено из этого утверждения, и всегда показывать, чем проверить факт прямо сейчас.
Поэтому в тексте два разных типа высказываний. Официальное - имя команды, ключ конфигурации, путь, событие, ограничение или статус функции, прямо описанные в документации Cursor: такие места опираются на первоисточник, и ссылки на него собраны в конце книги. Инженерный вывод - практическая рекомендация, которая следует из документированного механизма, но не является требованием продукта. Держать список разрешённых команд узким разумно, но это не правило Cursor, а следствие того, как устроены разрешения: продукт лишь даёт механизм, а решение о ширине списка принимаете вы и отвечаете за него тоже вы.
Разница между этими типами важнее, чем кажется. Приём, поданный как незыблемое правило, однажды упрётся в контекст, где он вреден, и вы не поймёте почему - ведь "так написано". Тот же приём, поданный как вывод из механизма, вы примените осознанно и там, где он к месту, а в неподходящем месте отбросите без внутреннего конфликта. Настройка приносит пользу только когда понятны три вещи: откуда она берётся, какое значение допустимо и чем грозит ошибка. Без третьего пункта настройка превращается в суеверие, которое команда передаёт из проекта в проект.
Отдельно стоит договориться про изменчивое. Каталог моделей, цены, доступность beta-функций, командные политики и то, что раскатывается постепенно, меняется быстрее, чем любой текст. Такие вещи здесь показаны как датированный снимок и снабжены способом проверить актуальное состояние: живой командой, страницей настроек или официальной документацией. Снимок полезен как ориентир и вреден как обещание. Постепенная раскатка делает его вдвойне ненадёжным: две учётные записи одной команды в один день могут видеть разный набор функций, и это не ошибка, а нормальный режим доставки.
Полезно один раз увидеть, как читать пометки в тексте. Ниже - короткая карта: официальное поведение, инженерный вывод, место повышенного риска и проверяемое действие. К ней возвращаются, когда нужно понять, на что можно опереться в споре о процессе, а что стоит перепроверить под свой контекст.
| Пометка | Как читать |
|---|---|
| Официально | Поведение, формат, ограничение или статус из первичной документации Cursor |
| Инженерный вывод | Практический baseline, выведенный из документированных механизмов |
| Осторожно | Место, где короткий путь расширяет права, стоимость или область изменения |
| Проверка | Действие с наблюдаемым результатом; отметка ставится после факта, а не намерения |
Разночтение между книгой и продуктом разбирается одинаково. Сначала определите тип высказывания: если это официальное - откройте связанную страницу документации и сверьте формулировку, потому что расхождение означает изменение в продукте. Если это инженерный вывод - сверять нечего, у него нет первоисточника, и вопрос переводится в другой: сохранился ли механизм, из которого вывод сделан. Механизм проверяется живой командой или страницей настроек в вашем аккаунте, а не памятью и не чужим пересказом. Ответ определяет и действие: официальное расхождение правит текст, изменившийся механизм отменяет рекомендацию целиком.
Цена смешения этих типов видна на командных решениях. Процесс, построенный на снимке цен или на доступности конкретной модели, ломается не в момент чтения, а через месяц, когда каталог изменился, и ломается тихо: сборка проходит, счёт растёт. Процесс, построенный на механизме, переживает смену каталога, потому что опирается на то, что в продукте устроено надолго: как выдаются разрешения, где живут правила, чем ограничена среда исполнения. Отсюда практический ориентир - в командные соглашения выносить механизмы, а имена и цифры держать в местах, которые не стыдно править каждый месяц.
Есть и практическое требование к читателю, без которого книга не работает. Перед тем как отпускать агента в реальный репозиторий, стоит знать, какая поверхность вам нужна, иметь понятный git status и способ отката, не вставлять токены и содержимое переменных окружения в запросы и проверять доступность изменчивых функций в своём аккаунте. Это не бюрократия: каждый пункт закрывает конкретный класс потерь, которые потом дороже разбирать.
Читать можно двумя способами. По порядку - главы идут от установки и первого управляемого проекта к ежедневной работе, безопасности, конфигурации, автоматизации и корпоративной раскатке, и каждая опирается на предыдущие. Или точечно - к нужному механизму: каждая глава самодостаточна и заканчивается тем, как проверить результат и куда вернуться, если что-то пошло не так.
Главный принцип простой: проверять состояние командой, а не памятью. Cursor меняется между релизами, и заученное однажды поведение расходится с текущим тихо, без предупреждения. Живой вывод команды, открытая страница настроек и актуальная документация всегда весомее уверенности - и своей, и чужой. Признак, по которому в работе замечают нарушение этого принципа, узнаваем: спор о поведении продукта идёт словами "раньше было" и "у меня работает", и никто за время спора не открыл ни одной страницы и не выполнил ни одной команды.