官方原文索引： Custom instructions with AGENTS.md / Project Instructions
1. 核心架构与原理解析
AGENTS.md 是 Codex 的项目级系统提示持久化机制。它的核心作用是：把"每次都要交代一遍的项目规则"写成文件，让 Codex 每次启动自动读取。
查找优先级（就近覆盖原则）：
合并规则：
- 从根目录向下逐层拼接，子目录覆盖父目录
- 总大小上限 32 KiB（可调至 64KB）
- 支持自定义回退文件名：
TEAM_GUIDE.md、.agents.md
与 codex.md 的区别：
| 维度 | codex.md | AGENTS.md |
|---|---|---|
| 作用域 | 用户级个人偏好 | 项目级团队规范 |
| 典型内容 | "always reply in Chinese" | "use TypeScript strict mode" |
| 优先级 | 低 | 高（目录级覆盖） |
| 版本控制 | 通常不入 Git | 必须入 Git |
🛠️ 专家视角 / 架构思考： AGENTS.md 的设计体现了**"配置即代码"（Config as Code）**理念。把团队规范写成 Markdown 而非口头传递，好处是：
- 可版本控制（Git 追踪变更）
- 可代码审查（PR 中 review 规范变更）
- 可自动化验证（CI 检查 AGENTS.md 是否符合模板）
- 新人 onboarding 即读即用，无需口口相传
2. 工程落地与代码示例
生产级 AGENTS.md 模板（金融级后端服务）
# Project: Payment Gateway API
# Stack: Node.js 22 + TypeScript + PostgreSQL + Prisma + Fastify
## Architecture Rules
- Follow Clean Architecture: Domain → UseCase → Adapter → Infrastructure
- All database access must go through Repository pattern in `src/infrastructure/db/`
- API routes in `src/routes/` must have corresponding OpenAPI spec in `specs/`
- All external calls must have timeout (default 5000ms) and circuit breaker
## Coding Standards
- Strict TypeScript: no `any`, explicit return types on all exported functions
- Use `Result<T, E>` from `neverthrow` for error handling, no thrown exceptions in business logic
- All async I/O must have timeout and retry logic
## Security Red Lines
- NO hardcoded secrets. Use `process.env` + `src/config/secrets.ts` abstraction
- NO SQL string concatenation. Only Prisma ORM or parameterized queries
- Input validation via Zod schemas in `src/validation/`
- Audit log required for: payments, refunds, plan changes, admin actions
## Testing Requirements
- Unit tests with Vitest for all UseCases (minimum 80% coverage)
- Integration tests for all route handlers
- Payment flows must have boundary tests: zero amount, max amount, currency precision
## Review Rules
- Changes to `src/domain/` require architecture impact description
- Migration files need rollback script verification
- New dependencies must be in `approved-packages.json`交互式生成 AGENTS.md
codex
> /init
# Codex 会自动扫描项目结构，生成 AGENTS.md 模板框架
# 你只需补充团队特定的规则和安全红线项目级配置协同
# .codex/config.toml（仅受信项目生效）
project_trust = true
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
# 审查用轻量模型，降低成本
review_model = "gpt-5.3-codex-spark"AGENTS.md 的目录级覆盖实战
project/
├── AGENTS.md # 全局规范（所有模块通用）
├── src/
│ ├── AGENTS.md # 后端特定规范
│ └── payment/
│ └── AGENTS.md # 支付模块特殊规则（最高优先级）
├── frontend/
│ └── AGENTS.md # 前端特定规范
合并效果：
3. 场景深入：AGENTS.md 在不同团队规模中的应用
场景：5 人初创团队
# AGENTS.md
## 项目说明
- Node.js + React 全栈项目
- 优先可读性，不过度工程化
## 代码风格
- 2 空格缩进
- 单引号字符串
- 中文注释
## 安全
- 不在代码中写密码
- 用户输入要校验要点：简单直接，不堆砌模板，聚焦"容易忘的规则"。
场景：50 人金融团队
# AGENTS.md
## 合规要求
- 所有支付相关代码必须经过双人 review
- 数据库变更需附带回滚脚本
- 新增外部依赖需安全团队审批
## 架构约束
- 严格分层：Domain / UseCase / Adapter / Infrastructure
- 禁止跨层调用
- 所有外部 HTTP 调用必须有熔断和重试
## 审计要求
- 敏感操作必须记录审计日志
- 日志格式：timestamp | user_id | action | resource | result要点：强调合规、审计、分层，每个规则都关联到具体检查点。
场景：开源项目维护
# AGENTS.md
## 贡献指南
- 新功能必须包含测试
- API 变更必须更新文档
- Breaking change 需要 migration guide
## 代码审查标准
- 拒绝没有测试的 PR
- 拒绝破坏向后兼容的未标记变更
- 优先修复正确性，其次性能要点：聚焦贡献流程和审查标准，降低维护者负担。
4. 💡 核心避坑与最佳实践 (Takeaways)
- AGENTS.md 不是代码规范全集：聚焦"不可推导的规则"（项目特定约束），通用规范交给 ESLint/Prettier
- 定期审计防止规范幻觉：过时的规则（如已废弃的技术栈）会导致 Agent 产生错误假设，建议每季度 review
- 安全红线用大写强调：Agent 对格式化强调更敏感，
## Security Red Lines比## Security更有效 - 版本控制策略：基础 AGENTS.md 入 Git 共享，个人覆盖文件
.gitignore隔离 - 不要写得太长：32KB 上限内，优先放"一定会影响代码质量的规则"，百科式内容放 wiki