企业官网建设流程全解析

AI 编程工具进入日常开发后的第一个变化，是“前端提效”不再等于“自动补全代码”。以 OpenAI Codex 为代表的编码代理能直接读仓库、改文件、执行命令，而 Spec Coding 则把需求文档变成开发规格，两者结合后，一个全栈工程师可以在不增加人手的情况下，跑完整套企业团队开发流程。这篇文章从 Codex CLI 的安装开始，讲清楚 Spec 文件怎么写、Codex 怎么按 Spec 实现前端和后端、测试和审查环节怎么验收，最后给出常见的报错排查表和可以复用的团队规范清单。

文章面向两类读者：一类是已经用过 AI 工具、但觉得“AI 写出来的代码不可控”的前端和全栈开发者；另一类是刚接触 Codex CLI，想知道它和自动补全工具有什么区别的工程师。读完之后，你可以直接在自己的项目里复刻这套流程：一个需求、一份 Spec、几句话描述任务、一批小步提交，然后像评审团队代码一样评审 AI 的产出。

1. 先分清 AI 补全、AI 编码代理与 Spec Coding 三件事

1.1 Codex 解决的是“从需求到改动”的完整链路

传统 AI 编程插件解决的是“写某一行、补某个函数”的问题。使用者仍然要自己决定改哪个文件、调用哪个接口、怎么组织代码结构。Codex 的定位不一样，它是一个编码代理（agent）：给它一个任务描述，它会自己规划步骤、读取项目文件、修改多处代码、执行命令，并根据执行结果调整下一步。

Codex CLI 是它在终端环境下的载体。安装完成后，你可以用两种方式使用它：

• 交互模式：在终端里输入codex进入对话，它会展示思考过程、准备改哪些文件、执行什么命令，并由你确认是否继续。
• 非交互模式：用codex exec一次性传入任务描述，适合批量执行和接入脚本。

这里要注意，Codex 并不是“全能免检”的。它依然会读错文件、写错逻辑、在边界条件上翻车。它真正的价值是把“查代码、改代码、跑命令、看结果”的循环自动化，让人从机械操作里退出来，把精力放在判断和验收上。

1.2 Spec Coding 的 Spec 到底指什么

Spec Coding 里的 “Spec” 指 specification，即规格说明。它不是某个固定框架，而是一类工作方式的统称：在让 AI 写代码之前，先用一份结构化的 Markdown 文档，把需求边界、数据模型、接口契约、页面行为、验收标准写清楚。

很多第一次接触这个概念的人会把“Spec”和测试框架里的 spec 文件搞混。在 Jest、Mocha 这类测试工具中，xxx.spec.js表示测试用例文件；在 Spec Coding 里，SPEC.md表示项目或功能的开发规格。两者都强调“描述清楚再执行”，但用途完全不同。

为什么 AI 场景下特别需要 Spec？因为大模型天然擅长“续写”。你只给它一句“做一个任务看板”，它大概率会自己发挥：加账号系统、加拖拽、改数据库表结构、换一套你不认识的状态字段。这些发挥在真实项目里往往带来返工。Spec 的作用就是把“自由发挥”约束在人类认可的范围里，告诉 AI 哪些要做、哪些明确不做、字段叫什么、接口返回什么。

1.3 单人跑团队流程的本质：把角色变成文档和检查点

企业团队开发流程可以简化成：需求评审、架构设计、编码、测试、代码审查、发布。单人状态下，这些角色没有消失，只是需要一个人用不同方式完成。Codex 加 Spec 的组合，正好把每个角色转成可执行产物：

这套流程能不能跑通，关键不在 Codex 的模型能力，而在于你愿不愿意花时间把“人脑里的需求”写成“文件里的 Spec”。否则，AI 的每次执行都像一次没有评审的临时外包，质量全凭运气。

2. 环境准备：安装 Codex CLI，先把一条最小命令跑通

2.1 环境检查和前置依赖

Codex CLI 本身是 npm 包，运行时需要 Node.js。不同版本对 Node 版本的要求略有差异，建议先确认本机版本，再参考官方文档安装。常见项目里可以按这个组合准备：

先运行下面的命令确认基础环境没有问题：

node -v npm -v git --version

常见项目里如果npm -v命令提示找不到，通常是 Node 没有正确加入 PATH。这个问题越早处理越好，否则后续安装 Codex 时会出现一连串不明报错。

2.2 安装 Codex CLI

确认 Node 环境正常后，使用 npm 全局安装：

npm install -g @openai/codex

安装完成后，立即确认版本号是否正常打印：

codex --version

如果输出类似于codex 0.x.x，说明安装成功。如果提示command not found: codex，优先检查 npm 全局 bin 目录是否在 PATH 中。在 Linux 或 macOS 上使用 Node 版本管理器时，还需要确认当前 Node 版本对应的是哪一套全局目录。

这里有一个环境差异：部分公司内网使用私有 npm 镜像。如果安装源不稳定导致依赖下载失败，先检查 npm registry 配置，确认能连上可用的 npm 源，再重试安装。

2.3 登录与初始配置

Codex CLI 第一次使用前需要登录账号：

codex login

执行后终端会显示一个跳转链接，在浏览器中完成授权，token 会保存在本机配置目录里。需要注意，token 属于敏感信息，不要提交进 git 仓库。

Codex 默认会使用当前账号可用的模型。不同时期、不同账号可用的模型可能不一样，执行codex --help或codex exec --help可以查看当前版本支持的参数。有些团队希望通过配置文件把 Codex 接入其他模型服务，比如 DeepSeek 等模型端点。这类接入需要 CLI 支持对应的模型协议和自定义 endpoint 配置，落地前先查阅你当前版本的官方文档，确认支持之后再改配置，不要直接照搬网上的旧教程。

2.4 用最小任务验证完整链路

登录成功后，先不要急着接真实项目。建一个临时目录，跑一个最小任务，验证“读需求、改文件、执行命令”的闭环是否正常：

mkdir codex-smoke-test cd codex-smoke-test git init

然后执行一个最简单的任务：

codex exec "创建一个 hello.js，文件内容只保留 console.log('codex ok')，然后运行它"

正常结果是在终端看到：

codex ok

这一步如果跑通，说明本机的登录状态、网络连通性、shell 执行权限、仓库识别都没有问题。如果这一步就报错，后面接真实项目只会更难排查。

这里还要提醒一个刚开始容易踩的坑：如果你在非 git 仓库目录中运行codex exec，某些版本会提示需要先初始化 git 仓库，或者要求确认是否在非仓库目录继续。解决方案很简单，一个是先git init，另一个是查看帮助参数是否有--skip-git-repo-check之类的开关。但真实项目中不建议跳过仓库检查，因为 git diff 是你审查 AI 改动最重要的依据。

3. 用 Spec 文件把需求锁死，Codex 才不会自由发挥

3.1 Spec 文件里应该包含哪些内容

一份能指导 Codex 开发的 Spec，至少要包含以下内容：

1. 背景与目标：这个功能解决什么问题，直接写清楚。
2. 范围与不做清单：明确本期做什么、明确不做什么。很多人忽略“不做清单”，这是 AI 自由发挥的头号原因。
3. 用户故事：从使用者角度描述核心场景。
4. 页面清单或路由清单：前端项目必须写清楚有哪些页面、每个页面放什么模块。
5. 数据模型：字段名、类型、长度、是否必填。
6. API 契约：方法、路径、请求体、响应体、状态码。
7. UI 行为：点击、跳转、加载、失败提示分别怎么处理。
8. 验收标准：能逐条验证的完成条件。

这八类信息本质上是在“替 AI 做决策”。你不写字段名，它就自己发明字段名；你不写状态码，它就自己选状态码；你不写失败交互，它就只实现“成功路径”。

3.2 一个最小全栈项目的 Spec 示例

下面用一个“团队任务看板”作为最小示例。技术栈在示例里采用 React 加 Vite 做前端、Express 加 SQLite 做后端，方便本地跑通。实际项目请按自己的技术栈替换描述。

# 团队任务看板（最小全栈版本） ## 背景 团队需要一个简单看板来管理开发任务，支持创建、移动和标记完成。 ## 用户故事 - 作为成员，我可以新增任务，记录待办事项。 - 作为成员，我可以把任务从未开始移到进行中、已完成。 - 作为成员，我可以查看任务列表，并按状态筛选。 ## 范围 本期只实现 Web 端，不包含账号体系、权限管理、多人实时协同、拖拽排序。 ## 页面清单 1. 看板页 `/`：显示三列，分别是未开始、进行中、已完成。 2. 新建任务弹窗：输入标题、描述、负责人。 ## 数据模型 task - id: string(uuid) - title: string(1-100) - desc: string(0-1000) - status: enum('todo','doing','done') - assignee: string(0-50) - created_at: datetime - updated_at: datetime ## API 契约 - GET /api/tasks -> 200 { "data": Task[] } - POST /api/tasks body { title, desc, assignee } -> 201 Task - PATCH /api/tasks/:id body { status } -> 200 Task ## UI 行为 - 新增成功后刷新列表，弹窗关闭。 - 状态切换后列内即时更新。 - 接口失败时显示错误提示，不刷新页面。 ## 验收标准 1. 三列看板能正确展示不同状态任务。 2. 新增任务后标题出现在“未开始”列。 3. 移动任务后状态接口返回正确。 4. 后端重启后数据仍存在（SQLite 落盘）。

核心在于两条：第一，“范围”里明确写了不做账号和拖拽，AI 就不会把问题复杂化；第二，“API 契约”写死了路径、方法和返回结构，前后端联调时不会出现一个返回data、一个读取list的尴尬。

3.3 把 AGENTS.md 变成团队章程

Spec 描述的是“某一个功能要做什么”，AGENTS.md 描述的是“这个项目里所有代码必须遵守什么”。Codex 会在处理项目时读取这类项目级约定文件，把全局约束注入每次会话。

继续用上面的项目举例，可以在仓库根目录创建docs/AGENTS.md：

# 项目约定（AGENTS.md） - 技术栈：React 18 + Vite + Express + SQLite。 - 每个功能开发前必须读取 docs/SPEC.md。 - 修改接口必须同步更新 SPEC.md 中的 API 契约。 - 新增依赖前先说明原因，并在 commit message 中记录。 - 时间字段统一使用 UTC ISO 8601 字符串。 - 代码通过 eslint 和 tsc 检查后再提交。

有了这份文件之后，执行 Codex 任务时，可以在描述里显式指定读取顺序：

codex exec "先读取 docs/SPEC.md 和 docs/AGENTS.md，然后按规格实现任务接口"

一个常见的坑是：把 Spec 写在对话里，而不是写在仓库文件里。对话上下文会被后续大任务冲掉，每次新会话都要重新粘贴，既浪费 token 又容易漏内容。把它放进仓库，Spec 就变成项目资产，所有会话、所有协作者都能复用。

4. 单人跑通企业团队流程：从拆解到验收的完整闭环

4.1 设计仓库结构，模拟团队分工

把团队流程落到单人操作，首先要有干净的仓库结构。以任务看板为例，可以这样组织：

team-kanban/ ├── docs/ │ ├── AGENTS.md │ └── SPEC.md ├── apps/ │ ├── web/ # React + Vite 前端 │ └── server/ # Express 后端 ├── .gitignore └── README.md

目录本身就在模拟团队分工：docs 目录对应需求评审和架构评审的产出，apps/web 是前端开发的工作区，apps/server 是后端开发的工作区。单人操作时，你不再需要“开会”来对齐，只需要保证这些文件的内容一致。

4.2 把需求拆成可验收的小任务

不要一次让 Codex 完成整个看板。任务拆得越小，diff 越容易审查，回滚越容易，模型上下文也不会被撑爆。上面的 Spec 可以拆成五个任务：

1. 初始化仓库结构和基础依赖。
2. 在 apps/server 中实现 SQLite 初始化和任务接口。
3. 在 apps/web 中实现看板三列页面。
4. 联调新增和状态移动。
5. 跑测试、补边界条件、清理报错。

每个任务都要有明确产出和验收方式。任务 2 的产出是接口能通过 curl 验证，任务 3 的产出是页面能在浏览器打开并展示接口数据。没有验收方式的拆解不算拆解。

4.3 让 Codex 按任务批量执行

对任务 2，可以这样执行：

codex exec "读取 docs/SPEC.md，在 apps/server 中实现 Express 应用、SQLite 初始化以及任务接口，按 API 契约返回数据"

如果项目里已经配置好沙箱或自动批准策略，也可以传入自动执行参数。具体参数名以你当前版本的codex exec --help输出为准，因为 Codex CLI 的参数一直在演进。自动执行意味着 Codex 会自己决定运行命令、自己修改文件，这对学习环境的快速原型很友好，但不要在真实主干分支上直接使用，应该在独立分支里跑。

真实项目里的推荐写法是：先在本地开一个功能分支，在分支上执行 Codex，每一步改动都保存为一次提交，这样中途任何一步不满意，都可以回退到最近的提交点。

4.4 人工检查点：跑测试、看 diff、调接口

每个任务完成后，至少保留一个“人工检查点”。Codex 说完成了不算完成，必须验证。

后端任务完成后，启动服务并调接口：

cd apps/server npm run dev

另开一个终端验证：

curl http://localhost:3000/api/tasks

预期输出：

{"data":[]}

然后再看改动范围：

git diff --stat git diff

检查点要回答三个问题：接口是否和 SPEC.md 里的契约一致；字段名、状态码是否符合预期；有没有引入无关改动。前端任务完成后，还要额外检查生产构建是否通过，不能用“开发模式能打开页面”代替：

cd apps/web npm run build

这里最容易犯的错误是让 Codex 自己完成主线合并。合并到主干、推送到远端、打标签这些操作应该由人来执行。AI 可以写代码，但“哪些改动进入主干”是工程决策，应该保留在人工手里。

4.5 用 Codex 做代码审查，但结论要人来定

企业流程里最难在单人模式下复刻的是代码审查。其实可以让 Codex 充当第一轮 reviewer，输出问题清单，再由你判断哪些需要改。

在功能分支上执行：

codex exec "请审查当前分支相对 main 的 git diff，重点检查错误处理、数据校验、安全风险，输出问题清单和修改建议，不要直接修改代码"

这一步的价值在于换一个视角看自己刚写完的改动。Codex 通常能发现空指针风险、未处理的异步错误、SQL 拼接隐患、缺少长度校验等问题。

需要注意，Codex review 的结论不能全信。它会提出一些似是而非的建议，也会漏掉业务语义上的问题。正确的处理方式是：把问题清单逐条对照 Spec 判断，需要改的让 Codex 再出一轮修改，不需要改的记录下来说明原因。这个“讨论”过程就是评审记录，写进 merge request 描述里，整个流程就和团队开发很像了。

5. 高频报错与排查路径：从日志反推原因

5.1 终端和编辑器常见的报错

Codex 使用过程中最影响效率的不是模型能力问题，而是环境配置问题。下面把高频报错按现象、原因、检查方式、处理建议整理成表：

其中unable to locate the codex cli binary这条非常典型。它通常不是 Codex CLI 本身的问题，而是 IDE 插件在启动时找不到可执行文件。解决的关键是让插件知道 CLI 安装在哪里。如果插件设置里有路径选择项，直接指向codex可执行文件位置；如果支持环境变量，把路径配置好再重启插件。

5.2 按优先级排查的固定顺序

遇到报错时，按下面的顺序排查，效率最高：

1. 环境问题：Node、npm、PATH、CLI 路径是否正常。
2. 登录问题：token 是否过期，重新执行codex login。
3. 网络问题：模型服务地址是否可达，网络出口是否正常。
4. 仓库问题：是否在 git 仓库内，工作目录是否正确。
5. 上下文问题：任务是否过大，历史是否过长。
6. 额度问题：账号是否还有可用额度。

大部分报错都集中在 1 到 3 步。不要一上来就怀疑模型能力，先拿一条最小命令跑通，再逐步加复杂度。

5.3 长任务的正确打开方式

一个频繁出现的问题不是报错，而是“代码写了但不符合预期”。根本原因通常是任务太大。一次让 Codex 实现完整系统，它会在中途丢失前文约束，漏掉边缘条件，甚至做出自相矛盾的改动。

正确做法是把大任务拆成小时段会话。一个会话只做一件事，比如“新增任务接口”“调整列表加载状态”“补充日期格式化”。每个会话开始时，重新让 Codex 读取 SPEC.md 的相关小节。这样做虽然看起来多花了一些时间，但每条改动都可控、可回退、可审查。

6. 沉淀团队规范：一套可以复用的落地清单

6.1 新功能上线前的逐项检查清单

这套流程跑过几次之后，把经验固化成检查清单，新功能照着走就行：

1. 需求是否已经写入docs/SPEC.md，包括背景、范围和验收标准。
2. “不做清单”是否明确，避免 AI 扩大实现范围。
3. docs/AGENTS.md是否包含本功能需要遵守的技术栈和代码约定。
4. 是否为功能创建了独立分支，而不是直接在主干上开始。
5. 每个任务都拆成可验收的小步，Codex 每完成一步就提交一次。
6. 每个任务完成后都人工查看 git diff，确认没有无关改动。
7. 后端接口用 curl 验证，前端页面用生产构建验证。
8. 让 Codex 对分支 diff 做一轮 review，问题清单逐条确认。
9. 数据库或数据结构变更是否有回滚方案。
10. 合并到主干由人工完成，评审记录保留在 merge request 描述里。

这份清单可以直接改成项目的docs/RELEASE_CHECKLIST.md，每次发布前过一遍。

6.2 学习环境与生产环境的差异

很多人刚开始实践时，会把学习环境里“全部自动、不检查”的习惯带到真实项目里。学习环境怎么快怎么来，生产环境则要加保障：

生产环境里最重要的一条是：不要在生产数据或真实密钥存在的工作目录里直接跑 Codex 的自动执行模式。AI 在自动化过程中会运行命令，一旦命令涉及线上环境，后果很难预估。

6.3 进一步扩展的方向

这套流程跑熟之后，可以往三个方向扩。

第一个方向是把 Codex 接进 CI，让它在 pull request 创建时自动执行 review，输出问题清单到评论里。这样团队里的其他人也能复用你的审查模板。

第二个方向是给 Spec 建立版本管理。Spec 变更和代码变更一样要有记录，至少要能在 merge request 里看出“这次需求改了什么、为什么改”。否则有一天需求变了，代码和文档对不上，AI 就会基于过时 Spec 再次生成错误实现。

第三个方向是尝试多模型接入。Codex CLI 是否能接入 DeepSeek 等其他模型，取决于当前版本是否支持自定义 endpoint 和模型协议。落地前先看官方文档，确认支持后再配置。注意，不同模型的代码质量、工具调用能力和上下文利用方式差异很大，切换模型之后要重新跑一遍验收清单。

回到最初的技术判断：Codex 提供的是执行能力，Spec Coding 提供的是执行边界。单人跑团队流程不是靠“让 AI 一口气干完所有事”，而是靠“把团队规则写成文档、把大任务拆成小步、把每次结果都审查一遍”。如果你的项目里有任何一个反复改不对的功能，不妨先把它写成一页 Spec，再交给 Codex 试一次。从一个小功能开始，逐步积累自己的 Spec 模板、审查清单和提交约定，这套流程就会从“实验玩法”变成真正可复用的工程标准。