需要"构架拆解 / 架构分析 / 项目模块拆分"时

• Claude（Claude Code / Claude Sonnet/Opus）更强：https://claude.ai/chat
• Codex（Codex CLI / GPT-5.x-Codex）比 Claude 逊色。

构架拆解：Claude 胜出

维度	Claude（Opus/Sonnet + Claude Code）	Codex（GPT-5.x-Codex + Codex CLI）
架构理解/拆解​	⭐⭐⭐⭐⭐ 擅长读全量代码、梳理依赖、输出分层模块划分和重构计划	⭐⭐⭐ 偏重执行实现，规划偏简略
上下文窗口​	Opus 4.7 默认 200K，最大 1M token，可吞下整个中小型全栈项目	Codex 默认 ~128K~400K，大单体仓库易截断
多文件关联推理​	Agent Teams 子智能体并行扫描，汇总后做全局判断	并行子 Agent 但无共享任务列表，偏各自执行
输出风格​	先出架构方案/计划让你审阅再动手（Plan Mode）	倾向直接动手改代码，少主动出架构分析
最适合场景​	陌生代码库梳理、微服务拆分、大重构规划、模块依赖分析	按已有架构快速生成代码、跑测试、修 Bug、DevOps 脚本

• 社区共识："Claude 是架构师，Codex 是执行力强的初级工程师"。
  • 构架拆解、模块划分、理解遗留代码 → 用 Claude；
  • 拿到架构后快速写代码/跑任务 → 用 Codex。
• 推荐混合策略：

  阶段 1 — 架构拆解 & 规划  → 用 Claude
    "分析本项目，输出：模块划分、依赖关系图、重构优先级、各模块接口定义"
    → Claude 给详细 Plan，你审核 ✅
  
  阶段 2 — 按模块实现代码   → 用 Codex（或 Copilot）
    "按上面 Plan 的 Module A，生成 xxx 文件"
    → Codex 快速产出、省 Token

Codex

必装

• superpowers
  •  GitHub - obra/superpowers: An agentic skills framework & software development methodology that works. · GitHub
  • 也可以直接在codex界面的内置插件市场那里搜索安装。
  • 作用：强制让 Codex 从"急着敲代码的实习生"变成"先问清楚再按计划 TDD 的靠谱搭档"。
• codegraph
  • 作用：给 Codex 一张项目"地图"，让它先查图谱再读文件，大仓里定位快、影响分析准、不乱翻无关代码。

在对话中使用技能

在对话框中输入美元符号＄后选中技能 即可：

省token妙招

AGENTS.md

OpenAI 官方文档说明，Codex 会读取项目里的 AGENTS.md，用它作为项目说明和工作规则；这能减少你每次重复解释项目背景。

1. 在项目根目录新建：AGENTS.md
2. 内容可以这样写：

   # Project Guide for Codex
   
   ## 项目类型
   这是一个 VSCode + Qt + C++ 项目。
   
   ## 构建环境
   - 使用 Qt Creator / VSCode 开发
   - C++ 项目
   - 构建系统可能是 CMake / qmake，请先根据项目文件判断
   - 不要擅自修改 Qt 安装路径、编译器路径、Kit 配置、第三方库路径
   
   ## 工作规则
   1. 默认只阅读与当前任务相关的文件，不要全项目扫描。
   2. 修改代码前，先列出需要查看和修改的文件。
   3. 每次只解决一个明确问题。
   4. 不要重构无关代码。
   5. 不要改变公共接口、信号槽接口、类名、文件名，除非我明确要求。
   6. 不要修改 UI 布局文件 .ui，除非任务与界面有关。
   7. 不要修改 CMakeLists.txt / .pro / .pri，除非编译必须。
   8. 修改后必须说明：
      - 改了哪些文件；
      - 为什么改；
      - 如何编译；
      - 如何测试；
      - 还有什么风险。
   
   ## 调试原则
   - 优先根据报错日志定位问题。
   - 优先查看调用链相关文件。
   - 不要凭猜测大范围搜索。
   - 如果信息不足，先要求我提供具体错误日志、函数名、模块名或复现步骤。
   
   ## 输出要求
   - 回答简洁。
   - 不要重复解释已知背景。
   - 先给结论，再给必要步骤。

3. 这样以后就不用每次都说一遍“这是 Qt C++ 项目、不要乱改配置”。

首次不优化，先让它建立“项目地图”

第一次可以让 Codex 做一次轻量分析，但要求它只输出模块索引，不改代码：

请先做一次轻量级项目结构分析，不要修改代码。

要求：
1. 只查看项目根目录、构建文件、主要 src/include 目录。
2. 不要深入阅读所有 cpp 文件。
3. 输出：
   - 构建方式：CMake 还是 qmake；
   - 程序入口；
   - 主要模块目录；
   - UI、业务逻辑、算法、数据结构、第三方库分别在哪里；
   - 后续排查 bug 时应该优先看哪些文件。
4. 输出要简洁。

在项目里准备一个 docs/codex_context.md

• 作用与codeGraph互补。
  • CodeGraph 是“代码索引/检索工具”，帮 Codex 更快找到代码。
  • docs/codex_context.md 是“项目说明书/背景说明”，帮 Codex 更快理解项目规则、业务背景和用户的要求。

对比项	CodeGraph	docs/codex_context.md
类型	工具/索引	人写的项目说明
主要作用	找代码、找符号、找调用关系	告诉 AI 项目背景、规则、限制
是否自动生成	可以根据代码索引	需要你手动维护
适合解决	“代码在哪里”	“为什么这样设计、哪些不能动”
对省 token 的帮助	减少全项目搜索	减少重复解释背景
对修 bug 的帮助	快速定位相关文件	避免改错方向、改错边界
能否替代对方	不能	不能

把项目中长期稳定的信息写进去，避免每次重复解释：

# Codex Context

## 项目简介
本项目是 Qt + C++ 图像处理软件。

## 主要模块
- src/ui：界面层
- src/core：业务流程
- src/vision：图像处理算法
- src/device：设备通信
- src/config：配置读写

## 常见入口
- main.cpp：程序入口
- MainWindow.cpp：主窗口
- VisionManager.cpp：视觉流程入口
- ImageProcessor.cpp：图像处理入口

## 构建方式
- 使用 CMake / qmake
- Debug 构建目录：
- Release 构建目录：

## 常用测试方式
- 运行 xxx.exe
- 测试图片目录：
- 日志目录：

## 禁止事项
- 不要改 Qt 安装路径
- 不要改第三方库路径
- 不要随意改公共接口

然后每次对 Codex 说：

请先阅读 AGENTS.md 和 docs/codex_context.md，然后只处理本次任务相关文件。

这样比你每次手打背景更省。

话术模板

中断继续

请继续从中断处执行剩余步骤，不要重做已完成的修改

库

目的：
帮我检查与processAutoGrafting模块相关的函数，是否哪里做了不必要的或测试期间临时的提前缩放。
先分析，先不要直接改动任何代码。

背景：
这是我自己写的视觉库，编译生成dll后，可以调用ImageProcess_test中的main运行测试视觉库的效果。


重点范围：
- @path/ImageProcessing/AutoGrafting.cpp
- @path/ImageProcessing/AutoGrafting.h
- E:\projec\振镜拼接\ImageProcess_test\ImageProcess_test/callingTest.cpp
请只读取与processAutoGrafting模块相关的文件，不要全仓库扫描。
输出：
1. 这个模块的入口函数和调用链
2. 主要数据结构和关键变量含义
3. 核心流程，按步骤说明
4. 当前逻辑中可能存在的问题或风险
5. 如果要修改，建议最小改动点在哪里

限制：
- 可以新增函数，也可以在main中新增调用的函数，其余任何已有的代码和逻辑都不要改，可以在。
- 代码优化结束后将ImageProcessing编译成debug版本的dll，随后运行ImageProcess_test中的main确切中间没有任何被拦截或没有被拦截的现象
- 可以重点增加我描述的新函数。
- 尽可能小的变动量帮我优化代码
- 不要重构
- 不要输出大段源码
- 只给结论和必要函数名

软件

发现的问题：
	
目的：
直接在界面增加一个按钮和一个勾选框。
勾选框：是否启用新生成的振镜校准文件，没勾上则使用本地路径对应的那个文件，勾上则使用。
按钮：自己生成振镜校准文件。
可以是点击按钮后打开类似实时采图匹配那样的窗口，支持获取相机图片，然后根据相机图自己获取打标得到图片中的点阵的各个点位，再另外获取或安规路自己生成振镜点位，再调用视觉库中的对应接口生成生成振镜校准文件。
现在还无法连接相机等硬件测试，所以先将整体流程跑通，用于标定的两张振镜打标图现在先支持读取指定图片，然后振镜点位根据界面输入的行列数调用视觉库中对应接口自行生成点位。
先分析，分析后将步骤分成小步骤整理给我，先不要直接执行。

背景：
这是一个现有的 qt + vscode + opencv + c++ 软件项目，通过vscode+cmake编译运行。
需要在这个软件项目中增加一个用于测试嫁接功能的模块。

重点范围：
- @path/test/AutoGraftingTest
- @path/test/AutoGraftingTest/MainWindow.h
- @path/test/AutoGraftingTest/MainWindow.cpp
请只读取与AutoGraftingTest模块相关的文件，不要全仓库扫描。
优先读取指定的几个具体文件，无法解决再读取- @path/test/AutoGraftingTest路径中的其他文件
输出：
1. 这个模块的入口函数和调用链
2. 主要数据结构和关键变量含义
3. 核心流程，按步骤说明
4. 当前逻辑中可能存在的问题或风险
5. 如果要修改，建议最小改动点在哪里

限制：
- 不要重构
- 不要全项目扫描
- 不要输出大段源码
- 只给结论和必要函数名
- 尽可能小的变动量帮我优化代码
- 不用加注释，新增函数只需给个一句话的功能总结即可
- 代码优化结束后编译运行以下，确认中间没有任何被拦截或崩溃的现象
- 所有的改动皆必须以预留后期会将AutoGraftingTest嵌入SLM.exe内部模块的准备为前提。
- 以利于后续剥离复用为前提，优先将控件的基础功能和可复用功能下沉到对应模块中去。
- 每次在功能完成够帮我总结一个精简版的用于提交分支时的描述
- 不要改动或重构SLM中除AutoGraftingTest模块以外的任何现有代码和逻辑，可以增加代码和功能。
- 重点在LiveCaptureInputPreparationService，优先只看这个模块，非必要不要扫码其余模块。

让codex帮忙推送git仓库

请先帮我对照下现有最新代码与git仓库该分支下最新一次提交的版本代码看下差异，然后按例如前面让你帮忙优化代码的细分项，分批推送到本地仓库中，中文版的总结和描述记得都加上。先分析。

工作树使用

1. 确认项目已经是Git仓库
2. 项目添加到codex

创建第一个并行任务

1. 新建对话（创建第一个并行任务）
2. 选择工作树Worktree
   1. Local：直接操作你的原项目目录。
   2. Worktree：创建隔离副本。
   3. 并行任务必须选择 Worktree。
   4. 选中某个git分支（作为起始分支）
3. 输入任务A（可以直接粘贴后点击发送）

   你正在 Codex 创建的独立 Worktree 中工作。
   
   任务：
   优化振镜校准结果图的保存目录。
   
   目标：
   生成校准文件 a.yaml 时，在同路径下创建 a 文件夹，
   所有结果图保存到该文件夹中。
   
   主要修改范围：
   - test/AutoGraftingTest/Device/CalibrationService.h
   - test/AutoGraftingTest/Device/CalibrationService.cpp
   
   限制：
   1. 不修改与本任务无关的功能。
   2. 原则上不要修改 ZoomableImageView 和界面右键菜单代码。
   3. 如果必须修改公共接口或 CMakeLists.txt，先说明原因。
   4. 使用当前 Worktree 自己的 build 目录。
   5. 修改后执行编译验证。
   6. 最后列出修改文件、实现逻辑、测试结果和潜在冲突。
   7. 暂时不要合并到 main。

   Codex 会自动创建一个受管理的 Worktree。默认情况下，该 Worktree 处于 detached HEAD，不会立即污染你的本地分支

创建第二个任务（无需等任务A结束）

1. 同个项目文件中新建对话
2. 再次设置：环境工作树，其实分支main
3. 任务B例如：

   你正在 Codex 创建的独立 Worktree 中工作。
   
   任务：
   为结果图增加右键菜单“打开结果目录”。
   
   主要修改范围：
   - test/AutoGraftingTest/Widgets/ZoomableImageView.h
   - test/AutoGraftingTest/Widgets/ZoomableImageView.cpp
   - test/AutoGraftingTest/Widgets/GalvoCalibrationGenerationDialog.h
   - test/AutoGraftingTest/Widgets/GalvoCalibrationGenerationDialog.cpp
   
   限制：
   1. 不修改结果图保存逻辑。
   2. 不重构无关界面代码。
   3. 不修改任务 A 负责的 CalibrationService 实现，除非只需要调用已经确定的公开接口。
   4. 如果缺少结果目录接口，先提出最小接口方案，不要自行大规模改动。
   5. 使用独立 build 目录完成编译。
   6. 最后列出修改文件、测试结果和可能与任务 A 冲突的位置。
   7. 暂时不要合并到 main。

   发送以后，左侧会出现两个独立对话：

   AutoGrafting
   ├─ 优化结果图保存目录
   └─ 增加打开结果目录菜单

   每个对话对应一个单独的 Codex 管理 Worktree，因此修改文件不会直接互相覆盖。官方说明，每个代理可以在独立代码副本中运行，并且多个线程可以在同一个项目下并行工作。

并行期间查看代码（每个 Worktree 都应使用自己的构建目录）

1. 进入任意任务对话后，顶部通常会有：Open
2. 点击后可以选择在编辑器中打开，例如：Open in VS Code

Codex 会让 VS Code 打开该任务对应的 Worktree，而不是原项目目录。官方文档说明，可以通过对话顶部的 Open 按钮直接在 IDE 中打开当前 Worktree。

打开后注意 VS Code 窗口标题和路径，应该不是原项目路径，而是 Codex 管理的 Worktree 路径。

你也可以在该对话里打开集成终端，执行：

git status
git diff
git rev-parse --show-toplevel

最后一条命令可以确认当前实际操作的是哪个目录。

Qt＋CMake 项目怎么编译

每个 Worktree 都应使用自己的构建目录。

• 在任务 A 的 Worktree：

  cmake -S . -B build
  cmake --build build --config Debug

• 任务 B 也使用它自己的：

  cmake -S . -B build
  cmake --build build --config Debug

• 虽然命令都叫 build，但因为两个 Worktree 的根目录不同，所以实际位置不同：

  CodexWorktree-A\build
  CodexWorktree-B\build

  不要通过 -B 把两个任务都指向原项目外部的同一个公共构建目录。

  还要避免两个任务同时：

  启动同一个生成的 EXE；
  覆盖同一个 DLL；
  连接同一个相机；
  连接同一个振镜设备；
  写入同一个测试结果目录。

  源码编译可以并行，硬件联调最好串行。

任务完成后先创建功能分支

1. Codex 创建的 Worktree 默认可能是 detached HEAD。任务完成后，进入任务对话，点击顶部：

   Create branch here

   官方文档明确说明，可以通过对话顶部的 Create branch here 将当前 Worktree 转换成正式分支。
2. 任务 A 创建：feature/calibration-result-storage
3. 任务 B 创建：feature/open-result-directory
4. 然后在任务 A 对话中告诉 Codex：

   请检查当前所有修改，只提交本任务相关文件。
   提交信息使用：
   
   feat: organize calibration result images by output file

5. 任务 B ：

   请检查当前所有修改，只提交本任务相关文件。
   提交信息使用：
   
   feat: add open result directory context menu

6. 可以让 Codex执行：

   git status
   git diff
   git add ...
   git commit -m "..."

7. 但提交前一定先看右侧 Diff，确认没有夹带：

   无关格式化
   临时文件
   构建产物
   用户配置
   测试图片
   设备配置

两种验收和合并方式

1. 方式一：继续在 Worktree 中验证

   适合没有硬件依赖、可以直接在隔离目录编译的任务。
       1、在对话顶部点击：Open
       2、用 VS Code 打开当前 Worktree，编译、运行和测试。
       3、测试通过后，保留功能分支，最后回原项目合并。

2. 方式二：Hand off 到 Local

   如果程序只能从原项目目录运行，或者相机、振镜、DLL、配置路径只在原目录有效，可以
       1、点击对话顶部：Hand off
       2、然后选择：Local
   Codex 会处理 Worktree 与本地工作区之间需要的 Git 操作。
   官方建议，当你需要在常用 IDE、既有开发服务器或唯一可运行的本地环境中验证时，
       使用 Hand off → Local。
   不过两个任务不要同时 Hand off 到 Local。
   推荐顺序：
       任务A完成
       → Hand off 到 Local
       → 验证
       → 提交
       → 处理任务B

推荐的实际合并流程

两个任务都创建分支并提交后，回到原项目目录：
cd D:\Projects\AutoGrafting

确认原项目没有未提交修改：git status

创建集成分支：
git switch main
git switch -c integration/calibration-improvements

先合并任务 A：git merge --no-ff feature/calibration-result-storage
编译：
cmake -S . -B build
cmake --build build --config Debug

再合并任务 B：git merge --no-ff feature/open-result-directory
再次完整编译和运行测试。

确认没问题后：
git switch main
git merge --no-ff integration/calibration-improvements

注意：

• 一个功能分支被某个 Worktree 检出时，不能同时在原项目中切换到该分支；这是 Git 的限制。
• 但你仍然可以在 main 或集成分支中执行 git merge feature/...。
• Codex 官方也建议，需要把同一分支带到 Local 工作时使用 Handoff，而不是在两个工作目录里同时检出。

CodeGraph

安装

1、在 Windows 左下角搜索：PowerShell ，然后点开 Windows PowerShell。

2、安装：

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

这是 CodeGraph 官方 README 给的 Windows 安装命令。官方也说明：这个方式不要求你提前安装 Node.js。

CodeGraph 已经安装成功了，只是没有加入 PATH，所以 PowerShell 找不到 codegraph 命令。

它已经装在这里：C:\Users\Administrator\AppData\Local\codegraph\current

测试：

& "C:\Users\Administrator\AppData\Local\codegraph\current\codegraph.exe" --help

如果能显示帮助信息，说明程序没问题。

3、永久加入 PATH ：

安装成功后，把 CodeGraph 加到环境变量 PATH：

$cgBin = "C:\Users\Administrator\AppData\Local\codegraph\current\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")

if (($userPath -split ";") -notcontains $cgBin) {
    [Environment]::SetEnvironmentVariable("Path", "$cgBin;$userPath", "User")
}

执行完以后，关闭 PowerShell，重新打开一个新的 PowerShell。

然后测试：

codegraph --help

若能显示一堆命令，则说明 PATH 修好了。

安装成功后在对应项目使用

• 全程在 PowerShell 中输入。

1、确认可用：

codegraph --help

2、如果成功，再进入项目目录：

Set-Location "你的项目路径"
例如：
Set-Location "E:\GalbanoCalibration"
或：
cd /d "E:\GalbanoCalibration"

3、初始化项目索引：

codegraph init -i

成功后，项目目录里会多一个文件夹：.codegraph 。

这就说明 CodeGraph 已经给你的项目建立索引了。

4、确认索引状态：

codegraph status

5、最后执行，配置给 Codex 用：

codegraph install --target=codex --yes

完成后，关闭 Codex，再重新打开 Codex。

CC Switch：切换Codex中转站

下载地址：Release CC Switch v3.16.5 · farion1231/cc-switch

vsCode

vsCode与git联动-注意事项：

• 安装顺序：先装VSCode，再装git
• git的默认编辑器安装的过程设置为vscode
  • 这个地方默认编辑器改为vscode 👇
• git的学习网站：Git

必备插件

通用必装（所有开发都建议装）

插件	作者	作用
Chinese (Simplified) Language Pack​	Microsoft	界面汉化
GitLens — Git supercharged​	GitKraken	行内显示代码作者/提交历史，Git 增强
Error Lens​	usernamehw	错误信息直接显示在代码行后，不用悬停
Material Icon Theme​	PKief	文件树图标美化，一眼认出文件类型
Path Intellisense​	Christian Kohler	输入路径时自动补全
Code Spell Checker​	Street Side Software	检查变量名/注释英文拼写错误
Bookmarks​	Alessandro Fragnani	打书签 + 上下跳转（就是书签功能）
EditorConfig for VS Code​	EditorConfig	读取 .editorconfig统一缩进/换行风格

• Prettier - Code formatter：代码格式化
• Chinese (Simplified) Language Pack：界面汉化
• GitLens — Git supercharged：行内显示代码作者/提交历史，Git 增强
• XML相关：
• One Dark Pro：深色主题
• ：

 C/C++ / Qt / CMake 专项

插件	作者	作用
C/C++​	Microsoft	IntelliSense 智能补全、跳转定义、调试支持（地基）
CMake Tools​	Microsoft	CMake 项目选 Kit、配置、构建、运行、调试一条龙
CMake​ (语法高亮)	twxs	CMakeLists.txt语法高亮和简单补全
Qt C++ Helpers​ / Qt Tools​	tonka3000 或 The Qt Company	.ui/.qrc预览、Qt 信号槽高亮（可选但推荐写 Qt 时装）

💡 也可直接搜 C/C++ Extension Pack（Microsoft），它打包了 C/C++ 及辅助工具，省得一个个装

常用快捷键

返回上次光标位置

操作	Windows / Linux
返回上一个光标位置（Go Back）	Alt + ←（左方向键）​
前进到下一个光标位置（Go Forward）	Alt + →（右方向键）​

• 对应 VS 里的 Ctrl + -（Navigate Backward）和 Ctrl + Shift + -（Navigate Forward）

补充说明：

• 该导航不仅记录同一文件内的光标移动，也记录跳转到其他文件后的位置（比如 F12跳转到定义后再按 Alt + ←跳回原处）。
• 若想用鼠标操作：右键编辑区 → Go Back​ / Go Forward（较少用，记快捷键更方便）。
• 若 Alt + ← 被系统或其他软件占用没反应，可按 Ctrl+Shift+P输入 Go Back​ 手动执行验证功能是否正常。

一句话：记住 Alt + ←/ Ctrl + -，就是 VS Code 版的"回到上次光标位置"

打包软件 NSiS

• nsis 是软件打包工具
• 教程：NSiS打包详细步骤教程_nsis打包教程-CSDN博客
• 写好打包脚本，剩下的跟压缩文件夹没什么区别