Codex工程化实践分享

默涵H
0 阅读8分钟

Codex 工程化实践分享：AGENTS.md、SKILL.md 与 MCP

面向团队主讲使用。本文基于掘金文章《Codex 工程化实践指南：深入理解 AGENTS.md、SKILL.md 与 MCP》重写，并补充了更适合落地实践的结构、纠偏和图示。

0. 先说这篇分享要讲什么

AI Coding 不是“让模型随便写代码”，而是把 AI 放进真实工程体系里，让它知道规则、复用流程、连接工具，并在明确边界内稳定交付。

这篇分享聚焦三个关键词：

  • AGENTS.md：告诉 AI “在这个项目里要遵守什么”。
  • SKILL.md：告诉 AI “遇到某类任务时该怎么做”。
  • MCP：告诉 AI “怎样安全访问外部系统和工具”。

主讲时可以先强调一个观点：AI 的能力上限不只取决于模型本身，也取决于我们是否给它提供了工程上下文、稳定流程和受控工具。

1. 总览：三层能力模型

概念解决的问题最短解释
AGENTS.mdAI 不懂项目规矩项目规则层
SKILL.md重复任务每次都要重新 Prompt可复用流程层
MCPAI 缺少外部上下文和工具能力外部连接层

可以把三者的关系理解为：

  • AGENTS.md 让 AI 懂规矩。
  • SKILL.md 让 AI 会流程。
  • MCP 让 AI 能办事。

只有三者结合，AI 才更像一个能进入团队协作的工程助手，而不是一次性的聊天窗口。

2. AGENTS.md：给 AI 看的项目说明书

AGENTS.md 是面向 AI 编程助手的项目指令文件。它有点像 README，但读者不是人类，而是 AI agent。

README 通常告诉人：项目是什么、怎么启动、怎么贡献。AGENTS.md 更应该告诉 AI：项目怎么改、哪里不能改、改完怎么验证、遇到风险时怎么处理。

一份实用的 AGENTS.md 可以包含这些内容：

  • 项目概览：技术栈、业务背景、核心目录。
  • 架构边界：模块职责、分层规则、禁止跨层调用的地方。
  • 编码规范：语言、类型、状态管理、请求、埋点、样式等约定。
  • 命令清单：启动、测试、lint、构建、专项检查。
  • 修改策略：哪些文件不要动，哪些操作需要先确认。
  • Review 清单：提交前必须关注的风险点。
  • 常见坑：AI 曾经犯过、团队希望它别再犯的错误。

2.1 它解决的核心问题

没有 AGENTS.md 时，我们经常在每次对话里重复写：

这是一个 React Native 项目。
不要改 generated 文件。
请求要走统一封装。
改完要跑 npm test。
不要随便新增依赖。

这类内容适合沉淀到 AGENTS.md。这样 AI 每次进入仓库时都能先读取同一套约定，团队成员也不用各自维护一套 Prompt。

2.2 写 AGENTS.md 的原则

做法说明
写稳定规则不要把一次性需求塞进去
写可执行规则“改完跑 npm test”比“保证质量”更有用
写路径和命令AI 对明确路径、命令、文件名更敏感
写边界哪些目录不要碰，哪些操作要确认
控制长度优先写高频、强约束、容易出错的内容

推荐把 AGENTS.md 当作工程护栏，而不是长篇教程。长文档可以放链接，让 AI 在需要时再读。

3. SKILL.md：把重复任务沉淀成技能

如果 AGENTS.md 解决“项目规则”，SKILL.md 解决的就是“任务流程”。

Skill 可以理解为一个可复用 SOP。它通常描述：什么情况下使用、需要什么输入、执行哪些步骤、输出什么结果、最后怎么检查。

适合做成 Skill 的任务通常有三个特征：重复、高价值、有固定流程。

常见例子：

  • code-review：按团队标准审查 MR / PR。
  • bugfix：根据日志定位、修复并补验证。
  • feature-dev：从读需求、查现有实现、编码到自测。
  • release-note：根据提交记录生成发版说明。
  • migration：按固定步骤做技术迁移。
  • data-report：分析表格并生成汇报材料。

3.1 Skill 和 Prompt 的区别

Prompt 是一次性的，Skill 是可复用的。

如果你发现某段 Prompt 每周都在复制，那它就值得被沉淀成 Skill。沉淀后，团队不需要每次重新解释流程，只要触发对应 Skill，AI 就能按统一方式执行。

3.2 好 Skill 的标准

标准判断方式
触发清楚AI 知道什么时候该用它
输入清楚需要 diff、日志、设计稿还是文档
步骤清楚不是“认真分析”，而是具体动作
输出稳定结果格式固定，方便团队消费
可验证包含测试、检查或人工确认点

Skill 的关键设计是渐进式披露：SKILL.md 只写主流程，脚本、模板、案例放在 Skill 目录里，AI 需要时再读取。这样既节省上下文，也能减少无关信息干扰。

4. MCP：让 AI 安全连接外部工具

MCP 是 Model Context Protocol，中文可理解为“模型上下文协议”。它让 AI 应用用统一方式连接外部系统，比如代码仓库、文档、Issue、CI、数据库、设计工具等。

这里需要纠正原文里一个容易误导的说法：MCP 不是 OpenAI 首创。更准确地说，MCP 最早由 Anthropic 在 2024 年作为开放标准推出，后来被 ChatGPT、Codex、Cursor、Gemini、Microsoft Copilot 等生态采用。Anthropic 后续也宣布把 MCP 捐赠给 Linux Foundation 旗下的 Agentic AI Foundation，以保持开放和中立治理。

主讲时可以这样说：MCP 不是某一家工具的私有接口，而是正在成为 Agent 连接外部系统的开放协议。

4.1 MCP 解决什么问题

  • 统一：不同外部系统通过统一协议接入。
  • 安全：权限、工具边界、审计可以集中管理。
  • 扩展：团队可以为内部系统写 MCP server。
  • 上下文：AI 不再只能依赖用户手动复制粘贴材料。

4.2 MCP 的风险边界

MCP 很强，但越能连接真实系统，越需要权限控制。

风险建议
权限过大最小权限原则，优先只读
高风险动作合并、发布、删数据等必须人工确认
工具命名混乱工具说明要清晰，避免 AI 误用
外部内容污染防 Prompt Injection，网页和文档不能变成高优先级指令
不可追踪关键调用要留日志

5. 团队怎么落地

建议不要一上来就追求“大而全”。可以按三步走。

第一步：先写最小可用 AGENTS.md

先覆盖这些内容就够了：

  • 项目是什么。
  • 核心目录怎么分。
  • 常用命令有哪些。
  • 新代码优先遵守哪些规范。
  • 哪些文件不要改。
  • 改完必须做哪些检查。

目标不是完美，而是让 AI 少犯最基础的工程错误。

第二步：沉淀 3 个高频 Skill

建议先从这三个开始：

  • code-review：统一 Review 关注点和输出格式。
  • bugfix：统一问题定位、修复、验证流程。
  • feature-dev：统一新需求从读代码到交付的流程。

这三类任务出现频率高，收益明显，也最容易形成团队共识。

第三步：用 MCP 接入低风险高收益系统

优先接入：

  • 代码仓库：读取 MR、diff、commit。
  • 文档系统：读取需求、技术方案、知识库。
  • CI 系统：读取构建和测试结果。
  • Issue 系统：读取任务背景和验收标准。

自动合并、自动发布、自动修改生产数据这类动作，不建议一开始开放给 AI。

6. 常见误区

误区一：AGENTS.md 写得越长越好

不对。太长会挤占上下文，也会让重点不清楚。AGENTS.md 应该写稳定、高频、强约束内容。

误区二：Skill 就是高级 Prompt

不完全对。Skill 不只是提示词，而是可复用工作流，可以带脚本、模板、案例和验证步骤。

误区三：MCP 等于给 AI 开后门

不对。好的 MCP 应该更安全，因为它把工具能力、权限、输入输出和审计集中管理。真正危险的是把账号、密钥、接口直接暴露给 AI。

误区四：用了这些以后人就不用管了

不对。AI Agent 的价值不是替代工程判断，而是把重复、琐碎、可流程化的部分自动化。架构取舍、权限审批和最终责任仍然需要人把关。

7. 主讲提纲

  1. 开场：AI 写代码不难，难的是遵守工程上下文。
  2. 总览：AGENTS.md 是规则，SKILL.md 是流程，MCP 是工具连接。
  3. 讲 AGENTS.md：把项目规则固化，减少重复 Prompt。
  4. 讲 SKILL.md：把重复任务沉淀成团队 SOP。
  5. 讲 MCP：连接外部系统，但要有权限和审计。
  6. 讲落地路线：先规则，再流程，最后工具。
  7. 收束：AI 工程化不是让 AI 更自由，而是让 AI 在明确边界内更稳定。

8. 一页总结

  • AGENTS.md：写给 AI 的项目说明书，解决“该遵守什么规则”。
  • SKILL.md：写给 AI 的工作流说明书，解决“这类任务该怎么做”。
  • MCP：AI 连接外部工具和数据的协议，解决“如何安全访问外部世界”。
  • 团队落地顺序：先固化项目规则，再沉淀重复流程，最后接入外部系统。
  • 人仍然负责架构判断、权限审批和最终质量。

9. 参考来源

avatar
文章
阅读
粉丝