让 Codex 真正进入
开发流程

官方依据：Use ChatGPT

1. 1
   填写项目名称按系统或代码库命名，如 codex-class-demo。
2. 2
   添加 Source folders选择 Codex 需要读取或修改的本地目录。
3. 3
   确认并创建以后从这个项目中新建任务，共用这些目录。

官方依据：Projects and chats

1. 01
   创建项目添加本地 Git 文件夹
2. 02
   进入 Plan锁定范围和验收
3. 03
   点 Local → Worktree选 main，发送任务后创建
4. 04
   实现功能保留数据、不加依赖
5. 05
   运行测试先验证再汇报
6. 06
   浏览器验收三种筛选逐一操作
7. 07
   查看 Diff确认修改范围
8. 08
   两轮 Review发现 → 修复 → 复核

按已确认计划实现状态筛选。
完成后运行现有测试，并用浏览器验证三种筛选。
不要提交、推送或修改无关文件。

检查当前改动是否满足验收条件。
列出运行过的测试、浏览器操作和仍未验证的风险。
不要根据代码推测页面已经可用。

修复 Code Review 中确认的问题。
保持改动最小，补充回归验证，然后再次 /review。
不要顺便重构无关代码。

目标：给任务清单增加状态筛选。
范围：只修改前端，不增加依赖。
限制：保留现有本地数据。
验收：全部/待办/完成筛选正确，刷新后数据不丢。

请先检查现有实现并给出完整计划，不要修改文件。

模型：默认即可；卡住再升高推理，不要一上来 Max。详见附录 A13。

1. 1新建或打开任务
2. 2点输入框左下角权限标签
3. 3选择三档之一
4. 4确认标签后再发送

陌生仓库 / 敏感任务

Ask for approval

编辑项目外文件、联网等动作先询问。课堂演示、新项目和不熟悉的脚本优先选它。

日常开发推荐

Approve for me

普通动作自动执行；检测到潜在不安全操作时再询问。每次弹窗仍要看清命令和目标。

明确需要时临时使用

Full access

可访问互联网和电脑上的任意文件。完成安装、跨目录操作或部署后，立即切回较低权限。

官方依据：Agent approvals & security · Permission profiles；三档名称以当前桌面版为准。

1. 1
   打开 Git 项目，新建任务只有 Git 仓库才会显示 Worktree。
2. 2
   点击输入框上方的 Local就是截图红框位置，不是在任务完成后再找。
3. 3
   选择 Worktree 和起始分支通常从最新的 main 或目标开发分支开始。
4. 4
   写需求并发送Codex 创建托管 Worktree；原本地目录保持不动。

官方依据：Git worktrees

Environment：确认代码落点

防什么：改错目录、改错分支、准备提交到错误仓库。

重点看：Local 还是 Worktree、当前分支、Changes 文件数与增删行。

提交前四问：仓库对吗？环境对吗？分支对吗？Diff 对吗？

Activity：追踪执行过程

防什么：长时间 Working、假进度、以为“做过”就是“做对”。

重点看：读文件、跑命令、搜索、是否在等输入。

原则：“做过”不等于“做对”；仍要核对测试、页面和最终结果。

TTerminal

何时：跑测试、脚本、服务。注意：命令真实执行；先看目录，破坏性操作仍要确认（别盲点 Allow）。

BBrowser

何时：验收三种筛选与真实交互。注意：打开的是当前 Worktree 启动的地址，不是旧服务。

RReview

何时：看 Diff 与范围。注意：看 Diff ≠ /review 自动分析；陌生文件先切 Last turn。

FFiles / Side chat

Files 定位文件；Side chat 旁支短问。独立交付请新建任务，别塞进主任务。

官方依据：Environments · Terminal · Browser；详细五工具说明见附录 A14。

# 项目规则
- 修改前阅读 README 和现有测试。
- 状态筛选相关改动完成后运行：npm test && npm run lint
- 不修改 .env、生成文件和无关模块。
- 汇报修改文件、测试结果和未验证风险。
- 未经确认不要提交、推送或发布。

官方依据：AGENTS.md · Build skills · Hooks

“+”：给当前任务增加上下文或模式

• Files and folders：添加文件或目录
• Attach Ghostty：带入终端上下文
• Goal：持续追踪多步骤目标
• Plan mode：先调查和形成方案
• Record a skill：把重复流程录成 Skill
• Plugins：调用已安装专业能力

Open in：用外部工具打开当前目录

• IDE / 编辑器：继续阅读、调试或手工修改
• Finder：定位当前项目或 Worktree
• Terminal / Ghostty：在同一目录运行命令

注意：只是打开当前目录，不会把 Worktree 改成 Local，也不等于 Handoff。

官方依据：Goal mode · Skills · Desktop app；具体菜单以当前版本为准。

1. 1
   把目标窗口放到最前面Appshots 只捕获当前最前面的窗口，不是整个桌面。
2. 2
   同时按两个 Command 键也可以在设置中改成自己的快捷键。
3. 3
   补一句明确任务例如：“分析这个报错，先说明原因，不要修改代码。”

报错现场设置面板设计与预览网页参考

发送前检查：截图和窗口可读取文字都会共享给 ChatGPT；账号、Token、客户信息等敏感内容先隐藏。部分应用只能提供可见截图，不能代替完整文件或插件。

官方依据：Appshots（目前仅支持 macOS 桌面应用）。

Documents / PDF

写方案、说明和复盘；PDF 用于读取规范与检查最终版。

Spreadsheets

做测试矩阵、字段映射、数据核对和迁移清单。

Presentations

把技术方案、培训内容或事故复盘做成可演示课件。

Template Creator

把周报、PPT、表格的固定结构做成下次可复用模板。

Sites

快速制作并发布演示页、内部工具或静态网站。

Browser

打开真实页面，点击验收、查控制台、截图并标记问题。

Computer

需要操作本机应用、又没有更合适接口时使用。

Product Design

评审页面流程和视觉问题，再给出可执行的改版建议。

官方说明：Plugins · Skills & Plugins

官方依据：Work with files

DOCXPPTXXLSXPNG邮件 / Slack

1

创建模板

提供一份代表性参考文件，说明要保留的结构、排版和语气；生成后先检查预览。

2

再次使用

从对应工具的 Template Gallery 选择，或输入 $artifact-template-模板名，再描述本次内容。

3

验收结果

核对旧项目名、人员、日期和业务数据是否已替换；格式是否仍与参考一致。

把附件《项目周报.docx》做成个人模板。保留标题层级、表格、字体和页眉；移除项目名、人员、日期与业务数据。以后输入本周进展、风险和下周计划即可生成新周报。先给我模板预览和隐私检查结果。

依据：当前已安装 Template Creator 插件说明；模板本质是可复用 Skill。通用机制见 Build skills。

适合

原型、培训页、活动页、内部看板、小工具。

不优先

必须接入现有 CI/CD、网关或公司服务器的正式系统。

1. 1
   说清网站目标受众、用途、核心功能和要使用的信息。
2. 2
   先看预览检查内容、交互、数据和敏感信息。
3. 3
   用文字继续修改也可以补截图或文件，指出具体位置。
4. 4
   确认后再分享设置访问范围，复制最终链接。

Sites 示例复制

为研发团队做一个值班任务看板网站。支持新增任务、负责人、状态筛选和本地保存。先生成可预览版本，完成浏览器验收后再问我是否部署。

官方依据：Sites

用途+主体+构图风格+尺寸+禁止项

图片提示词示例复制

为内部值班系统生成一张空状态插画。
主体：整齐的任务清单与一个绿色完成标记。
风格：简洁扁平、白底、低饱和绿色。
尺寸：16:9。不要文字、Logo、人物和渐变。

修改已有图：明确写“只改什么”和“必须保留什么”，一次只调整一个重点，避免构图漂移；图片中的文字和业务细节仍要人工复核。

官方依据：Image generation

1. 1
   打开真实页面先启动服务，用 Browser 打开当前 Worktree 的地址。
2. 2
   开启 Annotation mode点击元素，或拖动选择需要修改的区域。
3. 3
   写清问题与结果例如：“按钮在手机端溢出；保持卡片高度不变。”
4. 4
   让 Codex 按评论修改限制范围，修改后重新打开页面逐条验收。

注意：内置 Browser 使用独立浏览器配置，不自动继承日常 Chrome 登录；外部网页内容不可信，敏感操作仍需确认。

官方依据：Browser · Comment on the page

01 · 个人

~/.codex/AGENTS.md

所有项目都适用：表达语言、通用安全边界、默认工作习惯。

02 · 项目

<repo>/AGENTS.md

整个仓库适用：构建与测试命令、架构边界、禁止修改范围。

03 · 模块

<repo>/module/AGENTS.md

只约束该目录：模块专属命令、框架约定和验收要求。

官方依据：AGENTS.md · Personalization

1. 1
   说明重复任务做什么、什么时候触发、什么情况不能用。
2. 2
   给出步骤与验收输入、操作、输出证据，以及失败时怎么停。
3. 3
   先做最小 Skill默认只写指令；确实需要确定性执行时再加脚本。
4. 4
   用真实样例试跑检查是否误触发、是否越权、结果能否复现。

不要塞进去：密码、Token、个人绝对路径、一次性需求和未经验证的破坏性命令。Skill 是做法，不是秘密仓库。

官方依据：Build skills

SessionStart→Pre / Post Tool→Stop→SessionEnd

适合

• 提交前固定校验
• 阻止误贴 Token
• 记录任务活动
• 结束时生成摘要

不适合

• 替代完整 CI
• 运行不可信脚本
• 把临时需求全写成 Hook
• 隐藏副作用

安全边界

新增或变更的非托管 Hook 必须重新审核和信任；先看脚本，再启用。

官方依据：Hooks

Branch prefix

给 Codex 新分支统一前缀，便于识别负责人或来源。

Merge / Squash

必须服从仓库合并策略，不要个人随意切换。

Always force push

默认关闭；确需改写历史也只用 --force-with-lease。

Draft PR

开发中默认开草稿，验证完成再转 Ready。

Review delivery

Inline 留在当前任务；Detached 适合独立、较长审核。

Commit / PR instructions

固定语言、标题和描述结构，减少每次重复提示。

界面依据：Desktop settings · Code Review；具体 Git 项以当前版本为准。

官方依据：Models

官方依据：Terminal · Browser · Code Review；Files 与 Side chat 入口以当前界面为准。