Directed Contexts 完全指南：让 Claude Code 和 Codex 真正”看懂”你的代码库结构

用过 Claude Code 或 Codex 的开发者都知道一个痛点：你的 AI 编码 Agent 在单个文件里表现惊艳，但一旦面对数百个文件的复杂代码库，它往往迷失方向——不知道哪些文件相关、哪些可以改、哪些绝对不能碰。Agent 明明能帮你重构模块，却因为缺乏整体的代码库”地图”而跑偏。

Directed Contexts 正是为解决这个问题而生的开源规范与工具集。它定义了一套仓库自有指令模块（Repository-owned instruction modules），让 AI 编码 Agent 通过 AGENTS.md 路由器和 .subagents/ 目录下的领域上下文文件，真正理解代码库的所有权结构、边界约束和变更影响范围。

核心概念：Context Router + Directed Contexts

Directed Contexts 的思路比简单的 CONTRIBUTING.md 或 README 更结构化。它的核心是两个组件：

Context Router（AGENTS.md）

这是代码库的上下文地图。AGENTS.md 作为根路由器文件，定义了通用规则和路由表。当 Agent 启动一个任务时，它首先读取 AGENTS.md，然后根据任务类型和文件路径，路由到对应的领域上下文。

your-repo/
├── AGENTS.md                    # Context Router：通用规则 + 路由表
└── .subagents/
    ├── README.md                # 上下文索引
    ├── AGENTS-RUNTIME.md        # 运行时领域上下文
    ├── AGENTS-WORKER.md         # Worker 领域上下文
    ├── AGENTS-SECURITY.md       # 安全策略覆盖层
    └── route-cases.json         # 可测试的路由样例

Directed Context

每个 .subagents/AGENTS-{DOMAIN}.md 文件是一个有界上下文，包含：

• 领域范围（domain）：明确这个上下文负责什么
• 自有路径（owned paths）：这个上下文拥有的文件路径
• 不变量（invariants）：在这个上下文中必须遵守的约束
• 相邻上下文（adjacent contexts）：与哪些上下文有交集
• 验证契约（verification contract）：如何验证上下文仍有效

比如 AGENTS-SECURITY.md 作为策略覆盖层，不拥有任何路径（cross-cutting），但会对所有安全相关的变更施加约束。

加载 vs 衍生

Context Router 有两种工作模式：

• Inline load：在当前会话中直接载入上下文 Markdown
• Isolated spawn：启动一个子 Agent，限定在某个上下文范围内工作

这种设计让 Agent 既能获得全局视角，又能在具体任务中保持专注。

快速上手：bootstrap 你的第一个 Context Set

Directed Contexts 提供了一个 Go 语言 CLI 工具 contextctl，用来自动化生成上下文集合。以下是完整的上手流程：

1. 克隆仓库

git clone https://github.com/TGPSKI/directed-contexts.git
cd directed-contexts

2. 扫描代码库

让 Agent 对目标仓库执行扫描。contextctl scan 会做三件事：

1. 盘点所有包（packages）、入口点、已有的指令文件、CODEOWNERS 和构建命令
2. 验证仓库的坐标系统（根目录、monorepo 边界、源码 vs 生成树的区分）
3. 提出所有权边界划分建议，只对真正含糊的边界询问人工确认

go run scripts/contextctl.go scan --repo /path/to/your/repo

3. 生成上下文集合

扫描完成后，contextctl 会生成完整的 Context Set：

go run scripts/contextctl.go check --repo /path/to/your/repo
go run scripts/contextctl.go routes --repo /path/to/your/repo --cases .subagents/route-cases.json

生成的 route-cases.json 包含一系列可测试的路由样例，确保 Agent 在重构或新增功能时能正确命中对应的上下文。

4. 持续验证：使用 drift 检测

代码库在演进，上下文也可能过时。contextctl drift 命令可以检测：

go run scripts/contextctl.go drift --repo /path/to/your/repo

Drift 报告会列出：

• 无主的包（unowned packages）：新添加的包没有上下文覆盖
• 已删除的有主路径（deleted owned paths）：上下文声明的文件已被移除
• 重叠声明（overlapping claims）：多个上下文声称拥有同一路径
• 过期的审查时间（stale review dates）：上下文声明未定期审查
• 拆分/合并候选（split/merge candidates）：结构变化建议调整上下文边界

目录结构与核心概念词汇

理解 Directed Contexts 的几个关键术语：

设计原则

Directed Contexts 有几个值得注意的设计决策：

Markdown 是权威来源。 没有隐藏的 manifest 文件，contextctl 直接解析和验证路由表和上下文文件的 Markdown 内容。这意味着你可以在不安装任何工具的情况下，直接用编辑器查看和修改上下文。

上下文是协调机制，不是授权。 衍生出的子 Agent 继承调用者的权限。所有权范围不是安全强制的——它只是告诉 Agent 哪些路径是它的”责任区”，但 Agent 仍然可以读取其他路径。

确定性地做，人工判断只在必要时介入。 扫描器能回答所有存在磁盘上的问题（包结构、入口点、CODEOWNERS）。只有真正有争议的边界才会请求人工决策。扫描器默认只读，从不写入，从不执行仓库内容，从不跟随符号链接出仓库范围。

支持所有 Agent 框架。 输出是可移植的 Markdown，不依赖特定的 Agent 实现。无论你用的是 Claude Code、Codex、Cursor 还是 Copilot，只要 Agent 能读取 Markdown 指令，就能使用 Directed Context。

实际应用场景

场景一：大型 Monorepo 中的安全边界

假设你的代码库包含支付处理模块和用户管理模块。通过 AGENTS-SECURITY.md 作为 policy overlay，可以定义支付相关的安全约束（如 PCI 合规要求），而不需要改动其他上下文。当 Agent 在处理支付相关任务时，Context Router 会同时加载支付模块的 primary context 和安全 policy overlay。

场景二：前后端分离的团队协作

前端仓库和后端 API 定义在同一个 monorepo 中。AGENTS-FRONTEND.md 和 AGENTS-BACKEND.md 各自拥有自己的路径。当 Agent 被要求”添加一个新的 API 端点”时，它自动被路由到后端上下文；当要求”在新 API 上构建 UI 组件”时，它被路由到前端上下文。每个上下文还可以引用相邻上下文，方便跨边界的协作。

场景三：增量重构的安全网

在重构中，drift detection 是最有价值的能力。当你移动文件或重命名包时，contextctl drift 会立即报告上下文中的所有权声明与实际代码库结构之间的差异。这种”上下文即文档”的方式，比维护独立的架构文档要可靠得多——因为上下文和代码库是通过 drift 检查持续保活的。

与 Claude Code / Codex 集成

虽然 Directed Contexts 的安装方法是 go run scripts/contextctl.go，但更好的使用方式是通过 SKILL.md 驱动 Agent 执行：

提示 Agent： “Use SKILL.md to bootstrap a context set for my repository. Run the scanner, propose ownership boundaries, and generate the router and contexts.”

Agent 会依次执行 scan、check、routes 三步，生成完整的 Context Set。之后，每次 Agent 启动新任务时，通过读取 AGENTS.md 自动获取代码库的全局上下文地图。

项目状态与许可证

Directed Contexts 目前是 1.0 版本，由 TGPSKI 开发维护。仓库采用 GPL-3.0 许可证，代码和规范均开源公开。contextctl 工具使用 Go 1.22+ 标准库实现，零外部依赖。

总结

使用 Claude Code、Codex 或 Cursor 处理复杂代码库的开发者，最终都会遇到同一个瓶颈：Agent 缺乏代码库级别的上下文理解。Directed Contexts 提供了一个优雅的解决方案——通过仓库自有的 Markdown 指令模块，为 Agent 绘制结构化的”代码库地图”。

它不要求你改变现有的开发流程，不需要安装复杂的服务端组件，只是一个目录结构和一份规范。但正是这种轻量级的设计，让它能够适应各种规模和架构的项目。

如果你已经遇到 Agent 在大型代码库中”迷路”的问题，试试 contextctl scan——给你的 Agent 一张完整的地图。

相关链接

• Directed Contexts GitHub
• PATTERN.md — 规范完整定义
• SKILL.md — Agent 交互入口