AI 教程

注意：这里的 AI 指的是 Claude Code / Codex。

1. 基础理念

1. 工作流程：

   描述需求 (人) -->  提出方案 (AI) --> 审查并批准 (人) --> 执行方案 (AI) --> 确认执行 (人)
                        ^                                                 |
                        |                                                 v
                   进一步迭代的需求 (人) <------------------------------- 验证结果 (人)
   

   如果需求比较复杂（比如，搭建一个电商系统），可以让 AI 来采访你，从而一步一步地生成一份良好的需求文档：

   xxxxxxxxxx
   我想做一个电商系统，在动手之前，先采访我，问清楚所有你需要了解的事情。
   

   采访结束后，让 AI 把答案整理为一份 Spec（规范文档）。然后，开启一个全新的会话，把 Spec 文档传给 AI，并让它执行。

2. Context 管理的核心理念：不要试图给出所有信息，而是要给出任务所需要的正确的信息。

3. Project Onboarding：把 Claude Code 作为一个资深的代码导航员，你可以让它解读整个项目的架构，甚至是具体的函数细节。然后问它，项目的架构是什么、核心模块有哪些、数据流是什么样，等等。

4. AI 的三层模型：Prompt 层、Context 层、Harness 层。

   尽量把信息沉淀在 Context 层、把重复劳动交给Harness 层、仅在 Prompt 层处理真正需要临时决策的事情。

   对比维度	Prompt 层	Context 层	Harness 层
   层级位置	最内层（核心基线）	中间层（信息供给）	最外层（系统基础设施）
   核心定义	如何向模型表达任务。单次输入给 LLM 的指令与格式设计	模型执行任务时能看到什么。长时运行中的上下文动态组装与管理	模型运行其中的宿主系统。连接大模型与真实物理世界的确定性外壳
   关注核心	句式结构、System Prompt、Few-shot示例、思维链（CoT）	词元（Token）利用率、状态管理、信息检索与衰减控制	权限拦截、工具调用、状态持久化、确定性逻辑控制
   生命周期	单次交互（Token 级别）	单个会话（Session 级别）	跨系统/工程全程（持久化运行平台级别）
   失败时的典型表现	AI 听不懂人话、格式输出错误、胡言乱语	发生“上下文焦虑”，因 Token 堆积而遗忘前文，导致代码改了后面忘了前面	陷入无限死循环（反复执行失败的命令）、执行高危危险命令（如误删库）、系统失控逃逸
   生动形象的比喻	像是教新员工 “如何开口说话与表达”	像是给新员工 “一张干净的办公桌和查阅资料的权限”	像是为员工建立 “整套公司规章、审批工作流以及电脑防火墙”

   这三层在 Claude Code / Codex 中的具体体现：

   • Prompt 层：

     • 系统内置的基础指令流。

     • 静态的角色定义与意图格式化。

   • Context 层：

     • 动态代码检索（Semantic Search）。

     • 会话历史压缩与修剪。

     • CLAUDE.md / AGENTS.md（项目规范与技术栈规则）。

     • MEMORY.md / Memories（跨会话长期记忆积累）。

     • Skills 指令。

     • @ 附加的文件。

   • Harness 层：

     • 终端命令执行（如运行 npm test） 。

     • 权限门控（询问人类 "Allow this command?"） 或者沙箱策略。

     • MCP 协议（Model Context Protocol）工具链。

     • 运行拦截钩子（Hooks）与会话日志（Logs）。

     • 死循环熔断机制（防止 Agent 刷 Token）。

.

2. 基础使用技巧

1. Claude Code / Codex 默认以当前终端所在目录作为工作根目录。

   • 对于 Claude Code，无法通过命令直接切换工作目录。

   • 对于 Codex，可以在启动时指定目录：使用 --cd（或短参数 -C）参数。也可用 --add-dir <路径> 追加额外的可写目录。

     ​x
     # 在 TUI 交互模式下指定目录启动
     codex --cd /path/to/project
     
     # 在非交互（脚本）模式下指定目录执行单次任务
     codex exec "优化首页加载速度" --cd ~/projects/backend-service
     

     TUI 是文本用户界面（Text User Interface）的缩写。

2. 排查错误：直接把完整报错信息粘贴给 AI，不要手动转述。

3. 操作 git：AI 可以自动与 git 进行交互。例如直接提示：

   xxxxxxxxxx
   提交当前的改动，写一个有意义的 `commit message`
   

4. 交互式和非交互式执行：

   • 交互式执行：直接输入基础命令，即可进入一个人类可介入（Human-in-the-loop）的完整 TUI （Text User Interface）交互式工作空间。

     xxxxxxxxxx
     claude  # 直接启动
     claude "帮我重构一下 utils.ts 文件" # 带初始提示词启动
     codex   # 直接启动
     codex "帮我重构一下 utils.ts 文件"  # 带初始提示词启动
     

   • 非交互式执行（脚本）：让 AI 作为一个独立的 Agent 自动流式执行完所有工具链并直接输出最终结果，随后立刻退出。非常适合用于 CI/CD、Pre-commit Hooks、或者 Bash 脚本中。

     • Claude Code：通过 -p（或 --print）参数触发。

       xxxxxxxxxx
       claude -p "分析当前项目的代码结构" # 单次执行任务
       cat error.log | claude -p "解释这个报错并提供修复代码"  # 结合管道（Pipe）输入流
       claude -p "修复所有 lint 错误" --bare --max-budget-usd 2.0 # 限制最高消费预算（防止陷入死循环），提速启动
       

     • Codex：通过 codex exec 命令。

       xxxxxxxxxx
       codex exec "分析当前项目的代码结构" # 单次执行任务
       codex exec --full-auto "创建一个华丽的待办事项 App" # 开启沙盒全自动执行
       codex --dangerously-bypass-approvals-and-sandbox "部署当前项目到测试环境" # 跳过所有人工审批与沙盒限制执行（高风险/高自由度）
       codex exec --full-auto "生成API文档" --json # 输出逐行的 JSON 事件流（NDJSON格式），方便 jq 等工具解析
       codex exec "编写README" -o ./README.md # 过程不刷屏，仅将最终生成的回复直接写入特定文件
       

5. 极简模式：Claude Code / Codex 启动过程中，默认会在项目目录中动态加载大量上下文，包括自动查找上级目录的 CLAUDE.md （或者）规范、运行初始化 Hooks、加载外部插件/自定义 Skills、连接 MCP（Model Context Protocol）服务器、以及读取自动记忆（Auto Memory）。采用极简模式之后，上述所有环境发现动作全部被跳过。这使得启动速度提升高达数倍，避免了在自动化脚本中意外引入不需要的项目配置。

   • 主要用途：用于非交互式脚本和 CI/CD 自动化流水线中。

   • Claude Code 启用极简模式：用 --bare 参数。

     由于 --bare 保证了任务的幂等性（Stateless）与高启动速度，Anthropic 官方将其作为自动化调用的标准推荐。

     xxxxxxxxxx
     claude -p --bare "运行单元测试并仅报告失败的用例" # 在 CI/CD 脚本或 Git Hook 中的标准写法
     

   • Codex 启用极简模式：Codex 中没有一个名字完全叫 --bare 的单一代替参数，但可以通过组合 Codex 的原生参数，完美实现甚至超越 claude --bare 的效果。

     在脚本或 CI/CD 中，最接近 claude --bare 功能的 Codex 标准写法是：

     xxxxxxxxxx
     codex exec --ephemeral --ask-for-approval never "你的指令"
     

     • --ephemeral（短暂/临时模式）：这是 Codex 达成“干净上下文”的核心参数。它会告诉 Codex 完全禁用自动记忆、不创建或恢复本地持久化会话、不写入历史日志。每次执行都是完全隔离且幂等的（Stateless），这与 --bare 禁用自动记忆的底层逻辑完全一致。

     • --ask-for-approval never（禁用人工审批）：相当于 Claude 在 --bare 模式下收紧工具或静默执行。它强制关闭所有 TUI 交互式确认，一旦遇到无法安全自主执行的操作直接报错退出，防止 CI/CD 流程卡死。

     如果你的脚本是在已经隔离的安全环境（如 Docker、临时虚拟机）中运行，希望彻底剥离所有安全沙盒机制限制（类似于 Claude Code 的 CLAUDE_CODE_SIMPLE 状态），Codex 提供了更激进的标志：

     xxxxxxxxxx
     codex exec --ephemeral --yolo "编译项目并部署"
     

     • --dangerously-bypass-approvals-and-sandbox（简称 --yolo）：该参数不仅跳过所有人工审批，还会彻底关闭 Codex 本地的进程沙盒防护，直接向系统暴露最大原生执行权限。

     • --dangerously-bypass-hook-trust：跳过针对本地 Git Hooks 或项目自定义脚本的信任验证，直接静默执行，确保流水线无人值守时不会卡在 “是否信任此脚本” 的提示上。

3. 权限管理

3.1 审批模式

1. 在审批模式方面，Claude Code 和 Codex 既有相同点、又有不同点。

   • Claude Code：

     模式	含义与行为	适用场景	注意事项
     default（默认）	最安全。任何敏感操作前均需手动逐一批准	初次接触项目、处理敏感/生产环境代码	弹窗多，效率较低
     acceptEdits（自动接受编辑）	自动批准所有文件读写，Shell 命令仍需确认	日常开发、大规模重构、编写测试等重复性工作	警惕 Claude Code 自动修改文件的风险
     plan（计划模式）	只读分析，先制定详细执行计划，审核确认后才执行	复杂功能开发、架构设计、数据库迁移	不会自动执行任何修改，安全可控
     auto（自动模式）	内置 LLM 分类器自动判断操作安全性并执行	Team/Enterprise 计划的高信任项目	需特定模型和付费计划
     dontAsk（不询问模式）	仅执行 settings.json 中预授权的操作，其余静默拒绝	CI/CD 自动化流水线	需预先配置 allow 规则
     bypassPermissions（绕过权限）	跳过所有权限检查，全自动执行	完全隔离的 CI/CD 或 Docker 容器环境	高危，极不推荐日常使用

   • Codex：

     模式	含义与行为	适用场景	注意事项
     untrusted（全询问）	最安全。每一步操作都暂停并询问	初次接触项目、处理敏感/生产环境代码	弹窗多，效率较低
     plan（计划模式）	只读分析，先制定详细执行计划，审核确认后才执行	复杂功能开发、架构设计、数据库迁移	不会自动执行任何修改，安全可控
     on-request（按需询问，默认）	仅在风险操作前询问	日常开发	平衡安全与效率的推荐选项
     never（从不询问）	跳过所有权限检查，全自动执行	完全隔离的 CI/CD 或 Docker 容器环境	高危，仅限隔离环境

2. 审批模式的启用：

   • Claude Code：

     • 执行如下命令：

       xxxxxxxxxx
       claude # default
       claude --permission-mode acceptEdits # acceptEdits
       claude --permission-mode plan # plan
       claude --enable-auto-mode     # auto
       claude --permission-mode auto # auto
       claude --permission-mode dontAsk # dontAsk
       claude --dangerously-skip-permissions # bypassPermissions
       

     • 或者在会话中指定：Shift + Tab 切换；对于 plan 模式，也可以在会话过程中输入 /plan 指令。

     • 或者在配置中设定：在 .claude/settings.json 中配置：

       xxxxxxxxxx
       "defaultMode": "acceptEdits"
       

   • Codex：

     • 执行如下命令：

       xxxxxxxxxx
       codex --ask-for-approval untrusted  # untrusted
       codex -a untrusted                  # untrusted
       codex --ask-for-approval on-request # on-request
       codex -a on-request                 # on-request
       codex --ask-for-approval never      # never
       codex -a never                      # never
       

     • 对于 plan 模式，可以在会话过程中输入 /plan 指令来启动；或者通过 Shift + Tab 来循环切换；或者通过 Cmd + Shift + P 唤醒。

     • Codex 将安全和权限视为底层硬边界。因此，在会话中调整它的权限和控制模式主要依靠斜杠命令（Slash Commands），或通过 IDE 的全局快捷键来实现。它不支持像 Claude Code 的Shift + Tab 切换方式。

       在会话中的指令如下：

       xxxxxxxxxx
       /approval untrusted  # untrusted
       /approval on-request # on-request
       /approval never      # never
       

     • 或者在配置中设定：在 ~/.codex/config.toml 中配置：

       xxxxxxxxxx
       # 设置审批策略和沙盒权限
       approval_policy = "on-request"     # 遇到高风险操作或命令时才提示确认
       sandbox_mode = "workspace-write"   # 允许直接在当前工作区修改和写入文件
       

.

3.2 Claude Code

3.2.1 /permissions

1. 在 Claude Code 的交互式终端会话中，直接输入 /permissions 并回车，会唤起一个免代码的交互式菜单。在这个菜单中可以看到当前的规则（有哪些工具处于 Allow、Ask 或 Deny 状态）、设置新的规则。

   在 /permissions 中或对应的配置文件中，可以对权限进行非常精细的限制，支持通配符语法：

   • 针对大类工具：

     • Edit：允许或禁止 AI 修改/写入本地文件。

     • Read：文件读取权限。

     • Bash：所有终端命令的执行总开关。

   • 针对具体终端命令：

     • Bash(npm install)：只允许精确执行 npm install 这条命令。

     • Bash(git:*)：前缀匹配，允许所有以 git 开头的命令（如 git add, git commit）。

     • Bash(rm:*)：通常放入 Deny 列表，禁止 AI 执行任何删除操作。

2. 直接在会话内用 /permissions 修改的规则通常仅对当前会话生效。可以写入本地的配置文件（如项目的 .claude/settings.json 或全局的 ~/.claude/settings.json）：

   xxxxxxxxxx
   {
     "permissions": {
       "allow": ["Bash(npm:*)", "Bash(git:*)", "Edit"],
       "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)"]
     }
   }
   

3. 在使用 /permissions 交互面板或编辑配置文件时，所有工具的权限都被划分为以下三种状态：

   • Allow（自动允许）：AI 可以静默执行该操作，不需要向你弹窗确认。适用于高频、安全的命令（如 git status、ls）。

   • Ask（每次询问）：这是默认状态。当 AI 想要执行该操作时，会在终端弹窗等待你敲击 y/n 确认。

   • Deny（绝对禁止）：完全封死该操作。即使你在对话中要求 AI 去做，系统也会直接拦截，优先级最高（即使同时在 Allow 里也会被拒绝）。通常用于破坏性命令（如 rm -rf）。

3.2.2 Auto Mode

1. Claude Code 的 Auto Mode 与 Codex 的 auto_review 是当前 AI Agent 领域中最前沿的 “自主权与安全性平衡” 机制。它们的共同核心逻辑是：引入一个专门的独立背景分类器（Classifier）/ 审查智能体（Reviewer Agent）。当 main AI 意图执行某项操作时，该分类器会在后台拦截并评估风险，自动放行低风险操作（如纯读、普通文件修改），只有在发现高风险或不可逆操作（如高危 Shell 命令、外部网络请求）时，才会中断并上升为人工确认。

   Claude Code 采用独立的背景分类器，而 Codex 采用审查智能体。

2. Claude Code 的 Auto Mode：Auto Mode 并非简单的开关，它在后台依赖一个专用的 Claude 智能分类器（通常由快速且具备推理能力的模型如 Sonic 驱动），将 main Agent 的所有工具调用（Tool Calls）划分为三个层级：

   • Tier 1（绝对安全）：如读取本地文件。直接自动放行，不触发分类器，无额外费用。

   • Tier 2（项目内常规操作）：如在当前工作区内写入或修改代码文件、使用 mkdir / touch。同样自动放行。

   • Tier 3（潜在风险操作）：执行特定的 Shell 终端命令、执行外部网络请求、调用复杂的 MCP（Model Context Protocol）插件等。这类操作必须通过分类器审查。

   Claude Code 内置两阶段分类器：

   • 第一阶段：快速判断操作风险，倾向谨慎，误报率 8.5%。

   • 第二阶段：对第一阶段标记的操作深度推理，误报率降至 0.4%。

3.3 Codex

3.3.1 Codex Sandbox Mode

1. Codex 的沙箱策略是它用来约束 AI Agent 运行时行为的第一道技术防线。沙箱不是靠提示词（Prompt）告诉 AI “请不要乱动文件”，而是通过操作系统底层的原生内核机制，强行给 AI 圈定一个绝对无法逾越的技术边界。只要 AI 的操作在边界内，就能自主、流畅地运行；一旦跨越边界，系统就会强行卡死，并交由审批策略（Approval Policy）处理。

2. 有三种核心的沙箱模式（Sandbox Strictness）：

   沙箱模式	文件修改权限	命令执行权限	网络访问权限	典型适用场景
   read-only (只读)	禁止写入任何文件	禁止执行任意 Shell 命令	完全隔离	用于纯代码审查（Review）、架构分析或陌生项目探索，确保源码绝对不被污染
   workspace-write(工作区写；默认)	仅限当前项目目录（如 .codex/ 及源码）	允许运行本地工具（如 git, npm test）	默认禁止	日常开发的常规模式。AI 能自由修改代码和跑测试，但绝碰不到系统核心文件，也无法外传数据
   danger-full-access (完全控制)	无限制	无限制	允许访问互联网	极度危险。 沙箱边界被彻底移除。仅允许在一次性的 Docker 容器、云端沙箱或抛弃型虚拟机（VM）中使用

3. 设置沙箱模式：

   • 在启动时指定：

     xxxxxxxxxx
     codex --ask-for-approval on-request --sandbox workspace-write
     codex exec --sandbox workspace-write "重构 utils 目录" # exec 脚本中明确授权写入
     

   • 或者在对话中切换：

     xxxxxxxxxx
     /approvals                           # 手动切换
     /set sandbox_mode=read-only          # read-only
     /set sandbox_mode=workspace-write    # workspace-write
     /set sandbox_mode=danger-full-access # workspace-write
     

4. 沙箱模式 (Sandbox) vs 审批策略 (Approval)：“沙箱决定了 AI 在技术上能走多远，而审批策略（Approval Policy）决定了当 AI 走到边界时，该由谁来允许它开门。”

5. 完全绕过沙箱和审批（高危）：

   xxxxxxxxxx
   codex --dangerously-bypass-approvals-and-sandbox
   # 别名：codex --yolo
   

   仅在完全隔离的 Docker 容器或 CI runner 中使用，切勿在本机日常开发中开启。

3.3.2 /permissions

1. 与 Claude Code 不同（Claude Code 的 /permissions 指令用于查看和设置 Allow/Ask/Deny 规则），Codex 的 /permissions 仅仅用于切换三种内置的预设模式。

   在 Codex 中，设置 Allow/Ask/Deny 规则采用 Rules。

2. 在 Codex 交互 App 中输入 /permissions 会直接跳转到 App 权限设置管理入口，允许你在以下三种内置的预设模式之间高速切换：

   模式名称	核心权限与行为	适用场景
   Auto（默认模式）	允许 Codex 自动读取文件、改写代码、以及执行当前工作区目录内的常规本地命令。但在涉及网络访问或超出工作区边界（跨目录）的操作时，依然会暂停并弹窗向你请求确认	绝大多数日常开发、重构、本地测试场景
   Read-only（只读模式）	Codex 进入纯咨询状态。它能够浏览、阅读代码以提供架构设计或逻辑分析，但绝对不会在未经你对完整方案进行全局审批前修改任何文件或运行任何命令	接入未知的第三方开源仓库、审查复杂逻辑或只希望 AI 扮演“智囊”而不动手时
   Full Access（全开放模式）	授予 Codex 跨机器工作的全量权限（包括直接的网络访问），并且完全不再弹窗询问。这是最高危的模式	仅在你自己完全信任的本地私有仓库中，且需要 AI 进行大范围自动化脚本跑批、长上下文调用时极少使用

   通过 /permissions 菜单进行的修改往往只对当前终端会话生效。如果你想为你团队的项目或个人习惯定制一套永久的权限规则，Codex 支持在配置文件（如 config.toml）中编写声明式权限文件。

   xxxxxxxxxx
   # 设置 Codex 启动时默认应用的权限配置文件
   default_permissions = "my-secure-profile"
   
   [permissions.my-secure-profile]
   description = "自定义的安全开发权限配置"
   extends = ":workspace"  # 继承官方的默认工作区沙盒防护机制
   
   # 1. 文件系统（Filesystem）精细化控制
   [permissions.my-secure-profile.filesystem.":workspace_roots"]
   "**/*.env" = "deny"     # 强行禁止 Codex 读取或修改任何 .env 环境变量敏感文件
   
   # 2. 网络（Network）白名单控制
   [permissions.my-secure-profile.network]
   enabled = true          # 允许网络访问，但仅限于下方指定的域名
   
   [permissions.my-secure-profile.network.domains]
   "api.openai.com" = "allow" # 只允许向 OpenAI API 发送请求，其余出站流量全部拦截
   

3.3.3 Auto Review

1. 在 Codex 中，在 config.toml 中配置 approvals_reviewer = "auto_review" 是其沙箱与安全策略的高级进阶玩法。它用一个独立的 Guardian Subagent（守护者子智能体）取代了默认的客户端人工交互（user）。

   auto_review 并不会改变你原本在 config.toml 中定义的沙箱硬性边界（如 sandbox_mode = "workspace-write"），它改变的是交互式审批的执行人。它主要在以下敏感边界被触碰时激活：

   • 提权请求：Shell 或 exec 工具请求临时超出当前沙箱权限。

   • 网络阻断拦截：主模型触发了当前沙箱或外部策略限制的网络请求。

   • 越界写文件：修改了允许的可写根目录（writable_roots）以外的文件。

   • 高风险 MCP/浏览器操作：触发了标注为需要确认的 MCP 工具，或试图使用 Browser Use 访问未授信的新域名。

2. 当主模型触发上述操作时，Codex 机制流程如下：

   • 操作被拦截，Codex 将其转化为一个 PermissionRequest（权限请求）。

   • 请求被路由至 Reviewer Subagent（通常为高推理 effort 级别的独立模型）。

   • 该子智能体独立输出一份 Guardian Assessment（守护者评估报告）。

     • Allow（允许）：评估认为该操作符合用户意图且安全，无缝继续执行。

     • Deny / Abort（拒绝/中止）：评估认为存在越权或风险，直接阻断，并向用户解释拒绝原因。

3. 在 Auto Review 模式中，人工可以输入 /approve 指令来强行覆盖 Codex 的判断结果。它针对当前被 auto_review 误杀的那一个特定危险动作进行单次放行。

3.3.4 Rules

1. 在 Codex中，权限预授权（Rules）是用来控制 AI Agent 在沙盒环境外或执行敏感操作时，哪些终端命令可以“自动放行”、哪些需要“弹窗提示”、哪些被“绝对禁止”的精细化指令规则。

   当 Codex 在终端尝试执行某条 Shell 命令（例如 git push、npm install 等）时，它会首先检索配置的 Rules 规则文件：

   • 前缀匹配（Prefix Matching）：Codex 会将即将执行的命令与 Rules 中定义的规则模式（Patterns）进行前缀和参数匹配。

   • 执行决策（Decisions）：匹配成功后，根据规则中预设的决策直接响应，从而省去了每次都要人工按快捷键审批的麻烦。

2. 在编写 .rules 文件时，你可以为匹配的命令指定以下三种策略之一：

   • allow (允许)：命令无需通过沙盒隔离，直接在外部执行，且完全不弹窗询问用户。

   • prompt (提示)：每次触发该命令时，必须暂停并要求用户手动确认后才能运行。

   • forbidden (禁止)：直接封杀该命令，Codex 绝对无法执行此操作。

3. 安全优先原则：如果一条命令同时触发了多条不同的规则，Codex 会采用最严厉的限制级别，即 forbidden > prompt > allow。

4. 规则文件的配置：Codex 采用多层级配置，规则会在应用启动时自动扫描并叠加生效：

   • 全局/用户层：通常存放在系统用户目录下的 ~/.codex/rules/default.rules。当你在 Codex 的终端界面（TUI）里对某个弹窗选择 “总是允许（Always Allow）” 时，Codex 就会把这条命令的 prefix_rule 自动写入到这个全局文件中。

   • 项目层：存放于项目代码仓库内的 <repo>/.codex/rules/ 目录下。只有当该项目在 Codex 中被标记为 “受信任（Trusted）”时，项目级规则才会生效，非常适合团队统一规范。

5. rules 语法：一条典型的预授权规则使用类似 TOML 语法 的格式进行配置，通常通过 prefix_rule() 函数来定义：

   xxxxxxxxxx
   # 示例 1：允许 Codex 自由进行常规的 Git 状态查看与提交，无需每次人工点同意
   prefix_rule(
       pattern = ["git", ["status", "diff", "log"]],
       decision = "allow"
   )
   
   # 示例 2：允许运行项目本地测试，即便测试脚本涉及了沙盒外的一些常规工具调用
   prefix_rule(
       pattern = ["npm", "run", "test"],
       decision = "allow"
   )
   
   # 示例 3：出于绝对安全考虑，禁止 AI 执行任何数据库迁移或高危删除指令
   prefix_rule(
       pattern = ["rm", "-rf"],
       decision = "forbidden"
   )
   

   验证规则：

   xxxxxxxxxx
   codex execpolicy check --pretty \
     --rules ~/.codex/rules/default.rules \
     -- gh pr view 7888
   

6. Codex 中，沙箱、审批模式、Auto Mode、Rules、permissions 五者之间的关系：

   概念	核心解决什么问题？	控制的维度	典型配置/状态示例
   Sandbox (沙箱模式)	AI 能碰哪些文件？能不能联网？	空间与资源边界	read-only / workspace-write / danger-full-access
   Approval (审批策略)	AI 在边界内做事时，什么情况该停下来问我？	流程与交互频率	on-request / untrusted / never
   Auto Mode (自动模式)	我不想配那么复杂，默认怎么用最省心？	官方推荐的开箱即用预设	--full-auto (等同于：沙箱留在工作区 + 遇例外才弹窗)
   Rules (预授权规则)	某条特定命令（如 git push）我想每次直接放行或直接禁止	特定命令前缀的微调例外	prefix_rule(pattern=["git", "diff"], decision="allow")
   /permissions	怎么在终端里快速查看当前的权限配置或现场改模式？	实时交互指令	在 Codex 终端中直接输入 /permissions

   • Sandbox 与 Approval：安全的双黄金旋钮 (The Twin Knobs)。Codex 内部通过这两个指标的组合来决定 AI 的行动自由度。

     • Sandbox Mode：定义硬边界。如果是 workspace-write，AI 的写入权限就被锁死在当前项目目录内，无法越界去改你的系统盘。

     • Approval Policy：定义沟通频率。如果是 on-request，AI 在沙箱内部改文件、运行常规本地测试时完全不打扰你；但当它需要突破沙箱（比如要执行涉及网络或外部目录的指令）时，就会触发 “审批”，停下来等你说 Yes。

   • Auto Mode：效率与安全的平衡点。

     如果把 Approval 设为每次都问，你会面临“审批疲劳”（要点几十次允许）；如果设为 never 且关闭沙箱（俗称 --yolo 模式），AI 的代码一旦写错可能会格式化你的硬盘。

     Auto Mode 就是 OpenAI 帮大家选出的最佳甜点位（Sweet Spot）：它默认自动打包了 sandbox_mode = "workspace-write" 和 approval_policy = "on-request"。让 AI 拥有“有限的自主权”，既高效又安全。

   • Rules：打破僵硬沙箱的“特 批条”。

     虽然沙箱把 AI 关在了项目里，但有时候你必须让 AI 越界去执行某些命令（例如：去系统全局路径拿一个配置文件，或者调用全局的 git 指令）。

     此时你不需要为了这一条命令而把整个沙箱扩大到 danger-full-access。你只需要写一条 Rule：decision = "allow"，这就相当于给了这条特定命令一张“免死金牌/特批条”，允许它不经弹窗直接跨越沙箱执行。

   • /permissions：你的实时仪表盘。

     这是一个在 Codex 交互式 TUI 界面中输入的控制台斜杠命令。输入 /permissions 后，你会看到一个可视化界面，上面清晰列出了当前的 Sandbox 级别、当前的 Approval 状态、以及生效的 Rules 列表。例如，你可以在这里通过键盘上下键现场把 AI 的模式从 Auto 切换到 Read-only，调整 AI 的权限。

3.4 权限设置原则

1. 权限设置原则：

   • 最小权限原则：只允许绝对必要的、明确安全的操作。

   • 优先使用配置文件：将 settings.json （或者 config.toml）纳入版本控制，确保团队环境一致。

   • 避免"YOLO （You Only Live Once）模式"：不推荐日常使用 --dangerously-skip-permissions（或者 --dangerously-bypass-approvals-and-sandbox）。

   • 善用 deny 规则：主动阻止高风险操作，如 Bash(rm -rf *) 或 Write(*.env)。

   • 结合 CLAUDE.md（或者 AGENTS.md）：在项目根目录明确规范，从源头引导 Claude 的行为。

2. 在 Claude Code 中，可以配置 .claudeignore 文件，其功能和语法与大家熟知的 .gitignore 完全相同。它的主要作用包括：

   • 保护敏感信息：防止 Claude Code 意外读取或修改包含 API Key、密码的 .env 文件或私钥文件。

   • 节省 Token 与成本：屏蔽掉 node_modules/、.git/ 或大型构建产物目录，避免Claude Code 扫描无关文件，降低使用成本。

   • 提高工作效率：让Claude Code集中精力处理真正重要的源代码文件，避免因读取垃圾文件而 “迷路” 或产生幻觉。

   你只需要在项目的根目录创建一个名为 .claudeignore 的文件，并在里面写入不想让 Claude 碰到的文件或目录路径。

   而 Codex 目前不支持这种 .ignore 文件。

4. 多模态操作

1. Computer Use： Claude Code 和 Codex 都支持开启和使用 Computer Use（电脑操作模式）。

   • Claude Code ： Claude Code 在 CLI 原生提供了 Computer Use 研究预览版，可以让 AI 在后台打开 macOS 应用、移动鼠标、点击和截图，并支持全无人值守开发模式。

     • 前提条件：

       • 目前仅支持 macOS 平台（研究预览版）。

       • 需要订阅 Pro 或 Max 个人计划（目前不支持 Team 或 Enterprise 计划）。

       • 确保 claude-code 升级至 v2.1.85 或更高版本。

       • 必须在交互式会话中运行，使用 -p 标志的非交互模式无法使用该功能。

     • 使用方法：直接在终端对话中用自然语言对 Claude 下达需要操作桌面的任务。例如：

       xxxxxxxxxx
       启动我正在开发的 Swift App，点击右上角的 ‘测试’ 按钮，并把结果截图发给我。
       

   • Codex：Codex 主要通过 Codex App 来提供多模态操作。Codex 提供了三种不同的方式来操作电脑，根据任务需要使用不同的关键词（@ 指令）来触发：

     • 原生桌面端操作（@Computer）：

       • 适用场景：需要操作桌面应用、修改系统设置或控制没有 API 的软件界面。

       • 使用方法：在 Codex 聊天框中输入 @Computer 激活该模式，随后输入指令。它会看见你的屏幕并移动虚拟鼠标进行点击和输入。

     • 浏览器接管（@Chrome）：

       • 适用场景：任务依赖于你已经登录的 Chrome 浏览器状态、Cookie、多标签页协作或特定网页插件。

       • 使用方法：输入 @Chrome。Codex 会申请调用并连接你本地的 Chrome 浏览器（需在弹窗中点击确认授权），自动接管浏览器去执行网页级自动化任务（如抓取看板、发送邮件等）。

     • 内置独立浏览器（@Browser）：

       • 适用场景：正在开发网页、调试本地前端页面、检查响应式布局或做视觉反馈。

       • 使用方法：输入 @Browser，Codex 将在内置的安全沙盒浏览器中运行并测试网页，不会干扰你本地的浏览记录。

     Codex 的 Computer Use 可以通过 CLI（命令行界面）进行调用，但是存在一些限制：

     • 首先，必须使用 Codex.app 内部绑定的 CLI 工具，或通过其内置命令行环境。

     • 其次，必须在 Codex App 设置中激活并安装 Computer Use Plugin。

     通过 CLI 触发 Computer Use 的方式：

     • 显式指定技能（Skills）：使用带 -c 或技能调用标志参数，显式将 computer-use 作为环境技能加载。

     • 或者通过关键字引导（与 App 类似）：在交互会话中，直接在 Prompt 开头包含特定声明（如 “Use computer use plugin to...” 或在支持的会话中输入包含 @computer 的指令引导），模型便会分流至 GUI 控制流。

2. 语音输入：

   • Claude Code：Claude Code 拥有原生内置的语音听写模式（无需配置第三方工具）。

     • 启用：在 Claude Code 交互会话中输入 /voice 回车，即可开启语音模式。

     • 使用（对讲机模式）：按住空格键（Space）不放并开始说话；松开空格键，语音会自动被实时转录为文字并插入到当前光标位置。

     • 混合输入：你可以先打字，然后按住空格用语音补充，再接着打字，两者无缝切换。

     注意：语音转录功能对 Pro、Max、Team 等订阅用户完全免费，且不计入 Token 额度。

   • Codex：Codex 对语音的支持已经全面铺开，支持直接的语音转文字。

     • 使用：在 Codex App 或 Codex CLI 中，直接按下快捷键 Ctrl + M（或点击界面上的麦克风图标）即可开始语音听写。

     • 原理：它基于内置的 OpenAI Whisper 模型进行实时转录，精确度极高，能够很好地识别编程相关的技术术语。

3. 图片输入：

   • Claude Code：由于 Claude Code 主要在终端（Terminal）中运行，无法直接预览图片，但它完全支持将图片作为附件发送给底层的 Claude 模型进行视觉分析。

     • 使用方式：直接拖拽图片文件到终端窗口中，或者在电脑上复制图片后直接在输入框中粘贴（Ctrl+V / Cmd+V）。

     • 效果：图片会作为附加资源（Attachment）挂载在你的下一条提示词中，可以用来让 Claude 审查 UI 截图、报错设计图或参考设计。

   • Codex：Codex 背靠 GPT 强大的视觉与多模态能力，对图片的处理更加主动，甚至可以进行图像生成。

     • 图片分析（Vision）：

       • Codex App：直接将图片粘贴或拖入输入框，配合提示词让其分析视觉 Bug、解析架构图或还原 UI。

       • Codex CLI：在终端中，你无法直接 “粘贴” 图片，但可以通过指令显式挂载，例如在输入提示词时使用 --image 参数指定本地图片路径。例如：

         xxxxxxxxxx
         codex "帮我还原这个UI" --image ./ui_design.png
         

     • 图片生成（DALL-E 联动）：Codex 允许你在对话中直接输入指令，生成或修改占位图、图标、横幅等资产。例如：

       xxxxxxxxxx
       帮我生成一个 64x64 的返回按钮图标
       

5. Session 管理

1. Claude Code / Codex 的 Session（会话）在底层都是为了解决* “让 AI Agent 记住代码上下文并拥有执行权限”的问题，但它们在设计哲学、历史状态管理、跨会话记忆方面有着截然不同的实现方式。

5.1 Claude Code

1. Claude Code 的 Session 是上下文管理与状态持久化的核心单元。

   • 数据格式与存储：Claude Code 绑定特定项目目录。本质是以 JSONL 格式存储在 ~/.claude/projects/<项目哈希>/<会话ID>.jsonl 的本地日志，记录用户输入、Claude 回复、工具调用、文件变更快照等所有交互信息。

2. 在启动时进行 Session 管理：

   • 新建匿名会话：在当前目录创建全新匿名会话。

     • 使用场景：首次进入项目、开启全新任务。

     • 注意事项：后续可用 /rename 命名。

     xxxxxxxxxx
     claude
     

   • 新建命名会话：创建并启动指定名称的新会话。

     • 使用场景：重要任务提前命名，方便恢复。

     • 注意事项：名称避免特殊字符。

     xxxxxxxxxx
     claude -n <会话名>
     

   • 恢复最近会话：恢复当前目录最近一次会话。

     • 使用场景：上次任务中断，快速续做。

     • 注意事项：仅恢复当前目录的最近会话。

     xxxxxxxxxx
     claude -c
     claude --continue # 或者
     

   • 打开会话选择器：弹出会话列表，支持搜索/筛选/预览。

     • 使用场景：跨项目切换任务、找回历史会话。

     xxxxxxxxxx
     claude --resume
     

   • 恢复指定会话：一键恢复指定名称或 ID 的会话。

     • 使用场景：已知会话名，快速切换。

     • 注意事项：需会话已命名。

     xxxxxxxxxx
     claude --resume <会话名/ID>
     

   • 分支恢复会话：恢复最近会话并创建独立分支副本。

     • 使用场景：基于旧任务尝试新方案，不破坏原进度。

     • 注意事项：原会话工具授权不会继承到新分支。

     xxxxxxxxxx
     claude --continue --fork-session
     

3. 在会话中进行 Session 管理：

   • 清空当前会话：清空当前会话的对话上下文，开启全新对话流。原会话历史仍保存本地，可通过 /resume 找回。

     • 使用场景：当需要开始一个与当前会话完全不同的任务时。

     • 注意事项：同任务上下文过长时，优先用 /compact，不要用 /clear。

     xxxxxxxxxx
     /clear
     /reset # 或者
     /new   # 或者
     

   • 压缩当前会话的历史：将当前会话历史压缩为核心摘要，释放上下文 token 空间。可附加说明指定重点保留的信息（如技术决策、参数定义）。

     • 使用场景：上下文占用超过 80% 时建议执行（可用 /context 查看）。

     • 注意事项：压缩后无法回退到压缩前的历史节点。

     xxxxxxxxxx
     /compact [自定义说明]
     

   • 切换到指定的历史会话：不带参数时打开会话选择器；带参数时直接切换到指定会话。

     • 使用场景：需要回到历史会话继续工作。

     • 注意事项：默认仅显示当前项目会话，按 Ctrl+A 查看所有项目会话。

     xxxxxxxxxx
     /resume [会话名/ID]
     /continue # 或者
     

   • 创建独立分支会话：基于当前会话完整状态创建独立分支会话，原会话保持不变。

     • 使用场景：用于探索多种方案而不破坏主会话进度。

     • 注意事项：原会话已授权的工具权限不会继承到新分支。

     xxxxxxxxxx
     /branch <新分支名>
     /fork # 或者
     

   • 回滚当前会话：打开历史检查点列表，支持三种回退模式：同时回退对话 + 代码、仅回退对话（保留代码修改）、仅回退代码（保留对话）

     • 使用场景：当 Claude 正在做你不想要的事或者改坏了代码。

     • 注意事项：仅能撤销 Claude Code 在当前会话内的文件修改，无法撤销手动终端命令（如 rm、git push）；无法回退外部系统操作（数据库修改、API 调用）；/compact 压缩后的会话无法回退到压缩前节点。

     xxxxxxxxxx
     /rewind
     /checkpoint # 或者
     

     快捷键：双击 Esc。

   • 重命名当前会话：重命名当前会话。命名后可用 claude --resume <名称> 一键启动。

     xxxxxxxxxx
     /rename <新名称>
     

   • 导出当前会话：无参数时将对话复制到剪贴板；带参数时保存为本地可读文本文件。

     • 注意事项：仅导出文本对话，不含文件变更的二进制快照。

     xxxxxxxxxx
     /export [文件名]
     

   • 查看当前会话上下文：查看当前会话的上下文 token 占用与剩余空间。

     • 使用场景：当上下文过长从而想要压缩上下文时。

     • 注意事项：上下文超过 90% 后 AI 易出现信息遗漏、回答质量下降。

     xxxxxxxxxx
     /context
     

   • 结束当前会话：正常结束会话，退出 Claude Code。

     • 注意事项：Claude Code 会自动保存会话状态，下次可正常恢复。

     xxxxxxxxxx
     /exit
     /quit # 或者
     

   • 临时提问：临时提问，不污染主线任务上下文。

     • 使用场景：主线任务执行过程中突发简短的、一次性的、临时的任务。

     • 注意事项：不写入会话历史、不占用上下文窗口 token。关闭后完全不留痕迹。

     xxxxxxxxxx
     /btw [你的问题]
     

.

5.2 Codex

1. Codex 的 Session 核心是一套基于 “显式元提示词和显式文件挂载” 的原子化沙盒。

   • 数据格式与存储：Codex 每次会话的完整原始记录均以 .jsonl 格式持久化存储在本机的 ~/.codex/sessions/ 目录下。

   • 显式上下文管理：它的 Session 是高度结构化的。打开一个底层 JSONL，你会看到非常清晰的三层提示词结构：

     • Meta Prompt（元提示词）：定义当前底层模型（如 GPT-5）的 Agent 人设。

     • Environment Prompt（环境提示词）：当前工作目录、挂载的特定 API 权限。

     • Context / Skills（上下文与技能）：用户明确让其读取的代码片段、日志，以及当前挂载的自定义扩展技能。

2. 在启动时进行 Session 管理：

   • 新建匿名会话：在当前工作目录创建一个全新的交互式会话。

     • 使用场景：首次进入该项目，或需要单独开启一个全新编码任务时。

     • 注意事项：启动后可用内建命令为其命名以方便历史回溯。

     xxxxxxxxxx
     codex
     

   • 新建命名会话：通过参数指定名称直接启动新会话。

     • 使用场景：对特定复杂的功能开发做预先标记，便于后续通过名称精准找回。

     xxxxxxxxxx
        codex --name <会话名>
     

   • 恢复最近会话：一键拉起并继续当前项目或全局下最近一次的活跃会话。

     • 使用场景：接续中断的编码进度，省去重新扫描项目索引的时间。

     xxxxxxxxxx
        codex resume --last
     

   • 打开会话选择器：弹出一个可交互的命令行 TUI (Text User Interface) 界面，供用户搜索、筛选和预览历史会话。

     • 使用场景：跨模块寻找几天前的历史上下文或查看之前的技术方案。

     xxxxxxxxxx
     codex resume
     

   • 恢复指定会话：通过路径、会话名称或特定的会话 UUID 直接恢复。

     • 使用场景：精确知道要找哪个历史节点，不需要通过选择器人工筛选。

     xxxxxxxxxx
     codex resume <会话名/ID或文件路径>
     

   • 分支恢复（创建副本）：将最近一次的会话（或者历史会话）复制到一个独立的新线程副本中启动。

     • 使用场景：既想保留上一次的完整上下文基线，又想安全地试探另一种实现分支。

     xxxxxxxxxx
     codex fork --last
     codex fork <会话名>
     

3. 在会话中进行 Session 管理：

   • 清空当前会话：清空当前的对话上下文和缓存空间，就地开启一个干净的对话流。

     • 使用场景：当前任务已彻底完成，要在同一个项目下安排完全不相关的全新开发需求。

     • 注意事项：此命令仅清除内存上下文，不会抹除已存储的本地磁盘会话文件。

     xxxxxxxxxx
     /clear
     /reset # 或者
     /new   # 或者
     

   • 压缩当前会话的历史：将冗长的前文大面积压缩为一段概括核心逻辑的 Summary，以释放极其宝贵的上下文 Token 额度。

     • 使用场景：面对超大型长序列，长轮次对话后 Prompts Token 即将溢出时（可通过工具监控占用）。

     • 注意事项：压缩会截断并合并历史细节，一般无法反向平铺还原。

     xxxxxxxxxx
     /compact
     

   • 切换/导入历史会话：不带参数时通常会调出内部搜索器，或者通过技能插件直接加载对应的会话数据注入到当前上下文。

     • 使用场景：在交互中突发需要翻阅或合并之前的任务。

     xxxxxxxxxx
     /resume [会话名/ID]
     

   • 创建独立分支会话：就地基于当前会话的最新时刻，“分裂”出一个全新的独立会话。

     • 使用场景：类似于 Git Branch，用于针对一个 Bug 探索两种完全不同的修复路径，且彼此不污染。

     xxxxxxxxxx
     /fork [新分支名]
     

   • 回滚当前会话：呼出会话的检查点列表，允许用户将整个 Agent 的进程强制倒带回之前的某一步。

     • 使用场景：当 Codex 推理跑偏、陷入死循环调试或大面积把本地代码写坏时。

     • 注意事项：回滚会彻底舍弃该检查点之后的对话流及自动生成的临时代码 diff。

     xxxxxxxxxx
     /rewind
     

     快捷键：在部分交互终端中，通常可以通过 Esc 或者 Ctrl+C 快速重置和清理当前的输入提示。.

   • 导出当前会话：将当下的对话历史、执行过程以及系统回执完整转储或输出。

     • 使用场景：需要将 Agent 的思考链路或运行日志存档汇报、提供给队友查看。

     xxxxxxxxxx
     /export [文件名]
     

   • 查看当前会话状态/令牌：查看当前会话中已经消耗的模型 Token、输入输出配额以及当前缓存状态。

     • 使用场景：评估 Agent 还能维持多久的记忆，决定是否需要立即执行 /compact。

     xxxxxxxxxx
     /status
     /tokens # 或者
     

   • 结束当前会话：正常且安全地退出 Codex 交互式 CLI。

     • 注意事项：退出时 Codex 会确保本地 Session 和代理日志被完全刷入磁盘（Flush），以便后续可以完美 Resume。

     xxxxxxxxxx
     /exit
     /quit # 或者
     

   • 临时提问/微型目标：在不干扰和不污染当前主对话上下文与记忆链的前提下，插入一个一次性的微型查询任务。

     • 使用场景：在大型重构进行中，突发想问一个关于某 API 规范或基础语法的简短问题，不希望让这个插曲破坏主线的长上下文。

     xxxxxxxxxx
     /ask [你的问题]
     

   • 创建/管理侧边独立会话：在不中断当前主会话的前提下，开启一个共享项目上下文的侧边辅助对话流。无参数时列出所有侧边会话，带参数时可直接创建或切换。

     • 使用场景：在解决主线复杂任务（如大范围重构）时，突发需要并行排查一个独立的小 Bug 或查询特定 API，可用此命令拉起侧边独立讨论，避免主线上下文被不相关的长对话污染。

     • 注意事项：侧边会话是独立的上下文沙盒，其对话历史和 Token 消耗与主会话相互隔离。

     xxxxxxxxxx
     /side [侧边会话名/ID]
     

   • 归档历史会话：将当前会话（或指定会话）移入归档库。无参数时默认归档当前会话并自动退出或切换。

     • 使用场景：某个阶段性开发任务或功能模块已完美收工，不希望它继续堆积在活跃会话选择器（/resume）的主列表中，但又需要保留其历史轨迹以备日后审计。

     • 注意事项：已归档会话不会被物理删除，但在默认的会话列表中会被隐藏，需在选择器中切换筛选模式（或通过特定的全局查看参数）才能重新找回。

     xxxxxxxxxx
     /archive [会话名/ID]
     

   • 取消归档/激活历史会话：将已被移入归档库的冷冻会话重新激活，恢复其在活跃会话列表中的可见性与可操作性。不带参数时通常会打开已归档会话的选择列表。

     • 使用场景：原本以为已经完美收工的阶段性任务（例如一个已归档的功能模块），因为测试反馈了新的边缘 Bug，或者需要在此前技术方案的基础上继续追加迭代，需要将其重新唤醒。

     • 注意事项：激活后，该会话将自动重新绑定到当前项目的活跃会话列表中，用户可以使用 /resume 正常切入并继续对话。如果该会话此前关联的本地代码版本与当前代码仓状态冲突，建议在执行后优先检查代码上下文同步情况。

     xxxxxxxxxx
     /unarchive [会话名/ID]
     

   • 彻底删除会话：永久物理删除指定名称、ID 或当前的会话文件，释放本地磁盘空间。

     • 使用场景：因测试或临时提问产生的废弃会话，或者包含敏感信息、代码写坏需要彻底销毁痕迹的会话。

     • 注意事项：此操作不可逆！执行后对应的本地 JSONL 日志及快照将被彻底抹除，无法通过 /resume 或 /rewind 找回。如果删除当前正在进行的会话，系统通常会自动结束并退回到终端。

     xxxxxxxxxx
     /delete [会话名/ID]
     /remove # 或者
     /rm     # 或者
     

4. 对历史会话进行管理：

   • 将指定会话移入归档库。

     xxxxxxxxxx
     codex archive [会话名/ID]
     

   • 取消归档/激活历史会话：将已被移入归档库的冷冻会话重新激活，恢复其在活跃会话列表中的可见性与可操作性。

     xxxxxxxxxx
     codex unarchive [会话名/ID]
     

   • 彻底删除会话：永久物理删除指定名称、ID 或当前的会话文件，释放本地磁盘空间。

     xxxxxxxxxx
     codex delete [会话名/ID]
     codex delete --force [会话名/ID]  # 跳过确认直接删除
     

   注意：Claude Code 目前官方并没有关于 archive/unarchive/delete 会话的指令。

6. CLAUDE.md / AGENTS.md 配置

6.1 Claude Code

6.1.1 CLAUDE.md

1. CLAUDE.md 是 Claude Code 专属持久上下文配置文件，纯 Markdown，每次打开会话自动加载注入上下文，相当于给 Claude 一份永久项目说明书。

   核心作用：

   • 消除重复解释：不用每次对话重复说明技术栈、目录、命令、规范。

   • 统一代码输出风格：强制 Claude 遵循项目现有架构、命名、文件分层。

   • 约束危险操作：定义禁止行为、安全边界、数据库/生产环境红线。

   • 提升生成准确率：大幅减少 Claude Code 猜错框架、放错文件的问题。

2. CLAUDE.md 的加载优先级（由全局到局部，全部合并生效，不覆盖）：

   路径	作用域	用途
   ~/.claude/CLAUDE.md	本机所有项目	个人全局偏好（统一包管理器、默认开启单测等）
   仓库根目录 /CLAUDE.md	当前整个代码库	项目主配置（90% 场景只用这个）
   子目录 /modules/user/CLAUDE.md	仅该子文件夹	模块专属规则

3. 创建 CLAUDE.md ：

   • 快速生成（推荐）：在 Claude Code 中输入 /init，Claude Code 自动扫描项目生成基础模板（提取技术栈、命令、目录结构、代码风格）。

   • 手动创建步骤：

     • 在仓库根目录新建 CLAUDE.md（必须大写，小写不识别）。该文件用 UTF-8 编码，采用标准 Markdown 语法。官方建议单文件 ≤ 200–300 行，过长会稀释指令权重、占用上下文 token。

     • 保存后新开会话立即生效，已打开的窗口需重启会话。

4. CLAUDE.md 标准结构模板：遵循 “项目全景 → 工具命令 → 目录架构 → 编码规范 → 安全红线 → 外部文档引用” 分层，每条指令具体、可校验。

   xxxxxxxxxx
   ---
   name: 项目全局规则
   paths: ["**/*"]
   ---
   
   # 1. 项目全景
   ## 项目简介
   本项目是基于 Next.js 15 App Router 的 SaaS 用户后台，TypeScript Strict，PostgreSQL + Drizzle ORM，Auth.js 登录鉴权，部署 Vercel。
   
   ## 技术栈
   - 语言：TypeScript 5.6，strict: true，禁止 any、禁止隐式类型
   - 框架：Next.js 15.2 App Router，不创建 pages/ 目录
   - 样式：Tailwind CSS v4 + shadcn/ui，不引入 Ant Design
   - 数据库：PostgreSQL，ORM Drizzle，不混用 Prisma
   - 包管理器：pnpm 9，禁止 npm/yarn 命令
   - 测试：Vitest + React Testing Library，E2E Playwright
   
   # 2. 开发命令
   - pnpm dev：启动开发服务，端口 3000
   - pnpm build：生产打包，提交前必须无报错
   - pnpm lint：ESLint + Prettier 自动格式化
   - pnpm test：全部单元测试，新增功能必须补充单测
   - pnpm db:migrate：执行数据库迁移
   - pnpm db:seed：本地测试填充假数据，禁止线上执行
   
   # 3. 目录架构
   src/
   ├── app/           # App Router 路由与 API，route.ts 放接口
   ├── components/
   │   ├── ui/        # 通用基础组件 Button/Input
   │   └── features/  # 业务模块组件，按功能拆分文件夹
   ├── lib/
   │   ├── db/        # ORM 客户端、表定义、查询工具
   │   ├── auth/      # 登录、权限中间件
   │   └── utils/     # 纯工具函数，无组件逻辑
   ├── types/         # 全局类型定义，禁止散落在业务文件
   └── middleware.ts  # 全局路由鉴权拦截器
   
   ## 目录规则
   1. 所有接口统一放在 app/api/**/route.ts
   2. 数据库表结构仅在 lib/db/schema 下修改
   3. 组件不跨模块导入，公共逻辑抽 lib/utils
   
   # 4. 编码规范
   ## 命名规则
   1. 文件/文件夹：kebab-case（user-profile.ts）
   2. React 组件：PascalCase（UserProfile.tsx）
   3. 变量/函数：camelCase；常量全大写 USER_STATUS
   4. 数据库表：snake_case，模型类 PascalCase
   
   ## 代码格式
   1. 缩进 2 空格，单行长度 ≤ 120 字符
   2. 导出函数必须显式声明返回类型
   3. 组件 Props 统一抽单独 interface，不内联类型
   
   # 5. 安全红线
   ## 必须遵守
   1. 所有接口参数强制校验，禁止直接入数据库
   2. 环境变量统一读取 env 工具，不直接 process.env
   3. 修改数据库逻辑前先写测试用例
   
   ## 绝对禁止
   1. 禁止硬编码密钥、域名、Token
   2. 禁止生产数据库全表 DELETE / DROP 语句
   3. 禁止修改根目录 env.example、vercel.json 基础配置
   4. 架构变更前必须先提问确认，不直接重构目录
   
   # 6. 外部文档引用
   - API 设计规范：docs/api-design.md
   - 数据库表说明：docs/database-schema.md
   - 部署流程：docs/deploy.md
   

5. CLAUDE.md 内容设计原则：

   • 只写永久通用内容：临时需求、单次脚本、个人调试方法不写入；复杂文档单独建 docs/，在 CLAUDE.md 中用 @ 来引用。

   • 指令具象化，拒绝模糊话术。例如，不要写 “代码要规范，注意类型，写测试”，而要写 “所有导出函数必须显式标注返回类型；新增组件必须配套同目录 xxx.test.tsx 单元测试文件”。

   • 控制长度：主文件控制 200 行内，模块专属规则放子目录 CLAUDE.md，文件类型规则放 .claude/rules/。

   • 分层清晰：用 #、##、 ### 区分大模块，AI 更容易分块读取。

   • 持续迭代：Claude 反复犯同一错误时，直接补充进 CLAUDE.md 固化。

6. 常见误区：

   错误做法	后果
   文件名小写 claude.md	不会被自动加载
   写入密钥、线上配置	泄露风险，禁止提交 Git
   写上万字超长文档（包括 @ 引用一个大文件）	Token 过载，核心规则被稀释，Claude Code 无视约束
   只写业务细节，不写架构/命令	Claude Code 仍会搞错文件位置、执行错误脚本
   只有模糊软性要求，无明确禁止项	无法约束危险操作
   只有 “永远不要做 xxx“，而没有提供一个替代方案	Claude Code 不知道可以做哪些，因此可能会卡住

6.1.2 claude/rules/

1. 除了 CLAUDE.md 之外，.claude/rules/*.md 支持文件或者项目模块粒度的规则，仅按需加载（编辑对应文件或模块时加载）。它不会在启动时一次性加载所有规则，而是根据你当前给它的任务来动态加载。

   • 极大地节省 Token 成本：如果项目很大，各类规范加起来有几万字，每次对话都全盘读取会非常烧钱。按需加载能让每次对话的上下文保持精简。

   • 避免 AI “记忆过载”与混乱：AI 的上下文窗口是有限的。规则太多时，它容易顾此失彼。只给它看当前需要的规则，能让它的代码产出质量大幅提升。

2. 在 Claude Code 中，CLAUDE.md 和 .claude/rules/*.md 都是用来持久化配置 AI 编码规范的 Markdown 文件，两者的核心区别在于范围广度与模块化控制。

   维度	CLAUDE.md	.claude/rules/*.md
   定位描述	项目的通用宪法（全局常驻规范）	专项/模块化法规（垂直领域规范）
   文件位置	放置在项目的根目录（或子包根目录）	放置在项目根目录下的 .claude/rules/ 文件夹内
   文件结构	单文件，包含通用技术栈、编译/测试命令、基础风格	多文件/模块化，按技术栈、测试、安全等拆分
   加载机制	全局始终加载。启动任何会话或处理任何任务时均会读取	根据路径/条件加载。通过 YAML 元数据条件触发，或涉及特定文件时加载
   路径级过滤	不支持无法精细到具体的文件后缀或路径	支持。可在文件顶部使用 YAML paths 声明生效范围
   Token 消耗	高（如果写得过长，会全局占用 Context 窗口）	低（按需加载匹配规则，有效避免 Token 膨胀）
   最佳适用场景	记录项目的 pnpm build 命令、运行测试方法、核心架构原则	记录前端 React 组件规范、后端 API 路由约定、特定目录安全检查

3. 进阶用法示例：

   • 通用规章（CLAUDE.md）：适合存放整个项目无论修改什么文件都必须知道的大原则。

     xxxxxxxxxx
     # Project Commands
     - Build: pnpm build
     - Test: pnpm test
     
     # Universal Code Style
     - Always use TypeScript with strict mode.
     - Prefer descriptive variable names.
     

   • 条件触发规则（.claude/rules/api-style.md）：适合存放利用 YAML Frontmatter 实现按需加载的局部特化规则。

     xxxxxxxxxx
     ---
     paths:
       - "src/api/**/*"
       - "apps/server/**/*"
     ---
     # API Development Rules
     - ALWAYS include a `request_id` in response payloads.
     - Use explicit HTTP status codes (e.g., 201 for Created).
     - Never return raw database errors to the client.
     

     且仅当 Claude 修改或读取符合 paths 里的后端 API 代码时，该规则才会被加载进上下文，避免污染前端 UI 开发的会话。

4. 如果你遇到了 Claude 不听话的情况，可以在终端输入 /memory 指令，实时查看当前会话究竟加载了哪些规则文件。

6.2 Codex

6.2.1 AGENTS.md

1. AGENTS.md 是 Codex 的项目配置文件，相当于 Claude Code 的 CLAUDE.md。

2. AGENTS.md 的加载优先级（由全局到局部，全部合并生效，不覆盖）：

   路径	作用域	用途 / 最佳实践
   ~/.codex/AGENTS.md (或 AGENTS.override.md)	本机所有项目	个人全局偏好： 定义跨项目的通用 AI 行为，如代码审查风格、回复长短、默认首选的交互语言或通用的 Git 提交偏好。
   仓库根目录 /AGENTS.md	当前整个代码库	项目主配置（最核心）： 定义团队共享的架构规范、技术栈、依赖构建命令（npm run build）、测试套件运行方式以及目录结构约定。
   子目录 /packages/api/AGENTS.md (任何深度的子文件夹)	仅该子文件夹及下属目录	模块专属规则： 为特定服务或高危模块定制规则。例如：规定 /payments 目录必须执行更严格的安全校验，或规定子模块特有的本地测试命令。

3. 创建 AGENTS.md ：

   • 快速生成（推荐）：在 Codex 中输入 /init，Codex 自动扫描项目生成基础模板（提取技术栈、命令、目录结构、代码风格）。

   • 手动创建步骤：

     • 在仓库根目录新建 AGENTS.md（必须大写，小写不识别）。该文件用 UTF-8 编码，采用标准 Markdown 语法。官方建议单文件 ≤ 200–300 行，过长会稀释指令权重、占用上下文 token。

     • 保存后新开会话立即生效，已打开的窗口需重启会话。

4. AGENTS.md 标准结构模板：

   xxxxxxxxxx
   # 机器人项目 AI 助手指令 (AGENTS.md)
   
   ## 1. 项目概述
   - **技术栈**: React, TypeScript, Vite, TailwindCSS
   - **包管理器**: 优先使用 `pnpm`，禁止使用 npm 或 yarn
   
   ## 2. 核心目录结构
   - `/src/components`: 存放通用 UI 组件
   - `/src/hooks`: 存放全局自定义 React Hooks
   - `/src/pages`: 页面级组件，禁止在此处编写复杂的业务逻辑
   
   ## 3. 运行与验证命令
   - **开发环境**: `pnpm dev`
   - **代码构建**: `pnpm build`
   - **测试命令**: `pnpm test`（修改任何核心代码后必须运行此命令）
   - **代码检查**: `pnpm lint`
   
   ## 4. 编码规范与约束
   - **修改原则**: 优先进行最小化改动，改代码前先向用户解释原因。
   - **依赖管理**: 禁止擅自引入新的第三方 npm 依赖，必须先向用户确认。
   - **注释要求**: 所有的公共 API、导出的函数和接口必须补充完整的 TSDoc 注释。
   - **状态管理**: 优先使用本地状态（useState/useContext），不要轻易引入全局状态。
   
   ## 5. 任务交付定义 (Definition of Done)
   - 代码通过 `pnpm lint` 检查，无报错与警告。
   - 新编写的功能必须在 `/tests` 目录下附带对应的自动化测试用例。
   - 交付时需附带简短的修改说明及验证步骤。
   

    

6.3 静默截断

1. Codex 按以下顺序构建指令链，后加载的优先级更高：

   • ~/.codex/AGENTS.override.md（如存在）。

   • ~/.codex/AGENTS.md。

   • Git 根目录 → 当前目录，逐级检查 AGENTS.override.md 和 AGENTS.md。

   所有文件以空行分隔拼接，总大小默认上限为 32 KiB（project_doc_max_bytes）。如果超出上限，那么超出的部分则直接丢弃，而且没有任何报警。这会导致一个极具误导性的副作用：

   • 在正常情况下，最接近你当前工作目录（叶子节点）的 AGENTS.md 应该拥有最高优先级（因为后拼接的会覆盖前拼接的冲突规则）。

   • 但如果上层的 ~/.codex/AGENTS.md 或项目根目录 /AGENTS.md 已经写得太臃肿，直接塞满了 32 KiB，那么底层的子目录专属规则根本就不会被 Codex 读取和加载。这意味着你在子目录写的特定安全校验、专属测试命令等，将完全处于失效状态。

   解决方案：在你的全局配置文件 ~/.codex/config.toml 中，手动修改 project_doc_max_bytes：

   xxxxxxxxxx
   # 将限制扩大到 64 KiB
   project_doc_max_bytes = 65536
   

2. Claude Code 在加载 CLAUDE.md 时也存在严格的大小上限与静默截断机制：

   • 单个或合并后的 CLAUDE.md 会在内部读取时被限制在 40,000 字节（约 40 KB）的硬上限内（默认 lint 警告线为 30KB）

   • 当文件体积超过 ~30KB（精准值为 28,672 字节）时，Claude Code 底层的读取器会直接对其执行静默截断（即，默默截断而不会报警）。超出的规则和指令根本不会进入 Claude 初始化的 System Prompt 中。

   与 Codex 一口气把多层级拼接完不同，Claude Code 采用的是按需惰性加载（Lazy Loading）机制：

   • 全局与根目录 (~/.claude/CLAUDE.md 和 /CLAUDE.md) 会在 CLI 会话启动时立即加载。

   • 子目录 (/modules/user/CLAUDE.md) 的规则，只有当 Claude 真正去读取或修改该目录下的源码文件时，才会被动态注入。

   致命隐患：如果你的根目录 /CLAUDE.md 本身就已经非常臃肿（接近 30KB），那么当 Claude 深入到子目录工作、尝试动态追加子目录规则时，由于整体规则流迅速被推过了 40KB 硬限制，子目录的专属规则在注入的瞬间就会被直接截断丢弃。

7. Settings

7.1 Claude Code: settings.json

1. 与 Codex 统一使用全局或项目下的 config.toml 不同，Claude Code 的 settings.json 采用了更精细的多层作用域设计，从全局到本地层层覆盖：

   • 全局用户级：~/.claude/settings.json。

     • 作用：影响你这台电脑上的所有项目，通常用来配置通用的偏好、全局的模型路由等。

   • 项目级：你的项目根目录下 .claude/settings.json。

     • 作用：专门针对当前代码仓库。这个文件可以提交到 Git，让团队所有成员共享相同的运行配置（如同类模型、权限级别）。

   • 本地私有级（Local Scope）：.claude/settings.local.json。

     • 作用：仅在当前电脑的当前项目生效，会被 Git 忽略。适合存放你个人的测试配置或敏感控制。

   注意：对于 MCP 服务，Claude Code 还会配合使用全局的 ~/.claude.json 和项目级的 .mcp.json 来进行扩展工具的管理。

2. 在 Codex 中你可能需要频繁用文本编辑器打开 config.toml 修改参数。但是在 Claude Code 中，不需要手动改 settings.json：在 Claude Code 终端中直接输入 /config，它会弹出一个漂亮的 TUI（终端用户界面）页签，你可以直接用方向键和空格键勾选或修改权限、模型、日志级别等，保存后会自动帮你写入对应的 settings.json 中。

7.2 Codex: config.toml

1. config.toml 是 Codex 的核心配置文件，它采用 TOML（Tom's Obvious, Minimal Language）格式。

   • 技术参数：规定 Codex 底层的硬件和网络参数。

   • LLM 路由：指定调用哪个模型，包括 API 密钥、温度（Temperature）和最大 Token 数。

   • 工具绑定：激活或禁用 Codex 可以调用的外部工具、API 或沙盒环境。

   • 数据库连接：配置向量数据库或关系型数据库的连接字符串。

2. config.toml 与 AGENT.md 的核心区别：

   维度	config.toml	AGENT.md
   面向对象	机器 / 代码编译器	人类开发者 / LLM 提示词引擎
   文件格式	TOML（键值对、结构化数据）	Markdown（富文本、文档流）
   核心关注	How to Run（怎么运行、用什么资源）	Who & What（我是谁、要做什么任务）
   变动频率	较低（部署环境确定后很少修改）	较高（根据测试表现不断调优提示词）
   典型内容	api_key, model_name, timeout	Role, Skills, Constraints

3. 实例对比：

   • config.toml ：

     xxxxxxxxxx
     [agent]
     name = "CodeReviewer"
     version = "1.0.0"
     
     [llm]
     provider = "openai"
     model = "gpt-4o"
     temperature = 0.2
     
     [storage]
     vector_db = "chroma"
     path = "./data/vectordb"
     

   • AGENTS.md：

     xxxxxxxxxx
     # Code Reviewer Agent
     
     ## 角色设定
     你是一个严苛但资深的资深代码评审专家。
     
     ## 核心任务
     1. 检查代码中的内存泄漏隐患。
     2. 确保所有函数都包含异常处理。
     
     ## 约束条件
     - 永远不要修改用户的业务逻辑，只提供修改建议。
     - 必须使用严谨、专业的工程师口吻进行回复。
     

.

8. Memory

8.1 Claude Code: Auto Memory

1. Auto memory（自动记忆）是 Claude Code 的跨 Session 自主学习机制。

   • 在没有记忆系统前，AI 就像一个“临时工”，每次输入 /clear 或开启新命令行窗口，它就会忘记之前发生的调试经验和约定。

   • 开启 Auto memory 后，Claude 会像 “影子搭档” 一样，在协作过程中自主判断并悄悄记笔记。它会将项目特有的构建命令、踩坑记录、你的个人编码偏好等，自动写入本地的 ~/.claude/projects/<项目名>/memory/MEMORY.md 文件中。当你在第二天或新会话中启动 Claude Code 时，这些记忆会被自动重新加载，实现无缝接续工作。

2. Auto memory 和 CLAUDE.md 的区别：

   维度	CLAUDE.md（显式规则）	Auto memory（隐式经验）
   定义	你写给 Claude 的 ”员工守则”	Claude 自己整理的 ”工作笔记”
   维护者	开发者手动编写和维护	Claude 自动在后台读写与更新
   存储位置	项目根目录 ./CLAUDE.md（或 .claude/ 中）	个人全局用户目录 ~/.claude/projects/...
   内容偏向	硬性标准：技术栈版本、团队规范、严禁事项、固定的测试/编译命令	动态经验：特定 Bug 的排查线索、偏好的代码重构风格、临时工作流习惯
   团队共享	共享：通常会提交到 Git，团队所有人复用	私有：仅留在你的本地机器，不随 Git 提交

3. Auto memory 的配置：

   • 激活/非激活状态切换：

     • 快捷方式：输入 /memory，使用方向键选择 Auto memory 开关 (on/off)，敲击 Enter 即可完成切换。

     • 全局配置：可以在全局的 settings.json 中配置是否默认开启，或者使用环境变量（如某些特定脱敏环境）关闭。

   • 修改存储路径：如果你不想将 memory 存在默认的 ~/.claude/ 目录下，可以在 settings.json 中配置：

     xxxxxxxxxx
     {
       “autoMemoryDirectory”: “/your/custom/secure/path/memory”
     }
     

4. Auto memory 的使用：Auto memory 非常自动化，通常不需要刻意操作，但提供了丰富的交互方式。

   • 全自动记录（默认激活）：在正常的编码和 Debug 过程中，当 Claude 独立解决了某个复杂的报错，或者发现了项目特定的潜规则，它会在会话结束或合适时机自动更新 MEMORY.md。

   • 自然语言明示记忆：你可以在对话中直接对 Claude 像下命令一样让它记住某事：

     xxxxxxxxxx
     1. 记住，这个项目我们要用 pnpm，绝对不要用 npm。
     2. 在记忆里存一下：本地运行 API 测试前必须先启动本地 Redis
     

     Claude 回复 ”已记住” 后，该条目就会被实时写入它的草稿本。

   • 查看和管理控制台（/memory）：在 Claude Code 的交互式终端中输入 /memory 命令，会弹出一个管理界面。你可以在这里查看当前加载了哪些记忆文件，并能直接跳转、高亮或进入编辑。

     相反，Codex 不鼓励用户直接去手动修改 ~/.codex/memories/ 下的文件。

5. 注意事项与避坑指南：

   • 核心限制：200 行原则（200-Line Limit）。为了防止上下文（Context Window）被无限膨胀的记忆塞满，Claude Code 规定：在新会话启动时，只会自动加载 MEMORY.md 的前 200 行（或前 25KB）内容。

     应对策略：当 Memory 变多时，Claude 会聪明地将具体长篇内容剥离到独立的子主题文件（如 debugging.md），而在 MEMORY.md 仅保留索引摘要。建议定期通过 /memory 检查，把失效、过期的琐碎记忆手动删掉，挪出高价值空间。

   • 敏感信息泄露风险（安全第一）：MEMORY.md 是以明文纯文本形式保存在你本地磁盘上的。如果在会话中你打印了包含 API_KEY、生产环境密码、机密 Token 的报错日志，Claude 有可能误将其当作 ”重要调试上下文” 写入记忆。

     应对策略：涉及高度敏感数据或合规审查的开发时，建议通过 /memory 临时关闭 Auto memory；或者在操作完后，去本地对应目录下仔细检查并彻底抹除。

     相反，Codex 在生成 memories 时，会自动识别并抹除明文中的密码、API 密钥等敏感字段。

   • 团队同步的局限性：因为 Auto memory 存在于你个人的用户主目录下，它无法随 Git 共享给其他队友。

     应对策略：如果你发现 Auto memory 自动总结出了一条 ”针对该项目全员普适” 的金科玉律，请手动把它复制到项目根目录下的 CLAUDE.md 中，提交进代码库，让全团队都能共享这一智慧。

   • 配合 Auto Dream 机制：如果你连续使用了几十个会话，记忆可能会出现逻辑冲突（例如前天换了框架，今天的记忆与大前天矛盾）。Claude Code 内部还配套了 Auto Dream 机制（可在 /memory 中看到），它会在后台或者你手动输入 /dream 时，像人类睡觉一样，自动去重、修剪并纠正矛盾的记忆，保持记忆的高质量。

   • Memory 是辅助记忆层，关键约定必须写在 CLAUDE.md，因为 Memory 不保证始终加载。

8.2 Codex: Memories

1. Codex 的 Memories 系统可以跨 Session 保留有用上下文，包括技术栈偏好、工作流约定和常用命令，避免每次都重复提供背景信息。

   • Codex 在会话结束后后台处理历史线程，提炼关键信息写入本地记忆文件。因此，Memories 是在活跃会话结束后才生成，不会即时反映当前会话的内容。

   • 存储位置：~/.codex/memories/（包含摘要、持久条目、近期输入及支撑证据）。Codex 并不鼓励用户直接去手动修改 ~/.codex/memories/ 下的文件。

   • Codex 自动屏蔽 API Key、密码等敏感信息，但建议手动复查后再分享 ~/.codex/ 目录。

2. 启用 Memories：

   xxxxxxxxxx
   # ~/.codex/config.toml
   memories = true
   

   细粒度配置：

   xxxxxxxxxx
   [memories]
   generate_memories = true          # 是否从新会话生成记忆
   use_memories = true               # 是否向新会话注入记忆
   disable_on_external_context = true  # 使用 MCP 工具或网络搜索时禁用记忆存储
   min_rate_limit_remaining_percent = 10  # 接近速率限制时暂停生成
   

3. 会话内管理 Memories：

   xxxxxxxxxx
   /memories # 查看并配置当前线程的记忆注入/生成策略
   

   /memories 指令控制的是当前线程的行为，与全局设置相互独立。

4. Codex 具备内置的脱敏机制，在生成 memories 时，会自动识别并抹除明文中的密码、API 密钥等敏感字段。

5. 注意事项与避坑指南：

   • Memories 是辅助记忆层，关键约定必须写在 AGENTS.md，因为 Memories 不保证始终加载。

9. 模型与推理力度

9.1 Claude Code

9.1.1 Model

1. 在 Claude Code 中，可以直接输入命令进行切换，此操作无需重启终端，立即生效。

   xxxxxxxxxx
   /model
   

2. 也可以在 settings.json 中配置，从而将 Claude Code 的模型请求路由到特定的云服务端点（如 AWS Bedrock 或 Google Vertex AI）：

   xxxxxxxxxx
   {
     "modelOverrides": {
       "claude-opus-4-7": "arn:aws:bedrock:...",
       "claude-sonnet-4-6": "arn:aws:bedrock:..."
     }
   }
   

.

9.1.2 Effort

1. 在 Claude Code 中，effort（推理力度）参数用于控制 Claude 在回答问题或执行编程任务时投入的 Thinking Tokens 预算。通过调节 effort 级别，你可以在响应质量（思考深度）与响应速度（Token 成本）之间取得完美的平衡。

2. 根据你使用的模型（如 Sonnet 4.6、Opus 4.7/4.8、Fable 5 等），Claude Code 提供了以下几个级别：

   • low（低）：最小化或不进行扩展思考，直接生成答案。速度最快，最省 Token。

   • medium（中）：适度思考。在速度、成本和性能之间取得最佳平衡。

   • high（高）：进行深入且全面的逻辑推理。（API 的默认级别）。

   • xhigh（超高）：比 High 更深一层的推理。（Opus 4.7 的官方推荐与默认级别）。

   • max（最大）：解除 Thinking Tokens 的上限约束，让模型进行无限制的深度推理。

   • auto（自动）：交由 Claude 官方 API 的 Adaptive Thinking（自适应思考） 机制，根据提示词的复杂度自动决定思考深度。

   • ultracode（超级代码模式）：这不仅是一个 effort level，更是 Claude Code 独有的高级设置。它会向模型发送 xhigh 推理，同时在工程层面让 Claude 编排动态工作流来处理极度实质性的开发任务。

3. Claude Code 提供了多种层级的设置方式，按优先级从高到低排列如下：

   • 命令行交互（当前会话临时生效）：

     • 快捷命令：在 Claude Code 终端中直接输入 /effort <级别>（例如 /effort high 或 /effort auto）。

     • 交互式滑块：直接输入 /effort 不加参数，会弹出一个交互式滑块，使用键盘 ← → 键调节后回车即可。

     • 模型菜单：输入 /model 切换模型时，底部的 effort 程度滑块同样可以用左右方向键调节。

   • CLI 启动参数（单次运行生效）：在终端启动 Claude Code 时通过 --effort 标签指定：

     xxxxxxxxxx
     claude --effort high
     

   • 环境变量（全局或持久化生效）：在你的 Shell 配置文件（如 .bashrc 或 .zshrc）中加入环境变量，这会覆盖配置文件：

     xxxxxxxxxx
     export CLAUDE_CODE_EFFORT_LEVEL=high
     

   • 配置文件（长期默认生效）：你可以在全局或项目目录下的 settings.json 中配置。

     xxxxxxxxxx
     {
       "model": "sonnet",
       "effortLevel": "high"
     }
     

     注意：settings.json 只接受 low、medium、high、xhigh。max 和 ultracode 属于高危/高消耗模式，不支持在配置文件中持久化，只能在会话中临时开启或通过环境变量设置。

4. 不同 Effort Level 的应用场景：

   • low：跳过深度推理，基本直出。

     • 应用场景：简单问答、解释名词、文本格式化、单文件拼写错误（Typo）修复、运行简单的 build 编译命令。

   • medium：适度思考，具备一定的结构化能力。

     • 应用场景：日常业务代码编写、有明确 Specs 的单文件重构、跨文件修改、编写基本的单元测试。

   • high：权衡多种实现方案，自我审视逻辑。

     • 应用场景：复杂的 Bug 排查、涉及多文件的系统重构、新功能的架构设计、代码性能调优。

   • xhigh：极深推理，大规模探索工具调用。

     • 应用场景：针对 Opus 4.7/4.8 处理大规模 Agent 自动化任务、复杂黑盒问题的全盘扫描。

   • max：不惜代价，倾尽全力进行最深推理。

     • 应用场景：极其神秘的线上崩溃（Heisenbug）、算法复杂度极高的核心逻辑攻坚、涉及资金安全或核心系统设计的关键决策。

   • ultracode：xhigh 推理 + 动态多步工作流。

     • 应用场景：大规模端到端的功能开发、自动化迁移整个老旧项目的框架。

5. 不同 Effort Level 的注意事项：

   • Token 计费与成本消耗：在 Claude 中，Thinking Tokens 的计费标准与 Output Tokens 完全相同。调高 effort 级别（尤其是 high、xhigh 和 max）会导致 Claude 消耗大量 Token，从而快速触及你的单次请求限额或订阅账单。不要盲目全时段开启最高级别。

   • 响应延迟（Latency）：Effort 越高，Claude 在把最终代码吐出来之前在 “后台思维反思” 的时间就越长。如果在不需要的简单任务上开了 high 或 max，会遭遇明显的等待卡顿，甚至发生过度思考（Overthinking）。

   • 模型向后兼容（Fallback）：如果你设置的级别当前模型不支持，Claude Code 会自动向下回退（Fallback）到该模型支持的最高级别。例如，你在旧版 Opus 4.6 模型上强行设置 xhigh，它在后台会自动退回并以 high 级别运行。

   • 模型切换时的自动重置：当你首次在当前环境运行 Fable 5、Opus 4.8 或 Opus 4.7 时，Claude Code 会强制应用该模型的官方推荐默认值（Opus 4.7 为 xhigh，其他多为 high），即便你之前为别的模型设置过其他级别。切换模型后，建议随手打个 /effort 重新确认一下。

   • 在自动化 /CI-CD 脚本中优化：如果你在非交互式管道（如 GitHub Actions）中使用 Claude Code，可以通过 --effort 标识针对不同步骤精细化定制（例如：静态分析用 low，生成修复补丁用 high），这样可以打造出成本极其优化的 Agent 工作流。

6. 可以通过如下的命令来查看 tokens 的消耗：

   • /cost：查看当前会话开销。

     显示当前 Session 中已消耗的 Input Token、Output Token 以及缓存 Token 的具体数量。

   • /usage：查看额度与限制状态。

     展示你的计划额度限制和当前的速率限制状态（Rate-limit status）。

   • /stats：查看历史统计总览。

     打开一个内置仪表盘，可以查看热力图、总会话数、历史累计消耗的 Token 总量、以及各模型消耗的分布图（支持查看过去 7 天或 Lifetime 终身数据）。

   • /context：可视化上下文占用。

     如果担心 Token 消耗过快，输入 /context 可以通过彩色网格直观看到当前有哪些文件、MCP 工具输出或子代理（Subagent）正堆积在上下文窗口中，并提供清理优化建议。

9.2 Codex

9.2.1 Model

1. 在 Codex 中，可以通过两种方式选择模型：

   • 启动时指定模型：

     xxxxxxxxxx
     codex --model gpt-5.5
     

   • 会话中切换：/model 指令。

2. 常见的 Codex 模型：

   xxxxxxxxxx
   gpt-5.5  # 复杂编程任务（默认推荐）
   gpt-4.1  # 均衡速度与能力
   gpt-4.1-mini # 快速迭代、简单任务
   o4-mini / o3 # 需要深度推理的算法或架构问题
   

9.2.2 Reasoning Effort

1. 类似 Claude Code 的 Effort Level，Codex 的 Reasoning Effort 控制模型在推理上投入的 Token 预算：

   xxxxxxxxxx
   low    # 快速响应，适合简单任务
   medium # 默认值
   high   # 复杂问题、架构决策
   xhigh  # 最高推理深度，消耗 Token 最多
   

2. 在 Codex 中，可以通过两种方式设置 Reasoning Effort：

   • 在配置文件中设置：

     xxxxxxxxxx
     # ~/.codex/config.toml
     model_reasoning_effort = "high"
     

   • 在命令行中单次覆盖：

     xxxxxxxxxx
     codex --config model_reasoning_effort='"xhigh"' "重构认证模块"
     

3. Codex 的 fast 模式：是 Codex 针对其编程开发工具推出的一种高吞吐量推理配置，旨在为开发者大幅缩短模型响应时间。开启后，GPT-5.4 模型的运行速度可直接提升 1.5 倍。加速的同时，模型的智能级别和代码推理能力完全不变。

   简单来说，快速模式是用更多的钱（双倍额度）去换取服务器更多的 GPU 核心为你并行服务。它没有对模型做任何裁剪或量化，因此生成的代码质量、Debug 的精准度与标准模式完全一致。

   xxxxxxxxxx
   /fast on       # 开启快速服务层（更低延迟，适合调试）
   /fast off      # 关闭
   /fast status   # 查看当前状态
   

4. 为不同工作模式创建预设配置文件：

   • ~/.codex/deep-review.config.toml 配置文件：

     xxxxxxxxxx
     model = "gpt-5.5"
     model_reasoning_effort = "xhigh"
     

   • ~/.codex/fast-iteration.config.toml 配置文件：

     xxxxxxxxxx
     model = "gpt-4.1-mini"
     model_reasoning_effort = "low"
     

   然后，启动时加载指定 Profile：

   xxxxxxxxxx
   codex --profile deep-review
   codex --profile fast-iteration
   

5. 可以通过如下的命令来查看 tokens 的消耗：

   xxxxxxxxxx
   /usage             # 查看当前会话 Token 用量
   /usage daily       # 按天统计
   /usage weekly      # 按周统计
   /usage cumulative  # 累计用量
   /status            # 查看当前活跃终端 Session 的即时状态
   

10. Skills

1. 在 Claude Code / Codex 中，Skills（技能）是一种模块化的扩展机制，允许开发者将特定任务的 “行为规范”、“专业知识” 和 “工作流脚本” 打包成一个独立单元，供 Claude Code / Codex 在编码时自主调用。

10.1 Claude Code

10.1.1 Skills

1. 在底层设计中，一个 Skill 本质上是一个包含特定文件结构的目录，其核心是一个名为 SKILL.md 的 Markdown 文件，也可以选配 Python、Bash 脚本或模板资源。

   • 与 Prompt 的区别：Prompt 必须每次手动输入或注入。而 Skill 常驻内存并支持按需渐进式加载，平常用不到时不消耗大模型的上下文 Token 额度。

   • 与 CLAUDE.md 的区别：CLAUDE.md 存放的是项目级的事实与静态规范（如技术栈、代码作风、变量命名等），每次对话都会被加载。而 Skills 存放的是动态流程与操作指南（如打包部署、Bug 调试、自动生成 Commit 记录），只有触发时才加载。

2. SKILLS 配置：配置自定义技能非常简单，你只需要将包含 SKILL.md 的文件夹放置在指定的目录即可，Claude 启动时会自动扫描。

   • 存放位置：

     • 全局可用（仅限当前电脑用户）：放置在 ~/.claude/skills/ 目录下。

     • 项目级别可用（团队共享）：放置在当前项目的 ./.claude/skills/ 目录下。建议将该目录一并 Git 提交，这样团队所有人都能在当前项目中共享该编码技能。

     配置完成后，可以通过 /skills 命令查看已有的 SKILLS。

     优先级是本地覆盖全局。

   • 标准目录结构示例：

     xxxxxxxxxx
     .claude/skills/
     └── auto-commit/               <-- 技能文件夹名称
         ├── SKILL.md               <-- 核心配置文件（必须大写）
         └── generate_msg.py        <-- 可选：供该技能调用的辅助自动化脚本
     

3. SKILLS 的执行机制：Skills 的生命周期由 YAML 元数据（Frontmatter）驱动，其执行包含以下两个阶段：

   • 启动与静默扫描：当你在终端启动 claude 时，AI 引擎只会读取所有 SKILL.md 顶部的 YAML 元数据（约 30 Token 的名称和描述），此时并不会加载数千字的正文内容。

   • 触发与动态注入：有两种方式可以执行技能：

     • 手动/指令触发：在 Claude Code 终端中直接键入斜杠命令加上技能名称，例如 /auto-commit，强制要求 AI 执行该技能。

     • 自动/上下文触发：当你在终端对 Claude 说：“帮我检查一下刚才修改的代码并提交”，Claude 会在后台通过语义匹配到 auto-commit 技能的描述（description），并自动加载正文、执行相关规约。

4. SKILLS 内容怎么写：SKILL.md 必须由两部分组成：顶部的 YAML Frontmatter 元数据 以及下方的 Markdown 详细正文。

   核心模板示范（以自动生成 Commit 命令为例）：

   xxxxxxxxxx
   ---
   name: auto-commit
   description: 当用户要求提交代码、编写 commit 消息，或输入 /auto-commit 时触发。按照约定式提交规范生成优质的 Git 提交记录。
   user-invocable: true
   disable-model-invocation: false
   allowed-tools:
     - bash
   ---
   
   # 自动提交规范技能
   
   ## 任务目标
   你的任务是协助用户审查当前工作区的代码修改，并生成符合规范的规范化 Git Commit。
   
   ## 执行步骤
   1. 主动运行 `git status` 检查当前有哪些文件被修改。
   2. 运行 `git diff --staged`（若无暂存，则执行 `git diff`）分析代码更改的内容。
   3. 严格遵循 `<type>(<scope>): <subject>` 的约定式提交（Conventional Commits）规范生成一条消息。
   4. **禁止**生成空泛的“update code”，必须说清改动了哪个组件，修复了什么逻辑。
   
   ## 自查清单 (Checklist)
   - [ ] type 是否属于 feat, fix, docs, style, refactor, test, chore 之一？
   - [ ] 标题字数是否控制在 50 个字符以内？
   - [ ] 是否在末尾提供了破坏性更新（BREAKING CHANGE）的说明（若有）？
   

   YAML 字段参数解释：

   • name: 技能唯一标识，也是手动触发的命令名（如 /auto-commit）。

   • description: 最关键的字段。用于告诉 AI 在什么时候、遇到什么词汇时应该激活此项技能。

   • user-invocable:（可选）设为 false 则代表隐藏此命令，不允许用户通过斜杠手动触发，仅让 AI 在后台根据语境自动调用。

   • disable-model-invocation：（可选）设为 true 则代表禁止 Claude 自动触发该技能。一旦设置此参数，该技能将只能由用户通过斜杠命令（如 /auto-commit）手动触发，Claude 在对话中绝对不会自动加载或执行它。

   • allowed-tools:（可选）声明该技能被激活时，Claude 可以免弹窗警告直接调用的工具（如允许执行 bash 脚本）。

5. 创建 SKILL：

   • 直接用自然语言命令 Claude 创建：Claude Code 的基座模型本身就完美理解 Skill 的 YAML 格式和 SKILL.md 规范。不需要任何多余指令，直接用日常对话命令它即可：

     xxxxxxxxxx
     请帮我创建一个名为 pytest-gen 的本地 Skill。功能是：读取当前的 Python 文件，并在 tests/ 目录下生成对应的 test_*.py 单元测试文件，要求覆盖异常处理和边界条件。”
     

   • 通过 /plugin 正式安装 skill-creator 工具：

     • 在 claude 会话中输入 /plugin 并回车。

     • 在弹出的界面中，切换到 Discover 标签页，搜索 skill-creator 并选择安装。

     • 安装成功并重启会话后，使用 /skill-creator 指令（注意必须带斜杠 /）来启动交互式的 Skill 引导构建器。

6. 编写与使用注意事项：

   • Description 必须极其精准：AI 是否能自动触发完全取决于 description 的描述。请不要写模糊的 “这是一个写代码的技能”，而应写清具体的场景，如 “当用户需要对 React 组件编写单元测试，或者输入 /test-gen 时”。

   • 注意上下文自动压缩（Compaction）机制：随着你和 AI 聊天的轮次变多，终端会触发上下文压缩机制。Claude Code 在压缩时会自动保留最近触发的 Skills（上限通常为总计 25,000 tokens），但如果技能包含过于冗长的参考文档，且你同时开启了过多技能，较老触发的技能可能会被顶掉（清除出内存）。

   • 精简为王（控制在 500 行以内）：建议单个 SKILL.md 正文控制在 500 行以内。如果需要庞大的外部库文档、API 手册，正确的做法是将它们作为独立的文件放在同目录下，在 SKILL.md 里写 “需要时，请使用 bash 工具读取同目录下的 api-reference.json”，利用 AI 的工具链按需读取，这样更加节省 Token。

   • 官方内置技能与第三方插件：Claude Code 默认自带了一批优质的 Bundled Skills（如 /debug, /code-review, /simplify, /loop）。当你自己编写自定义技能时，注意不要与内置的命令重名以免引发冲突。

   • 编写常驻指令而非一次性步骤：在 SKILL.md 的正文中，要把规约写成 AI 在整个会话中需要一直遵守的原则或框架（如 “在输出任何内容前必须通过自查清单检查”），而不是一笔带过的一次性命令。

10.1.2 Slash Commands

1. 在 Claude Code 中，Slash Commands（斜杠命令）是你在交互式会话中用来快速控制 AI 行为、管理会话或触发特定工作流的快捷入口。通过输入以 / 开头的指令，你可以无需编写长篇提示词，瞬间调动特定的专家能力。

   根据 Anthropic 的最新更新，自定义 Slash Commands 已正式并入 Skills（技能）系统。

2. 在 Claude Code 的终端交互界面中，直接在输入框首位输入 /，随后会弹出可用命令列表。

   • 基本语法：/<command-name> [arguments]。

   • 参数传递：后面跟的参数不需要严谨的命令行格式，直接写自然语言即可。例如：/commit 修复了登录页面的样式 bug。

3. 你可以通过编写 Markdown 文件来创建自己的斜杠命令。你可以将其配置在两个层级：

   • 项目级（推荐）：在当前项目根目录下创建 .claude/skills/（或旧版的 .claude/commands/）文件夹，仅对当前项目生效。

   • 全局级：在系统家目录下创建 ~/.claude/skills/（或 ~/.claude/commands/）文件夹，对所有项目生效。

4. Anthropic 官方在 v2.1.3 版本中正式将自定义斜杠命令并入了 Skills 系统。这意味着，过去由 .claude/commands/ 承载的“提示词模板”功能，现在已经被 Skills 彻底包容（Envelop）和强化了。

   阶段	你需要做什么？	Claude Code 底层如何处理？
   旧版逻辑 (已淘汰)	想手动调用的写在 commands/ 里；想让 AI 自动用的写在 skills/ 里。	两个完全独立的系统，互不相通，容易导致 Prompt 重复。
   2026年新版逻辑	只需要学习并在 skills/ 目录下编写结构化的 SKILL.md。	统一解析为 Skill。同时自动在终端 UI 里注册一个同名的 / 斜杠命令。

.

10.2 Codex

10.2.1 Skills

1. SKILLS 配置：

   • 存放位置（优先级从高到低）：

     • 仓库本地：.agents/skills/。

     • 仓库父目录：../.agents/skills/。

     • 仓库根目录：$REPO_ROOT/.agents/skills/。

     • 用户全局：~/.agents/skills/。

     • 系统管理员：/etc/codex/skills/。

   • 标准目录结构示例：

     xxxxxxxxxx
     my-skill/
     ├── SKILL.md              # 必须，包含 YAML frontmatter 和 Markdown 指令
     ├── scripts/              # 可选，辅助脚本
     ├── references/           # 可选，参考文档
     ├── assets/               # 可选，静态资源
     └── agents/openai.yaml    # 可选，UI 与调用策略配置
     

   其中 agents/openai.yaml 的示例如下：

   xxxxxxxxxx
   interface:
     display_name: "端到端测试"
     icon_small: "./assets/logo.svg"
     brand_color: "#22C55E"
   
   policy:
     allow_implicit_invocation: true   # 允许自动触发
   
   dependencies:
     tools:
       - type: "mcp"
         value: "playwright"
   

2. SKILL.md 示例：

   xxxxxxxxxx
   ---
   name: run-e2e-tests
   description: 在提交前运行端到端测试。当用户提到"e2e"、"端到端测试"或要求提交前验证时触发。
   ---
   
   ## 步骤
   
   1. 确保开发服务器已启动：`npm run dev`
   2. 运行 Playwright 测试套件：`npx playwright test`
   3. 如有失败，展示截图并逐一分析原因
   4. 修复失败用例后重新运行，直到全部通过
   

3. SKILLS 的执行机制：

   • 显式调用：在对话中输入 /skills 浏览并选择，或直接输入 $run-e2e-tests。

   • 隐式调用：Codex 根据任务描述自动匹配 Skill 的 description 字段触发。

4. 创建 SKILL：

   • 通过 skill-creator 工具：交互式创建新 Skill。

   • 通过 skill-installer 工具：从社区安装已有 Skill。

   • 在 Codex 中，可以通过录制来生成 SKILL：

     xxxxxxxxxx
     /record  # 开始录制（在 App 界面）
     

     Codex 会记录每一步操作，检查步骤后自动生成对应的 SKILL.md。

5. 可以在配置文件中禁用特定 Skill：

   xxxxxxxxxx
   # ~/.codex/config.toml
   [[skills.config]]
   path = "/path/to/skill/SKILL.md"
   enabled = false