# 使用 Codex 开发

在正确的工作区、项目和分支中，让 Codex 完成定位、实现、测试、审查、发布与结果确认。

Codex 可以在选定的本地项目中读取和修改文件、运行开发命令并检查结果。可靠的开发任务需要明确目标、上下文、约束和完成标准，不能只给出一句模糊的功能描述。

## 从正确的目录开始

先完成[安装与配置开发环境](/development/environment-setup/)和[选择工作区并获取项目](/development/project-setup/)，然后从项目目录启动 Codex，或者在 ChatGPT desktop app 的 Codex 中打开该目录。

启动任务前至少确认：

```bash
baijimu workspace current
git status
git branch --show-current
```

工作区、项目目录或分支任一项不明确时，先停止写入并查清归属。

## 写清任务合同

推荐在第一条消息中说明四部分：

```text
目标：需要实现或修复的最终行为。
上下文：相关页面、目录、日志、接口或复现步骤。
约束：架构边界、不能改变的行为、安全要求和发布方式。
完成标准：必须通过的测试、构建、发布和真实功能验证。
```

复杂任务应先让 Codex检查代码、数据、日志和现有文档，说明根因及修复点，再进入实现。发布任务要明确包含“发布并验证正式入口”，否则本地构建成功不能代表已经上线。

## 使用 AGENTS.md 保存项目规则

把长期有效且属于仓库的规则写入 `AGENTS.md`，例如：

- 目录结构和各部分所有权。
- 安装、启动、测试、构建和发布命令。
- 代码规范、数据契约和安全边界。
- 禁止修改的对象以及需要人工确认的操作。
- 什么结果才算完成。

Codex 会从项目根目录向当前工作目录逐层读取适用的 `AGENTS.md`；更靠近当前目录的规则优先。一次性需求、临时范围和本次验收条件应留在当前任务中，不要写成永久规则。完整机制见 OpenAI 的 [AGENTS.md 指南](https://learn.chatgpt.com/docs/agent-configuration/agents-md)。

## 完成一次开发闭环

建议让 Codex 按以下顺序推进：

1. **定位**：读取项目规则、相关代码和真实错误，确认根因与责任边界。
2. **实现**：修改权威源码或版本化配置，不把工作区、项目、环境、主机或业务目录项硬编码进通用逻辑。
3. **验证**：运行相关测试、类型检查、构建和必要的本地功能验证。
4. **复核**：检查完整差异，确认没有无关改动、敏感信息或遗漏的失败路径。
5. **提交**：先运行 `baijimu project branch-policy get` 读取项目实际策略；`DIRECT` 项目快进直推 `main`，`PROTECTED` 项目推送个人分支并通过 `baijimu project merge` 更新 `main`。详见[项目分支策略](/concepts/projects/#git-main-写入策略)。
6. **发布**：按照交付对象的权威流程发布，不用另一类项目的流水线代替。
7. **确认**：从正式入口完成一次真实操作，并核对版本、日志和运行状态。

## 按交付对象发布

| 交付对象              | 开发与发布入口                                       |
| ----------------- | --------------------------------------------- |
| Web 前端            | [前端网站开发](/development/frontend-development/)  |
| Hosted Service 后端 | [后端应用开发](/development/backend-development/)   |
| 模块、平台应用和 Bundle   | [百积木平台开发](/development/bundle-development/)   |
| 本地 Connector      | [本地应用开发](/development/local-app-development/) |

这些对象可以共同组成一个产品，但源码、不可变版本、构建和发布状态彼此独立。某一部分发布成功不能替代其他部分的发布与验证。

## 安全与协作边界

- 不要把 token、API Key、Cookie、认证文件或生产数据粘贴到对话和仓库中。
- 不要因为本地目录名称相同就假设工作区、项目或环境相同。
- 修改依赖、数据结构、权限、计费或生产配置时，让 Codex 先说明影响和恢复方式。
- 使用 Codex 工作树并行开发时，每个任务使用独立分支，避免多个任务同时写同一工作树。
- 接受结果前检查差异和测试证据；高风险变更还要验证正式业务路径。

更多通用方法可参考 OpenAI 的 [Codex 最佳实践](https://learn.chatgpt.com/guides/best-practices)。