开始Vibe Coding之前的准备工作

在开始工作前，还有一些配置和工具推荐准备好

安装OpenSpec

Spec-driven development (SDD)是当前Vibe Coding的一大趋势，最常用的两个SDD工具是spec-kit和OpenSpec。本文档系列中将使用OpenSpec：

npm install -g @fission-ai/openspec@latest

全局配置

Codex的全局配置写在~/.codex/config.toml中，有一些值得打开的功能

网络搜索

[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true

网络搜索功能是默认关闭的，建议打开。打开后Codex可以从网络上搜索信息，当希望Codex去搜索时可以主动在prompt中写关键字search on web。

默认模型以及reasoning effort

model = "gpt-5.2"
model_reasoning_effort = "xhigh"

可以在config.toml中指定默认模型和reasoning effort，社区当前普遍认同GPT 5.2 + extra high reasoning是表现最好的组合，但需要注意这个组合的速度也是最慢的。需要其他模型时可以进入Codex session之后用/model命令手动切换。

MCP Server

MCP也需要写在config.toml中，格式大致类似于

[mcp_servers.docfork]
command = "npx"
args = ["-y", "docfork"]

准备Workspace

Git & OpenSpec init

在使用包括Codex在内的任何AI工具时都推荐在Git仓库中进行，以方便随时回滚代码：

mkdir <repo>
cd <repo>
git init -b main

与此同时，OpenSpec也需要init操作：

openspec init

此命令会进入交互式界面，按提示选择Codex作为AI工具并回车。命令完成后会显示一大段OpenSpec文档，可以暂时忽略。

AGENTS.md

简言之AGENTS.md是给AI准备的README，不同于README.md往往向人类介绍和解释如果使用本项目，AGENTS.md向AI规定在开发本项目时所有需要注意的点。其原理为Codex在新建Session时会自动寻找并读取AGENTS.md的内容到上下文中：

  1. ~/.codex/AGENTS.md，这个文件中的提示词对所有Session生效（Global-level）
  2. <repo>/AGENTS.md，这个文件中的提示词对这个项目下的所有Session生效（Repo-level）
  3. <repo>/**/AGENTS.md，这个文件中的提示词仅在处理这个路径时生效（Dir-level）

这三种类型中，第二种使用得最频繁，所以在新建完Git仓库后，可以马上开始编辑AGENTS.md，推荐描述以下内容

  1. Project Description：向AI概述这个项目的目标和大致思路
  2. Environment：向AI描述这个项目使用什么管理环境（conda, uv, mamba, etc.）
  3. File Structure：向AI描述项目的文件树，否则AI可能会随意构建使得可读性很差
  4. Behavior：向AI规定一些行为准则，使得工作流程更顺畅（例如告诉AI不要自动commit，否则AI可能会过于频繁地commit，又比如告诉AI主动维护一个文档方便之后查阅）

下面分享一个模板，可以根据自己的需求做更改：

# Project Description
This project aims to 1. Create a webpage to interactively visualize a 3D RGB point cloud, 2. Use VGGT to convert the images to point clouds, 3. Build another interactive webpage to trim, move, rotate, scale and merge the generated point clouds with the original point cloud.

# Python Environment

This project uses `mamba` to control the python environment. The environment name is "ENV-NAME". The `mamba` command and the environment has already been installed and created. Whenever a new package is required, a prompt should be sent to the user asking for manual installation. Never install new packages automatically to the environment. However, the `env.yaml` (described below) can be automatically updated to include new packages. In terms of conda channels, `conda-forge` is always preferred than other channels. However, there are certain packages that are much easier to deal with through pip, such as `cv2` (`opencv-python` in pip). For such packages, move them to the pip part in `env.yaml`. The machine also has a GPU, so whenever possible, install the cuda version (e.g. PyTorch).

# File Structure

repo_dir/
├── .gitignore # A common ignore file for python projects plus customized items for this project
├── README.md # A README that briefy describes this project, its installation and usage
├── env.yaml # A conda environment yaml
├── data/ # Data used for this project, ignored in git
├── datasets/ # Datasets for machine learning (e.g. PyTorch dataset class, Lightning datamodule class, or anything else similar)
├── models # Machine learning models (e.g. PyTorch networks, Lightning lightning_module, or anything else similar)
├── docs/ # Documentation for this project
├── submodules/ # Submodules (other existing git repo) to be used for this project
├── scripts/ # Scripts of the projet
├── outputs/ # Outputs of the project, ignored by git
└── <OTHERS> # To be specified in the future

# Documentation

Within source codes, only put short and necessary comments. Instead, maintain a folder of documentation that:
- Describes the purpose of the codes, the high-level ideas of how they are implemented.
- Records the necessary details which can lead to confusions if missing.
- Gives a few useful examples. For scripts, these should be examples to call them in the command line. For code snippets, these should be examples to use and refer to them in other codes.
The structure of documentation are dynamic, one documentation file can focus on one source code file or multiple source code files, depending on the importance of the specific part. The golden standard of documentation is to let a new comer to quickly be ready for development.

# Git

Only commit the changes when the user explicitly asks so.

尤其建议加入#Documentation段，因为在使用Codex中不可避免会新建Session，这也意味着上下文丢失，让AI自我维护文档有助于让新Session快速回到开发轨迹上去。

OpenSpec配置

写完AGENTS.md之后，还需要配置OpenSpec，这一步其实是AI自己完成的，只需要开启Codex Session并输入一下内容即可：

Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions. More details can be found in `./AGENTS.md`

init commit

最后，告诉AI完成初始提交：

create a proper `./.gitignore` and `./README.md`, then commit the changes.

Codex调用GPU

Codex可以自动debug代码，当涉及到AI相关代码无法避免要调用GPU，然而Codex默认的沙盒模式无法访问GPU。此时需要给Codex更高的权限：

codex --yolo
codex resume --yolo

可以在开启或者重回session时加入--yolo参数，此时Codex可以调用GPU。但需要注意Codex有过高权限也有可能会误操作，例如删除你的文件，所以建议只在必要的时候使用！