ZFK

AI GUIDE

新项目 Codex 启动最佳实践

创作时间
2026/05/20
字数
8,353
阅读时间
17 分钟

一套可复用的新项目启动手册：把目标、调研、仓库骨架、验证、文档和安全边界先立起来，再让 Codex 小步推进。

AI 原生项目启动工作台：笔记、知识网络、CI 流程和云端协作

用途

用途配图

这份文档是以后新建项目时给 Codex 的通用启动手册。

它不是某个项目的百科全书，而是一套可复用的工程约束：让 Codex 先理解目标、调研现实、搭出可回顾的仓库骨架，再进入小步实现、验证、提交和 PR。

适用场景：

  • 从 0 创建一个新软件项目。
  • 从一个想法开始，先调研竞品和技术路线，再决定是否写代码。
  • 把一个临时脚本逐步升级成可维护仓库。
  • 多仓库协作时复制同一套工程文化。

一句话原则

一句话原则配图

人类掌舵，Codex 执行；调研先于代码，文档先于遗忘，验证先于扩大。

启动顺序

启动顺序配图

新项目默认按下面顺序推进：

  1. 明确目标和非目标。
  2. 做资料、竞品和技术路线调研。
  3. 写项目地图和执行计划。
  4. 建仓库骨架和最小运行环境。
  5. 实现最小可验证闭环。
  6. 补测试、lint、脚本和文档同步。
  7. 走分支、commit、PR、验收、合并。

不要一上来就让 Codex 写完整系统。第一轮的目标是把方向、边界、目录、验证方式和下一步变清楚。

推荐目录结构

推荐目录结构配图

project-root/
  AGENTS.md
  README.md
  ARCHITECTURE.md
  PROJECT_PLAN.md
  ROADMAP.md
  docs/
    WORKFLOW.md
    design-docs/
      index.md
    product-specs/
      index.md
    exec-plans/
      active/
      completed/
    references/
    research/
      competitors/
      technical/
  scripts/
  tests/
  src/
  workspace/
  .gitignore

目录职责：

  • AGENTS.md：给 Agent 的短地图，控制在可快速阅读的范围内。
  • ARCHITECTURE.md：系统边界、模块地图、依赖方向和非目标。
  • PROJECT_PLAN.md：阶段规划和当前优先级。
  • ROADMAP.md：完成状态、下一步和延后事项。
  • docs/WORKFLOW.md：分支、commit、PR、验证和删除规则。
  • docs/design-docs/：架构决策，记录为什么这样做。
  • docs/product-specs/：功能规格，记录做什么和不做什么。
  • docs/exec-plans/active/：当前执行计划，小而清楚。
  • docs/references/：稳定参考、验收记录、操作手册。
  • docs/research/：竞品、技术选型、调研样本和判断。
  • workspace/：运行期产物、大文件、中间结果，默认不进 git。

AGENTS.md 写法

AGENTS.md 写法配图

AGENTS.md 要像地图，不要像百科全书。它只放稳定规则和入口链接，细节放进 docs/。

建议包含：

  • 项目名、目标、当前阶段。
  • 默认技术栈和本地运行命令。
  • 开始前必须读的文档。
  • 不可违反的安全边界。
  • 协作规则：实质操作前说明、删除前确认、持久知识写入 docs/。
  • Git 规则：分支前缀、commit 格式、PR 要求。
  • 特殊文档入口：状态同步清单、模型选型、部署说明等。

避免包含：

  • 大段历史流水账。
  • 会频繁变化的命令输出。
  • 太细的实现说明。
  • 没有长期价值的聊天结论。

配置和记忆层

配置和记忆层配图

官方最新实践都在强调同一件事：不要只靠一次 prompt，要把稳定偏好放进工具能自动加载的位置。

Codex 项目建议增加：

.codex/
  config.toml

用途：

  • 保存仓库级 Codex 配置，例如默认模型、reasoning effort、sandbox、approval、MCP servers、profiles。
  • 个人默认配置放在 ~/.codex/config.toml。
  • 临时命令行 override 只用于一次性任务。

Claude Code 项目如果也要兼容，可以增加：

CLAUDE.md
.claude/
  settings.json
  skills/
  agents/
  rules/

规则：

  • AGENTS.md 作为跨工具通用地图。
  • CLAUDE.md 只放 Claude Code 专属记忆和命令。
  • 如果要同时支持 Codex 和 Claude Code，CLAUDE.md 开头应指向 AGENTS.md，避免两套规则漂移。
  • 个人本地记忆、token、路径偏好放用户目录或 local 文件，不进 git。

Review 规则单独成文

Review 规则单独成文配图

OpenAI Codex 官方建议把 review 行为做成可复用文件，再从 AGENTS.md 引用。

推荐新增：

docs/references/code-review.md

或更短：

code_review.md

内容建议：

  • 严重程度定义。
  • 必查项：正确性、回归风险、安全、数据破坏、测试缺口、文档状态漂移。
  • 不查项：纯主观风格、已由 formatter/typecheck 覆盖的问题。
  • 输出格式：先 findings，后 summary。

这样以后可以让 Codex/Claude 按同一套口径做 /review、PR review 或自检。

调研先于代码

调研先于代码配图

默认规则：只要项目还没有稳定产品方向、技术路线或用户体验判断，就先做调研分支。

推荐分支：

research/<scope>-<topic>

推荐产物：

docs/research/
  competitors/<date>-<topic>.md
  technical/<date>-<topic>.md
  references/<library-or-platform>.md

调研不是让 Codex 替人类决定审美，而是让它把材料摆上桌：

  • 收集竞品入口、截图、价格、功能、用户路径和明显摩擦。
  • 记录它们真正解决了什么，不要只抄 feature list。
  • 标记哪些地方值得借鉴，哪些地方只是行业惯性。
  • 把“看起来很垃圾”的地方写成可讨论的设计反例。
  • 最后由人类做取舍：我们要坚持什么，不做什么，哪里要更有品味。

竞品调研建议字段：

name
url
target_user
core_workflow
pricing_or_business_model
onboarding_path
strong_points
weak_points
design_quality_notes
trust_and_safety_notes
features_to_ignore
features_to_consider
our_judgment
evidence

our_judgment 很重要。竞品数据是证据，不是标准答案。

竞品抓取边界

竞品抓取边界配图

如果需要抓竞品数据，默认先抓公开页面和用户可访问内容，不绕过登录、付费墙、平台限制或反爬策略。

如果调研需要登录后的真实产品体验，可以使用 CDP / 浏览器自动化辅助完成更彻底的观察，但必须满足这些条件：

  • 登录、二次验证、授权和付费访问由人类用户亲自完成或明确协助。
  • Codex 不记录、导出、复用密码、cookie、token、验证码或登录态。
  • 只访问用户本来有权访问的页面和功能。
  • 不绕过平台权限、反爬、付费墙、风控或访问限制。
  • 优先记录产品路径、交互、信息架构、价格、功能边界、体验问题和截图证据。
  • 对需要操作真实账号、发消息、下单、发布、删除、邀请成员等动作，必须先说明影响并等待用户确认。
  • 登录态调研结论仍要写入 docs/research/，不要只停留在浏览器会话或聊天里。

推荐流程：

  1. 列出要看的竞品和问题。
  2. 抓公开页面、截图、价格页、文档、帮助中心和产品演示。
  3. 如需登录后体验，由用户协助登录，Codex 通过 CDP / 浏览器观察关键路径。
  4. 对关键路径做人工体验记录。
  5. 归纳共性、差异和坏味道。
  6. 由人类决定产品审美和取舍。

不建议：

  • 为了“全量数据”提前做复杂爬虫。
  • 把竞品当前做法等同于最佳实践。
  • 在没有判断标准时批量复制功能。
  • 把用户授权登录误用成批量抓取、越权访问或规避平台限制。

规划文档

规划文档配图

新项目至少先写这些文档：

  • PROJECT_PLAN.md：目标、阶段、当前决定、下一步。
  • ROADMAP.md：已确认、待推进、延后事项。
  • ARCHITECTURE.md：主链路、模块布局、依赖方向、运行期目录、非目标。
  • docs/WORKFLOW.md：分支、commit、PR、验证、删除规则。
  • docs/design-docs/001-bootstrap-decisions.md：第一批关键决策。

每个功能最好配一个小规格：

docs/product-specs/<feature>.md

每个中等以上任务最好配一个执行计划：

docs/exec-plans/active/<date>-<topic>.md

执行计划要小。一个计划只解决一个主问题。如果标题里出现“以及、顺便、另外”，通常应该拆开。

Git 和 PR 规则

Git 和 PR 规则配图

默认分支：

  • main 是唯一长期分支。
  • 中等以上任务不直接在 main 开发。

分支命名：

<type>/<scope>-<short-name>

推荐 type：

  • docs
  • feat
  • fix
  • chore
  • refactor
  • test
  • ci
  • research

commit 格式：

<type>(<scope>): <summary>

原则：

  • 一个 commit 表达一个清晰意图。
  • commit 要能解释为什么改，不只是改了什么。
  • 每完成一个最小可验证单元再提交。
  • PR 描述必须写清楚目标、变更、验证命令和未完成边界。
  • 即使是一人项目，PR 也是项目记忆，不只是流程。

从最新主分支开新任务：

git fetch origin main
git switch -c docs/example-topic origin/main

创建 PR 前检查：

git status --short --branch
git diff --check
git diff --name-status origin/main...HEAD
git diff --stat origin/main...HEAD

Windows 中文 PR 描述默认写入 UTF-8 文件，再用：

gh pr edit <number> --body-file <path>

不要用 PowerShell 管道把中文正文传给 --body-file -。

验证策略

验证策略配图

每个项目都要有“最小可验证单元”。测试框架可以不同，但不能没有验证闭环。

常见验证层：

  • format：格式化或格式检查。
  • lint：静态规则、项目约定、禁止模式。
  • typecheck：类型检查。
  • unit test：核心函数和服务逻辑。
  • integration smoke test：真实或近真实输入的小样本。
  • dry-run：外部 API、下载、发布、写 vault、发邮件等高风险动作先预览。
  • manual review：产品审美、内容质量、知识入库等不能完全自动化的判断。

成功输出要尽量安静，失败输出要足够可修。给 Agent 看的错误信息应该包含下一步建议。

Hooks、MCP、Skills 和 Automations

Hooks、MCP、Skills 和 Automations配图

这些不是第一天必须全部配置，但要进入项目模板的演进路线。

Hooks

Hooks配图

Hooks 适合“必须发生、不能只靠 Agent 记得”的动作：

  • 编辑后运行 formatter、lint、typecheck 或目标单测。
  • 阻止写入敏感目录、历史 migration、真实 vault、生产配置。
  • 阻止提交 .env、token、cookie、运行期大文件。
  • session 结束时记录状态摘要。

注意：

  • hooks 能自动执行命令，必须小心审阅。
  • hooks 成功时尽量静默，失败时给出可执行修复建议。
  • hooks 不替代测试，只是确定性触发器。

MCP

MCP配图

MCP 适合连接仓库外的动态上下文：

  • GitHub issue / PR / CI。
  • Figma / 设计稿。
  • 文档站、知识库、Notion、Google Drive。
  • 日志、监控、部署系统。

不要一开始接满所有工具。先接 1-2 个能明显减少复制粘贴的高频来源。

Skills

Skills配图

当同一类任务反复出现，就沉淀成 skill：

  • 发布流程。
  • 数据库迁移。
  • PR review。
  • CI 失败排查。
  • 竞品调研。
  • 文档状态同步。

好的 skill 应像一个小 CLI：

  • 有清楚的触发条件。
  • 有输入、输出和验收标准。
  • 有反例：什么时候不要使用。
  • 有脚本或模板时，优先复用脚本和模板。

Automations

Automations配图

只有当 workflow 已经稳定，才把它自动化。

适合自动化：

  • 定期扫描文档状态漂移。
  • 总结最近 commits。
  • 检查 CI 失败。
  • 生成 release notes 草稿。
  • 定期刷新外部官方文档摘要。

不适合自动化：

  • 仍需要大量人工判断的产品方向。
  • 尚未验证的抓取、发布、删除、迁移流程。
  • 会写真实外部系统且没有 preview/dry-run 的任务。

是否需要自定义 lint 规则

是否需要自定义 lint 规则配图

结论：不必一开始就写复杂自定义 lint，但要从第一天记录“黄金规则”。当同一种错误重复出现，或者某条架构边界很重要，就把它升级成脚本、lint 或 CI 检查。

适合自定义 lint 的规则：

  • 禁止跨层直接 import。
  • 禁止运行期产物进入 git。
  • 禁止把 API key、cookie、token 写入仓库。
  • 禁止业务代码绕过统一配置、日志、鉴权、数据库访问层。
  • 禁止直接写真实外部目标，必须先 dry-run 或 preview。
  • 禁止修改已冻结的历史 migration、原始数据或已审阅产物。
  • 检查文档状态词，避免 README、ROADMAP、AGENTS 状态漂移。
  • 检查 PR 里是否混入不该出现的目录，比如文档 PR 混入 src/。

暂时不适合自定义 lint 的情况：

  • 规则还没稳定，只是个人偏好。
  • 团队还没踩过对应问题。
  • 普通格式化器、类型检查器、单元测试已经能覆盖。
  • 维护脚本成本高于它能防住的问题。

推荐演进：

口头规则
-> AGENTS.md Known Pitfall
-> docs/WORKFLOW.md 明确约定
-> scripts/check-*.ps1 或 scripts/check-*.py
-> CI 必跑
-> 自定义 lint / 架构检查

Agent 友好的代码约定

Agent 友好的代码约定配图

优先选择无聊、清楚、可组合的技术：

  • 明确模块边界。
  • 单向依赖。
  • 外部输入在边界处解析成结构化对象。
  • 配置从统一入口读取。
  • 输出路径可配置，默认写入项目内运行期目录。
  • 高风险操作先 dry-run。
  • 错误分类清楚，失败报告可回看。
  • 大批量任务先 --limit 小样本验证。

对 Agent 友好的代码库，不是“让 Agent 自由发挥”，而是让正确路径更容易被它找到。

长会话和上下文管理

长会话和上下文管理配图

长任务的主要风险不是模型不聪明，而是上下文变脏、变满、变旧。

默认规则：

  • 一个 thread/session 只承载一个清晰任务。
  • 无关任务另开新 thread。
  • 长任务要有 docs/exec-plans/active/ 作为跨会话锚点。
  • context 变长时，保留关键事实：目标、约束、已改文件、验证命令、剩余风险。
  • 如果同一个问题连续修两次还错，停下来总结失败路径，开干净上下文继续。
  • 探索型任务可用 subagent / explorer 隔离噪声，主 thread 只接收结论。
  • 大规模并行任务必须使用 git worktree 或明确 disjoint write set，避免互相覆盖。

适合 subagent 的任务：

  • 大量读文件的代码库探索。
  • PR review / 安全 review。
  • 测试失败分类。
  • 竞品资料收集。
  • 互相独立的方案比较。

不适合 subagent 的任务：

  • 下一步立刻依赖结果的阻塞任务。
  • 需要紧密设计判断的核心实现。
  • 写同一批文件的并行改动。

状态同步

状态同步配图

阶段收口、能力验收、CLI 变化、真实数据验证、跨仓库边界变化时，必须做 status sync。

至少检查：

  • README.md
  • AGENTS.md
  • ROADMAP.md
  • PROJECT_PLAN.md
  • ARCHITECTURE.md
  • docs/product-specs/index.md
  • 对应 docs/product-specs/*.md
  • 对应 docs/exec-plans/active/*.md
  • 对应验收记录或设计决策

不允许只更新局部执行计划，就把阶段标记为完成。

删除和高风险操作

删除和高风险操作配图

默认规则：

  • 删除任何文件、缓存、运行产物、分支之前，都先请求用户确认。
  • 不执行 rm、Remove-Item、git reset --hard、git clean 等破坏性命令，除非用户明确确认。
  • 不原地修改用户源数据。
  • 不覆盖已审阅产物，除非有明确迁移计划和用户确认。
  • API key、cookie、token、登录态只放本机环境变量或未提交配置。
  • 写真实外部系统前，先生成 preview / dry-run / draft。

Windows 和编码实践

Windows 和编码实践配图

如果项目主要在 Windows 上开发，默认使用 PowerShell 7，也就是 pwsh.exe，不要默认使用 Windows PowerShell 5.1 的 powershell.exe。

原因：

  • PowerShell 7 默认文本输出是 utf8NoBOM，更适合现代工具链。
  • Windows PowerShell 5.1 的编码行为不一致，重定向、Out-File、Set-Content、Export-Csv 等默认编码可能不同。
  • Windows PowerShell 5.1 中 > / >> 通过 Out-File 写入，容易生成 UTF-16LE，后续被 Node/Python/GitHub CLI/Unix 工具读错。
  • 无 BOM 的 UTF-8 脚本如果包含中文，可能被 Windows PowerShell 5.1 当成本地 ANSI code page 解析。

推荐写入新项目规则：

Windows 默认 shell: PowerShell 7 / pwsh.exe
文档、JSON、YAML、源码默认编码: UTF-8
跨平台文本默认: UTF-8 no BOM
必须兼容 Windows PowerShell 5.1 且脚本含中文: 使用 UTF-8 with BOM

推荐命令：

pwsh -NoLogo -NoProfile
$PSVersionTable.PSVersion

在脚本里需要显式写文件时：

Set-Content -Path .\docs\example.md -Value $text -Encoding utf8

注意：PowerShell 7 的 -Encoding utf8 是 UTF-8 no BOM；Windows PowerShell 5.1 的 -Encoding utf8 会写 BOM。需要严格一致时，要在文档里写明运行 shell 版本。

中文内容写入规则

中文内容写入规则配图

不要这样做：

@"
大段中文 PR 描述或 Markdown 正文
"@ | gh pr edit 123 --body-file -

也不要把大段中文塞进一行 PowerShell 命令，再交给 Python/Node/gh 写文件。Windows 终端、管道、native command 参数编码中任何一环错了，都可能把中文变成 ???? 或 mojibake。

推荐做法：

  • 文档编辑优先用 apply_patch。
  • PR body、release notes、长 Markdown 正文先写入 UTF-8 文件，再用 --body-file <path> 或等价参数读取。
  • Python 写文件必须显式 encoding="utf-8"。
  • Node 写文件使用 fs.writeFileSync(path, text, "utf8") 或等价 API。
  • 生成后用 Python/Node 按 UTF-8 读回抽样检查，不只看命令退出码。

Console 和 native command

Console 和 native command配图

$OutputEncoding 只影响 PowerShell 向外部程序传递字符串时使用的编码；它不影响 Set-Content、Out-File 或重定向写文件的编码。

不要把 chcp 65001 当成通用修复。它只影响控制台 code page，一些旧程序、字体、管道或重定向仍可能出问题。只有在明确某个 native command 需要 UTF-8 console code page 时才使用，并且要验证输出字节或读回文件。

如果必须和 native command 传递中文：

  • 优先通过 UTF-8 文件交换，而不是 stdin 管道或命令行参数。
  • 如果工具支持 --body-file、--input、--config、--json-file，优先使用文件。
  • 避免在 PowerShell here-string 里写中文后再 pipe 给 native executable。

命令重试规则

命令重试规则配图

不要因为命令失败就反复尝试同一条命令。

默认规则：

  • 同一条命令最多重试 1 次，且必须先说明改变了什么。
  • 第二次失败后停止，阅读错误输出并分类。
  • 分类为：环境缺失、路径错误、权限问题、编码问题、网络问题、依赖版本问题、命令语义错误。
  • 如果怀疑是编码问题，先检查 shell 版本、文件编码、输入方式和是否经过 native command 管道。
  • 长命令先拆成可验证的小命令，不要盲目堆参数。
  • 网络或平台接口失败，先确认是否临时错误，再决定是否重试。

常用诊断：

$PSVersionTable.PSVersion
[Console]::OutputEncoding
$OutputEncoding
Get-Command pwsh
git status --short --branch

当中文文件已经乱码：

  • 不要继续基于乱码文件修改。
  • 找到最后一个未乱码来源：git、UTF-8 草稿、浏览器页面、原始 JSON、截图或聊天记录。
  • 重新生成为 UTF-8 文件。
  • 用 UTF-8 读回抽样验证。

第一轮交付标准

第一轮交付标准配图

新项目第一轮不追求功能完整，追求可继续推进：

  • Codex 能从 AGENTS.md 知道该读哪里。
  • 人能从 README.md 知道当前项目是什么。
  • 后续开发能从 PROJECT_PLAN.md 和 ROADMAP.md 知道下一步。
  • 架构边界写进 ARCHITECTURE.md。
  • 第一个关键决策写进 docs/design-docs/001-bootstrap-decisions.md。
  • 有一个 active exec plan。
  • 有最小验证命令。
  • 有 Git/PR 规则。
  • 有 review 口径。
  • 调研结论和竞品判断没有停留在聊天里。

来自当前项目的经验

来自当前项目的经验配图

当前 video-knowledge-pipeline 项目里最值得复用的经验：

  • AGENTS.md 只做地图，长期知识沉入 docs/。
  • 从 V0 调研和骨架开始，不提前锁死复杂字段。
  • 真实数据样本出来后，再反推结构和抽取策略。
  • 大批量任务先 --limit 小样本，再扩大。
  • LLM/API/外部写入先 dry-run，不直接消耗 quota 或写真实目标。
  • 源数据、原始转写、已审阅产物保持可回溯，不为新阶段回头覆盖。
  • PR、验收记录和 status sync 是项目记忆的一部分。
  • 多仓库可以拆，但 AGENTS.md、Workflow、设计文档、测试和 PR 纪律要继承。

参考来源

参考来源配图