Vibe Coding 知识库

AGENTS.md 项目指令 ​

AGENTS.md 是给 Codex 自动加载的项目工作说明。它适合承载长期有效的上下文：项目结构、工程约定、命令、验证标准和安全边界。

加载与优先级 ​

Codex 会在启动任务时读取指令文件，并按作用域合并：

  1. 全局作用域：默认在 ~/.codex 下读取 AGENTS.override.md，否则读取 AGENTS.md。
  2. 项目作用域：从项目根目录一路向当前工作目录查找。
  3. 同一目录中优先读取 AGENTS.override.md，再读取 AGENTS.md，再读取配置中的 fallback 文件名。
  4. 越靠近当前工作目录的指令越晚出现，因此会覆盖更上层的通用规则。

默认合并上限是 project_doc_max_bytes，官方文档当前说明默认值为 32 KiB。过长的指令容易被截断，建议把主文件控制在可读范围内，把专项流程拆到独立文档中再引用。

本项目推荐模板 ​

可以在仓库根目录添加：

markdown
# AGENTS.md

## 项目概览

这是一个 VitePress 文档站。正文位于 docs/，VitePress 配置位于 docs/.vitepress/。

## 常用命令

- 安装依赖：npm install
- 开发预览：npm run docs:dev
- 构建检查：npm run docs:build
- 本地预览构建产物：npm run docs:preview

## 文档规范

- 新增 Markdown 页面必须包含 title 和 order frontmatter。
- 文档链接优先使用相对路径或 VitePress 站内路径。
- 新栏目需要确认 docs/.vitepress/sidebar.ts 是否能自动纳入导航。
- 不要修改 node_modules/、压缩包、截图资产，除非任务明确要求。

## 完成标准

- 文档结构或导航变更后运行 npm run docs:build。
- 如果无法运行验证，说明原因和剩余风险。
- 最终回答列出修改文件和验证结果。

编写原则 ​

  • 写真实命令，不写“运行相关测试”这种空泛句子。
  • 写项目特有规则，不堆通用软件工程口号。
  • 规则要能被执行或检查。
  • 当 Codex 重复犯同一类错误时，做一次复盘，再把规则补进 AGENTS.md。
  • 对不同子目录有不同规则时，在子目录放更具体的 AGENTS.md 或 AGENTS.override.md。

和其他文档的关系 ​

AGENTS.md 不应该替代完整工程文档。它更像任务启动时的“默认工作协议”。详细规范可以拆到：

  • docs/codex/best-practices.md
  • docs/workflow/spec-driven.md
  • docs/testing/test-strategy.md
  • docs/production/security-checklist.md

然后在 AGENTS.md 里用短句引用。

来源 ​