AI 入门 2：为 Claude Code 中的 AI-vibecoding 配置 macOS 环境

本课程介绍为使用 Claude Code（Codex）、GitHub、Python、JavaScript、音频、Google 服务、插件、MCP、AGENTS.md、skills 和文件夹命令结构而正确准备 macOS 的顺序。

步骤 1. 最新的 macOS 以及具有管理员权限的 macOS 账户

在为 Claude Code（Codex）配置 AI-vibecoding 环境之前，需要确保计算机本身已在操作系统层面为这项工作做好准备。

1. 使用现代 macOS

只能在受支持更新的最新、现代版本 macOS 26 Tahoe 上使用 Claude Code（Codex）。不能在 3-5 年前的旧版操作系统上工作。

旧版 macOS 几乎必然会导致问题：

访问错误；
权限错误；
与现代开发工具不兼容；
安装软件包和依赖项时出现问题；
终端、浏览器、IDE、Claude Code（Codex）和相关工具运行不稳定。

对于 AI-vibecoding，系统必须支持现代版本的 developer tools、shell 工具、浏览器、Node.js、Python、Docker/OrbStack、GitHub CLI 以及其他环境组件。

2. 安装所有可用的 macOS 更新

仅仅拥有新版 macOS 还不够。在您的 Desktop 或 Laptop 上开始配置 AI 环境之前，需要安装截至当天可用的所有系统更新。

通过以下位置检查：

System Settings -> General -> Software Update

如果 macOS 提供更新，必须在配置 Claude Code（Codex）环境之前完成安装。

这可以降低与以下事项有关的偶发错误风险：

过时的系统库；
不完整的 security updates；
Xcode Command Line Tools 不兼容；
权限问题；
终端、shell 脚本和 package managers 运行不稳定。

3. 使用主管理员账户工作

应从具有管理员权限的主 macOS 账户中配置和使用 AI-vibecoding 环境。

不要从受限账户、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. 在 macOS 上将 Claude Code 项目存放在哪里

在 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 基础设施，您需要 Claude 的 desktop 版本，它包含 Claude Code 和 Claude Co-work。仅通过浏览器版本使用 Claude 会显著限制您的能力。

Claude Code（Codex）app 用于：

使用本地安装的文件夹和文件
使用本地安装的编程语言
完整使用插件、连接 Google、Atlassian、Github 服务
编码和 vibe coding
在编码中使用语音界面以及图片/截图界面
处理多个项目；
运行诸如 dev server、tests、build 等 actions；
比只使用终端更方便地进行日常 AI-vibecoding。

在搭载 Apple Silicon 的 Mac 上安装 Codex Desktop app 时，需要选择 Apple Silicon 版本。在使用 Intel Core 处理器的 Mac 上，则选择 Intel 版本。

4. Mac 上的基础结构应该是什么样子

第一步中本地文件夹的最小结构：

~/Documents/Claude/
  AI/
  Product/

用户在 Documents 内 Claude 主文件夹中创建自己的项目文件夹：

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

然后通过 Project -> Use an existing folder 将这些项目添加到 Claude Code desktop app。

重要提示：如果该文件夹是为团队已经在进行的项目创建的，不要立刻向其中写入随机文件。必须找到与该项目对应的 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 上使用哪一种命令行。

命令行应用程序，即终端，是在编码和 vibe coding 时运行和执行面向操作系统及文件的低级命令所必需的。

在 Windows 中，我们经常说“安装 PowerShell 7”。在 macOS 上情况不同：基础命令行已经内置于系统中。

1. macOS 上什么相当于 PowerShell 7

macOS 上有两种经常被混淆的不同事物：

终端应用程序，即输入命令的窗口；
shell，即理解并执行这些命令的程序。

内置终端应用程序名为：

Terminal.app

现代 macOS 中内置的标准 shell：

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 本身，并且与 AI-vibecoding 中使用的大多数 developer tools 兼容性更好。

步骤 04. 用于 Claude Code 工作的 macOS 截图

对于使用 Claude Code（Codex）的 AI-vibecoding，截图是传递上下文的主要方式之一。团队必须能够快速截取所需窗口或屏幕区域，并立即将图像粘贴到 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。随后可通过 Cmd+V 将其粘贴到 Claude Code（Codex）中。

将特定窗口截图到剪贴板：

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，并且必须能将区域或特定窗口直接截图到剪贴板，以便通过 Cmd+V 将其粘贴到 Claude Code（Codex）中。

这至关重要，因为高效使用 Claude Code（Codex）不仅依靠文本，也依靠对错误、界面、终端、浏览器和应用程序结果的快速截图。

步骤 05. macOS 上的 Xcode Command Line Tools

在 Windows 上，对于 JavaScript/Node.js 项目，有时需要安装 Microsoft Visual Studio Build Tools 2022，以构建 native dependencies：这些软件包会在 npm install 或 pnpm install 期间通过 node-gyp 编译 C/C++ 代码。

在 macOS 上则安装 Xcode Command Line Tools。

必须在安装 Git、GitHub CLI、Homebrew、Python 软件包、Node.js 软件包和 FFmpeg 之前完成此步骤，因为 Xcode Command Line Tools 为 macOS 提供基础 developer toolchain。

1. macOS 上的 Xcode Command Line Tools

macOS 上的 Build tools 是 Apple 工具：

Xcode Command Line Tools

它们也称为：

Command Line Tools for Xcode

它们为系统提供用于构建 native packages 的 compiler toolchain：

clang；
make；
headers；
SDK；
developer command-line utilities。

2. 它默认包含在 macOS 中吗

Xcode Command Line Tools 是适用于 macOS 的 Apple 工具，但它们并不总是已安装在全新的 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 是使用 Claude Code（Codex）进行 AI-vibecoding 的必备工具。没有 Git，就难以甚至无法安全地修改代码、检查 diff、回滚错误、进行提交、创建 pull request，以及了解代理究竟修改了什么。

在此步骤之前，必须已安装或检查 Xcode Command Line Tools。在 macOS 上，正是它们提供基础 developer 工具，Git 通常通过这些工具安装或激活。

1. macOS 默认有 Git 吗

安装 Xcode Command Line Tools 后，macOS 上通常已经可以使用 Git。

可在 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 下载链接，或不明白应选择哪种安装方式，不要在随机文章和视频中自行搜索。

规则：

应向 Claude Code（Codex）询问最新 Git 链接或安装方式。

请求示例：

Claude，我需要在 macOS 上安装 Git。请告诉我适合我情况的最新官方安装方式，并在需要时提供链接。

在 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 被配置为可在 macOS 上与 Claude Code 进行 AI-vibecoding。

接下来将安装中每个不清楚步骤的截图发送到 Claude Code，它会解释应选择什么以及原因。

这很重要，因为错误的 Git 设置可能导致问题：

在终端中找不到 Git；
提交使用错误的姓名或 email 创建；
SSH keys 不工作；
GitHub 一次又一次要求输入密码；
文件中的换行符被更改；
Claude Code 在 diff 中看到多余更改；
pull/push 工作不稳定。

4. macOS 上推荐的 Git 安装路径

团队的基础路径如下：

打开 Terminal.app。
检查 Git：

git --version

如果未安装 Git，安装 Xcode Command Line Tools：

xcode-select --install

安装后再次检查：

git --version

稍后，在安装 Homebrew 后，必要时可通过 Homebrew 安装更新的 Git：

brew install git

但在第一阶段无需复杂化。如果通过 Xcode Command Line Tools 的 Git 可以工作，开始时就足够了。

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]

最好使用与 GitHub 账户关联的 Email。如果使用私密 GitHub noreply email，需要从 GitHub 设置中获取它并在此处粘贴。

6. Git 必须能从 Claude Code 项目文件夹运行

配置后，需要在工作文件夹中检查 Git：

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

如果命令显示 Git 版本，说明 Claude Code CLI 也能够在项目内使用 Git。

对于具体项目，建议检查：

git status

如果文件夹已经是 Git repository，命令会显示工作副本的状态。如果不是，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 是 macOS 的 package manager。它用于方便地安装和更新 developer tools、command-line utilities、libraries 和一些 desktop 应用程序。

对于 Claude Code（Codex）环境，Homebrew 尤其有用，因为可方便地通过它安装：

GitHub CLI (gh)；
FFmpeg；
用于 Python audio packages 的 libsndfile；
如果团队选择 Homebrew 路径，则可安装 Node.js；
如果团队选择 Homebrew 路径，则可安装 Python versions；
额外的 command-line tools。

1. Homebrew 不包含在 macOS 中

Homebrew 不是 macOS 的标准组件。

需要单独安装它。

检查是否已安装 Homebrew：

brew --version

如果找不到该命令，说明 Homebrew 尚未安装或未添加到 PATH。

2. 为什么在 Git 之后安装 Homebrew

Homebrew 大量使用 macOS 的 developer 基础设施和 GitHub。

因此正确的顺序为：

Xcode Command Line Tools -> Git -> Homebrew

Xcode Command Line Tools 提供 compiler/developer toolchain。

Git 用于处理 repositories，也可能被 Homebrew 使用。

Homebrew 则安装在该基础层之上。

3. 不要自行搜索安装命令

严格规则：

应向 Claude Code（Codex）询问 Homebrew 链接和 Homebrew 安装命令。不要在互联网中搜索随机说明，也不要复制文章、视频或论坛中的命令。

正确的请求：

Claude，我需要在 macOS 上为 Claude Code 环境安装 Homebrew。请告诉我最新的官方安装命令，检查步骤顺序，并说明安装后如何处理 PATH。

截至编写本说明时，Homebrew 官方 install script 如下：

/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，我正在 macOS 上安装 Homebrew。这是 installer 的截图/输出。请告诉我该选择什么，是否可以继续。

5. 安装 Homebrew 后的 PATH

安装后，Homebrew 几乎总会输出 Next steps 区块。

其中可能包含需要添加到 shell config 的命令，以便在 Terminal.app 中可以找到 brew。

对于 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 正确添加到我的 Mac 的 PATH 中。

6. 检查安装

安装后，打开一个新的 Terminal.app 窗口并执行：

brew --version
brew doctor

brew --version 应显示 Homebrew 版本。

brew doctor 可能显示警告。并非所有警告都很关键，但需要阅读它们。

如果 brew doctor 显示不清楚的 warning 或 error，不要盲目修复：

Claude，这是 macOS 上 brew doctor 的输出。请说明哪些警告对于 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。

附加严格规则：

从 Claude Code（Codex）获取 Homebrew 的链接、安装命令和 PATH 配置。不要在互联网中搜索随机说明，不要盲目修改 shell config，也不要在不了解的情况下运行 sudo 命令。

步骤 08. 安装 GitHub CLI

在安装 Git 和 Homebrew 后，需要安装 GitHub CLI。它是 GitHub 的命令行界面，可让您从 Terminal.app 使用 GitHub：进行授权、检查 repositories、创建 pull request、查看 issues、读取 CI 状态并执行其他操作，而无需切换到浏览器。

GitHub CLI 使用以下命令启动：

gh

1. 首先需要 GitHub 账户

只有在人员已经拥有企业 GitHub 账户后，才应安装和配置 GitHub CLI。

原因：

安装 gh 后将需要在 GitHub 中授权；
授权需要已有的 GitHub 账户；
未授权时，GitHub CLI 虽已安装，但对于实际工作几乎没有用；
如果用户未登录 GitHub，Claude Code（Codex）将无法通过本地 gh 协助处理 pull request、issues 和 GitHub workflows。

规则：

先创建或准备 GitHub 账户，然后安装并授权 GitHub CLI。

2. 不要自行搜索安装命令

在 Windows 上，GitHub CLI 通常直接通过专门的命令从命令行安装。在 macOS 上也有命令式安装方法，但不应手动在互联网中搜索它。

严格规则：

应向 Claude Code（Codex）询问最新 GitHub CLI 安装命令。

请求示例：

Claude，我需要在 macOS 上安装 GitHub CLI。请告诉我适用于我的 Mac 的最新官方安装命令，并考虑我是否已有 Homebrew。

这很重要，因为安装方法取决于情况：

是否已安装 Homebrew；
是 Apple Silicon Mac 还是 Intel Mac；
使用普通 GitHub.com 还是 GitHub Enterprise；
是否存在企业软件包安装限制；
需要通过 package manager 安装还是通过官方 binary/pkg 安装。

截至编写本说明时，通过 Homebrew 安装 macOS 版本的官方基础方式：

brew install gh

但在团队的工作说明中，主要规则仍然是：不要搜索随机文章，而应询问 Claude Code（Codex）并使用官方方法。

3. 检查安装

安装后需要检查 gh 命令是否可用：

gh --version

如果命令显示 GitHub CLI 版本，则安装成功。

如果 Terminal.app 提示找不到 gh，不要猜测解决方案，而应询问 Claude Code（Codex）：

Claude，我在 macOS 上安装了 GitHub CLI，但在 Terminal.app 中找不到 gh 命令。请帮助检查 PATH 并修复安装。

4. 在 GitHub 中授权

安装后需要执行授权：

gh auth login

通常 GitHub CLI 会提出几个问题：

GitHub.com 还是 GitHub Enterprise Server；
HTTPS 还是 SSH；
打开浏览器进行授权，还是粘贴 token；
默认使用哪种 Git protocol。

如果人员不确定选择什么，应将截图发送到 Claude Code（Codex）并询问。

请求示例：

Claude，我正在 macOS 上运行 gh auth login。这是选项截图。请告诉我在 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 显示账户的 repositories，说明 GitHub CLI 已准备就绪。

在具体 GitHub repository 内，建议检查：

gh repo view

如果命令显示当前 repository 信息，说明本地文件夹与 GitHub 已关联。

7. macOS 特性

在 macOS 上，通常最方便的是通过 Homebrew 安装 GitHub CLI：

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. 在 macOS 上安装 Python

Claude Code（Codex）环境中需要 Python，不是因为我们喜欢或不喜欢这门语言。

需要 Python 是因为 AI-vibecoding 中大部分简单自动化都适合使用 Python 脚本完成：

从一个文件获取数据并放入另一个文件；
解析 CSV、JSON、Markdown、HTML 或文本日志；
生成小型报告；
重命名一组文件；
检查文件夹结构；
为导入准备数据；
快速编写一次性的 utility script；
自动化手动完成既耗时又有风险的重复操作。

对于 Claude Code（Codex），Python 不是品味问题，而是必备的工作工具。

1. Python 是必需的

每一台为 Claude Code（Codex）AI-vibecoding 准备的 Mac 都必须拥有可用的 Python 3。

检查 Python 是否存在：

python3 --version

检查 pip：

python3 -m pip --version

如果这些命令不工作或显示不合适的版本，则需要安装 Python。

2. 不要自行搜索链接

不需要自行在互联网中搜索最新 Python 下载链接或最新安装命令。

规则：

应向 Claude Code（Codex）询问 Python 下载链接和安装方式。

请求示例：

Claude，我需要在 macOS 上为 AI-vibecoding 安装 Python。请告诉我最新的官方下载链接或安装命令。需要稳定的 Python 3.12.x 版本，而不是最新的 experimental/latest 版本。

这很重要，因为 Python 网站上可能有最新版本的大按钮，但我们的任务不需要最新版本。我们需要的是最稳定且兼容的 Python 编程语言版本，用于日常自动化。

3. 应安装哪个 Python 版本

对于我们的 Claude Code（Codex）环境，基础标准：

Python 3.12.x

截至 2026 年 6 月 18 日，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. macOS 内置 Python

macOS 中可能有系统 Python 组件或与 Python 有关的 developer tools。

规则：

不要触碰 macOS 系统 Python，也不要将其视为 Claude Code（Codex）的工作 Python。

系统 Python 是 macOS 本身或 Apple developer tools 所需的。不要删除、覆盖或手动修复它。

为了使用 Claude Code（Codex），应安装单独的用户/developer Python。

5. 在 macOS 上将 Python 安装到哪里

在 Windows 上，有时会把 Python 安装到磁盘根目录 C:\，以便 Python 可预测地访问。

在 macOS 上不应这样做。macOS 的文件系统结构和 developer tools 安装方法不同。

正确方法：

不要将 Python 安装到磁盘根目录；
不要手动修改系统文件夹；
使用 python.org 的官方 macOS installer 或 package manager；
通过 Terminal.app 检查可用性。

官方 macOS Python installer 通常会将 Python 安装到系统预期的 developer 位置，例如：

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

并将启动 Python 3.12 的命令添加到标准路径。

如果通过 Homebrew 安装 Python，它将安装在 Homebrew prefix 中：

/opt/homebrew

在 Apple Silicon Mac 上，或：

/usr/local

在 Intel Mac 上。

两种选项都正常。对团队而言，比物理安装文件夹更重要的是以下命令可在 Terminal.app 中稳定运行：

python3 --version
python3 -m pip --version

6. 推荐安装方式

对于不熟悉 package managers 的团队成员，最清晰的路径：

向 Claude Code（Codex）询问适用于 macOS 的 Python 3.12.x 最新官方下载链接。
从 python.org 下载官方 macOS installer。
运行 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 中。

如果 Python 脚本属于特定项目，Claude Code（Codex）应看到并使用此类环境。

9. 如果版本不匹配怎么办

如果安装后命令：

python3 --version

显示的不是 Python 3.12.x，不要盲目删除 Python 或修改系统文件。

应询问 Claude Code（Codex）：

Claude，我在 macOS 上安装了 Python，但 python3 --version 显示的不是正确版本。请帮助我了解当前使用的是哪个 Python、它安装在哪里，以及如何为 Claude Code（Codex）安全配置 Python 3.12.x。

10. 规则

配置的第九步：

Python 是 Claude Code 环境的必需项，因为大多数简单自动化适合用 Python 脚本完成。对于基础稳定环境，安装 Python 3.12.x，不触碰 macOS 系统 Python，也不手动将 Python 安装到磁盘根目录。

附加规则：

应向 Claude Code（Codex）询问下载链接、安装命令和 installer 中任何不清楚的设置，而不是在随机来源中搜索或猜测。

步骤 10. 安装 must-have Python 软件包

安装 Python 后，需要准备一组用于日常 Claude Code（Codex）工作的基础 Python 软件包。

这是极其重要的一步，因为如果在 vibe coding 时编程语言缺少执行任务所需的软件包，您很容易出现超支或陷入循环，而您的 Claude Code 可能不会告诉您这一点。结果是您会损失大量时间和 token 消耗。

在大型任务或项目之前，始终先思考并询问 Claude Code：我们将使用哪种编程语言完成此任务，以及需要哪些必要的编程语言软件包。

这些软件包并非“以防万一”所需，而是针对真实 AI-vibecoding 场景：

使用 OpenAI API；
处理图像；
处理音频；
准备和处理语音转录；
voice activity detection；
本地 ML/audio utilities。

1. 软件包不全局安装，而是在 virtual environment 中安装

主要规则：

Claude Code 项目的 Python 软件包不要在没有必要时全局安装。应在具体项目内的 .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 dependencies 的基础库。

torch==2.5.1 用于 ML/audio 任务以及诸如 Resemblyzer 等 dependencies。

librosa==0.10.2.post1 用于分析和处理音频文件。

soundfile==0.12.1 用于读取和写入音频文件。

imageio-ffmpeg==0.6.0 用于需要通过 Python 进行 ffmpeg 处理的任务。

webrtcvad==2.0.10 用于 voice activity detection：确定音频中哪里有语音，哪里是静音或噪声。

Resemblyzer==0.1.4 用于 speaker/audio embeddings 和与语音相关的任务。

setuptools==80.9.0 是 Python 软件包的基础 build-dependency。

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 上无法在 Python 3.12 .venv 中安装 webrtcvad==2.0.10。这是完整错误文本。请帮助了解是否缺少 compiler tools、wheel、pip/setuptools，或者是否需要兼容的 fallback。

单独项目可能的 fallback 是 webrtcvad-wheels 软件包，它提供 macOS 的 binary wheels。但未经团队单独决定，它不能取代基础 pinned 集合。

8. macOS 上的 `torch`

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 发送完整错误文本，并要求针对特定 Mac、Python 3.12.x 和当前 pinned 集合提供安全 fix。

始终只使用严格官方且安全的软件包进行工作，不得使用来源不明的软件包，这可能导致您的代码出现漏洞。

步骤 11. 安装 JavaScript 环境：Node.js 和 pnpm

在 Python 之后，需要准备 JavaScript 环境。对于 Claude Code（Codex），这同样是 must-have 层，因为大量现代项目、frontend 工具、dev servers、CLI utilities、build 系统和 AI integrations 都通过 Node.js 工作。

我们需要 JavaScript 环境并不是因为 JavaScript 比 Python 更好或更差，而是因为在实际 AI-vibecoding 工作中，Claude Code（Codex）不断遇到：

web 应用程序；
frontend 项目；
React、Next.js、Vite 和类似 frameworks；
npm/pnpm/yarn 软件包；
dev servers；
Playwright/browser automation；
用于 JavaScript/TypeScript 的 OpenAI SDK；
通过 Node tooling 处理文件、图像、音频和视频。

MiniApps 也恰恰运行在脚本编程语言上。

1. 需要安装什么

基础 JavaScript 集合：

Node.js
pnpm

Node.js 是在浏览器外运行 JavaScript 的 runtime。

pnpm 是 package manager，处理 dependencies 时通常比普通 npm 更快、更整洁。如果项目使用 pnpm-lock.yaml，必须通过 pnpm 工作。

重要提示：

此步骤仅安装 Node.js 和 pnpm。我们不会预先安装所有可能用于 OpenAI、音频、视频、图像、frontend 和测试的 JavaScript 软件包。

从技术上说，npm 通常与 Node.js 一起安装，但作为我们项目的命令标准，如果特定项目不要求其他 package manager，我们更偏好 pnpm。

Node.js 还拥有内置 core modules，例如 fs、path、http、crypto。它们是 Node.js 本身的一部分，不能也不需要单独安装或删除。在我们的说明中，“不带所有软件包的 Node.js”是指：

安装 Node.js runtime，但不全局安装 project dependencies

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）环境，应安装稳定的 Node.js LTS 版本，而非 Current/latest。

截至 2026 年 6 月 18 日，官方 Node.js LTS 是：

Node.js v24.17.0 LTS

同时 Node.js v26.x 已作为 Current 存在，但对于基础稳定环境，默认不安装它。

规则：

团队安装 Node.js LTS。仅当特定项目明确要求时才安装 Current/latest。

4. 不要自行搜索链接或安装命令

应向 Claude Code（Codex）询问最新 Node.js 下载链接或安装命令。

请求示例：

Claude，我需要在 macOS 上为 AI-vibecoding 安装 Node.js。请告诉我最新官方安装方式。需要 LTS 版本，不是 Current。

这很重要，因为 Node.js 网站上可能有多个选项：

LTS；
Current；
macOS installer；
Homebrew；
version manager；
Apple Silicon；
Intel Mac。

不要盲目选择。

5. macOS 上的推荐方法

团队有两个正常选项。

选项 1：nodejs.org 的官方 installer。

此路径对新手更简单。人员下载 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。
主要规则：除非项目要求其他版本，否则 everywhere 使用 Node.js LTS。

如果人员不了解选择哪个选项，应询问 Claude Code（Codex）。

6. 安装 pnpm

安装 Node.js 后，需要安装或启用 pnpm。

现代安全的选项通常通过随 Node.js 提供的 Corepack 完成：

corepack enable
corepack prepare pnpm@latest --activate

之后检查：

pnpm --version

如果命令在企业 Mac 上运行，且 corepack enable 要求权限或因 permissions 而失败，不要运行互联网上随机的 sudo 命令。应向 Claude Code（Codex）发送完整错误输出。

如果 Corepack 不可用或命令无法工作，不要猜测 fix。应询问 Claude Code：

Claude，我在 macOS 上安装了 Node.js LTS，但无法通过 Corepack 启用 pnpm。这是终端输出。请帮助安全安装 pnpm。

7. 不要全局安装 project packages

全局只应提供 node、npm、pnpm 等基础工具。

Project dependencies 应在具体项目内安装：

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）该项目具体需要哪些 dependencies。

请求示例：

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；
package.json 中的 engines；
现有 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；
schema 和验证：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，以及项目的 OpenAI、语音、音频、转录、图像、视频和其他任务需要哪些 exact 软件包。

这样，JavaScript 环境将变得可控，而不是一堆随机安装的全局软件包。

步骤 12. 允许 Claude Code 和 developer tools 在 macOS 上访问互联网

在 Windows 上，Claude Code（Codex）可能因 Windows Defender Firewall 或其他安全规则而无法访问互联网。macOS 上也可能出现类似问题，但其工作方式不同。

主要区别：

内置 macOS Firewall 主要管理到 Mac 的传入连接。出站互联网问题通常并非与 macOS Firewall 本身有关，而是与 VPN、proxy、企业 MDM 政策、DNS、antivirus、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。首先应允许具体应用程序或服务。

严格规则：

如何为 Claude Code、Terminal.app、dev server 或其他 developer tool 正确配置 macOS Firewall，应询问 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 servers，同时不不必要地削弱安全性。

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. 在 macOS 上配置 PATH

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 可能开始陷入循环、提出变通方案、重新安装多余内容，或错误诊断问题。这会导致时间浪费和巨大的 token 超支。

因此，安装每个工具后，不仅要检查是否完成安装，还要检查该命令能否从 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. macOS 上典型的 PATH 文件夹

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.org 的 Python installer，可能出现如下路径：

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

对于通过 version manager 安装的 Node.js，可能出现用户 home folder 内的路径。

5. 在 zsh 中配置 PATH 的位置

现代 macOS 上的标准 shell 是 zsh。

对于 zsh，最常使用的文件：

~/.zprofile
~/.zshrc

但不理解的情况下不能手动编辑它们。

重要提示：

不要随意在 .zshrc、.zprofile、.bash_profile 或其他 shell 文件中插入行。

PATH 中错误的行可能破坏终端、package managers，或导致运行错误版本的 Python/Node/Git。

6. Homebrew 和 PATH

在 macOS 上安装 Homebrew 后，它通常会自行显示需要添加到 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 说明

严格规则：

在 macOS 上配置 PATH 时，必须清楚知道要将哪一行添加到哪个文件中。应询问 Claude Code，而不是在互联网中搜索或自行编造。

正确的请求：

Claude Code，我正在为 Claude Code 环境配置 macOS 上的 PATH。这是 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

未经明确理由和 Claude Code 确认，不能更改 /etc/paths 等系统文件。

11. 规则

配置的第十三步：

在 macOS 上，需要检查所有关键 Claude Code 环境命令是否可通过 PATH 从 Terminal.app 访问：git、gh、codex、python3、node、pnpm、brew。

附加严格规则：

不要盲目配置 macOS 上的 PATH。不要在互联网中搜索随机命令，不要在不理解的情况下编辑 .zshrc、.zprofile 和系统文件。始终询问 Claude Code，展示当前 PATH，并执行针对具体 Mac 的精确说明。

步骤 14. 安装 FFmpeg 以处理音频和视频

在我们的工作中，Claude Code 经常收到与音频相关的任务：

准备语音转录；
切分音频文件；
转换格式；
从视频中提取音频；
检查文件时长；
规范化或准备文件以供进一步处理；
使用需要 ffmpeg 的 Python 和 JavaScript 工具。

因此，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。

严格规则：

应向 Claude Code 询问 FFmpeg 下载链接、安装命令和配置路径的说明。不要在互联网中搜索随机说明，也不要自行编造路径。

正确的请求：

Claude，我需要在 macOS 上安装 FFmpeg，以处理音频、视频和转录。请告诉我适合我的 Mac 的最新官方/推荐安装方式，并说明是否需要配置 PATH。

如果是手动安装：

Claude，我正在 macOS 上手动安装 FFmpeg。请告诉我应该把 ffmpeg 和 ffprobe 正确放在哪里，以及向 zsh 的 PATH 添加哪一行。这是我的当前 echo "$PATH" 和 uname -m。

4. macOS 上的推荐方法

如果 Homebrew 已安装并正常工作，推荐方法：

brew install ffmpeg

安装后检查：

ffmpeg -version
ffprobe -version

如果命令可以工作，通常无需单独配置路径：Homebrew 将 binaries 安装在其 prefix 中，该位置应已包含在 PATH 内。

在 Apple Silicon Mac 上，通常是：

/opt/homebrew/bin

在 Intel Mac 上，通常是：

/usr/local/bin

5. 如果未安装 Homebrew

如果尚未安装 Homebrew，不要立即下载随机 FFmpeg 压缩包。

应询问 Claude Code（Codex）：

Claude，我的 Mac 上还没有 Homebrew，但我需要为 Claude Code 环境安装 FFmpeg。哪种方式更正确：先安装 Homebrew，还是使用手动 binary？请提供适用于 macOS 的安全说明。

在大多数情况下，团队的正确路径：

先 Homebrew -> 然后 brew install ffmpeg

仅当有理由不使用 Homebrew 时，才允许手动安装 binary。

6. 在 macOS 上手动安装

默认不进行 macOS 上的 FFmpeg 手动安装。

如果确实需要手动安装，不要像 Windows 一样将文件放到磁盘根目录。

在 macOS 上最好使用用户或标准 Unix 位置，例如：

~/bin

或 Claude Code 明确为具体 Mac 确认的其他文件夹。

之后，文件夹路径必须包含在 PATH 中。

但再次强调：

具体把 ffmpeg 和 ffprobe 放到哪里，以及向 ~/.zprofile 或 ~/.zshrc 添加哪一行，应在考虑当前 PATH 的情况下询问 Claude Code。

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；
从视频中提取音频的工具。

重要的是理解：

如果项目或 Claude Code 脚本预期使用 command-line 命令 ffmpeg 和 ffprobe，Python 软件包 imageio-ffmpeg 并不会取消拥有系统 ffmpeg 的必要性。

因此，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

附加严格规则：

始终向 Claude Code 询问 FFmpeg 的下载链接、安装命令和 PATH 说明。不要在互联网中搜索随机说明，不要将文件放入系统文件夹，也不要盲目配置路径。

步骤 15. 安装用于 Markdown 和 YAML 的文本编辑器

对于 macOS 上的 Claude Code（Codex）环境，必须拥有一个好的文本编辑器。

它的任务不是替代 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 用于说明、文档、prompts、handoff 文件、product docs 和 Claude Code（Codex）材料。

YAML 用于配置、CI/CD、GitHub Actions、docker-compose、automation 文件和基础设施描述。

3. macOS 上的 Best practice 编辑器

适用于 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 上必须至少有一个能快速打开 Markdown 和 YAML 的正常 plain-text editor。

5. 不要自行搜索链接

严格规则：

应向 Claude Code（Codex）询问文本编辑器下载链接和安装方式。不要在互联网中搜索随机下载网站。

正确的请求：

Claude，我需要在 macOS 上为 Claude Code 环境安装用于 Markdown 和 YAML 的文本编辑器。请告诉我 CotEditor/Sublime Text/BBEdit 的官方下载来源，以及最适合我任务的选项。

如果人员已选择编辑器：

Claude，我想在 macOS 上安装 Sublime Text/CotEditor/BBEdit。请提供官方下载来源，并检查应选择 Apple Silicon 还是 Intel Mac 的哪个 build。

6. 安装

可能的安全来源：

编辑器官方网站；
Mac App Store；
官方 Homebrew cask，如果团队已使用 Homebrew。

不得从 random download 网站、镜像、“free cracked”、“portable build”及类似来源下载编辑器。

如果通过 Homebrew 安装，也应向 Claude Code 询问命令：

Claude，可以通过 macOS 上的 Homebrew cask 安装所选文本编辑器吗？请提供安全命令和官方来源。

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. 配置文件打开方式

安装后，可为 .md、.yaml、.yml 配置默认编辑器。

但不必为所有人员以同样方式配置。

如果需要将编辑器设为默认应用程序，请询问 Claude Code：

Claude，我想在 macOS 上将 CotEditor/Sublime Text/BBEdit 设为 .md、.yaml 和 .yml 的默认编辑器。请通过 Finder 提供逐步说明。

9. 未经检查不要安装多余 extensions

如果使用 VS Code 或带 extensions/plugins 的其他编辑器，不能安装随机 extensions。

规则：

Markdown、YAML、GitHub、OpenAI、formatting 和 preview 的 extensions 仅在与 Claude Code（Codex）检查后安装。

原因：extensions 可以访问项目文件，并可能影响安全性、格式化和编辑器行为。

10. 规则

配置的第十五步：

在 macOS 上，必须安装用于快速处理 Markdown 和 YAML 的 plain-text editor。最低推荐选项是 CotEditor。专业替代方案是 Sublime Text 或 BBEdit。VS Code 可用作更重型的 code editor。

附加严格规则：

向 Claude Code 询问下载链接、安装方式、Apple Silicon/Intel build 的选择和默认编辑器配置。不要从 random download 网站下载编辑器，也不要未经检查安装 extensions。

步骤 16. 为产品 Markdown 文档安装 Obsidian

如果您从事产品工作，普通文本编辑器可能很快就不够用。

Markdown 文件会变得很多。会出现文件夹、子文件夹、草稿、翻译、handoff 文件、source of truth、call notes、产品要点、ADR、vision documents 及其他材料。

在普通文本编辑器中，很容易开始混乱：

所需文件在哪里；
哪个版本是最新；
哪些文档彼此关联；
产品文件夹 Data 位于哪里；
哪些属于项目，哪些属于旧草稿；
哪些文件已准备好，哪些仍在处理中。

为此需要 Obsidian。

1. 什么是 Obsidian

Obsidian 是用于处理 Markdown 文件和知识库的本地应用程序。

重要提示：

Obsidian 在本地工作。
Obsidian 基于包含 Markdown 文件的普通文件夹工作。
Obsidian 不会将您的文档变为封闭的 Web 格式。
Obsidian 不要求为基础工作进行强制授权。
Obsidian 可免费使用。

它不是 web 服务，不是 SaaS，也不是 GitHub/Google Drive/Confluence 的替代品。

它是一个本地外壳，用于方便处理您的 Markdown 文档文件夹。

2. 第一个超级能力：查看产品文件结构

可以将 Obsidian 连接到您的产品文件夹，例如：

~/Documents/Claude/Product/Data

或包含产品知识库的其他文件夹。

之后 Obsidian 会显示：

文件树；
文件夹；
Markdown 文档；
笔记之间的关联；
快速搜索；
Markdown preview；
方便的导航。

这对于产品工作尤其重要，其中不仅需要打开一个文件，还需要理解整个文档结构。

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，我想为我的产品 Markdown 文件库安装 Obsidian plugin。请说明是否需要它、它是否安全，以及它具体解决什么任务。

5. 第四个能力：知识图谱

Obsidian 有 graph view：文档之间关系的可视化图谱。

可以构建知识图谱，它看起来很有趣。

但我们当前诚实的立场是：

我们目前尚未学会在日常产品工作中高效应用 graph view。

因此可以研究 graph view，但不应将其视为基础 workflow 的必需部分。

目前对我们更重要的是：

文件夹结构；
快速搜索；
方便编辑 Markdown；
与 AI 并行工作；
将文档保存为普通本地 .md 文件。

6. 安装 Obsidian

Obsidian 必须仅从官方来源下载。

严格规则：

应向 Claude Code（Codex）询问 Obsidian 下载链接和安装方式。不要搜索随机 download 网站。

正确的请求：

Claude，我需要在 macOS 上安装 Obsidian，以处理产品 Markdown 知识库。请提供官方下载来源，说明应选择哪个 Mac build，并解释如何将本地 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

这很方便，但需要纪律。

规则：

在 Obsidian 中大规模 AI 编辑文档之前，需要检查 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 界面

安装用于 Markdown 和 YAML 的 plain-text editor 后，可以安装完整的代码编辑器：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 用于：

阅读和编辑代码；
在项目中导航；
syntax highlighting；
处理 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. 为什么不应只通过 IDE 进行 AI 工作

我们并不禁止 VS Code、Cursor 和类似工具。

但极不建议仅通过 IDE 构建全部 AI 工作，因为：

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. 在 macOS 上安装什么 IDE/code editor

正常选项：

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

严格规则：

应向 Claude Code（Codex）询问 VS Code、Cursor 或其他 IDE/code editor 的下载链接。不要自行在互联网中搜索安装程序。

正确的请求：

Claude，我需要在 macOS 上为 Claude Code 环境安装 VS Code/Cursor。请提供官方下载来源，说明应选择 Apple Silicon 还是 Intel Mac 的哪个 build，并说明安装后检查什么。

如果通过 Homebrew 安装：

Claude，可以通过 macOS 上的 Homebrew cask 安装 VS Code/Cursor 吗？请提供安全命令和官方来源。

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。

如果 IDE 内置 terminal 看不到命令，而普通 Terminal.app 可以看到，说明问题在 IDE 内的 shell/PATH。应向 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 开始寻找变通方案；
代理建议多余的安装；
任务膨胀；
token 消耗增加；
执行时间增加；
最终工作成本增加数倍。

重要的是，您的 Claude Code 在 vibe coding 过程中可能不会告诉您缺少工具，您永远不会知道这一点。但您会很长时间地观察 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 在 vibe coding 过程中可能不会告诉您缺少访问权或权限，您永远不会知道这一点。但您会很长时间地观察 AI 代理解决无穷访问问题的工作。

正确结论：

环境必须配置为使 Claude Code（Codex）可以立即读取文件、运行命令、下载 dependencies、使用 GitHub、音频、视频、Python、Node.js 和 Google APIs。

3. 防止陷入循环

AI 开发中最昂贵的问题之一是循环。

当代理一次又一次尝试解决同一个基础设施问题时，就会出现循环：

找不到命令；
软件包无法安装；
PATH 未更新；
permissions 不允许读取或写入文件；
network request 被阻止；
API 未启用；
credentials 不工作；
compiler 缺失；
找不到 FFmpeg；
Python/Node 版本冲突。

每个这样的循环都会消耗：

用户时间；
tokens；
金钱；
注意力；
对 AI 工具的信任。

重要的是，如果您的 Claude Code 在 vibe coding 过程中陷入循环，它不会告诉您真正的问题，您可能只能从消息上下文中猜到这一点。

正确结论：

良好的预先环境配置是防止 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. 经济意义

这些规则节省：

时间；
金钱；
tokens；
精力；
团队工作时间。

它们还提高结果质量：

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）连接到团队工作服务的插件：邮件、日历、文档、任务、repositories、设计和内部系统。

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 server 可将 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 是用于教导 Claude Code（Codex）正确执行某类具体任务的说明或 workflow。

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。

这些插件/connectors 允许 Claude Code（Codex）协助处理邮件、日历、文档、文件、表格和演示文稿。

Atlassian Rovo

用于处理：

Jira；
Confluence；
任务；

重要提示：Jira 插件的正确名称是 Atlassian Rovo

GitHub

用于协调开发：

repositories；
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，我正在为 Gmail/Google Drive/GitHub/Atlassian/Figma 授权 plugin。这是 permissions 截图。请解释我具体允许了什么，以及这对工作任务是否安全。

9. 直接连接 MCP 服务器

并非所有外部系统都作为现成的 marketplace plugin 提供。

有时需要通过 Claude Code 或 Codex 设置直接连接 MCP server。

示例：

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 和人员实际需要的其他工作 integrations。

附加严格规则：

必须在正确的工作账户中授权每个 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

它设定具体项目或 repository 的规则。

子文件夹中可以有更具体的规则：

<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-lock.yaml，则使用 pnpm。
更改前检查 git status。
不要提交 secrets。
修改 Python 脚本后，如果存在测试则运行 pytest。
修改 frontend 后，如果命令可用则运行 lint/build。
未经确认不要添加新的 production dependencies。

4. Skills - 可复用的工作流程

Skills 是 Claude Code（Codex）的 reusable workflows。

Skill 可以包含：

SKILL.md；
说明；
reference 文件；
scripts；
templates；
assets。

简化地说：

skill = Claude Code（Codex）可调用的重复性工作技能

例如：

将 Markdown 文件上传到 Confluence；
使用 service desk；
任务 triage；
生成 status report；
发布 Product 文档；
处理 transcript；
准备 Jira tickets；
使用内部 pipelines。

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，应使用它们。

尤其有用的是：

用于将文件上传到 Confluence 的 skills；
用于 service desks 的 skills；
用于 Jira 的 skills；
用于 Confluence 的 skills；
用于内部 workflow 的 skills；
用于重复 product/documentation 任务的 skills；
用于 Neuronet 场景的 skills。

这不是装饰。这是巨大的时间节省。

规则：

如果公司有用于该任务的现成 skill，先使用 skill，而不是每次要求 Claude Code（Codex）重新发明流程。

8. 正确的文件夹结构

除了 AGENTS.md 和 skills，还需要正确配置文件夹。

最重要的组合：

本地项目文件夹
Claude Code 或 Codex 中的文件夹/workspace
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. 新成员 onboarding：文件夹、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、批准的模板或现有 source of truth 初始填充之前，不要在新的团队文件夹中写入随机文件。
获得企业 GitHub 账户和所需 repository 的访问权。团队工作通常需要企业账户，而不是个人 GitHub。
请求 repository 所有者将用户添加为 collaborator，或通过组织授予访问权。
通过 Git remote 或正确的 clone 将本地文件夹连接到 GitHub repository。
如果在工作中使用它们，则授权 GitHub CLI 和 Claude Code（Codex）中的 GitHub plugin。
检查本地文件夹、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、产品决策、bugs、transcripts 和个人笔记。

在普通 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，请检查我的本地项目文件夹、Claude Code workspace 和 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，为处理 Confluence、Jira、service desk 和 Product docs，我需要安装哪些公司 skills？

Claude，请检查项目文件夹结构和与 GitHub 的关联。请说明 AGENTS.md 应位于哪里，project skills 应位于哪里。

15. 规则

配置的第二十二步：

安装 plugins 和 MCP 后，需要配置 AGENTS.md、skills、文件夹结构和工作聊天纪律。这为 AI 代理设定行为规则，连接可复用 workflows，并防止本地文件夹、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. 在 macOS 上将 Claude Code 项目存放在哪里

2. 安装 Claude Code CLI

3. 安装 Claude Code desktop app

4. Mac 上的基础结构应该是什么样子

5. 规则

步骤 03. macOS 上的终端和命令行

1. macOS 上什么相当于 PowerShell 7

2. 内置 Terminal.app 是否足够

4. 何时值得安装 iTerm2

6. 每位团队成员应具备的能力

7. 规则

步骤 04. 用于 Claude Code 工作的 macOS 截图

1. 是否需要单独的截图工具

2. 主要要求

3. macOS 基础快捷键

4. 团队 Best practice

5. 规则

步骤 05. macOS 上的 Xcode Command Line Tools

1. macOS 上的 Xcode Command Line Tools

2. 它默认包含在 macOS 中吗

3. 如何检查安装

4. 如何安装 Xcode Command Line Tools

5. 通常不需要完整 Xcode

6. 与 Node.js 和 pnpm 的关系

7. 不要自行搜索说明

8. 不要盲目修复 developer tools

9. 规则

步骤 06. 安装和配置 Git

1. macOS 默认有 Git 吗

2. 不要自行寻找 Git 链接

3. 不要猜测安装程序中的勾选项

4. macOS 上推荐的 Git 安装路径

5. Git 基础配置

6. Git 必须能从 Claude Code 项目文件夹运行

7. 对 Claude Code（Codex）还有什么重要

8. 规则

步骤 07. 安装 Homebrew

1. Homebrew 不包含在 macOS 中

2. 为什么在 Git 之后安装 Homebrew

3. 不要自行搜索安装命令

4. 安装

5. 安装 Homebrew 后的 PATH

6. 检查安装

7. 可以通过 Homebrew 安装什么

8. 不要使用随机 sudo

9. 规则

步骤 08. 安装 GitHub CLI

1. 首先需要 GitHub 账户

2. 不要自行搜索安装命令

3. 检查安装

4. 在 GitHub 中授权

5. 检查授权

6. 在 Claude Code 项目文件夹中检查工作状态

7. macOS 特性

8. 规则

步骤 09. 在 macOS 上安装 Python

1. Python 是必需的

2. 不要自行搜索链接

3. 应安装哪个 Python 版本

4. macOS 内置 Python

5. 在 macOS 上将 Python 安装到哪里

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. macOS 上的 `torch`