如果你经常用 Codex 干活应该能理解我的痛点每次开一个新项目第一步不是写代码而是先花十几分钟把环境理顺。要装依赖、要拷贝 OpenSpec 的规范模板、要挂载 Matt Pocock Skills、还要在 Codex 配置里告诉它项目规则。漏掉任何一步后续 AI 写代码的质量都会打折扣。所以我把这套项目初始化流程做成了一键脚本跑完直接得到一个可以开始干活的 Codex 工作区。这篇文章没有高深原理就是把我踩过的坑、脚本的设计思路、核心代码还有实测结果分享出来。适合已经在用 Codex或者准备切换到 Codex 驱动开发工作流的开发者。如果你被AI 写代码不稳定折腾过这篇应该对你有帮助——大部分不稳定其实不是模型不行而是你给了它一个没有上下文的空仓库。1. 为什么我要做这个一键脚本先说我的使用场景。我接手的项目通常不是从零开始的单文件 demo而是带数据库、带接口、带前端交互的全栈项目。过去我依赖 Cursor 或者直接在 ChatGPT 网页里粘贴代码后来切到 Codex 这类能直接操作本地文件系统的 CLI 工具效率提升非常明显。但随之而来的是初始化成本。这里的初始化成本不是指安装 Codex 本身而是指每次新仓库要重复搭建的 AI 工作上下文。手动流程大概是这样的先执行git init创建基础目录拷贝 OpenSpec 的模板目录包括项目背景、任务清单、规范文档把 Matt Pocock Skills 目录拉下来放到约定位置编辑 Codex 的配置文件让它在启动时加载这些规范再写一个AGENTS.md告诉 Codex动手之前先读 openspec 下的文件最后还要验证一下配置有没有成功否则等 Codex 跑起来才发现没读到规范又是浪费一轮对话。这一套流程前两次是新鲜的第三次开始就烦了。尤其是手动拷贝 OpenSpec 目录时经常漏掉某个子文件夹或者复制的是上一版旧模板。等 Codex 真开始干活它没读到规范按自己的理解去写代码方向直接跑偏。你以为是 AI 不听话其实是你没把规则喂给人家。所以我写了一个初始化脚本把上面所有步骤串起来。目前我已经在五个项目里用过这个流程每次都是同一套标准新建目录跑脚本确认输出然后就可以直接跟 Codex 说什么需求、让它读哪个 spec、按什么技能干活。脚本本身不到两百行但省下来的时间非常可观更重要的是它把可复现性还给了我。2. 三个核心组件到底在干什么在拆脚本之前有必要把这三个东西串一遍。因为很多人听说过 Codex但不一定清楚 OpenSpec 和 Skills 是怎么跟它配合的。我尽量用大白话讲清楚它们各自的定位。2.1 Codex能动手的 AI 编程代理Codex 是 OpenAI 推出的命令行编程工具可以把它理解成长在终端里的 AI 工程师。你不是在网页对话框里和它聊天而是让它直接面对一个真实目录。它能读文件、创建文件、执行 shell 命令遇到报错还能自己看错误信息继续改。这种工作方式比复制代码到网页里问自然得多因为 AI 真正看到了完整的项目上下文。不过工具再强也需要约束。Codex 默认状态下就像一个能力很强但没有入职培训的新人你让它写一个用户登录接口它可能直接造出你项目里完全不存在的目录结构或者用了一套和你现有代码风格完全不同的写法。这时候我们就需要给它入职手册也就是 OpenSpec 和 Skills 要做的事。2.2 OpenSpec把需求变成可验收的任务清单OpenSpec 是一套基于 Markdown 的规范约定。它不是什么神秘框架核心思想就是在项目里用一个专门目录存放所有任务说明书和验收标准让 AI 在开发前先读这些说明书而不是凭空猜测。我习惯把 OpenSpec 类比成软件工程里的 PRD 加技术文档。没有它需求只存在于对话上下文里窗口一关就没了。有了它需求被固化成文件Codex 每次启动都能重新读取。目录结构大致是openspec/ project.md # 项目整体目标与非功能性约束 tasks/ task-001.md # 一个任务的详细描述 task-002.md specs/ user-auth.md # 某模块的技术规范project.md是给 AI 的全局约束比如技术栈清单、代码风格、目录约定。tasks下的每个文件描述一个独立任务包含背景、要做的事、验收标准。当 Codex 开始干活前我们会在AGENTS.md里要求它先扫描 openspec 目录把相关任务读一遍再动手。这个先读后写的机制解决了 AI 编程最常见的跑偏问题。2.3 Matt Pocock Skills专家经验的结构化沉淀Matt Pocock 是 TypeScript 社区里很有影响力的开发者他整理的 Skills 集合可以理解成一批经过验证的最佳实践技能包。这些技能包本质上还是 Markdown 文件但内容非常聚焦比如如何写出类型安全的 React 组件、如何设计可维护的 API 层、如何在大型项目里做渐进式类型迁移。为什么叫 Skills因为大模型的 prompt 决定能力边界而这些技能包把某个领域的资深经验组织成模型容易理解、容易遵循的分步指导。当 Codex 遇到对应任务时它会读取这些技能文件像是拿到了一个专属导师的备忘录而不是靠模型训练时形成的泛泛印象。我把这三个工具组合在一起是因为它们互补得很干净Codex 提供执行手段OpenSpec 提供流程和验收标准Matt Pocock Skills 提供编码经验。缺了任何一块整个流程都会失衡。只有 Codex代码容易乱只有 OpenSpecAI 知道目标但可能用很烂的姿势实现只有 Skills懂很多套路但没有任务上下文。三件套放一起才是完整的 AI 驱动开发工作台。3. 一键脚本的设计思路与核心实现脚本不是简单把命令堆在一起而是要把初始化一套 AI 工作区这个目标拆成几个明确的子任务。我在动手写脚本之前先画了需求清单然后一步步实现。3.1 脚本要解决的四个问题第一个问题是环境检查。如果用户机器上根本没装 Codex或者没有 Git脚本后面跑得再欢也白搭。所以脚本开头要做一个干净的依赖检查缺什么就明确提示什么。第二个问题是目录骨架。新项目不需要一开始就有几十个文件夹但 openspec 目录、docs 目录、src 目录这些是 AI 后续干活的重要上下文位置初始化时必须创建出来。宁可先建空目录也比让 Codex 自己乱建强。第三个问题是模板文件生成。OpenSpec 的初始project.md、Matt Pocock Skills 的加载入口、Codex 的config.toml、AGENTS.md这些文件内容比较固定脚本可以直接写出来。这样用户不需要记住语法也不容易漏字段。第四个问题是验证反馈。脚本跑完不能只是看起来成功必须做几个检查比如确认 openspec 目录存在、确认 config.toml 能被 Codex 找到、确认 Skills 目录里有内容。如果哪一步失败立即输出错误而不是让用户带着残缺配置去开始工作。3.2 初始化后的目录结构长什么样我把脚本生成的目录结构固定成下面这样my-project/ ├── .git/ ├── AGENTS.md ├── config.toml ├── src/ ├── openspec/ │ ├── project.md │ └── tasks/ │ └── .gitkeep └── skills/ └── matt-pocock/ ├── typescript-best-practices.md └── react-hooks.mdAGENTS.md是 Codex 这类工具默认会读取的指令文件里面写清楚开发前先读 openspec/project.md再读 tasks 下的对应任务遇到 TypeScript 相关任务先查 skills/matt-pocock。config.toml则用来配置 Codex 的模型和运行参数让它知道加载哪些 Skill。你可能发现这个结构没有过度设计。这正是关键初始化脚本不应该替开发者做好所有事它只需要铺好一条轨道让 AI 后续能顺着轨道走。随着项目演进目录自然会变多但那应该是业务驱动的不是脚本强加的。3.3 关键代码逐段拆解脚本主体是 Bash我贴几个核心片段加上我当时的思考。先看环境检查部分#!/usr/bin/env bash set -euo pipefail # 检查必要命令是否存在 for cmd in git codex curl; do if ! command -v $cmd /dev/null 21; then echo 缺少依赖命令: $cmd echo 请先安装后再运行本脚本 exit 1 fi doneset -euo pipefail很重要。-e让脚本在遇到第一条失败命令时退出-u避免变量未定义pipefail防止管道中的错误被忽略。这种防御式写法让脚本在出错时不会一路狂奔非得等最后才爆出奇怪问题。然后是目录创建和模板生成mkdir -p src mkdir -p openspec/tasks mkdir -p skills/matt-pocock # 生成 project.md 模板 cat openspec/project.md EOF # 项目背景 在这里描述项目要解决什么问题 # 技术栈 - 语言: TypeScript - 运行时: Node.js - 框架: 待定 # 项目约定 - 使用 pnpm 管理依赖 - 所有新功能必须附带测试 - 模块设计遵循单一职责原则 EOF这里用 heredoc 而不是直接echo是为了保持多行内容规整。注意我用的是EOF带引号这样 Bash 不会展开里面的$符号避免模板内容里如果有$TEXT这种变量被误替换。Skills 目录的生成更有意思。如果用户机器上已经有 Matt Pocock Skills 的仓库脚本会把它复制过来如果没有脚本会先尝试用git clone拉一份。这段逻辑我写成SKILLS_SOURCE${SKILLS_SOURCE:-$(pwd)/skills/matt-pocock} if [ ! -d $SKILLS_SOURCE ]; then echo 未找到本地 Skills 目录尝试拉取远程仓库... git clone --depth 1 https://github.com/some-example/matt-pocock-skills.git $SKILLS_SOURCE fi--depth 1是为了只拉最新记录速度快很多。注意我把远程地址写成了示例实际使用时应该换成 Matt Pocock 公开的 Skills 仓库地址。这个环节是你真正构建脚本时需要确认的不要照抄我的占位 URL。3.4 让 Codex 在每次任务前自动读规范光有文件还不够必须让 Codex 知道这些文件的存在。我一般用两种方式双保险。第一种是在项目根目录写AGENTS.md# 项目级指令 你必须先阅读 openspec/project.md 了解项目全局。 开始任何任务前必须阅读 openspec/tasks/ 下对应任务描述。 如果任务涉及 TypeScript 或 React必须阅读 skills/matt-pocock/ 下的相关文档。AGENTS.md会被当前目录及子目录下的 AI 工具自动发现。Codex 运行时会把它作为系统提示词的补充相当于给每个会话都注入了项目规则。第二种是在 Codex 的配置中显式引导。我在config.toml里加上一段 instruction[project] model gpt-5 instruction_file AGENTS.md实际上不同版本的 Codex 配置字段名可能有变化但原则一致让 AI 读到项目规则文件。你要做的就是把这些配置放进初始化脚本里保证每次生成的项目都是同样的基础配置。4. 一次完整实测从空目录到 AI 可干活理论说了这么多不如直接跑一次看效果。4.1 前置环境准备我测试用的机器是 macOS提前装好了 Homebrew、Git、Node.js LTS以及 Codex CLI。Codex 的安装方式很简单一条 Homebrew 命令就能装完装完以后确认一下版本codex --version这一步确认 pass。工具没问题后我打开一个全新的空目录准备跑一键脚本。4.2 执行一条命令我把脚本命名为init-ai-workspace.sh放在个人工具目录里然后在新项目目录执行bash ~/tools/init-ai-workspace.sh my-awesome-project脚本运行时的输出如下我精简了一点检查依赖... git ok, codex ok, curl ok 创建目录结构... done 写入 openspec/project.md... done 写入 openspec/tasks/... done 挂载 Matt Pocock Skills... done 写入 AGENTS.md... done 写入 config.toml... done 初始化 Git 仓库... done 全部完成当前项目已具备 AI 驱动开发环境。整个流程耗时不到 5 秒主要是git clone拉 Skills 仓库时稍微等了一下。如果本机已经有克隆好的 Skills 缓存这个时间还能更短。4.3 验证 OpenSpec 是否生效只看到输出还不够我马上用一个简单任务做验证。在 openspec/tasks/ 里新建一个add-ping-api.md内容是实现一个 GET /ping 接口返回 JSON{ message: pong }要求用 TypeScript 编写。然后启动 Codexcodex 请根据 openspec/tasks/add-ping-api.md 实现任务Codex 的响应让我放心它先列出了AGENTS.md的内容然后主动找到 openspec/tasks 目录读取了任务描述又从 skills/matt-pocock 里翻出 TypeScript 相关 skill最后才声称我现在开始写代码。在这个过程里它没有自作主张引入数据库没有把目录乱改成别的结构整个实现路径跟任务描述高度一致。这就是规范文件起作用了。4.4 对比手动初始化 vs 一键初始化我做了一个简单的时间统计。手动初始化一个新项目按我之前的习惯大概需要思考目录结构2 分钟创建文件夹1 分钟复制 OpenSpec 模板并修改项目名3 分钟去 Skills 仓库找对应文档并复制4 分钟手动写AGENTS.md和配置文件3 分钟检查有没有遗漏2 分钟合计 15 分钟上下。而且这个过程中很容易因为复制了错误的模板导致后续返工。一键脚本把时间压缩到了 5 秒左右还顺带做了一轮环境检查出错概率大大降低。对高频开新项目的开发者来说这个收益是可以量化的。5. 常见问题与排查建议脚本写出来不是一劳永逸的我在使用中收集了不少问题列成速查表方便你对照。5.1 脚本运行时报 command not found最常见的原因就是本机没有安装 Codex 或者 Git。脚本开头的环境检查会直接提示缺哪个命令。这种情况先安装依赖再重新跑。注意如果用的是 macOSGit 通常随 Xcode Command Line Tools 一起装但 Codex 需要单独安装。另外有些用户把 Codex 装到了非标准路径比如 Homebrew 在 Apple Silicon 上是/opt/homebrew/bin如果这个路径不在PATH里即使安装成功也会报 command not found。我习惯在脚本里加一句兼容处理export PATH$PATH:/opt/homebrew/bin:$HOME/.local/bin当然这不是万能的还是要以本机实际环境为准。5.2 配置写好了但 Codex 不读规范如果你发现 Codex 运行时没有读取AGENTS.md最常见的原因是文件位置不对。AGENTS.md必须放在你启动 Codex 时的当前目录或者放在项目的根目录并且 Codex 配置文件里没有关闭自动读取。你可以通过启动时的日志确认它是否加载了这个文件。另一个坑是文件名大小写。有的工具约定是AGENTS.md如果你不小心写成了agents.md或者Agents.md某些版本的工具不会识别。统一使用大写AGENTS.md最稳妥。5.3 Skills 没有生效如果 Codex 明明看到了 Skills 目录但在执行任务时没有主动查阅很大原因是你的AGENTS.md指令不够明确。不要只写一句使用 TypeScript 最佳实践而要写如果任务涉及 TypeScript必须先阅读 skills/matt-pocock/typescript-best-practices.md。显式路径比模糊描述可靠得多。还有一个细节Skills 目录里如果有大量无关文档反而会稀释模型注意力。我通常只在初始化时复制与项目技术栈最相关的几份 skill而不是把所有技能文件全塞进去。这样既减少了 token 占用也让指令更聚焦。5.4 重复运行脚本把已有文件覆盖了脚本刚写出来的版本会在重复运行时直接把openspec/project.md覆盖掉导致我之前写好的项目背景丢失。后来我加了一个保护逻辑if [ -f openspec/project.md ]; then echo 检测到已存在 openspec/project.md跳过覆盖 else # 生成模板 fi更稳妥的做法是提供--force参数只有在显式指定时才覆盖。我现在用的版本默认跳过已有文件避免误伤。5.5 Codex 报错 401 或 403这基本上跟脚本无关多半是 API Key 没配好。Codex 会读取环境变量OPENAI_API_KEY或相关配置文件。你可以在终端里执行env | grep OPENAI检查环境变量是否存在。如果没设置按官方文档把 key 配好再启动。有些情况下报错是因为模型权限或者账号额度限制这种需要到账号后台确认。脚本能帮你的只有环境检查没法替你做账号层面的验证。5.6 Windows / Git Bash 兼容性我平时主要在 macOS 上开发但这个脚本我也在 Windows 的 Git Bash 环境里跑过。有两个坑一个是command -v在 Git Bash 下行为正常但curl可能不是系统自带的最好确认已经在 PATH 中。另一个是路径分隔符问题如果脚本里写死了 Unix 风格路径在 Windows 上可能会踩坑。我的建议是Windows 用户尽量先处理好环境和路径或者在 WSL 里运行脚本体验更顺滑。最后再分享一个小技巧脚本写完以后我建议大家把AGENTS.md的生成逻辑做成独立的函数因为它是整个流程中影响最大、也最容易调整的部分。初始化脚本只负责搭骨架而AGENTS.md决定了 Codex 在这个项目里的职业素养。你觉得某个项目里 AI 表现特别好多半是这个文件写得好这时候把它复制到新项目价值比别人给你推荐什么神级 prompt 都大。我现在这个一键脚本已经迭代了三个版本最初只有二十多行后来逐步加入环境检查、目录保护、Skills 缓存已经变成一个稳定可靠的工具。如果你也常用 Codex 开新项目我强烈建议复制我这个思路做一套属于自己的初始化脚本。不用一开始就追求功能全先把最常做的几个动作串起来后续哪一步出了问题再往里面补检测和容错。用着用着你就会发现AI 编程真正省下的时间有一部分其实来自这些不起眼的自动化。