AI intro 2. Настройка macOS-окружения для AI-vibecoding в Claude Code

Этот урок описывает правильный порядок подготовки macOS для работы с Claude Code (Codex), GitHub, Python, JavaScript, аудио, Google-сервисами, plugins, MCP, AGENTS.md, skills и командной структурой папок.

Шаг 1. Актуальная macOS и учетная запись macOS с правами администратора

Перед настройкой окружения для AI-vibecoding на Claude Code (Codex) нужно убедиться, что сам компьютер готов к такой работе на уровне операционной системы.

1. Использовать современную macOS

Работать с Claude Code (Codex) необходимо только на актуальной, современной версии macOS 26 Tahoe с поддержкой обновлений. Работать на старых версиях операционной системы 3-5 летней давности нельзя.

Старая macOS почти неизбежно приведет к проблемам:

ошибки доступа;
ошибки прав;
несовместимость с современными инструментами разработки;
проблемы с установкой пакетов и зависимостей;
нестабильная работа терминала, браузеров, IDE, Claude Code (Codex) и сопутствующих инструментов.

Для AI-vibecoding важно, чтобы система поддерживала современные версии developer tools, shell-инструментов, браузеров, Node.js, Python, Docker/OrbStack, GitHub CLI и других компонентов окружения.

2. Установить все доступные обновления macOS

Недостаточно просто иметь новую macOS . Перед началом настройки AI окружения на вашем Desktop или Laptop нужно установить все доступные обновления системы на текущий день.

Проверка выполняется через:

System Settings -> General -> Software Update

Если macOS предлагает обновления, их нужно установить до настройки Claude Code (Codex)-окружения.

Это снижает риск случайных ошибок, связанных с:

устаревшими системными библиотеками;
неполными security updates;
несовместимостью Xcode Command Line Tools;
проблемами с разрешениями;
нестабильной работой терминала, shell-скриптов и package managers.

3. Работать из основной учетной записи администратора

Настраивать и использовать AI-vibecoding окружение нужно из основной учетной записи macOS с правами администратора.

Не нужно начинать настройку из ограниченной учетной записи, guest-аккаунта или профиля без admin-доступа.

Права администратора нужны для:

установки developer tools;
установки Homebrew и системных зависимостей;
настройки shell и путей;
управления разрешениями macOS;
установки браузеров, IDE, CLI-инструментов и локальных сервисов;
устранения проблем с доступом к файлам, сертификатам, ключам и локальным серверам.

Правило

Первый шаг перед любой установкой:

macOS должна быть современной, полностью обновленной и использоваться из учетной записи администратора.

Если это условие не выполнено, настройку окружения для Claude Code (Codex) лучше не начинать: дальнейшие ошибки будут выглядеть как проблемы Claude Code, Node.js, Python, Git или Homebrew, хотя на самом деле причина будет в неподготовленной системе.

Шаг 2. Установить Claude Code и создать рабочую папку проектов

После проверки macOS, обновлений и прав администратора следующий шаг - установить Claude Code (Codex) и подготовить место в файловой системе, где будут лежать проекты для AI-vibecoding.

1. Где хранить проекты Claude Code на macOS

На macOS аналог привычной папки "Мои документы" - это:

~/Documents

Для работы с Claude Code (Codex) лучше создать внутри нее отдельную папку:

~/Documents/Claude
~/Documents/Codex

Именно туда стоит складывать папки проектов, с которыми будет работать Claude Code:

~/Documents/Claude/
  AI/
  Product/
  Project-1/
  Project-2/
  Product-docs/
  Experiments/

Для базового командного onboarding можно сразу создать две стартовые папки:

~/Documents/Claude/
  AI/
  Product/

AI - это папка для настройки Claude Code, обучения, handoff-документов, экспериментов с AI-инструментами и материалов по AI-workflow.

Product - это папка для продуктовой работы: PRD, спецификаций, транскриптов, Markdown-документов, базы знаний и файлов, которые затем могут синхронизироваться с GitHub, Confluence или другими командными системами.

Имена папок лучше писать латиницей: AI, Product, Claude. Так меньше шансов столкнуться с проблемами в shell-скриптах, путях, CI, package managers и инструментах разработки.

Почему лучше использовать именно `~/Documents/Claude, а не случайные папки на рабочем столе или в Downloads:

путь понятный человеку и агенту;
правильные права доступа на папки и файлы в AI проектах (самое важное);
проекты лежат в одном предсказуемом месте;
меньше риска потерять файлы среди загрузок и временных документов;
удобнее выдавать Claude контекст: "работай в проекте из ~/Documents/Claude/...";
проще делать резервные копии;
проще переносить рабочую структуру на новый Mac.

Папку можно создать через Finder или через Terminal:

mkdir -p "$HOME/Documents/Claude"

2. Установить Claude Code CLI

Claude Code CLI нужен для работы из терминала: открыть папку проекта, запустить claude, дать задачу агенту, позволить ему читать файлы, править код и запускать команды.

Актуальный официальный способ установки на macOS/Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

После установки нужно проверить, что команда доступна:

codex --version

Затем можно перейти в рабочую папку и запустить Claude Code (Codex):

cd "$HOME/Documents/Claude Code (Codex)"
codex

При первом запуске Claude Code (Codex) попросит войти через ChatGPT-аккаунт или OpenAI API key.

3. Установить Claude Code desktop app

После CLI, на macOS необходимо установить Claude Code (Codex) desktop app. Для полноценной работы с AI инфраструктурой вам требуется именно desktop версия Claude, которая содержит Claude Code и Claude Co-work. Работа с Claude только через браузерную версию значительно ограничивает ваши возможности.

Claude Code (Codex) app требуется для:

работы с установленными локально папками и файлами
работы с установленными локально языками программирования
полноценной работы с плагинами, подключением к сервисам Google, Atlassian, Github
кодинга и вайбкодинга
использования голосового интерфейса и интерфейса картинок/скриншотов в кодинге
работы с несколькими проектами;
запуска actions вроде dev server, tests, build;
более удобного повседневного AI-vibecoding, чем только терминал.

При установке Codex Desktop app На Mac с Apple Silicon нужно выбирать сборку для Apple Silicon. На Mac с процессорами Intel Core - сборку для Intel.

4. Как должна выглядеть базовая структура на Mac

Минимальная структура локальных папок на первом шаге:

~/Documents/Claude/
  AI/
  Product/

Пользователь создает в главной папке Claude внутри Documents папки своих проектов:

cd "$HOME/Documents/Claude/Product"
claude

И далее добавляет эти проекты в Claude Code desktop app через Project -> Use an existing folder.

Важно: если папка создается для проекта с которым уже работает команда, то не нужно сразу писать туда случайные файлы. Необходимо найти соответствующий проекту GitHub repository, и уже из GitHub repository заполнить содержимое проекта.

Иначе очень легко получить две разные "актуальные" версии проекта.

5. Правило

Второй шаг настройки:

Установить Claude Code CLI, установить Claude Code Desktop App и создать постоянную рабочую папку `~/Documents/Claude для всех проектов, с которыми будет работать Claude Code.

Не нужно разбрасывать проекты по Desktop, Downloads и случайным временным папкам. Claude Code работает лучше, когда у него есть стабильная, понятная структура файловой системы с правильными правами и доступами к локальным папкам и файлам.

Шаг 03. Терминал и командная строка на macOS

После установки Claude Code (Codex) нужно правильно договориться, через какую командную строку команда работает на Mac.

Приложение командной строки, или терминал требуется для запуска и выполнения низкоуровневых команд для операционной системы и файлов при работе с кодингом и вайбкодингом.

В Windows мы часто говорим "поставить PowerShell 7". На macOS ситуация другая: базовая командная строка уже встроена в систему.

1. Что является аналогом PowerShell 7 на macOS

На macOS есть две разные вещи, которые часто путают:

терминальное приложение, то есть окно, в котором вводятся команды;
shell, то есть программа, которая эти команды понимает и выполняет.

Встроенное терминальное приложение называется:

Terminal.app

Встроенный стандартный shell на современных macOS:

zsh

zsh отдельно устанавливать не нужно. Он уже входит в современную macOS и обычно запускается по умолчанию внутри стандартного Terminal.app.

То есть базовый аналог рабочей командной строки на Mac - это не PowerShell, а связка:

Terminal.app + zsh

Этого достаточно, чтобы выполнять команды установки, запускать Claude Code (Codex) CLI, работать с Git, Homebrew, Node.js, Python и проектами.

Проверить, какой shell сейчас используется:

echo "$SHELL"

Нормальный ожидаемый результат:

/bin/zsh

Проверить версию zsh:

zsh --version

2. Достаточно ли встроенного Terminal.app

Да, для начала встроенного Terminal.app достаточно.

Он уже есть в macOS и находится здесь:

Applications -> Utilities -> Terminal

Или его можно открыть через Spotlight:

Cmd + Space -> Terminal -> Enter

Для первой настройки AI окружения не нужно ставить дополнительный терминал. Чем меньше лишних шагов до рабочего Claude Code , тем лучше.

4. Когда стоит поставить iTerm2

После базовой настройки можно поставить iTerm2 как более удобное терминальное приложение.

iTerm2 не заменяет shell. Он заменяет только окно терминала. Внутри него все равно обычно работает тот же zsh.

iTerm2 полезен, если человеку нужны:

удобные вкладки и split panes;
профили;
быстрый поиск по истории вывода;
более гибкая настройка шрифтов и цветов;
комфортная ежедневная работа в терминале.

Но iTerm2 не должен быть обязательным первым шагом. Сначала команда должна уметь открыть обычный Terminal.app и выполнить базовые команды.

6. Что должен уметь каждый участник команды

Перед дальнейшей установкой окружения человек должен уметь:

открыть Terminal.app;
перейти в папку проектов:

cd "$HOME/Documents/Claude"

посмотреть текущую папку:

pwd

посмотреть список файлов:

ls

создать папку:

mkdir -p "$HOME/Documents/Claude"

запустить Claude Code:

claude

7. Правило

Третий шаг настройки:

На macOS команда работает через встроенный Terminal.app и стандартный shell zsh. iTerm2 можно установить позже как более удобное терминальное окно, но не как обязательное условие для старта.

Такой подход проще, ближе к самой macOS и лучше совместим с большинством developer tools, которые используются в AI-vibecoding.

Шаг 04. Скриншоты на macOS для работы с Claude Code

Для AI-vibecoding с Claude Code (Codex) скриншоты - один из главных способов передавать контекст. Команда должна уметь быстро снять нужное окно или область экрана и сразу вставить изображение в Claude Code.

1. Нужен ли отдельный скриншотер

На первом этапе отдельный скриншотер устанавливать не нужно.

В macOS уже есть встроенный инструмент для скриншотов. Он достаточно хорош для базовой работы с Claude Code:

снять весь экран;
снять выбранную область;
снять конкретное окно;
скопировать скриншот сразу в буфер обмена;
вставить скриншот в Claude Code (Codex) без сохранения файла на диск.

Это ровно тот сценарий, который нужен для общения с Claude Code (Codex) через скриншоты и голосовые сообщения.

2. Главное требование

Главное требование к скриншотеру:

Нажать горячую клавишу, выбрать конкретное окно или область, положить картинку в буфер обмена и сразу вставить ее в Claude Code (Codex).

На Mac вставка обычно выполняется не через Ctrl+V, а через:

Cmd+V

То есть рабочий сценарий такой:

сделал скриншот -> скриншот попал в clipboard -> открыл Claude Code (Codex) -> нажал Cmd+V

3. Базовые горячие клавиши macOS

Скриншот области экрана в файл:

Shift+Cmd+4

Скриншот области экрана сразу в буфер обмена:

Ctrl+Shift+Cmd+4

После этого нужно выделить нужную область мышью. Скриншот не сохранится отдельным файлом, а попадет в clipboard. Потом его можно вставить в Claude Code (Codex) через Cmd+V.

Скриншот конкретного окна в буфер обмена:

Ctrl+Shift+Cmd+4 -> Space -> клик по нужному окну

Это самый важный вариант для работы с Claude Code (Codex), потому что он позволяет быстро показать агенту конкретное окно: браузер, терминал, ошибку, IDE, настройки macOS или результат работы приложения.

Панель Screenshot:

Shift+Cmd+5

Через нее можно выбрать режим скриншота или записи экрана, а также настроить, куда сохраняются скриншоты.

4. Best practice для команды

Командный стандарт:

Основной инструмент: встроенный macOS Screenshot
Обязательный навык: скриншот области или окна сразу в буфер обмена
Основная вставка в Claude Code (Codex): Cmd+V
Сторонний скриншотер: не обязателен на старте

Каждый участник команды должен выучить минимум две команды:

Ctrl+Shift+Cmd+4

для скриншота области в буфер обмена.

Ctrl+Shift+Cmd+4 -> Space -> click

для скриншота конкретного окна в буфер обмена.

5. Правило

Четвертый шаг настройки:

Команда использует встроенный macOS Screenshot и обязательно умеет делать скриншот области или конкретного окна сразу в буфер обмена, чтобы вставлять его в Claude Code (Codex) через Cmd+V.

Это критично, потому что эффективная работа с Claude Code (Codex) строится не только на тексте, но и на быстрых скриншотах ошибок, интерфейсов, терминала, браузера и результатов работы приложения.

Шаг 05. Xcode Command Line Tools на macOS

На Windows для JavaScript/Node.js-проектов иногда нужно устанавливать Microsoft Visual Studio Build Tools 2022, чтобы собирались native dependencies: пакеты, которые во время npm install или pnpm install компилируют C/C++-код через node-gyp.

На macOS устанавливается Xcode Command Line Tools.

Этот пункт нужно выполнять до установки Git, GitHub CLI, Homebrew, Python-пакетов, Node.js-пакетов и FFmpeg, потому что Xcode Command Line Tools дают macOS базовый developer toolchain.

1. Xcode Command Line Tools на macOS

Build tools на macOS - это инструменты Apple:

Xcode Command Line Tools

Их также называют:

Command Line Tools for Xcode

Они дают системе compiler toolchain, который нужен для сборки native packages:

clang;
make;
headers;
SDK;
developer command-line utilities.

2. Входит ли это в macOS по умолчанию

Xcode Command Line Tools - это инструменты Apple для macOS, но они не всегда установлены на чистом Mac.

Они могли уже установиться раньше, например:

при установке Git;
при первом запуске developer command;
при установке Homebrew;
при установке Xcode;
при выполнении xcode-select --install.

Поэтому правильный подход:

не предполагать, а проверить

3. Как проверить установку

Проверить путь к active developer tools:

xcode-select -p

Если tools установлены, команда покажет путь, например:

/Library/Developer/CommandLineTools

Проверить compiler:

clang --version

Проверить make:

make --version

Если эти команды работают, базовые build tools готовы.

4. Как установить Xcode Command Line Tools

Если tools не установлены:

xcode-select --install

macOS откроет системное окно установки. Нужно согласиться на установку и дождаться завершения.

После установки снова проверить:

xcode-select -p
clang --version
make --version

5. Полный Xcode обычно не нужен

Полное приложение Xcode занимает много места и нужно не всегда.

Для большинства задач Claude Code (Codex), Node.js, Python, Homebrew, Git и native npm/pnpm dependencies достаточно:

Xcode Command Line Tools

Полный Xcode нужен только если проект явно связан с:

iOS-разработкой;
macOS app development;
Swift/Objective-C проектами;
Xcode projects;
симуляторами iPhone/iPad;
сборкой Apple-приложений.

Если таких задач нет, полный Xcode не ставим по умолчанию.

6. Связь с Node.js и pnpm

Некоторые JavaScript-пакеты при установке могут запускать node-gyp и собирать native module.

Если Xcode Command Line Tools не установлены, можно увидеть ошибки вроде:

gyp ERR!
No Xcode or CLT version detected
make failed
clang not found

В таком случае нужно проверить и установить Xcode Command Line Tools.

7. Не искать инструкции самостоятельно

Строгое правило:

Если pnpm install, npm install, Python package install или Homebrew падает с ошибкой сборки на macOS, нужно спросить Claude Code (Codex), какие build tools нужны. Не нужно искать случайные инструкции в интернете.

Правильный запрос:

Claude, на macOS при установке Node.js/Python пакетов падает сборка native dependency. Вот полный лог ошибки. Проверь, установлены ли Xcode Command Line Tools, и скажи, какие команды выполнить.

Если появляется системное окно установки:

Claude, macOS предлагает установить Command Line Tools for Xcode. Это нужно для Claude Code окружения? Вот скриншот.

8. Не чинить developer tools наугад

Не нужно без инструкции выполнять команды вроде:

sudo xcode-select --switch ...
sudo rm -rf /Library/Developer/CommandLineTools

Это может сломать Homebrew, Git, Python packages и Node.js native builds.

Если xcode-select или clang ведут себя странно, нужно показать Claude Code (Codex):

xcode-select -p
xcode-select --version
clang --version
make --version

и полный текст ошибки.

9. Правило

Пятый шаг настройки:

На macOS для Claude Code окружения ставим Xcode Command Line Tools. Этот шаг выполняется до установки Git и остальных developer tools. Если установка Xcode выдает непонятные ошибки, или если ошибки выходят в процессе работы с Xcode вернитесь на два шага назад и проверьте чистая и новая ли у вас macOS. Если нет то переустановите macOS предварительно сохранив ваши личные и рабочие файлы. На чистой macOS ошибок с Xcode не будет.

Проверка:

xcode-select -p
clang --version
make --version

Установка при необходимости:

xcode-select --install

Дополнительное правило:

Если сборка JavaScript/Python-пакетов падает не чиним compiler toolchain наугад. Спрашиваем Claude Code (Codex) и действуем по точной инструкции для macOS.

Шаг 06. Установить и настроить Git

Git - обязательный инструмент для AI-vibecoding с Claude Code (Codex). Без Git сложнее и даже невозможно безопасно менять код, проверять diff, откатывать ошибки, делать коммиты, открывать pull request и понимать, что именно изменил агент.

Перед этим пунктом должны быть установлены или проверены Xcode Command Line Tools. На macOS именно они дают базовые developer-инструменты, через которые часто устанавливается или активируется Git.

1. Есть ли Git в macOS по умолчанию

На macOS Git часто уже доступен после установки Xcode Command Line Tools.

Проверить можно в Terminal.app:

git --version

Если Git уже установлен, команда покажет версию, например:

git version 2.x.x

Если Git не установлен, macOS может предложить установить Xcode Command Line Tools. Это нормальный путь для Mac.

Команда для установки Xcode Command Line Tools:

xcode-select --install

После установки нужно снова проверить:

git --version

2. Не искать ссылку на Git самостоятельно

Если Вам нужна актуальная ссылка на скачивание Git или он не понимает, какой способ установки выбрать, то не нужно искать это самостоятельно в случайных статьях и видео.

Правило:

Актуальную ссылку или способ установки Git нужно спросить у Claude Code (Codex).

Пример запроса:

Claude, мне нужно установить Git на macOS. Подскажи актуальный официальный способ установки для моего случая и дай ссылку, если она нужна.

На macOS чаще всего ссылка вообще не нужна: достаточно Xcode Command Line Tools или Homebrew. Но если Claude Code (Codex) рекомендует скачать установщик, он должен дать актуальную официальную ссылку и объяснить, почему выбран именно этот вариант.

3. Не угадывать галочки в установщике

В Windows-установщике Git действительно много экранов с настройками и галочками. На macOS такой сценарий встречается реже, но правило все равно должно быть общим для команды.

Строгое правило:

Не угадывать настройки установщика Git. Если на экране появились галочки, варианты PATH, editor, line endings, SSH, credential helper или другие непонятные настройки, нужно отправить скриншот в Claude Code и спросить, что выбрать.

Правильный запрос:

Claude, я сейчас устанавливаю Git и буду присылать тебе скриншоты экранов с настройками. Пожалуйста, скажи, какие галочки и варианты выбрать, чтобы Git был настроен для AI-vibecoding с Claude Code на macOS.

Дальше отправляете скриншоты каждого непонятного шага установки в Claude Code и он объясняет, что выбрать и почему.

Это важно, потому что неправильные настройки Git могут привести к проблемам:

Git не находится в терминале;
коммиты создаются с неправильным именем или email;
SSH-ключи не работают;
GitHub просит пароль снова и снова;
меняются переносы строк в файлах;
Claude Code видит лишние изменения в diff;
pull/push работают нестабильно.

4. Рекомендуемый путь установки Git на macOS

Для команды базовый путь такой:

Открыть Terminal.app.
Проверить Git:

git --version

Если Git не установлен, установить Xcode Command Line Tools:

xcode-select --install

После установки снова проверить:

git --version

Позже, после установки Homebrew, можно при необходимости поставить более свежий Git через Homebrew:

brew install git

Но на первом этапе не нужно усложнять. Если Git через Xcode Command Line Tools работает, этого достаточно для старта.

5. Базовая настройка Git

После установки нужно один раз указать имя и email для коммитов:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Проверить настройки:

git config --global --list

Минимально должны быть видны:

user.name=Your Name
[email protected]

Email лучше использовать тот, который связан с GitHub-аккаунтом. Если используется приватный GitHub noreply email, нужно взять его из настроек GitHub и вставить сюда.

6. Git должен работать из папки проектов Claude Code

После настройки нужно проверить Git в рабочей папке:

cd "$HOME/Documents/Claude"
git --version

Если команда показывает версию Git, значит Claude Code CLI тоже сможет использовать Git внутри проектов.

Для конкретного проекта полезно проверить:

git status

Если папка уже является Git-репозиторием, команда покажет состояние рабочей копии. Если нет, Git честно скажет, что это не repository. Это нормально.

7. Что еще важно для Claude Code (Codex)

Для AI-vibecoding Git нужен не только "чтобы был установлен". Он нужен как система безопасности.

Перед крупной задачей желательно иметь чистый статус:

git status

Если есть важные незакоммиченные изменения, их нужно сохранить или закоммитить до того, как Claude Code начнет активно менять проект.

После работы Claude Code нужно снова смотреть:

git diff
git status

Так человек понимает, какие файлы изменились и что именно сделал агент.

8. Правило

Шестой шаг настройки:

Git должен быть установлен, доступен из Terminal.app, настроен с правильными user.name и user.email, и проверен в папке `~/Documents/Claude.

Дополнительное строгое правило:

Не искать случайные инструкции и не угадывать галочки установщика Git. Актуальный способ установки и все непонятные настройки нужно спрашивать у Claude Code (Codex), присылая скриншоты экранов установки.

Так Git становится не случайной программой на компьютере, а нормальной основой для безопасной работы Claude Code (Codex) с кодом.

Шаг 07. Установить Homebrew

После Xcode Command Line Tools и Git нужно установить Homebrew.

Homebrew - это package manager для macOS. Он нужен, чтобы удобно устанавливать и обновлять developer tools, command-line utilities, libraries и некоторые desktop-приложения.

Для Claude Code (Codex) - окружения Homebrew особенно полезен, потому что через него удобно ставить:

GitHub CLI (gh);
FFmpeg;
libsndfile для Python audio-пакетов;
Node.js, если команда выбирает Homebrew-путь;
Python versions, если команда выбирает Homebrew-путь;
дополнительные command-line tools.

1. Homebrew не входит в macOS

Homebrew не является стандартной частью macOS.

Его нужно устанавливать отдельно.

Проверить, установлен ли Homebrew:

brew --version

Если команда не находится, Homebrew еще не установлен или не добавлен в PATH.

2. Почему Homebrew ставим после Git

Homebrew активно использует developer-инфраструктуру macOS и GitHub.

Поэтому правильный порядок:

Xcode Command Line Tools -> Git -> Homebrew

Xcode Command Line Tools дают compiler/developer toolchain.

Git нужен для работы с репозиториями и может использоваться Homebrew.

Homebrew уже ставится поверх этого базового слоя.

3. Не искать команду установки самостоятельно

Строгое правило:

Ссылку на Homebrew и команду установки Homebrew нужно спрашивать у Claude Code (Codex). Не нужно искать случайные инструкции в интернете и копировать команды из статей, видео или форумов.

Правильный запрос:

Claude, мне нужно установить Homebrew на macOS для Claude Code окружения. Подскажи актуальную официальную команду установки, проверь порядок шагов и скажи, что делать после установки с PATH.

На момент составления этой инструкции официальный install script Homebrew выглядит так:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Но в рабочей инструкции для команды главное правило остается прежним:

Актуальную команду берем у Claude Code (Codex), а Claude Code должен опираться на официальный сайт Homebrew.

4. Установка

Перед установкой проверить:

xcode-select -p
git --version

Если оба шага работают, спросить Claude Code актуальную команду установки Homebrew и выполнить ее в Terminal.app.

После запуска installer внимательно читать вывод. Homebrew installer обычно объясняет, что он собирается сделать, и может попросить пароль администратора.

Если появляется непонятный prompt, не угадывать ответ:

Claude, я устанавливаю Homebrew на macOS. Вот скриншот/вывод installer. Скажи, что выбрать и можно ли продолжать.

5. PATH после установки Homebrew

После установки Homebrew почти всегда печатает блок Next steps.

В нем могут быть команды, которые нужно добавить в shell config, чтобы brew находился в Terminal.app.

Для Apple Silicon Mac Homebrew обычно устанавливается сюда:

/opt/homebrew

Для Intel Mac Homebrew обычно устанавливается сюда:

/usr/local

Но команды для PATH нельзя придумывать вручную.

Строгое правило:

Команды из блока Next steps нужно показать Claude Code (Codex) или скопировать в Claude Code и выполнить только после подтверждения. Особенно если речь идет о ~/.zprofile, ~/.zshrc или PATH.

Правильный запрос:

Claude, Homebrew установился и показал Next steps. Вот полный текст. Скажи, какие команды выполнить, чтобы brew правильно добавился в PATH на моем Mac.

6. Проверка установки

После установки открыть новое окно Terminal.app и выполнить:

brew --version
brew doctor

brew --version должен показать версию Homebrew.

brew doctor может показать предупреждения. Не все предупреждения критичны, но их нужно прочитать.

Если brew doctor показывает непонятные warning или error, не чинить наугад:

Claude, вот вывод brew doctor на macOS. Объясни, какие предупреждения важны для Claude окружения и что безопасно исправить.

7. Что можно ставить через Homebrew

После установки Homebrew можно ставить developer tools:

brew install gh
brew install ffmpeg
brew install libsndfile

Но каждую конкретную команду установки лучше брать из соответствующего пункта инструкции или спрашивать Claude Code (Codex).

Homebrew - это не повод ставить все подряд глобально.

8. Не использовать случайный sudo

Если случайная инструкция предлагает чинить Homebrew через:

sudo chown
sudo chmod
sudo rm -rf

нужно остановиться и спросить Claude Code (Codex).

Homebrew может попросить пароль во время установки, но регулярная работа brew install ... обычно не должна превращаться в хаотичный набор sudo-команд.

9. Правило

Седьмой шаг настройки:

После Xcode Command Line Tools и Git устанавливаем Homebrew. Homebrew не входит в macOS, но нужен как package manager для установки GitHub CLI, FFmpeg, audio libraries и других developer tools.

Дополнительное строгое правило:

Ссылку, команду установки и PATH-настройку Homebrew берем у Claude Code (Codex). Не ищем случайные инструкции в интернете, не правим shell config наугад и не запускаем sudo-команды без понимания.

Шаг 08. Установить GitHub CLI

После установки Git и Homebrew нужно установить GitHub CLI. Это интерфейс командной строки GitHub, который позволяет работать с GitHub из Terminal.app: авторизоваться, проверять репозитории, создавать pull request, смотреть issues, читать статусы CI и выполнять другие действия без переключения в браузер.

GitHub CLI запускается командой:

gh

1. Сначала нужна учетная запись GitHub

GitHub CLI нужно устанавливать и настраивать только после того, как у человека уже есть корпоративная GitHub-учетная запись.

Почему:

после установки gh нужно будет авторизоваться в GitHub;
для авторизации нужен существующий GitHub-аккаунт;
без авторизации GitHub CLI установлен, но почти бесполезен для реальной работы;
Claude Code (Codex) не сможет помогать с pull request, issues и GitHub workflows через локальный gh, если пользователь не вошел в GitHub.

Правило:

Сначала создать или подготовить GitHub-аккаунт, потом устанавливать и авторизовывать GitHub CLI.

2. Не искать команду установки самостоятельно

В Windows GitHub CLI часто устанавливают прямо из командной строки специальной командой. На macOS тоже есть командный способ установки, но его не нужно искать в интернете вручную.

Строгое правило:

Актуальную команду установки GitHub CLI нужно спросить у Claude Code (Codex).

Пример запроса:

Claude, мне нужно установить GitHub CLI на macOS. Подскажи актуальную официальную команду установки для моего Mac и учти, есть ли у меня Homebrew.

Это важно, потому что способ установки зависит от ситуации:

установлен ли Homebrew;
Apple Silicon Mac или Intel Mac;
обычный GitHub.com или GitHub Enterprise;
есть ли корпоративные ограничения на установку пакетов;
нужна ли установка через package manager или через официальный binary/pkg.

На момент составления этой инструкции официальный базовый способ для macOS через Homebrew:

brew install gh

Но в рабочей инструкции для команды главное правило остается прежним: не искать случайные статьи, а спрашивать Claude Code (Codex) и использовать официальный способ.

3. Проверить установку

После установки нужно проверить, что команда gh доступна:

gh --version

Если команда показывает версию GitHub CLI, установка прошла успешно.

Если Terminal.app пишет, что gh не найден, нужно не угадывать решение, а спросить Claude Code (Codex):

Claude, я установил GitHub CLI на macOS, но команда gh не находится в Terminal.app. Помоги проверить PATH и исправить установку.

4. Авторизоваться в GitHub

После установки нужно выполнить авторизацию:

gh auth login

Обычно GitHub CLI задаст несколько вопросов:

GitHub.com или GitHub Enterprise Server;
HTTPS или SSH;
открыть браузер для авторизации или вставить token;
какой Git protocol использовать по умолчанию.

Если человек не уверен, что выбирать, он должен прислать скриншот в Claude Code (Codex) и спросить.

Пример запроса:

Claude, я запускаю gh auth login на macOS. Вот скриншот с вариантами. Скажи, что выбрать для обычной работы с GitHub и Claude Code.

5. Проверить авторизацию

После входа нужно проверить статус:

gh auth status

Ожидаемый результат: GitHub CLI должен показать, что пользователь авторизован в GitHub.

Если используется несколько аккаунтов или GitHub Enterprise, нужно явно проверить, в какой аккаунт выполнен вход.

6. Проверить работу в папке проектов Claude Code

После установки и авторизации нужно перейти в рабочую папку:

cd "$HOME/Documents/Claude"

И проверить:

gh auth status
gh repo list

Если gh repo list показывает репозитории аккаунта, значит GitHub CLI готов к работе.

Внутри конкретного GitHub-репозитория полезно проверить:

gh repo view

Если команда показывает информацию о текущем репозитории, значит локальная папка связана с GitHub.

7. Особенности macOS

На macOS GitHub CLI обычно удобнее всего ставить через Homebrew:

brew install gh

Но это предполагает, что Homebrew уже установлен. Если Homebrew еще не установлен, нужно сначала перейти к пункту инструкции про Homebrew или спросить Claude Code (Codex), какой путь установки выбрать сейчас.

На Mac важно помнить:

команды выполняются в Terminal.app;
shell обычно zsh;
вставка текста и скриншотов обычно через Cmd+V;
если появляются системные запросы доступа, не нажимать случайно, а прислать скриншот в Claude Code;
если авторизация открывает браузер, нужно войти именно в нужный GitHub-аккаунт.

8. Правило

Восьмой шаг настройки:

GitHub CLI устанавливается только после подготовки GitHub-аккаунта. Актуальную команду установки нужно спросить у Claude Code. После установки обязательно выполнить gh auth login и проверить результат через gh auth status.

Дополнительное правило:

Если при установке или авторизации GitHub CLI появляются непонятные варианты выбора, галочки, вопросы про HTTPS/SSH, browser login, token или GitHub Enterprise, человек не угадывает ответ, а присылает скриншот в Claude Code (Codex).

GitHub CLI должен стать стандартным мостом между локальной папкой проекта, GitHub и Claude Code (Codex).

Шаг 09. Установить Python на macOS

Python в окружении для Claude Code (Codex) нужен не потому, что нам нравится или не нравится этот язык.

Python нужен потому, что большая часть простых автоматизаций в AI-vibecoding удобно делается именно Python-скриптами:

взять данные из одного файла и переложить в другой;
распарсить CSV, JSON, Markdown, HTML или текстовый лог;
собрать маленький отчет;
переименовать набор файлов;
проверить структуру папок;
подготовить данные для импорта;
быстро написать одноразовый utility script;
автоматизировать рутинное действие, которое руками делать долго и рискованно.

Для Claude Code (Codex) Python - это не вопрос вкуса, а обязательный рабочий инструмент.

1. Python обязателен

Каждый Mac, подготовленный для AI-vibecoding с Claude Code (Codex), должен иметь рабочий Python 3.

Проверить наличие Python:

python3 --version

Проверить pip:

python3 -m pip --version

Если эти команды не работают или показывают неподходящую версию, Python нужно установить.

2. Не искать ссылку самостоятельно

Актуальную ссылку на скачивание Python или актуальную команду установки не нужно искать самостоятельно в интернете.

Правило:

Ссылку на скачивание Python и способ установки нужно спросить у Claude Code (Codex).

Пример запроса:

Claude, мне нужно установить Python на macOS для AI-vibecoding. Подскажи актуальную официальную ссылку или команду установки. Нужна стабильная версия Python 3.12.x, а не самая новая experimental/latest версия.

Это важно, потому что на сайте Python может быть крупная кнопка с самой новой версией, но для нашей задачи не нужна самая новая версия. Нам нужна самая стабильная и совместимая версия языка программирования Python для повседневных автоматизаций.

3. Какую версию Python ставить

Для нашего Claude Code (Codex)-окружения базовый стандарт:

Python 3.12.x

На 18 июня 2026 года последняя версия в ветке 3.12 - Python 3.12.13.

При этом официально более новые ветки уже существуют: Python 3.13 находится в bugfix support, Python 3.14 является latest feature release. Но для стабильного AI-vibecoding мы не гонимся за самой новой версией.

Почему выбираем 3.12.x:

зрелая и широко поддерживаемая ветка;
хорошая совместимость с библиотеками;
меньше риска, что простые automation scripts сломаются из-за свежих изменений;
достаточно новая версия для большинства современных Python-инструментов;
более предсказуемая среда для команды.

Строгое правило:

Для базового Claude Code окружения ставим Python 3.12.x. Python 3.14 и более новые версии не ставим по умолчанию, пока команда отдельно не решила обновить стандарт и не проверила совместимость.

4. Встроенный Python в macOS

В macOS могут быть системные компоненты Python или developer tools, связанные с Python.

Правило:

Не трогать системный Python macOS и не рассчитывать на него как на рабочий Python для Claude Code (Codex).

Системный Python нужен самой macOS или Apple developer tools. Его не нужно удалять, перезаписывать или чинить вручную.

Для работы Claude Code (Codex) ставится отдельный пользовательский/developer Python.

5. Куда ставить Python на macOS

На Windows иногда используют установку в корень диска C:\, чтобы Python был доступен предсказуемо.

На macOS так делать не нужно. У macOS другая структура файловой системы и другой подход к установке developer tools.

Правильный подход:

не ставить Python в корень диска;
не менять системные папки вручную;
использовать официальный macOS installer с python.org или package manager;
проверять доступность через Terminal.app.

Официальный macOS installer Python обычно устанавливает Python в системно ожидаемую developer-локацию вроде:

/Library/Frameworks/Python.framework/Versions/3.12

И добавляет команды для запуска Python 3.12 в стандартные пути.

Если Python ставится через Homebrew, он будет установлен в Homebrew-префикс:

/opt/homebrew

на Apple Silicon Mac, или:

/usr/local

на Intel Mac.

Оба варианта нормальны. Для команды важнее не физическая папка установки, а то, чтобы в Terminal.app стабильно работали команды:

python3 --version
python3 -m pip --version

6. Рекомендуемый способ установки

Для членов команды без уверенной работы с package managers самый понятный путь:

Спросить у Claude Code (Codex) актуальную официальную ссылку на Python 3.12.x для macOS.
Скачать официальный macOS installer с python.org.
Запустить installer.
Не угадывать непонятные настройки, если они появятся, а прислать скриншот в Claude Code (Codex).
После установки открыть новый Terminal.app.
Проверить:

python3 --version
python3 -m pip --version

Для людей, у которых уже установлен Homebrew, возможен вариант:

brew install [email protected]

Но команду установки все равно нужно предварительно спросить у Claude Code (Codex), потому что Homebrew, PATH и политика команды могут отличаться.

7. Проверка после установки

После установки нужно выполнить:

python3 --version

Ожидаемый результат для нашего стандарта:

Python 3.12.x

Проверить pip:

python3 -m pip --version

Проверить, где находится Python:

which python3

Проверить, что Python может выполнить простой скрипт:

python3 -c "print('Python is ready for Claude Code (Codex) automation')"

8. Виртуальные окружения

Для проектов важно не ставить все Python-библиотеки глобально без необходимости.

Внутри конкретного проекта лучше использовать виртуальное окружение:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

После активации .venv библиотеки ставятся внутрь проекта, а не в глобальный Python.

Claude Code (Codex) должен видеть и использовать такое окружение, если Python-скрипты относятся к конкретному проекту.

9. Что делать, если версия не совпадает

Если после установки команда:

python3 --version

показывает не Python 3.12.x, не нужно наугад удалять Python или менять системные файлы.

Нужно спросить Claude Code (Codex):

Claude, я установил Python на macOS, но python3 --version показывает не ту версию. Помоги понять, какой Python сейчас используется, где он установлен, и как безопасно настроить Python 3.12.x для Claude Code (Codex).

10. Правило

Девятый шаг настройки:

Python обязателен для Claude Code окружения, потому что большинство простых автоматизаций удобно делать Python-скриптами. Для базового стабильного окружения ставим Python 3.12.x, не трогаем системный Python macOS и не ставим Python вручную в корень диска.

Дополнительное правило:

Ссылку на скачивание, команду установки и любые непонятные настройки installer нужно спрашивать у Claude Code (Codex), а не искать в случайных источниках и не угадывать.

Шаг 10. Установить must-have Python-пакеты

После установки Python нужно подготовить базовый набор Python-пакетов, который используется в повседневной работе с Claude Code (Codex).

Это максимально важный шаг, потому что без необходимых для ваших задач пакетов к языкам программирования при вайбкодинге вы можете легко попасть на перерасход или в зацикливание из-за недостающего пакета, и ваш Claude Code может вам об этом не сказать. В результате вы потеряете много времени и расхода токенов.

Всегда перед крупной задачей или проектом сначала подумайте и спросите у Claude Code на каком языке программирования мы будем делать данную задачу, и какие необходимые пакеты языка программирования нам понадобятся.

Эти пакеты нужны не "на всякий случай", а под реальные сценарии AI-vibecoding:

работа с OpenAI API;
работа с изображениями;
работа с аудио;
подготовка и обработка голосовых транскрипций;
voice activity detection;
локальные ML/audio utilities.

1. Пакеты ставятся не глобально, а в virtual environment

Главное правило:

Python-пакеты для Claude Code проектов не ставятся глобально без необходимости. Их нужно ставить в .venv внутри конкретного проекта или внутри отдельного bootstrap-проекта окружения.

Причина простая: разные Python-пакеты и разные версии пакетов могут быть несовместимы друг с другом. Если ставить все глобально, рано или поздно одна автоматизация сломает другую.

Рабочий шаблон:

cd "$HOME/Documents/Claude Code (Codex)"
mkdir -p python-tooling
cd python-tooling
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

После активации окружения prompt терминала обычно показывает (.venv).

2. Совместимый pinned-набор пакетов

Для нашей практики фиксируем совместимый набор версий:

imageio-ffmpeg==0.6.0
openai==2.33.0
numpy==1.26.4
torch==2.5.1
librosa==0.10.2.post1
soundfile==0.12.1
webrtcvad==2.0.10
Resemblyzer==0.1.4
setuptools==80.9.0

Это важно: версии закреплены не из эстетики, а потому что в практической работе разные версии Python-пакетов часто конфликтуют друг с другом.

Строгое правило:

Не обновлять эти пакеты на более новые версии автоматически. Если хочется обновить пакет, сначала спросить Claude Code (Codex), проверить совместимость и прогнать тестовую установку в отдельном .venv.

3. Создать requirements-файл

Внутри проекта нужно создать файл:

requirements-codex-python-tooling.txt

Содержимое:

imageio-ffmpeg==0.6.0
openai==2.33.0
numpy==1.26.4
torch==2.5.1
librosa==0.10.2.post1
soundfile==0.12.1
webrtcvad==2.0.10
Resemblyzer==0.1.4
setuptools==80.9.0

Установка:

python -m pip install -r requirements-codex-python-tooling.txt

4. Что делают эти пакеты

openai==2.33.0 нужен для работы с OpenAI API.

numpy==1.26.4 нужен как базовая библиотека для числовых данных, массивов, аудио и ML-зависимостей.

torch==2.5.1 нужен для ML/audio-задач и зависимостей вроде Resemblyzer.

librosa==0.10.2.post1 нужен для анализа и обработки аудиофайлов.

soundfile==0.12.1 нужен для чтения и записи аудиофайлов.

imageio-ffmpeg==0.6.0 нужен для задач, где требуется ffmpeg-обработка через Python.

webrtcvad==2.0.10 нужен для voice activity detection: определить, где в аудио есть голос, а где тишина или шум.

Resemblyzer==0.1.4 нужен для speaker/audio embeddings и связанных задач с голосом.

setuptools==80.9.0 нужен как базовая build-зависимость для Python-пакетов.

5. Особенности macOS

На macOS часть пакетов может требовать системные developer tools.

Перед установкой этого набора должны быть выполнены предыдущие шаги:

установлена современная macOS;
установлены обновления системы;
пользователь работает из admin-аккаунта;
установлен Git;
установлены Xcode Command Line Tools;
установлен Python 3.12.x.

Проверка Xcode Command Line Tools:

xcode-select -p

Если tools не установлены:

xcode-select --install

6. `soundfile` и libsndfile

Пакет soundfile работает через системную библиотеку libsndfile.

Если soundfile установился, но импорт или чтение аудио падает с ошибкой про libsndfile, нужно установить системную библиотеку через Homebrew:

brew install libsndfile

После этого снова проверить:

python -c "import soundfile; print(soundfile.__version__)"

7. `webrtcvad` может собираться из исходников

webrtcvad==2.0.10 может потребовать компиляцию. Поэтому Xcode Command Line Tools должны быть установлены до попытки поставить пакет.

Если установка webrtcvad==2.0.10 ломается на конкретном Mac, не нужно хаотично менять версии всех пакетов.

Нужно спросить Claude Code (Codex):

Claude, на macOS не устанавливается webrtcvad==2.0.10 в Python 3.12 .venv. Вот полный текст ошибки. Помоги понять, не хватает ли compiler tools, wheel, pip/setuptools или нужен совместимый fallback.

Возможный fallback для отдельного проекта - пакет webrtcvad-wheels, у которого есть binary wheels для macOS. Но это не замена базового pinned-набора без отдельного решения команды.

8. `torch` на macOS

PyTorch поддерживает macOS, но установка зависит от версии Python, архитектуры Mac и доступных wheel-пакетов.

Для нашего baseline используем:

torch==2.5.1

Если torch==2.5.1 не устанавливается на конкретном Mac, не нужно сразу обновлять весь requirements-файл.

Нужно спросить Claude Code (Codex):

Claude, на macOS в Python 3.12 .venv не устанавливается torch==2.5.1. Вот ошибка. Проверь совместимость с моей архитектурой Mac и предложи безопасный вариант, не ломая остальной pinned-набор.

9. Проверка установки

После установки пакетов нужно проверить импорты:

python - <<'PY'
import imageio_ffmpeg
import openai
import numpy
import torch
import librosa
import soundfile
import webrtcvad
import resemblyzer
import setuptools

print("imageio-ffmpeg", imageio_ffmpeg.__version__)
print("openai", openai.__version__)
print("numpy", numpy.__version__)
print("torch", torch.__version__)
print("librosa", librosa.__version__)
print("soundfile", soundfile.__version__)
print("webrtcvad import ok")
print("Resemblyzer import ok")
print("setuptools", setuptools.__version__)
PY

Если все импорты прошли, Python tooling готов к работе.

10. Не ставить пакеты до Python

Пакеты нельзя ставить до того, как установлен и проверен правильный Python.

Правильный порядок:

Python 3.12.x установлен.
python3 --version показывает Python 3.12.x.
Создан .venv.
.venv активирован.
Обновлен pip.
Установлен pinned requirements-файл.
Выполнена проверка импортов.

11. Правило

Десятый шаг настройки:

Must-have Python-пакеты ставятся только в .venv, строго по pinned-версиям, через requirements-файл. Этот набор нужен для OpenAI API, изображений, аудио, транскрипций и простых автоматизаций Claude Code (Codex).

Дополнительное правило:

Если один пакет не устанавливается на macOS, не обновлять весь набор наугад. Нужно прислать Claude Code полный текст ошибки и попросить безопасный fix под конкретный Mac, Python 3.12.x и текущий pinned-набор.

Всегда используйте только строго официальные и безопасные пакеты для работы, пакеты непонятного источника использовать нельзя, это может привести к уязвимости в вашем коде.

Шаг 11. Установить JavaScript-окружение: Node.js и pnpm

После Python нужно подготовить JavaScript-окружение. Для Claude Code (Codex) это такой же must-have слой, потому что огромное количество современных проектов, frontend-инструментов, dev servers, CLI-утилит, build-систем и AI-интеграций работают через Node.js.

JavaScript-окружение нам нужно не потому, что JavaScript лучше или хуже Python, а потому что в реальной AI-vibecoding работе Claude Code (Codex) постоянно встречает:

web-приложения;
frontend-проекты;
React, Next.js, Vite и похожие фреймворки;
npm/pnpm/yarn-пакеты;
dev servers;
Playwright/browser automation;
OpenAI SDK для JavaScript/TypeScript;
обработку файлов, изображений, аудио и видео через Node tooling.

Так же именно на скриптовых языках программирования работают MiniApps.

1. Что нужно установить

Базовый JavaScript-набор:

Node.js
pnpm

Node.js - runtime, который запускает JavaScript вне браузера.

pnpm - package manager, который часто быстрее и аккуратнее работает с зависимостями, чем обычный npm. Если проект использует pnpm-lock.yaml, работать нужно именно через pnpm.

Важно:

На этом шаге мы ставим только Node.js и pnpm. Мы не ставим заранее все возможные JavaScript-пакеты для OpenAI, аудио, видео, картинок, frontend и тестов.

npm обычно устанавливается вместе с Node.js технически, но как командный стандарт для наших проектов мы предпочитаем pnpm, если конкретный проект не требует другого package manager.

У Node.js также есть встроенные core modules, например fs, path, http, crypto. Это часть самого Node.js, их нельзя и не нужно отдельно устанавливать или удалять. Под фразой "Node.js без всех пакетов" в нашей инструкции понимается:

ставим runtime Node.js, но не ставим глобально project-зависимости

2. Node.js не встроен в macOS

В отличие от zsh, Node.js не является стандартной частью macOS.

Его нужно установить отдельно.

Проверить, установлен ли Node.js:

node --version

Проверить npm:

npm --version

Проверить pnpm:

pnpm --version

Если node или pnpm не находятся, значит JavaScript-окружение еще не готово.

3. Какую версию Node.js ставить

Для Claude Code (Codex)-окружения нужно ставить стабильную LTS-версию Node.js, а не Current/latest.

На 18 июня 2026 года официальный Node.js LTS - это:

Node.js v24.17.0 LTS

При этом Node.js v26.x уже существует как Current, но для базового стабильного окружения его не ставим по умолчанию.

Правило:

Для команды ставим Node.js LTS. Current/latest ставим только если конкретный проект явно этого требует.

4. Не искать ссылку или команду установки самостоятельно

Актуальную ссылку на скачивание Node.js или команду установки нужно спрашивать у Claude Code (Codex).

Пример запроса:

Claude, мне нужно установить Node.js на macOS для AI-vibecoding. Подскажи актуальный официальный способ установки. Нужна LTS-версия, не Current.

Это важно, потому что на сайте Node.js может быть несколько вариантов:

LTS;
Current;
macOS installer;
Homebrew;
version manager;
Apple Silicon;
Intel Mac.

Не нужно выбирать наугад.

5. Рекомендуемый подход на macOS

Для команды есть два нормальных варианта.

Вариант 1: официальный installer с nodejs.org.

Этот путь проще для новичков. Человек скачивает LTS installer, устанавливает Node.js, потом проверяет:

node --version
npm --version

Вариант 2: version manager, например fnm или nvm.

Этот путь лучше для разработчиков, которые работают с несколькими проектами на разных версиях Node.js.

На macOS нужно учитывать архитектуру Mac:

Apple Silicon: arm64
Intel Mac: x64

Если человек скачивает installer вручную, он должен выбрать правильный вариант для своего Mac. Если он не уверен, нужно спросить Claude Code и прислать скриншот страницы скачивания или вывод:

uname -m

Ожидаемые варианты:

arm64
x86_64

Командный стандарт можно сформулировать так:

Новичкам: официальный Node.js LTS installer.
Разработчикам с несколькими проектами: version manager.
Главное правило: везде используем Node.js LTS, если проект не требует другого.

Если человек не понимает, какой вариант выбрать, он спрашивает Claude Code (Codex).

6. Установить pnpm

После установки Node.js нужно установить или включить pnpm.

Современный безопасный вариант часто делается через Corepack, который поставляется вместе с Node.js:

corepack enable
corepack prepare pnpm@latest --activate

После этого проверить:

pnpm --version

Если команда работает на корпоративном Mac и corepack enable просит права или падает из-за permissions, не нужно запускать случайные sudo-команды из интернета. Нужно прислать Claude Code (Codex) полный вывод ошибки.

Если Corepack недоступен или команда не работает, не нужно угадывать fix. Нужно спросить Claude Code:

Claude, я установил Node.js LTS на macOS, но не могу включить pnpm через Corepack. Вот вывод терминала. Помоги безопасно установить pnpm.

7. Не ставить project-пакеты глобально

Глобально должны быть доступны только базовые инструменты вроде node, npm, pnpm.

Project-зависимости нужно ставить внутри конкретного проекта:

cd "$HOME/Documents/Claude Code (Codex)/my-project"
pnpm install

или, если проект использует npm:

npm install

Нельзя наугад ставить глобально пакеты вроде:

npm install -g openai
npm install -g typescript
npm install -g vite

если проект этого явно не требует.

Для нашей команды это отдельное строгое правило:

Node.js ставится без глобального набора дополнительных JS-пакетов. Все пакеты для OpenAI, голоса, аудио, транскрибации, картинок, видео, frontend и тестов ставятся только внутри конкретного проекта после проверки package.json и lockfile.

8. Перед работой с проектом спрашивать про нужные JS-пакеты

Перед началом работы с конкретным JavaScript/TypeScript-проектом нужно спросить Claude Code (Codex), какие зависимости нужны именно для этого проекта.

Пример запроса:

Claude, я начинаю работу с этим проектом на macOS. Посмотри package.json, lockfile и структуру проекта. Скажи, какие Node.js-пакеты нужно установить и какой package manager использовать: npm, pnpm или yarn.

Для проектов с OpenAI, голосом, аудио, транскрибацией, изображениями и видео нужно задавать отдельный вопрос:

Claude, проект будет работать с OpenAI API, голосом, аудио, транскрибацией, изображениями и видео. Проверь, какие JavaScript/TypeScript-пакеты нужны, какие версии совместимы, и предложи установку без конфликта зависимостей.

Claude Code (Codex) должен смотреть:

package.json;
pnpm-lock.yaml;
package-lock.json;
yarn.lock;
README;
.nvmrc;
.node-version;
engines в package.json;
существующие scripts.

9. Как выбрать package manager в проекте

Не выбирать package manager наугад.

Правило:

Если есть pnpm-lock.yaml -> использовать pnpm.
Если есть package-lock.json -> использовать npm.
Если есть yarn.lock -> использовать yarn.
Если lockfile нет -> спросить Claude Code (Codex), что выбрать для проекта.

Для новых проектов можно использовать pnpm, если нет ограничений.

10. Частые пакеты для AI/медиа-проектов

Не нужно заранее ставить все эти пакеты в каждый проект, но команда должна понимать, какие категории обычно встречаются:

OpenAI API: openai;
схемы и валидация: zod;
изображения: sharp, jimp;
browser automation: playwright;
видео/аудио через ffmpeg: fluent-ffmpeg, ffmpeg-static;
чтение metadata аудио/видео: music-metadata;
WAV/audio utilities: wavefile, node-wav;
TypeScript tooling: typescript, tsx, ts-node;
тесты: vitest, jest, playwright/test.

Но еще раз:

Эти пакеты не ставятся автоматически. Их нужно подбирать под конкретный проект и конкретную задачу.

11. Проверка установки

После установки JavaScript-окружения выполнить:

node --version
npm --version
pnpm --version

Проверить выполнение простого JavaScript:

node -e "console.log('Node.js is ready for Claude Code (Codex) automation')"

Проверить папку проектов:

cd "$HOME/Documents/Claude Code (Codex)"
node --version
pnpm --version

12. Правило

Одиннадцатый шаг настройки:

На macOS нужно установить Node.js LTS, npm и pnpm. Node.js не встроен в macOS. Актуальную команду или ссылку установки спрашиваем у Claude Code (Codex), а не ищем случайно в интернете.

Дополнительное правило:

Перед работой с каждым JavaScript/TypeScript-проектом нужно спросить Claude Code (Codex), какой package manager использовать и какие exact-пакеты нужны для OpenAI, голоса, аудио, транскрибации, изображений, видео и других задач проекта.

Так JavaScript-окружение становится управляемым, а не набором случайно установленных глобальных пакетов.

Шаг 12. Разрешить Claude Code и developer tools работать с интернетом на macOS

На Windows Claude Code (Codex) может не ходить в интернет из-за Windows Defender Firewall или других правил безопасности. На macOS похожая проблема тоже возможна, но устроена иначе.

Главное отличие:

Встроенный macOS Firewall в основном управляет входящими соединениями к Mac. Проблемы с исходящим интернетом чаще связаны не с самим macOS Firewall, а с VPN, proxy, корпоративными MDM-политиками, DNS, антивирусами, network filters или сторонними firewall-приложениями.

Поэтому на macOS нужно проверять несколько слоев.

1. Что должно иметь доступ в интернет

Для нормальной работы Claude Code (Codex) окружения интернет нужен таким приложениям и инструментам:

Claude Code (Codex) Desktop app;
Claude Code (Codex) CLI;
Terminal.app;
браузер, через который выполняется login;
Git;
GitHub CLI (gh);
Homebrew;
Node.js/npm/pnpm;
Python/pip;
package managers и dev servers конкретных проектов.

Если один из этих инструментов не может выходить в интернет, работа Claude Code будет ломаться странными ошибками: packages не скачиваются, login не проходит, GitHub не открывается, потому что Claude Code (Codex) не может использовать сетевые функции.

2. Проверить базовый интернет из Terminal.app

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

curl -I https://www.apple.com
curl -I https://github.com
curl -I https://api.openai.com

Если эти команды не получают ответ, проблема не в Claude Code (Codex) как таковом. Нужно диагностировать сеть, DNS, proxy, VPN или корпоративные ограничения.

3. Проверить macOS Firewall

Открыть настройки:

Apple menu -> System Settings -> Network -> Firewall

Если Firewall выключен, встроенный macOS Firewall не должен блокировать Claude Code (Codex).

Если Firewall включен, открыть:

Firewall -> Options

И проверить, нет ли там явного запрета для Claude Code (Codex) app, Terminal.app, браузера или других developer tools.

Если приложение добавлено в список и рядом стоит block/deny, нужно изменить правило на allow.

Важно:

Не нужно выключать firewall полностью без причины. Сначала нужно разрешить конкретное приложение или сервис.

Строгое правило:

Как правильно настроить macOS Firewall для Claude Code, Terminal.app, dev server или другого developer tool, нужно спрашивать у Claude Code. Не нужно сочинять настройки самостоятельно и не нужно искать случайные инструкции в интернете.

Правильный запрос:

Claude, я настраиваю macOS Firewall для работы Claude Code и developer tools. Вот скриншот текущих настроек Firewall/Options и описание проблемы. Скажи, какие приложения разрешить и какие настройки выбрать.

4. Разрешить приложение через Firewall Options

Если Claude Code (Codex) Desktop app или другое нужное приложение блокируется:

Открыть System Settings.
Перейти в Network.
Открыть Firewall.
Нажать Options.
Добавить нужное приложение через +.
Выбрать Allow incoming connections.
Сохранить настройки.

Это особенно важно для приложений, которые поднимают локальный сервер, dev server или принимают локальные соединения.

5. Исходящий интернет: где обычно настоящая проблема

Если Claude Code, curl, git, gh, brew, npm, pnpm или pip не могут подключиться к интернету, а macOS Firewall не показывает явного запрета, нужно проверить:

включен ли VPN;
есть ли корпоративный proxy;
управляется ли Mac через MDM;
установлен ли сторонний firewall: Little Snitch, LuLu, Radio Silence, корпоративный endpoint security;
не блокируются ли домены openai.com, chatgpt.com, api.openai.com, github.com, npmjs.com, pypi.org;
не сломан ли DNS;
не требует ли сеть captive portal login, например в офисе, отеле или аэропорту.

На Mac именно эти слои чаще блокируют исходящие соединения приложений.

6. Не угадывать разрешения

Если macOS показывает popup с сетевым разрешением, firewall warning или security prompt, человек не должен нажимать наугад.

Правило:

Сделать скриншот popup и отправить его в Claude Code с вопросом, что нажать.

Пример запроса:

Claude, macOS показывает сетевое разрешение для Claude Code/Terminal/dev server. Вот скриншот. Скажи, что выбрать, чтобы Claude Code мог работать с интернетом и локальными dev-серверами, но без лишнего ослабления безопасности.

7. Проверить Claude Code CLI

После настройки сети проверить Claude Code CLI:

codex --version

Затем запустить:

codex

Если login или сетевой запрос не проходит, нужно скопировать ошибку или прислать скриншот в Claude Code (Codex).

8. Проверить package managers

Проверить, что основные package managers ходят в интернет:

git ls-remote https://github.com/openai/codex.git
gh auth status
brew update
python3 -m pip index versions openai
pnpm view openai version

Если какая-то команда падает, не нужно сразу переустанавливать весь инструмент. Нужно определить, какой именно сетевой слой блокирует доступ.

9. Командный стандарт

Для команды фиксируем:

macOS Firewall проверяем, но не считаем его единственной причиной сетевых проблем.
Claude Code app, Terminal.app и developer tools должны иметь разрешение на сеть.
Исходящие блокировки чаще ищем в VPN/proxy/MDM/стороннем firewall.
Непонятные security и firewall prompts отправляем скриншотом в Claude Code.

10. Правило

Двенадцатый шаг настройки:

На macOS нужно проверить, что Claude Code (Codex) Desktop app, Claude Code CLI, Terminal.app, Git, GitHub CLI, Homebrew, pip и pnpm могут обращаться в интернет. Встроенный macOS Firewall обычно управляет входящими соединениями, но его Options нужно проверить, если приложение явно заблокировано.

Дополнительное правило:

Если Claude Code или developer tools не ходят в интернет, не выключать безопасность вслепую. Нужно проверить Firewall, VPN, proxy, DNS, MDM и сторонние network filters, а все непонятные окна разрешений отправлять в Claude Code скриншотом.

Шаг 13. Настроить PATH на macOS

На Windows есть переменная Path, где прописываются папки с программами, которые должны запускаться из терминала. На macOS есть такая же идея, но называется она обычно:

PATH

PATH - это список папок, в которых shell ищет команды.

Если команда есть на компьютере, но ее папка не попала в PATH, Terminal.app и Claude Code (Codex) не смогут нормально ее запускать.

1. Почему PATH важен для Claude Code

Claude Code постоянно запускает команды:

git;
gh;
codex;
python3;
pip;
node;
npm;
pnpm;
brew;
curl.

Если какая-то команда не находится, Claude Code может начать зацикливаться, предлагать обходные пути, переустанавливать лишнее или неправильно диагностировать проблему. Это приводит к потере времени и огромному перерасходу токенов.

Поэтому после установки каждого инструмента нужно проверять не только факт установки, но и то, что команда доступна из Terminal.app.

2. Как посмотреть PATH

Показать текущий PATH:

echo "$PATH"

Более читаемый вариант:

echo "$PATH" | tr ':' '\n'

Каждая строка - это отдельная папка, где shell ищет исполняемые команды.

3. Как проверить конкретную команду

Проверить, находится ли команда:

command -v git
command -v gh
command -v codex
command -v python3
command -v node
command -v pnpm
command -v brew

Можно также использовать:

which git
which gh
which codex
which python3
which node
which pnpm
which brew

Если команда настроена правильно, macOS покажет путь к исполняемому файлу, например:

/usr/bin/git
/opt/homebrew/bin/brew
/opt/homebrew/bin/node

Если команда не найдена, будет ошибка вроде:

command not found

или пустой результат.

4. Типичные папки PATH на macOS

На macOS часто встречаются такие пути:

/usr/bin
/bin
/usr/sbin
/sbin
/usr/local/bin
/opt/homebrew/bin

Для Apple Silicon Mac Homebrew обычно находится здесь:

/opt/homebrew/bin

Для Intel Mac Homebrew часто находится здесь:

/usr/local/bin

Для Python installer с python.org могут появляться пути вида:

/Library/Frameworks/Python.framework/Versions/3.12/bin

Для Node.js, установленного через version manager, могут появляться пути внутри home folder пользователя.

5. Где PATH настраивается в zsh

На современных macOS стандартный shell - zsh.

Для zsh чаще всего используются файлы:

~/.zprofile
~/.zshrc

Но редактировать их вручную без понимания нельзя.

Важно:

Не нужно наугад вставлять строки в .zshrc, .zprofile, .bash_profile или другие shell-файлы.

Неправильная строка в PATH может сломать терминал, package managers или привести к тому, что будет запускаться не та версия Python/Node/Git.

6. Homebrew и PATH

После установки Homebrew на macOS он обычно сам показывает команду, которую нужно добавить в shell profile.

На Apple Silicon это часто похоже на:

eval "$(/opt/homebrew/bin/brew shellenv)"

Но эту строку нельзя просто копировать всем подряд без проверки.

Правильное действие:

сделать скриншот или скопировать вывод Homebrew installer -> отправить в Claude Code -> выполнить точную команду, которую Claude Code подтвердил для конкретного Mac

7. Что должно работать после настройки PATH

Минимальный чек-лист:

git --version
gh --version
codex --version
python3 --version
node --version
pnpm --version

Если установлен Homebrew:

brew --version

Если все команды запускаются из нового окна Terminal.app, PATH настроен достаточно хорошо для Claude Code.

8. После изменения PATH нужно открыть новый Terminal.app

После правки shell profile старое окно Terminal.app может не увидеть изменения.

Нужно:

Закрыть текущее окно Terminal.app.
Открыть новое окно Terminal.app.
Снова выполнить проверки:

echo "$PATH" | tr ':' '\n'
command -v codex
command -v gh
command -v python3
command -v node
command -v pnpm

9. Не искать PATH-инструкции самостоятельно

Строгое правило:

При настройке PATH на macOS нужно четко понимать, какую именно строку и в какой именно файл добавлять. Это нужно спрашивать у Claude Code, а не искать в интернете и не придумывать самостоятельно.

Правильный запрос:

Claude Code, я настраиваю PATH на macOS для Claude Code окружения. Вот вывод echo "$PATH", command -v brew, command -v codex, command -v gh, command -v python3, command -v node, command -v pnpm. Скажи, нужно ли что-то добавить в ~/.zprofile или ~/.zshrc, и дай точную команду.

Если какая-то команда не находится:

Claude Code, на macOS команда node/pnpm/gh/codex/python3 не находится в Terminal.app. Вот вывод echo "$PATH" и command -v. Помоги безопасно исправить PATH.

10. Не использовать sudo без причины

Для настройки PATH почти никогда не нужно использовать sudo.

Если инструкция из интернета предлагает:

sudo nano /etc/paths

или правку системных файлов PATH, это красный флаг.

Для обычного Claude Code окружения почти всегда достаточно пользовательских shell-файлов:

~/.zprofile
~/.zshrc

Системные файлы вроде /etc/paths менять нельзя без явной причины и без подтверждения Claude Code.

11. Правило

Тринадцатый шаг настройки:

На macOS нужно проверить, что все ключевые команды Claude Code окружения доступны из Terminal.app через PATH: git, gh, codex, python3, node, pnpm, brew.

Дополнительное строгое правило:

PATH на macOS не настраиваем наугад. Не ищем случайные команды в интернете, не правим .zshrc, .zprofile и системные файлы без понимания. Всегда спрашиваем Claude Code, показываем текущий PATH и выполняем точную инструкцию для конкретного Mac.

Шаг 14. Установить FFmpeg для работы с аудио и видео

В нашей работе Claude Code часто получает задачи, связанные с аудио:

подготовить голосовую транскрипцию;
разрезать аудиофайл;
конвертировать формат;
извлечь аудио из видео;
проверить длительность файла;
нормализовать или подготовить файл для дальнейшей обработки;
использовать Python- и JavaScript-инструменты, которым нужен ffmpeg.

Поэтому FFmpeg - обязательный системный инструмент для Claude Code (Codex) окружения.

1. Что такое FFmpeg

FFmpeg - это набор command-line инструментов для работы с аудио и видео.

Самые важные команды:

ffmpeg
ffprobe

ffmpeg выполняет конвертацию, нарезку, извлечение аудио и другие операции.

ffprobe показывает техническую информацию о медиафайле: длительность, кодеки, дорожки, bitrate, sample rate и другие параметры.

2. FFmpeg не встроен в macOS

FFmpeg обычно не является стандартной частью macOS.

Его нужно установить отдельно.

Проверить, установлен ли FFmpeg:

ffmpeg -version
ffprobe -version

Если команды не находятся, FFmpeg нужно установить.

3. Не искать ссылку или команду самостоятельно

На Windows FFmpeg часто ставится вручную: скачать архив по ссылке, разархивировать, положить в корневую папку диска C:\, потом прописать путь в Path.

На macOS основной подход другой. Чаще всего FFmpeg ставят через package manager, обычно Homebrew.

Строгое правило:

Ссылку на скачивание FFmpeg, команду установки и инструкцию по прописыванию пути нужно спрашивать у Claude Code. Не нужно искать случайные инструкции в интернете и не нужно придумывать путь самостоятельно.

Правильный запрос:

Claude, мне нужно установить FFmpeg на macOS для работы с аудио, видео и транскрибациями. Подскажи актуальный официальный/рекомендуемый способ установки для моего Mac и скажи, нужно ли настраивать PATH.

Если установка ручная:

Claude, я устанавливаю FFmpeg на macOS вручную. Скажи, куда правильно положить ffmpeg и ffprobe, и какую строку добавить в PATH для zsh. Вот мой текущий echo "$PATH" и uname -m.

4. Рекомендуемый способ на macOS

Если Homebrew уже установлен и работает, рекомендуемый способ:

brew install ffmpeg

После установки проверить:

ffmpeg -version
ffprobe -version

Если команды работают, отдельно прописывать путь обычно не нужно: Homebrew устанавливает бинарники в свой prefix, который уже должен быть в PATH.

На Apple Silicon Mac это обычно:

/opt/homebrew/bin

На Intel Mac это часто:

/usr/local/bin

5. Если Homebrew не установлен

Если Homebrew еще не установлен, не нужно сразу скачивать случайный архив FFmpeg.

Нужно спросить Claude Code (Codex):

Claude, на моем Mac еще нет Homebrew, но мне нужно установить FFmpeg для Claude Code окружения. Что правильнее: сначала установить Homebrew или использовать ручной binary? Дай безопасную инструкцию под macOS.

В большинстве случаев правильный путь для команды:

сначала Homebrew -> потом brew install ffmpeg

Ручная установка binary допустима только если есть причина не использовать Homebrew.

6. Ручная установка на macOS

Ручную установку FFmpeg на macOS не делаем по умолчанию.

Если она все-таки нужна, не нужно класть файлы в корень диска, как на Windows.

На macOS лучше использовать пользовательскую или стандартную Unix-локацию, например:

~/bin

или другую папку, которую Claude Code явно подтвердил для конкретного Mac.

После этого путь к папке должен попасть в PATH.

Но еще раз:

Куда именно положить ffmpeg и ffprobe, и какую именно строку добавить в ~/.zprofile или ~/.zshrc, нужно спрашивать у Claude Code с учетом текущего PATH.

7. Проверить PATH

После установки проверить, что Terminal.app видит команды:

command -v ffmpeg
command -v ffprobe

Ожидаемый результат при установке через Homebrew на Apple Silicon:

/opt/homebrew/bin/ffmpeg
/opt/homebrew/bin/ffprobe

Ожидаемый результат при установке через Homebrew на Intel Mac:

/usr/local/bin/ffmpeg
/usr/local/bin/ffprobe

Если command -v ничего не показывает, значит FFmpeg установлен не туда или папка не попала в PATH.

Тогда нужно спросить Claude Code:

Claude Code, FFmpeg установлен на macOS, но command -v ffmpeg ничего не показывает. Вот вывод echo "$PATH", brew --prefix и ls нужной папки. Помоги безопасно добавить FFmpeg в PATH.

8. Проверить работу на файле

После установки полезно проверить не только версию, но и саму работу ffprobe.

Пример:

ffprobe -hide_banner path/to/audio-or-video-file

Если файла пока нет, достаточно:

ffmpeg -version
ffprobe -version

9. Связь с Python и JavaScript

Некоторые Python- и JavaScript-пакеты могут использовать FFmpeg внутри:

imageio-ffmpeg;
audio/video processing scripts;
transcription pipelines;
video conversion utilities;
tools that extract audio from video.

Важно понимать:

Python-пакет imageio-ffmpeg не отменяет необходимость иметь системный ffmpeg, если проект или Claude Code скрипты ожидают command-line команды ffmpeg и ffprobe.

Поэтому проверка ffmpeg -version обязательна.

10. Не использовать sudo без причины

При установке через Homebrew обычно не нужно вручную использовать sudo.

Если случайная инструкция предлагает:

sudo cp ffmpeg /usr/bin
sudo nano /etc/paths

это красный флаг.

Нужно остановиться и спросить Claude Code.

11. Правило

Четырнадцатый шаг настройки:

Для работы с аудио, видео и транскрибациями на macOS нужно установить FFmpeg и проверить команды ffmpeg и ffprobe.

Рекомендуемый путь:

brew install ffmpeg

Дополнительное строгое правило:

Ссылку на скачивание FFmpeg, команду установки и инструкцию по PATH всегда спрашиваем у Claude Code. Не ищем случайные инструкции в интернете, не кладем файлы в системные папки и не прописываем пути наугад.

Шаг 15. Установить текстовый редактор для Markdown и YAML

Для Claude Code (Codex) окружения на macOS обязательно нужен хороший текстовый редактор.

Его задача - не заменить IDE и не стать главным инструментом программирования. Его задача проще и важнее:

быстро открыть Markdown-файл;
быстро открыть YAML-файл;
прочитать структуру документа;
поправить текст, заголовки, списки, конфиги;
увидеть syntax highlighting;
не ломать кодировку;
не превращать plain text в rich text;
не добавлять невидимое форматирование.

1. Почему TextEdit недостаточно

В macOS есть встроенный TextEdit, но для Claude Code (Codex) окружения его не считаем достаточным редактором.

Причина: TextEdit ориентирован не только на plain text, но и на rich text. Это повышает риск случайно сломать Markdown, YAML или конфигурационный файл.

Для нашей работы нужен именно plain-text editor.

2. Главные форматы

Редактор должен уверенно работать минимум с:

.md
.markdown
.yaml
.yml
.txt
.json
.toml
.env

Особенно важны:

Markdown
YAML

Markdown нужен для инструкций, документации, промптов, handoff-файлов, product docs и Claude Code (Codex) материалов.

YAML нужен для конфигов, CI/CD, GitHub Actions, docker-compose, automation-файлов и инфраструктурных описаний.

3. Best practice редакторы на macOS

Для macOS нормальные варианты:

CotEditor
Sublime Text
BBEdit
Visual Studio Code

CotEditor

Хороший бесплатный macOS-native plain-text editor.

Подходит как базовый вариант для команды, если нужен простой, быстрый и понятный редактор для Markdown/YAML.

Sublime Text

Очень быстрый профессиональный редактор.

Подходит как платный или условно-бесплатный вариант для тех, кто привык к Sublime вместо Notepad++.

BBEdit

Классический профессиональный macOS text editor.

Хорош для больших текстовых файлов, поиска, plain text, Markdown, HTML/XML и технических текстов.

4. Рекомендованный стандарт для команды

Минимальный стандарт:

CotEditor

Расширенный стандарт:

CotEditor + Visual Studio Code

Платная/профессиональная альтернатива:

Sublime Text или BBEdit

Главное:

На Mac должен быть хотя бы один нормальный plain-text editor, который быстро открывает Markdown и YAML.

5. Не искать ссылку самостоятельно

Строгое правило:

Ссылку на скачивание текстового редактора и способ установки нужно спрашивать у Claude Code (Codex). Не нужно искать случайные download-сайты в интернете.

Правильный запрос:

Claude, мне нужно установить на macOS текстовый редактор для Markdown и YAML в Claude Code окружении. Подскажи официальный источник скачивания для CotEditor/Sublime Text/BBEdit и лучший вариант для моей задачи.

Если человек уже выбрал редактор:

Claude, я хочу установить Sublime Text/CotEditor/BBEdit на macOS. Дай официальный источник скачивания и проверь, какой build выбрать для Apple Silicon или Intel Mac.

6. Установка

Возможные безопасные источники:

официальный сайт редактора;
Mac App Store;
официальный Homebrew cask, если команда уже использует Homebrew.

Нельзя скачивать редакторы с random download-сайтов, зеркал, "free cracked", "portable build" и похожих источников.

Если установка идет через Homebrew, команду тоже спрашиваем у Claude Code:

Claude, можно ли установить выбранный текстовый редактор через Homebrew cask на macOS? Дай безопасную команду и официальный источник.

7. Проверка после установки

После установки нужно проверить:

Редактор открывается.
Можно открыть .md.
Можно открыть .yaml и .yml.
Видна подсветка синтаксиса.
Файл сохраняется как plain text.
Редактор не добавляет rich-text форматирование.

Тестовые файлы:

test.md
test.yaml

Пример YAML:

name: codex-macos-setup
tools:
  - codex
  - git
  - homebrew

Пример Markdown:

# Claude Code macOS setup

- Markdown works
- YAML works

8. Настроить открытие файлов

После установки можно настроить default editor для .md, .yaml, .yml.

Но делать это необязательно для всех людей одинаково.

Если нужно сделать редактор приложением по умолчанию, спросить Claude Code:

Claude, я хочу сделать CotEditor/Sublime Text/BBEdit редактором по умолчанию для .md, .yaml и .yml на macOS. Дай пошаговую инструкцию через Finder.

9. Не ставить лишние extensions без проверки

Если используется VS Code или другой редактор с extensions/plugins, нельзя ставить случайные extensions.

Правило:

Extensions для Markdown, YAML, GitHub, OpenAI, formatting и preview ставим только после проверки с Claude Code (Codex).

Причина: extensions имеют доступ к файлам проекта и могут влиять на безопасность, форматирование и поведение редактора.

10. Правило

Пятнадцатый шаг настройки:

На macOS обязательно должен быть установлен plain-text editor для быстрой работы с Markdown и YAML. Минимальный рекомендуемый вариант - CotEditor. Профессиональные альтернативы - Sublime Text или BBEdit. VS Code можно использовать как более тяжелый code editor.

Дополнительное строгое правило:

Ссылку на скачивание, способ установки, выбор Apple Silicon/Intel build и настройку default editor спрашиваем у Claude Code. Не скачиваем редакторы с random download-сайтов и не ставим extensions без проверки.

Шаг 16. Установить Obsidian для продуктовых Markdown-документов

Если вы занимаетесь продуктовой работой, обычного текстового редактора может быстро стать недостаточно.

Markdown-файлов становится много. Появляются папки, подпапки, черновики, переводы, handoff-файлы, source of truth, call notes, продуктовые тезисы, ADR, vision documents и другие материалы.

В обычном текстовом редакторе можно быстро начать путаться:

где лежит нужный файл;
какая версия актуальная;
какие документы связаны между собой;
где находится продуктовая папка Data;
что относится к проекту, а что к старому черновику;
какие файлы уже готовы, а какие еще в работе.

Для этого нужен Obsidian.

1. Что такое Obsidian

Obsidian - это локальное приложение для работы с Markdown-файлами и базой знаний.

Важно:

Obsidian работает локально.
Obsidian работает поверх обычной папки с Markdown-файлами.
Obsidian не превращает ваши документы в закрытый веб-формат.
Obsidian не требует обязательной авторизации для базовой работы.
Obsidian бесплатен для использования.

Это не веб-сервис, не SaaS и не замена GitHub/Google Drive/Confluence.

Это локальная оболочка для удобной работы с вашей папкой Markdown-документов.

2. Первая супервозможность: видеть структуру продуктовых файлов

Obsidian можно подключить к вашей продуктовой папке, например:

~/Documents/Claude/Product/Data

или к другой папке, где лежит продуктовая база знаний.

После этого Obsidian показывает:

дерево файлов;
папки;
Markdown-документы;
связи между заметками;
быстрый поиск;
preview Markdown;
удобную навигацию.

Это особенно важно для продуктовой работы, где нужно не просто открыть один файл, а понимать всю структуру документов.

3. Вторая супервозможность: параллельное редактирование с AI

Obsidian очень удобен для совместной работы человека и AI.

Сценарий:

С одной стороны открыт Obsidian.
В нем человек руками редактирует Markdown-документ.
С другой стороны открыт Claude Code/Codex/AI-интерфейс.
Человек просит AI изменить этот же документ: заменить термин, переписать блок, структурировать раздел, вычистить повтор, перевести текст или привести файл к шаблону.
Изменение появляется в файле.
Obsidian сразу показывает обновленный документ.

Это ощущается почти как совместное редактирование документа человеком и AI.

Примеры задач:

Claude Code (Codex), замени в этом документе термин MetaSites на Metasites.
Claude Code (Codex), приведи этот Markdown к структуре Source of Truth.
Claude Code (Codex), вынеси все вопросы к Dima в отдельный раздел.
Claude Code (Codex), проверь, что YAML frontmatter не сломан.
Claude Code (Codex), сделай русский перевод рядом с английским, без потери структуры.

Для продуктовой работы это очень эффективно.

4. Третья супервозможность: плагины Obsidian

В Obsidian есть развитая система plugins.

Плагины могут помогать:

организовывать базу знаний;
работать с таблицами;
улучшать поиск;
строить dashboards;
связывать документы;
работать с templates;
улучшать навигацию;
управлять задачами.

Но плагины Obsidian не нужно ставить сразу пачкой.

Строгое правило:

На старте используем Obsidian как локальный Markdown workspace. Плагины ставим позже, только если понятно, какую задачу они решают.

Перед установкой plugin нужно спросить Claude Code (Codex):

Claude, я хочу поставить Obsidian plugin для моей продуктовой базы Markdown-файлов. Объясни, нужен ли он, безопасен ли он, и какую конкретную задачу он решает.

5. Четвертая возможность: граф знаний

В Obsidian есть graph view: визуальный граф связей между документами.

Граф знаний можно построить, и он выглядит интересно.

Но честная текущая позиция:

Мы пока не научились эффективно применять graph view в повседневной продуктовой работе.

Поэтому graph view можно изучать, но не нужно считать его обязательной частью базового workflow.

Сейчас для нас важнее:

структура папок;
быстрый поиск;
удобное редактирование Markdown;
параллельная работа с AI;
сохранение документов как обычных локальных .md файлов.

6. Установка Obsidian

Obsidian нужно скачивать только из официального источника.

Строгое правило:

Ссылку на скачивание Obsidian и способ установки нужно спрашивать у Claude Code (Codex). Не нужно искать случайные download-сайты.

Правильный запрос:

Claude, мне нужно установить Obsidian на macOS для работы с продуктовой Markdown-базой. Дай официальный источник скачивания, скажи, какой build выбрать для Mac, и объясни, как подключить локальную папку Data как vault.

Для macOS официальный installer обычно скачивается с сайта Obsidian, после чего приложение перетаскивается в Applications.

7. Как подключить папку продукта

В Obsidian рабочая папка называется:

vault

Для продуктовой работы vault должен указывать на уже существующую папку с Markdown-файлами.

Например:

~/Documents/Claude/Product/Data

или:

~/Documents/Claude/<project>/Data

Не нужно создавать случайный новый vault, если у вас уже есть рабочая папка с документами.

Нужно спросить Claude Code (Codex):

Claude, помоги выбрать правильную папку Obsidian vault для моей продуктовой работы. Вот структура ~/Documents/Claude. Я хочу редактировать продуктовые Markdown-файлы и не сломать связь с GitHub/Confluence.

8. Obsidian и Git

Obsidian редактирует обычные файлы на диске.

Если эта папка является Git repository, изменения Obsidian будут видны через:

git status
git diff

Это удобно, но требует дисциплины.

Правило:

Перед массовым AI-редактированием документов в Obsidian нужно проверить git status, чтобы понимать, какие изменения уже есть.

9. Obsidian не заменяет Confluence

Obsidian удобен только для локальной работы с Markdown.

Confluence нужен для публикации, совместного чтения, корпоративного доступа и согласованных страниц.

Правильная связка:

Obsidian = локальное редактирование и структура Markdown
Claude Code (Codex) = AI-редактирование и автоматизация
GitHub = версия и синхронизация
Confluence = публикация и корпоративное потребление

10. Правило

Шестнадцатый шаг настройки:

Если вы занимаетесь продуктовой работой, установите Obsidian как локальную оболочку для Markdown-документов и подключите его к правильной папке Data или другой продуктовой базе знаний.

Дополнительное строгое правило:

Obsidian скачиваем только из официального источника, который просим у Claude Code (Codex). Vault выбираем осознанно: он должен указывать на правильную локальную папку документов, а не создавать новую случайную структуру.

Шаг 17. Установить IDE или code editor, но не делать его главным AI-интерфейсом

После установки plain-text editor для Markdown и YAML можно установить полноценный редактор кода: VS Code, Cursor или аналог.

Важно аккуратно различать термины.

VS Code, Cursor, Windsurf и похожие приложения часто называют IDE, но технически многие из них ближе к:

code editor / AI code editor

Полноценная IDE обычно включает более тяжелый набор встроенных возможностей: project system, debugger, profiler, GUI builders, language-specific tooling и так далее. Но в бытовой речи разработчики часто называют VS Code и Cursor словом IDE. В этой инструкции можно использовать общий термин:

IDE / code editor

1. IDE нужна, но это не первый и не главный шаг

В старых привычках разработчика установка VS Code, Cursor или другой IDE часто считается первым и главным шагом настройки компьютера.

В Claude Code (Codex) окружении это уже не так.

IDE нужна для:

чтения и редактирования кода;
навигации по проекту;
подсветки синтаксиса;
работы с Git diff;
локального запуска scripts;
debugging;
TypeScript/Python/React/Node.js workflows;
точечной ручной правки файлов.

Но IDE не должна быть главным интерфейсом общения с AI.

2. Почему главный AI-интерфейс - Claude Code (Codex) GUI

Наша работа с Claude Code (Codex) построена не только на тексте.

Мы постоянно используем:

голосовые сообщения;
большие устные постановки задачи;
скриншоты ошибок;
скриншоты интерфейсов;
AI-опросники;
изображения и макеты;
файлы;
последовательный диалог;
проверку результатов;
объяснение контекста обычным человеческим языком.

Claude Code (Codex) GUI удобнее для такого режима, потому что он лучше подходит для разговора с агентом, передачи скриншотов, голосового контекста и файлов.

IDE/code editor хорош внутри кода, но хуже как основной разговорный интерфейс для AI-vibecoding.

3. Суровая новая реальность

Разработчики привыкли думать:

сначала ставим IDE -> потом начинаем работу

Для Claude Code (Codex)-работы правильнее:

сначала готовим macOS, Claude Code, терминал, Git, Homebrew, Python, Node.js, PATH и медиа-инструменты -> потом ставим IDE/code editor как дополнительный рабочий инструмент

IDE больше не является центром всей разработки.

Центр AI-vibecoding workflow - это Claude Code (Codex) и правильно подготовленное окружение.

4. Почему не стоит вести AI-работу только через IDE

Мы не запрещаем VS Code, Cursor и аналоги.

Но крайне не рекомендуем строить всю AI-работу только через IDE, потому что:

голосовой ввод в IDE обычно менее удобен, чем в специально организованном Claude Code (Codex) workflow;
работа со скриншотами и изображениями может быть менее быстрой;
не всегда удобно передавать большой контекст голосом;
не всегда удобно вести длинный продуктовый или архитектурный диалог;
IDE провоцирует сразу лезть в код, а не сначала правильно сформулировать задачу;
разработчик начинает спорить с агентом на уровне файлов, вместо того чтобы сначала дать полный контекст, критерии готовности и ограничения.

Да, современные редакторы развиваются. VS Code имеет Copilot Chat, extensions, voice/speech возможности и image inputs. Cursor позиционирует себя как agent-first editor. Но это не отменяет нашего командного правила прямо сейчас:

IDE/code editor - инструмент для работы с кодом. Claude Code (Codex) GUI - основной интерфейс постановки задач, голосового общения, скриншотов, файлов и агентной работы.

5. Какой IDE/code editor ставить на macOS

Нормальные варианты:

Visual Studio Code
Cursor
Windsurf
JetBrains IDEs

Для нашей команды базовый вариант:

Visual Studio Code

Если человек уже использует Cursor, можно поставить Cursor, но не превращать его в единственный AI-интерфейс команды.

JetBrains IDEs имеют смысл для конкретных стеков: Java, Kotlin, backend, mobile, heavy refactoring. Но они не обязательны для базового Claude Code (Codex)-окружения.

6. Не скачивать IDE из случайных источников

Строгое правило:

Ссылку на скачивание VS Code, Cursor или другой IDE/code editor нужно спрашивать у Claude Code (Codex). Не нужно искать установщик в интернете самостоятельно.

Правильный запрос:

Claude, мне нужно установить VS Code/Cursor на macOS для Claude Code окружения. Дай официальный источник скачивания, скажи, какой build выбрать для Apple Silicon или Intel Mac, и что проверить после установки.

Если установка через Homebrew:

Claude, можно ли установить VS Code/Cursor через Homebrew cask на macOS? Дай безопасную команду и официальный источник.

7. Что проверить после установки

После установки IDE/code editor нужно проверить:

Приложение открывается.
Можно открыть папку проекта из `~/Documents/Claude.
Видны файлы проекта.
Открываются .md, .yaml, .json, .ts, .js, .py.
Терминал внутри редактора видит команды:

git --version
python3 --version
node --version
pnpm --version
codex --version

Редактор не ломает line endings, encoding и YAML indentation.

Если встроенный terminal IDE не видит команды, а обычный Terminal.app видит, значит проблема в shell/PATH внутри IDE. Это нужно показать Claude Code (Codex).

8. Extensions и плагины

Не нужно сразу ставить много extensions.

Минимально полезные категории:

Markdown;
YAML;
Git/GitHub;
Python;
JavaScript/TypeScript;
formatter/linter только под конкретный проект.

Строгое правило:

Extensions ставим только после проверки с Claude Code и только под конкретную задачу. Не ставим случайные AI/extensions packs.

Причина: extensions имеют доступ к workspace, файлам, terminal, environment variables и иногда tokens и должны быть только официальных версий и безопасными. Установка неизвестного extension может привести к уязвимости на вашем desktop.

9. Как объяснять это разработчикам

Формулировка для команды:

Мы не забираем у вас VS Code или Cursor. Вы можете использовать их для чтения и редактирования кода.

Но основной AI-workflow команды идет через Claude Code (Codex) GUI, потому что там быстрее и естественнее ставить задачи голосом, прикладывать скриншоты, давать файлы, обсуждать архитектуру и проверять результат.

IDE остается инструментом ручной работы с кодом. Claude Code (Codex) GUI становится главным интерфейсом работы с AI-агентом.

Это не вопрос вкуса. Это вопрос скорости, качества контекста и снижения количества ошибок.

10. Правило

Семнадцатый шаг настройки:

На macOS можно и нужно установить IDE/code editor, обычно VS Code или Cursor. Но IDE не является главным AI-интерфейсом команды. Главный интерфейс AI-vibecoding - Claude Code (Codex) GUI.

Дополнительное строгое правило:

IDE скачиваем только из официального источника, который просим у Claude Code (Codex). Extensions ставим осторожно и только после проверки. Если IDE terminal не видит git, python3, node, pnpm или codex, не чиним наугад, а показываем Claude Code (Codex) вывод команд и текущий PATH.

Шаг 19. Зачем нужна вся эта настройка

После выполнения всех предыдущих пунктов у пользователя появляется качественно настроенное macOS-окружение для работы с Claude Code, Codex и другими AI-инструментами разработки.

Эта инструкция нужна не ради формальности и не ради любви к установке программ.

Она нужна, чтобы AI-vibecoding был быстрым, предсказуемым, безопасным и экономически разумным.

1. Не заставлять AI разрабатывать недостающие инструменты

Если на компьютере не установлен Git, Python, Node.js, pnpm, FFmpeg, GitHub CLI, Xcode Command Line Tools или другой базовый инструмент, AI-агент начинает тратить время не на задачу, а на исправление отсутствующего окружения.

Это приводит к плохим сценариям:

Claude Code (Codex) пытается заменить недостающий инструмент временным скриптом;
Claude Code начинает искать обходные пути;
агент предлагает лишние установки;
задача разрастается;
увеличивается расход токенов;
растет время выполнения;
итоговая стоимость работы становится в разы выше.

Важно что ваш Claude Code в процессе вайбкодинга может не сообщить вам об отсутствующем инструменте, и вы никогда не узнаете об этом. Но будете очень долго наблюдать за работой AI агента по решению бесконечных проблем.

Правильный вывод:

Базовые инструменты должны быть установлены заранее. AI не должен тратить рабочее время на изобретение того, что должно быть частью окружения.

2. Не заставлять AI сражаться с доступами и разрешениями

Плохо подготовленный Mac может ломать работу Claude Code (Codex) не из-за ошибки в коде, а из-за окружения:

нет прав администратора;
старая macOS;
не установлены обновления;
Terminal.app не видит команды;
сломан PATH;
firewall или VPN блокирует сеть;
GitHub CLI не авторизован;
Google API не включены;
FFmpeg не находится;
Python packages установлены глобально и конфликтуют;
Node.js-пакеты поставлены не тем package manager;
IDE terminal видит другой environment.

В таких условиях AI начинает бороться не с задачей, а с компьютером.

Это делает AI-vibecoding медленным, дорогим и неприятным. Часто приводит к разочарованию что AI глупый и работает плохо.

Важно что ваш Claude Code в процессе вайбкодинга может не сообщить вам об отсутствующем доступе или разрешении, и вы никогда не узнаете об этом. Но будете очень долго наблюдать за работой AI агента по решению бесконечных проблем с доступами.

Правильный вывод:

Окружение должно быть настроено так, чтобы Claude Code (Codex) мог сразу читать файлы, запускать команды, скачивать зависимости, работать с GitHub, аудио, видео, Python, Node.js и Google APIs.

3. Защититься от зацикливания

Одна из самых дорогих проблем AI-разработки - зацикливание.

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

команда не находится;
пакет не устанавливается;
PATH не обновился;
permissions не позволяют читать или писать файл;
network request блокируется;
API не включен;
credentials не работают;
compiler отсутствует;
FFmpeg не найден;
Python/Node версии конфликтуют.

Каждый такой цикл расходует:

время пользователя;
токены;
деньги;
внимание;
доверие к AI-инструменту.

Важно что ваш Claude Code в процессе вайбкодинга в случае если попал в зацикливание не сообщит вам о реальной проблеме, вы возможно только сможете догадаться об этом по контексту сообщений.

Правильный вывод:

Хорошая предварительная настройка окружения - это защита от зацикливания Claude Code или Codex.

4. Почему порядок важен

Порядок установки не случайный.

Нельзя начинать с IDE и надеяться, что все остальное само появится.

Правильная последовательность снижает количество ошибок:

macOS -> admin account -> Claude Code (Codex) -> Terminal/zsh -> screenshots -> Xcode Command Line Tools -> Git -> Homebrew -> GitHub CLI -> Python -> Python packages -> Node.js/pnpm -> network/firewall -> PATH -> FFmpeg -> text editor -> IDE -> plugins -> Google APIs

Если нарушить порядок, можно получить странные ошибки:

Git установлен, но compiler tools отсутствуют;
Homebrew установлен, но brew не в PATH;
GitHub CLI установлен, но нет GitHub account;
Python packages ставятся не в ту версию Python;
Node.js есть, но pnpm не работает;
FFmpeg установлен, но Claude Code (Codex) его не видит;
Google API credentials есть, но API не включены.

5. Экономический смысл

Эти правила экономят:

время;
деньги;
токены;
нервы;
рабочие часы команды.

Они также повышают качество результата:

Claude Code (Codex) меньше отвлекается;
меньше случайных установок;
меньше конфликтов версий;
меньше ошибок доступа;
меньше сетевых блокировок;
меньше ручной паники;
больше стабильной разработки.

6. Человеческий смысл

Цель этой инструкции - сделать работу с AI приятной, а не разочаровывающей.

Плохо настроенное окружение создает ощущение, что AI "тупит", "зациклился", "не умеет", "не может поставить пакет", "не понимает Mac" или "ломает проект".

Часто проблема не в AI.

Проблема в том, что компьютер не был подготовлен к AI-vibecoding.

Правильное окружение меняет ощущение работы:

меньше борьбы -> больше результата
меньше диагностики -> больше разработки
меньше раздражения -> больше удовольствия от AI

7. Финальное правило

Девятнадцатый шаг настройки:

Соблюдать всю инструкцию и порядок установки не ради бюрократии, а ради экономии времени, денег и внимания. Хорошее окружение не позволяет Claude Code и Codex уходить в разработку недостающих инструментов, сражаться с доступами и попадать в дорогие циклы ошибок.

Итог:

Правильно настроенный Mac делает AI-vibecoding быстрым, дешевле, спокойнее и намного приятнее.

Шаг 20. Настроить плагины Claude Code (Codex) и MCP-серверы

После того как macOS-окружение настроено, можно переходить к настройке самого Claude Code (Codex).

На этом этапе важно установить плагины, которые подключают Claude Code (Codex) к рабочим сервисам команды: почте, календарю, документам, задачам, репозиториям, дизайну и внутренним системам.

1. Что такое плагин в Claude Code (Codex)

В Claude Code (Codex) плагин - это installable bundle, который расширяет возможности агента.

Плагин может включать:

skills;
app integrations/connectors;
MCP servers;
команды;
hooks;
assets;
настройки и metadata.

Упрощенно можно думать так:

plugin = готовый пакет возможностей для Claude Code (Codex)

Часто внутри плагина действительно есть MCP server и набор skills для работы с ним. Но технически плагин может быть шире, чем просто "MCP server + skills".

2. Что такое MCP-сервер

MCP server - это прослойка между AI-интерфейсом и внешним backend/service.

Он позволяет Claude Code (Codex) работать с внешней системой через tools:

читать данные;
искать данные;
создавать задачи;
обновлять документы;
работать с файлами;
получать контекст;
запускать разрешенные операции.

Простая формула:

MCP server = мост между AI-чатом и backend другого продукта

Например, MCP-сервер может подключать Claude Code (Codex) к:

GitHub;
Gmail;
Google Drive;
Google Calendar;
Jira;
Confluence;
Figma;
внутреннему backend;
Xolo;
Metasites;
любому другому продукту, у которого есть MCP-интерфейс.

3. Плагины и MCP - не одно и то же

Важно различать:

Plugin
MCP server
Connector/App integration
Skill

Плагин - это упаковка возможностей.

MCP server - это один из способов дать Claude Code (Codex) tools для работы с внешним сервисом.

Skill - это инструкция или workflow, который учит Claude Code (Codex) правильно выполнять конкретный тип задач.

Connector/app integration - это авторизованное подключение к сервису вроде Google Drive, Gmail, Calendar, GitHub или Atlassian.

В повседневной речи можно говорить "плагин Gmail" или "плагин GitHub", но важно понимать, что внутри может быть набор разных компонентов.

4. Какие плагины нужны в первую очередь

Для нашей продуктовой, корпоративной и разработческой работы базовый набор:

Google services
Atlassian Rovo
GitHub
Figma

Google services

Нужны для работы с:

Gmail;
Google Calendar;
Google Drive;
Google Docs;
Google Sheets;
Google Slides.

Эти плагины/коннекторы позволяют Claude Code (Codex) помогать с почтой, календарем, документами, файлами, таблицами и презентациями.

Atlassian Rovo

Нужен для работы с:

Jira;
Confluence;
задачами;

Важно: корректное название плагина для Jira - Atlassian Rovo

GitHub

Нужен для координации разработки:

репозитории;
issues;
pull requests;
review comments;
CI;
GitHub Actions;
draft PR;
разработческие handoff-сценарии.

Figma

Нужен для работы с дизайном:

читать дизайн-контекст;
создавать или обновлять макеты;
работать с компонентами;
строить экраны;
готовить design-to-code workflow;
работать с FigJam/Slides, если это требуется.

Figma - не обязательный плагин для каждого человека, но для продуктовой и дизайн-связанной работы он очень эффективен.

5. Где устанавливать плагины

В Claude Code (Codex) app нужно открыть раздел:

Plugins

Дальше:

Найти нужный plugin.
Открыть его details.
Нажать install/add.
Если plugin требует подключение внешнего сервиса, пройти authorization.
После установки начать новый thread или перезапустить рабочую сессию, если Claude Code (Codex) этого требует.

В Claude Code (Codex) CLI плагины можно открыть через:

/plugins

7. Авторизация обязательна

После установки большинства рабочих плагинов нужно авторизоваться.

Это нормально: авторизация дает плагину доступ именно к вашим данным в конкретном сервисе.

Примеры:

Gmail plugin должен получить доступ к Gmail;
Google Calendar plugin должен получить доступ к календарю;
Google Drive plugin должен получить доступ к Drive/Docs/Sheets/Slides;
GitHub plugin должен получить доступ к GitHub;
Atlassian Rovo должен получить доступ к Jira/Confluence workspace;
Figma plugin должен получить доступ к Figma-файлам.

Без авторизации plugin может быть установлен, но не сможет работать с реальными данными.

8. Безопасность авторизации

Авторизовывать плагины нужно только:

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

Если окно авторизации показывает scopes/permissions, которые непонятны, нужно сделать скриншот и спросить Claude Code (Codex).

Правильный запрос:

Claude, я авторизую plugin для Gmail/Google Drive/GitHub/Atlassian/Figma. Вот скриншот permissions. Объясни, что именно я разрешаю и безопасно ли это для рабочей задачи.

9. Прямое подключение MCP-серверов

Не все внешние системы приходят как готовый marketplace plugin.

Иногда нужно подключить MCP server напрямую через настройки Claude Code или Codex.

Примеры:

MCP server Xsolla;
MCP server Metasites;
MCP server конкретного продукта;
кастомный backend;
локальный MCP server для разработки.

Правило:

Если MCP server не является официальным плагином из marketplace, его подключение нужно делать только по точной инструкции владельца сервера и после проверки с Claude Code (Codex).

10. Не подключать неизвестные плагины и MCP-серверы

Плагины и MCP-серверы могут получать доступ к рабочим данным.

Поэтому нельзя:

ставить random plugins;
подключать непонятные MCP endpoints;
выдавать permissions без понимания;
использовать личные аккаунты вместо рабочих;
подключать корпоративные сервисы с незащищенного компьютера;
сохранять tokens/secrets в открытых файлах.

11. Правильный запрос к Claude Code (Codex)

Перед установкой plugin:

Claude, мне нужно настроить плагины для рабочей Claude Code среды. Я использую Gmail, Google Calendar, Google Drive, Jira, Confluence, GitHub и Figma. Подскажи, какие официальные plugins установить, в каком порядке, и какие authorization steps ожидать.

Перед подключением MCP server:

Claude, мне нужно подключить MCP server к Claude Code. Вот документация или endpoint от владельца сервера. Проверь безопасность, объясни, какие tools он даст, и скажи, как правильно подключить его в настройках.

12. Правило

Двадцатый шаг настройки:

После настройки macOS-окружения нужно настроить плагины Claude Code (Codex): Google services, Atlassian Rovo, GitHub, Figma и другие рабочие интеграции, которые реально нужны человеку.

Дополнительное строгое правило:

Каждый plugin нужно авторизовать в правильном рабочем аккаунте и понимать, какие permissions он получает. MCP-серверы подключаем только из доверенных источников, по инструкции владельца и после проверки с Claude Code (Codex).

Шаг 21. Настроить AGENTS.md, skills и структуру папок проектов

После настройки плагинов, connectors и MCP-серверов нужно настроить поведение самого Claude Code/Codex внутри ваших проектов.

Три большие темы:

AGENTS.md
skills
правильная структура папок

Это уже не установка операционной системы. Это настройка того, как AI-агент будет понимать вашу работу, ваши правила, ваши проекты и ваши командные процессы.

1. AGENTS.md - общие правила для AI-агента

AGENTS.md - это файл инструкций для Claude Code (Codex).

Он задает устойчивые правила:

как работать с проектом;
какие команды запускать;
какие файлы не трогать;
какие проверки обязательны;
как оформлять результат;
как работать с Git;
как относиться к безопасности;
какие проектные договоренности соблюдать.

Упрощенно:

AGENTS.md = правила поведения Claude Code (Codex) в вашем workspace

2. Глобальный и проектный AGENTS.md

Есть разные уровни правил.

Глобальный файл:

~/.codex/AGENTS.md

Он задает личные правила пользователя для всех проектов.

Проектный файл:

<project-root>/AGENTS.md

Он задает правила конкретного проекта или репозитория.

Внутри подпапок могут быть более конкретные правила:

<project-root>/services/payments/AGENTS.md
<project-root>/apps/web/AGENTS.md

Claude Code (Codex) читает инструкции от общего уровня к более конкретному. Поэтому правила ближе к текущей папке проекта могут уточнять или переопределять более общие правила.

3. AGENTS.md требует отдельной настройки

AGENTS.md нельзя писать случайно.

Это не место для длинной философии и не место для противоречивых пожеланий.

Хороший AGENTS.md должен быть:

коротким;
конкретным;
проверяемым;
связанным с реальными командами проекта;
понятным для AI;
полезным для повторяющихся задач.

Пример тем для AGENTS.md:

Используй pnpm, если есть pnpm-lock.yaml.
Перед изменениями проверяй git status.
Не коммить secrets.
После изменения Python-скриптов запускай pytest, если тесты есть.
После изменения frontend запускай lint/build, если команды доступны.
Не добавляй новые production dependencies без подтверждения.

4. Skills - переиспользуемые рабочие процессы

Skills - это reusable workflows для Claude Code (Codex).

Skill может содержать:

SKILL.md;
инструкции;
reference-файлы;
scripts;
templates;
assets.

Упрощенно:

skill = повторяемый рабочий навык, который Claude Code (Codex) может вызвать

Например:

загрузка Markdown-файлов в Confluence;
работа с service desk;
triage задач;
генерация status report;
публикация Product-документов;
обработка transcript;
подготовка Jira tickets;
работа с внутренними пайплайнами.

5. Почему skills экономят время

Если вы каждый день делаете похожую операцию, ее нужно превращать в skill.

Пример:

загрузить файл в Confluence

Без skill Claude Code (Codex) каждый раз должен заново понимать:

где лежит файл;
какой script использовать;
какие credentials нужны;
как делать dry-run;
как проверять результат;
какие ошибки типичны;
как не сломать публикацию.

Со skill это превращается в устойчивый workflow.

Итог:

Skills экономят время, снижают ошибки и делают Claude Code (Codex) похожим не на случайного помощника, а на обученного участника команды.

6. Где лежат skills

Для проектных skills:

<project-root>/.agents/skills

Для личных skills пользователя:

~/.agents/skills

Для командных или системных skills могут использоваться другие управляемые локации.

Важно:

Skills нужно устанавливать и хранить осознанно. Не нужно копировать случайные skills без понимания, что они делают.

7. Скиллы компании и Neuronet

Если в компании уже есть готовые skills, их нужно использовать.

Особенно полезны:

skills для загрузки файлов в Confluence;
skills для service desks;
skills для Jira;
skills для Confluence;
skills для внутренних workflow;
skills для повторяющихся product/documentation задач;
skills для Neuronet-сценариев.

Это не украшение. Это огромная экономия времени.

Правило:

Если в компании есть готовый skill для задачи, сначала используем skill, а не просим Claude Code (Codex) каждый раз изобретать процесс заново.

8. Правильная структура папок

Кроме AGENTS.md и skills нужно правильно настроить папки.

Самая важная связка:

локальная папка проекта
папка/workspace в Claude Code или Codex
GitHub repository

Эти три слоя должны указывать на один и тот же проект.

Если они расходятся, начинаются проблемы:

Claude Code (Codex) работает не в той папке;
GitHub repo не соответствует локальным файлам;
AI меняет не тот проект;
инструкции AGENTS.md не загружаются;
skills лежат не там;
Git status показывает не те изменения;
pull request уходит не из той ветки;
команда не понимает, где актуальная версия.

9. Рекомендуемая структура

Базовая папка проектов на Mac:

~/Documents/Claude

Внутри нее:

~/Documents/Claude/AI
~/Documents/Claude/Product
~/Documents/Claude/project-a
~/Documents/Claude/project-b
~/Documents/Claude/product-docs

Для первого командного onboarding особенно полезны две стартовые папки:

~/Documents/Claude/AI
~/Documents/Claude/Product

AI - для настройки Claude Code, AI-инструкций, handoff-документов, обучения и рабочих материалов по AI-процессам.

Product - для продуктовой базы, Markdown-документов, PRD, спецификаций, транскриптов и файлов, которые могут синхронизироваться с GitHub и Confluence.

Каждая папка проекта должна соответствовать своему GitHub repository или явно быть non-code workspace.

Пример:

~/Documents/Claude/my-app
  .git/
  AGENTS.md
  .agents/skills/
  package.json
  README.md

Claude Code/Codex нужно открывать именно в папке проекта, а не в случайной родительской папке.

10. Онбординг нового участника: папки, Claude Code (Codex) и GitHub

Для нового участника команды порядок должен быть таким:

Открыть Documents.
Создать папку Claude Code (Codex).
Внутри создать стартовые папки AI и Product или другие папки, которые команда заранее согласовала.
В Claude Code/Codex создавать проект не "с нуля", а через вариант Use Existing Folder, Open Existing Folder или аналогичную кнопку выбора уже существующей папки.
Выбрать конкретную папку проекта, например ~/Documents/Claude Code (Codex)/Product, а не весь Documents.
Не писать в новую командную папку случайные файлы до первичного заполнения из GitHub repository, утвержденного шаблона или уже существующего источника правды.
Получить доступ к корпоративному GitHub-аккаунту и нужному repository. Для командной работы обычно нужен именно корпоративный аккаунт, а не личный GitHub.
Попросить владельца repository добавить пользователя как collaborator или выдать доступ через организацию.
Подключить локальную папку к GitHub repository через Git remote или корректный clone.
Авторизовать GitHub CLI и GitHub plugin в Claude Code (Codex), если они используются в работе.
Проверить, что локальная папка, Claude Code (Codex) workspace и GitHub repository указывают на один и тот же проект.

Главная идея:

Сначала создаем правильную папку, потом открываем именно ее в Claude Code, потом связываем ее с GitHub. Не создаем параллельные копии проекта в разных местах.

Если локальная папка уже создана, в Claude Code нужно выбирать именно существующую папку. Если начать создавать новые проекты без привязки к реальной папке, очень быстро появится хаос: Claude Code будет работать в одной директории, GitHub будет связан с другой, а человек будет искать файлы в третьей.

11. Дисциплина чатов и agents внутри проекта

В Claude Code и Codex чат внутри проекта - это не просто случайная переписка. На практике каждый чат начинает вести себя как рабочий агент с определенной функцией.

Поэтому для серьезной работы нельзя смешивать все темы в один чат.

Хорошие примеры отдельных чатов:

Claude Code setup
GitHub Updates
Product docs
Confluence upload
Lessons
Bug triage

Плохая практика:

Один чат одновременно для настройки Claude Code, GitHub sync, продуктовых решений, багов, транскриптов и личных заметок.

В обычном ChatGPT смешанный чат еще может быть терпимым. В Claude Code/Codex это быстро становится вредным, потому что AI-агент начинает связывать между собой несвязанные контексты, задачи, папки и правила.

Правило:

Каждый рабочий чат должен иметь понятную функцию. Если появилась новая большая тема, лучше создать отдельный чат внутри того же проекта, чем ломать контекст текущего.

Отдельный пример важного чата:

GitHub Updates

Такой чат можно использовать только для задач синхронизации локальной папки с GitHub: проверить изменения, сделать commit, подготовить pull request, подтянуть обновления, проверить статус repository. Это защищает команду от ситуации, когда GitHub-операции размазываются по случайным разговорам.

12. Проверка связки папок

Перед серьезной работой нужно проверить:

pwd
git status
git remote -v
ls

Понять:

где я нахожусь;
это правильный проект или нет;
есть ли Git repo;
какой GitHub remote подключен;
виден ли AGENTS.md;
есть ли .agents/skills;
нет ли незакоммиченных изменений, которые нельзя потерять.

Если есть сомнения, нужно спросить Claude Code (Codex):

Claude, проверь, что моя локальная папка проекта, workspace Claude Code и GitHub repository связаны правильно. Вот вывод pwd, git status и git remote -v.

13. Не смешивать рабочие папки

Нельзя вести один и тот же проект одновременно в нескольких несогласованных папках:

~/Downloads/project
~/Desktop/project
~/Documents/Claude/project

Это почти гарантирует путаницу.

Правило:

Для каждого проекта должна быть одна основная локальная папка, один понятный Claude Code (Codex)/Claude Code workspace и один GitHub repository.

14. Что настраивать через Claude Code

Эти темы нельзя настраивать наугад.

Нужно спрашивать Claude Code (Codex):

Claude, помоги мне настроить AGENTS.md для этого проекта. Сначала прочитай README, package.json/pyproject, структуру папок и существующие команды. Потом предложи короткий AGENTS.md.

Claude, какие skills компании мне нужно установить для работы с Confluence, Jira, service desk и Product docs?

Claude, проверь структуру папок проекта и связь с GitHub. Скажи, где должен лежать AGENTS.md и где должны лежать project skills.

15. Правило

Двадцать второй шаг настройки:

После установки plugins и MCP нужно настроить AGENTS.md, skills, структуру папок и дисциплину рабочих чатов. Это задает правила поведения AI-агента, подключает переиспользуемые workflow и защищает от путаницы между локальной папкой, Claude Code/Codex workspace и GitHub repository.

Дополнительное строгое правило:

AGENTS.md, skills, папочную структуру и GitHub-связку не настраиваем наугад. Сначала просим Claude Code прочитать проект, проверить GitHub-связку и предложить минимальные, точные правила под конкретную работу.

Шаг 1. Актуальная macOS и учетная запись macOS с правами администратора

1. Использовать современную macOS

2. Установить все доступные обновления macOS

3. Работать из основной учетной записи администратора

Правило

Шаг 2. Установить Claude Code и создать рабочую папку проектов

1. Где хранить проекты Claude Code на macOS

2. Установить Claude Code CLI

3. Установить Claude Code desktop app

4. Как должна выглядеть базовая структура на Mac

5. Правило

Шаг 03. Терминал и командная строка на macOS

1. Что является аналогом PowerShell 7 на macOS

2. Достаточно ли встроенного Terminal.app

4. Когда стоит поставить iTerm2

6. Что должен уметь каждый участник команды

7. Правило

Шаг 04. Скриншоты на macOS для работы с Claude Code

1. Нужен ли отдельный скриншотер

2. Главное требование

3. Базовые горячие клавиши macOS

4. Best practice для команды

5. Правило

Шаг 05. Xcode Command Line Tools на macOS

1. Xcode Command Line Tools на macOS

2. Входит ли это в macOS по умолчанию

3. Как проверить установку

4. Как установить Xcode Command Line Tools

5. Полный Xcode обычно не нужен

6. Связь с Node.js и pnpm

7. Не искать инструкции самостоятельно

8. Не чинить developer tools наугад

9. Правило

Шаг 06. Установить и настроить Git

1. Есть ли Git в macOS по умолчанию

2. Не искать ссылку на Git самостоятельно

3. Не угадывать галочки в установщике

4. Рекомендуемый путь установки Git на macOS

5. Базовая настройка Git

6. Git должен работать из папки проектов Claude Code

7. Что еще важно для Claude Code (Codex)

8. Правило

Шаг 07. Установить Homebrew

1. Homebrew не входит в macOS

2. Почему Homebrew ставим после Git

3. Не искать команду установки самостоятельно

4. Установка

5. PATH после установки Homebrew

6. Проверка установки

7. Что можно ставить через Homebrew

8. Не использовать случайный sudo

9. Правило

Шаг 08. Установить GitHub CLI

1. Сначала нужна учетная запись GitHub

2. Не искать команду установки самостоятельно

3. Проверить установку

4. Авторизоваться в GitHub

5. Проверить авторизацию

6. Проверить работу в папке проектов Claude Code

7. Особенности macOS

8. Правило

Шаг 09. Установить Python на macOS

1. Python обязателен

2. Не искать ссылку самостоятельно

3. Какую версию Python ставить

4. Встроенный Python в macOS

5. Куда ставить Python на macOS

6. Рекомендуемый способ установки

7. Проверка после установки

8. Виртуальные окружения

9. Что делать, если версия не совпадает

10. Правило

Шаг 10. Установить must-have Python-пакеты

1. Пакеты ставятся не глобально, а в virtual environment

2. Совместимый pinned-набор пакетов

3. Создать requirements-файл

4. Что делают эти пакеты

5. Особенности macOS

6. soundfile и libsndfile

7. webrtcvad может собираться из исходников

6. `soundfile` и libsndfile

7. `webrtcvad` может собираться из исходников

8. `torch` на macOS