Codex 五层架构：记忆/知识/护栏/委派/分发¶

Ch09.083 Codex 五层架构：记忆/知识/护栏/委派/分发¶

📊 Level ⭐⭐ | 9.5KB | entities/codex-5-layer-architecture.md

Codex 五层架构：记忆/知识/护栏/委派/分发¶

摘要¶

Codex 团队开发环境配置的五层架构：AGENTS.md（记忆层）→ skills/（知识层）→ hooks/（护栏层）→ subagents/（委派层）→ plugins/（分发层），形成一个从规则对齐到安全管控到多 Agent 协作的完整工程体系。

五层详解¶

L1 记忆层 — AGENTS.md¶

全局配置、项目级规则、代码规范、工程红线。写死的团队共识，所有 AI 成员以此对齐。这是 Codex 环境的"宪法"层。

设计要点： - 所有 AI 成员启动时自动加载，确保全局规则一致性 - 内容聚焦不可变规范（编码风格、命名约定、安全红线） - 项目级而非全局级——每个项目维护自己的 AGENTS.md，反映该项目的特定约束

L2 知识层 — skills/¶

沉淀团队最佳实践，避免重复造轮子。Agent 按场景自动识别并调用对应 skill，按需获取能力。

设计要点： - 每个 skill 对应一个特定场景的工作流（单元测试编写、部署检查、代码重构等） - Skill 遵循统一的声明式接口，Agent 自动解析可用技能列表 - 团队可以像维护代码库一样维护技能库——PR 提交、Code Review、版本迭代

L3 护栏层 — hooks/¶

特定行为前后自动执行：

• 事前拦截：危险命令（rm -rf、生产环境写操作）在执行前被阻止
• 操作验证：关键操作后的自动检查（部署验证、测试通过检查）
• 部署通知：自动向团队发送部署结果通知

Hooks 的本质是将"安全策略"从 Agent 提示词中解耦出来，作为独立可配置的检查点注入 Agent 工作流。

L4 委派层 — subagents/¶

每个子智能体拥有独立上下文窗口、自定义工具与权限。结果回传主线程，保持主线逻辑干净。支持并行执行。

设计要点： - 每个 subagent 完全隔离：不知道其他 subagent 的存在 - 主线程负责任务拆分和结果聚合，subagent 专注执行单一任务 - 并行执行充分利用多模型推理能力，显著缩短整体执行时间

L5 分发层 — plugins/¶

通过 NPM 包分发，版本可控。技能、规则、子智能体一键安装，确保全队配置同步。

设计要点： - 所有配置（skills、hooks、subagents）打包为 NPM 包 - 版本号语义化，团队可锁定特定版本 - npx codex plugins install 一键同步全队配置

层间交互机制¶

五层架构的交互遵循自顶向下的调用链：

用户指令
  → L1 记忆层（对齐全局规则）
    → L2 知识层（按需加载技能）
      → L3 护栏层（安全检查）
        → L4 委派层（并行执行）
          → L5 分发层（跨项目共享）

每层只关注自己的职责，通过标准接口传递上下文。这种分层设计确保了每一层的可替换性——更换记忆策略不需要修改委派逻辑，更换护栏工具不需要改变技能设计。

深度分析¶

五层架构本质上是 AI 协作的"企业治理模型"¶

Codex 的五层架构可以映射到人类组织的治理层级：

这种映射不是巧合——AI 团队协作面临的问题本质上与人类团队协作相同：对齐共识、沉淀知识、管控风险、并行分工、共享成果。Codex 的五层架构是这些治理需求在 AI 原生开发环境中的具体实现。

从"提示词工程"到"环境工程"的范式转变¶

五层架构标志着 AI 编码从提示词工程向环境工程的转变。 传统方式依赖在每次对话中编写高质量提示词来引导模型；五层架构则将规则、知识、安全策略沉淀为文件系统中的持久化配置，Agent 启动时自动加载。

这意味着： - 知识不复失：团队积累的最佳实践存储在 skills/ 中，不会因人员流动或对话丢失 - 安全不依赖记忆：安全策略编码在 hooks/ 中，不会因忘记在提示词中提及而被绕过 - 能力可编排：Agent 的能力通过配置组合而非临时代码定义

这与 Harness Engineering 的"工程化 AI 协作"理念一脉相承。

Hooks 层的安全价值被低估¶

在五层中，hooks/（护栏层）往往最容易被忽视，但它可能是最关键的——它将 AI 操作的安全性从"信任"转变为"验证"。

没有 hooks 时，安全依赖于模型在提示词指导下做出正确判断（信任模式）；有 hooks 时，每个危险操作都被外部检查点拦截（验证模式）。即使模型判断失误，hooks 仍然提供了一层安全网。这种设计模式是零信任安全模型在 AI 协作中的应用。

分发层缺失：团队级 AI 工程的最大瓶颈¶

大多数 AI 编码实践止于 L3（hooks），缺乏 L5（plugins）的分发能力。 这意味着每个团队成员独立维护自己的 AGENTS.md、skills、hooks —— 导致配置碎片化、版本不同步、最佳实践无法共享。L5 分发层的核心价值不在于技术实现（NPM 包分发并不复杂），而在于建立团队级的配置治理规范。

实践启示¶

1. 从 L1 开始，逐层建设：不必一次性部署全部五层。先从 AGENTS.md（L1）开始建立团队共识，再逐步引入 skills（L2）沉淀最佳实践，最后按需添加 hooks（L3）、subagents（L4）、plugins（L5）。每层都有独立价值，不需要全部到位才生效。

2. 将安全从提示词解耦为检查点：不要仅靠提示词约束 Agent 行为，将安全规则实现为 hooks/ 中的独立检查点。事前拦截比事后纠正成本低得多。关键检查点：危险命令过滤、敏感文件保护、部署前验证。

3. 知识层的版本迭代：将 skills/ 当作代码库管理：提交 PR、Code Review、版本标签。定期审查技能库的使用频率和效果，淘汰过时技能，优化高频路径。

4. Subagent 的隔离粒度：设计 subagent 时，确保每个子任务完全独立——不需要访问其他 subagent 的上下文或结果。如果两个子任务需要共享状态，它们应该合并为一个 subagent 或在主线程中串行处理。

5. 尽早建立分发机制：当团队超过 2 人时，就应建立配置分发机制。使用 NPM 包或类似方案（Git 子仓库、私有 Registry）实现一键同步，避免"我改了 AGENTS.md 但你没同步"的协作摩擦。

参照¶

• Codex AGENTS.md 配置实践
• 古法程序员 Codex 三层 Skill 架构
• Harness Engineering 实践
• Agent Harness 上下文管理
• Skill 驱动开发

来源¶

→ 原文存档