Codex 工程化实践指南：深入理解 AGENTS.md、SKILL.md 与 MCP

AI 就像自动驾驶，其价值并非让没摸过方向盘的新手上路开车，而在于为熟练的驾驶者节约精力和时间。

在 Codex 的设计中，有三个非常关键的概念：

AGENTS.md
SKILL.md
MCP（Model Context Protocol）

如果把 Codex 看成一个 "AI 工程师"，那么这三个概念相当于：

概念	角色
`AGENTS.md`	团队开发规范
`SKILL.md`	可复用工作流
`MCP`	外部系统接口

注意这里的"团队开发规范"不是指人类工程师所组成的团队，而是包含 AI Agent 工程师在内的团队。

这三个组件共同构成了 AI 工程协作的基础设施。

本文将系统介绍这三个概念，并重点讨论：

它们分别是什么
解决了什么问题
如何在真实工程中使用
有哪些实践技巧

一、AGENTS.md：给 AI 写的工程手册

1.1 AGENTS.md 是什么

当我们让 AI 修改代码时，经常会遇到这样的问题：

AI 修改了不该修改的模块
AI 写的代码不符合团队规范
AI 不知道项目架构
AI 重复犯同样的错误

原因其实很简单：

AI 并不了解该项目的设计规则、编码规范。

在真实团队中，新人工程师加入项目时，通常会阅读：

设计文档
需求定义书
架构说明
coding style
PR 规范

这些信息帮助新人快速理解项目。Codex 也是一样的。于是 OpenAI 引入了 AGENTS.md。

简单来说：

AGENTS.md 是写给 AI agent 的工程文档。

它的作用类似于：

团队开发规范
项目背景文档信息文档

但对象不是人类，而是 AI。

图：AGENTS.md 是供 AI 阅读的结构化文档

1.2 AGENTS.md 的核心作用

AGENTS.md 的主要目标有三个：

作用	说明
提供项目上下文	帮助 AI 理解项目结构
约束 AI 行为	避免 AI 随意修改代码
减少重复 Prompt	把规则固化在仓库中

在没有 AGENTS.md 时，每次 Prompt 都需要写：

plaintext 复制代码

项目是 Kotlin MVVM 架构
Repository 不能依赖 UI
所有 IO 使用 coroutine

这不仅浪费时间，还容易遗漏。而 AGENTS.md 可以把这些规则固定下来。

1.3 AGENTS.md 的典型结构

一个好的 AGENTS.md 通常包含以下部分：

模块	内容
Project overview	项目简介
Architecture	系统架构
Coding conventions	编码规范
Build & test	构建方式
Common tasks	常见任务
Review checklist	代码审查规则

示例如下：

md 复制代码

# AGENTS.md

## Project Overview

Android application for smartwatch dial management.

## Architecture

The project follows MVVM architecture.

Layers:

- UI
- ViewModel
- UseCase
- Repository
- DataSource

Rules:

- UI must not access DataSource
- Repository handles business logic
- BLE communication only in ble module

## Coding conventions

Language: Kotlin

Rules:

- Prefer Kotlin Flow over callbacks
- Avoid blocking IO
- Use suspend functions

## Build & test

Build:

./gradlew assembleDebug

Test:

./gradlew test

Lint:

./gradlew ktlintCheck

这份文档会在 Codex 运行时自动加载。

1.4 AGENTS.md 的层级机制

图：AGENTS.md 层级示意图

Codex 支持 多级 AGENTS.md。例如：

javascript 复制代码

~/.codex/AGENTS.md
repo/AGENTS.md
repo/module/AGENTS.md

优先级规则：越靠近当前目录，优先级越高。这种机制非常适合大型仓库，例如：

层级	用途
global	个人偏好
repo	团队规范
module	模块规则

1.5 AGENTS.md 的实践技巧

技巧一：只写关键规则

AGENTS.md 不应该太长。推荐 100~300 行。因为 AI 会自动将该文件加入上下文，如果太长的话会增加 token 消耗。

技巧二：记录 AI 曾犯过的错误

一个非常有效的方法是，当 AI 犯错时，把规则写入 AGENTS.md。这样 AI 就不会再犯同样的错误。例如：

英文	中文
Avoid modifying generated protobuf files.	不要修改生成的 protobuf 文件。

二、SKILL.md：AI 的技能包

2.1 什么是 SKILL

SKILL 原本是 Claude Code 引入的概念，后被 Codex 借鉴，并逐渐发展为 AI Agent 范式。

如果说 AGENTS.md 是 规则系统 ，那么 SKILL.md 就是 能力系统 。它定义了 AI 在面对某种任务时，应该如何执行 。其核心是 渐进式披露 与 模块化插拔。

2.2 为什么需要 SKILL

在真实开发中，有很多重复任务：

修复 crash
添加 API
写单元测试
发布版本

如果每次都写 Prompt：

复制代码

分析 crash
定位代码
修复
写测试

这样每次复制粘贴一大段，效率非常低。Skill 的目标是：将特定能力拆分为独立的描述-资源集合，供 AI 按需加载。

2.3 SKILL 的结构化存储

图：Claude SKILL 目录结构

一个 Skill 通常是一个目录：

SKILL.md：能力概述，遵循一定的格式规范。
script.py：（也可以是目录）该能力可以调用的脚本。
docs.md：（也可以是目录）该能力相关的其它文档。

SKILL.md 示例：

md 复制代码

---
name: android-bugfix
description: Fix Android runtime crash
---

Steps:

1. Analyze stacktrace
2. Locate source file
3. Identify root cause
4. Implement fix
5. Add regression test

之后只需说：

复制代码

Use android-bugfix skill

Codex 就会按流程执行。

2.4 SKILL 的"渐进式披露（Progressive Disclosure）"

在前文的 SKILL.md 中，我们看到有 name description 这一段：

yaml 复制代码

---
name: android-bugfix
description: Fix Android runtime crash
---

它们被称作 元数据，通过概括该 SKILL 的主要用途，为 AI 提供了选择性加载 SKILL 的功能。这种上下文管理方式称为 "渐进式披露"。其最大作用在于节约上下文窗口，防止过长且无效的上下文引起 AI 输出的稳定性和准确性问题。

图：渐进式披露

2.5 SKILL 的典型应用

在工程实践中，可以创建多种 Skill：

Skill	用途
android-feature	实现新功能
android-bugfix	修复 bug
code-review	代码审查
refactor-module	模块重构

2.6 SKILL 的实践技巧

技巧一：Skill 可以调用脚本

在"SKILL 的结构化存储"一节中已经介绍，SKILL 可以包含代码、脚本等可执行文件。例如对于单元测试，SKILL 目录下有 scripts/run-tests.sh。那么，该 SKILL 就可以自动执行 run tests 进行验证。

技巧二：SKILL 可以自我进化

一个非常有趣的用法是，让 AI 自己生成 Skill。例如如下 Prompt：

|英文|中文| |You solved a complex problem.

Create a SKILL.md for this workflow.|你刚刚解决了一个典型问题，将它总结为 SKILL.md，以便未来解决类似问题。|

这样 AI 的经验会逐渐沉淀，真正成长为独当一面的助手。

技巧三：SKILL 可以组合

如下图，以"分析销售数据表格，使用公司模板生成 PPT"这一任务来说，它组合了"表格分析 SKILL"、"汇报成果 SKILL"，将这两者组装成一个流水线 pipeline。

图：SKILL 流水线

三、MCP：连接外部世界

前两个概念 AGENTS.md SKILL.md 主要解决 代码仓库内部问题。但 AI Agent 还需要访问外部数据源：

GitHub
数据库
issue tracker
CI/CD

于是 OpenAI 提出了 MCP（Model Context Protocol，模型上下文协议）。

3.1 MCP 的核心思想

MCP 是一种协议，用于 让 AI Agent 安全地访问外部工具。例如：

工具	用途
GitHub MCP	读取 PR
Jira MCP	查看任务
Database MCP	查询数据

3.2 MCP 架构

MCP 的基本架构如下：

图：MCP 架构

3.3 MCP 的优势

相比直接调用 API，MCP 的优势在于：

安全：权限隔离
统一：统一接口
可扩展：支持新工具