dev-context-engineering

上下文工程

使用此技能来设计原生于仓库的 Agent 上下文，使其可移植、高信噪比且易于维护。此技能负责跨 AGENTS.md、特定运行时层、规范、规则、钩子、编译后的 Markdown 知识库及相关构件管理上下文模型、迁移路径、成熟度评估和上下文图规范。

快速参考

任务	使用
可移植的仓库指令	agents-memory 技能，references/fast-track-guide.md
规范和计划流程	docs-ai-prd、dev-workflow-planning
上下文图设计	references/context-graph-guide.md、python3 scripts/scan_context_artifacts.py --help、python3 scripts/validate_context_graph.py --help
热层过时情况和取代关系完整性检查	scripts/validate_context_graph.py（检查 check_stale_tiers、check_supersession_integrity）
查询上下文图（PPR、BFS、扇入、层级预算）	python3 scripts/query_context_graph.py <graph> --help（模式：--node、--impact、--rank、--ppr --seed、--tier-budget）
编译后的 Markdown 知识层	docs-notes-retrieval 技能、references/context-graph-guide.md、references/multi-repo-strategy.md
多仓库策略	references/multi-repo-strategy.md、dev-context-multi-repo
选择框架（superpowers、GSD、Spec Kit、OpenSpec 等）	references/framework-selection-matrix.md
受监管环境的推出	references/regulated-environment-patterns.md、assets/ai-agent-governance.md、assets/compliance-fca-emi.md

适用场景

• 设置或改进 AGENTS.md、CLAUDE.md、Copilot 指令、钩子或 Agent 规则层。
• 将仓库从临时提示词迁移到持久化的 Agent 上下文。
• 决定哪些内容应纳入常驻上下文，哪些应放入文档、检索内容或按需构件。
• 为仓库构建上下文图和加载层级模型。
• 为单个仓库或多个仓库组合制定 AI 辅助开发的成熟度路径。
• 为大型编译型仓库知识库设计运营模式，让 Agent 根据结构化构件创建和更新仓库说明、索引及报告。

转到其他技能

• 编写可移植的仓库指令：使用 agents-memory 技能。
• 探索仓库组合并生成中心索引：使用 dev-context-multi-repo。
• 符号级代码图和影响范围分析：使用 dev-context-code-graph。
• 任务分解和验证计划：使用 dev-workflow-planning。
• 钩子、MCP 或子 Agent 实现细节：使用 agents-hooks、agents-mcp 或 agents-subagents。

默认原则

• 将 AGENTS.md 作为可移植的基线。
• 仅在运行时专属层能够解锁实际能力时才添加它们。
• 仅将无法推断的约束放入始终生效的上下文。
• 使用精简的热指令层和更大的编译型 Markdown 知识库，而不是一个庞大的清单。
• 优先改善状态和结构，而不是增加文本。
• 让大模型维护冷知识层和派生笔记；由人类审查策略、安全性和架构约束。
• 优先将输出保存为持久文件，归档回仓库上下文，而不是只留在聊天记录中。
• 创建新的 Markdown 前，先运行文档归置检查；优先更新规范文档或生成的上下文产物，而不是添加一次性文件。
• 像审查代码变更一样审查、验证和精简上下文变更。
• 仓库达到结构化上下文成熟阶段后，生成 context-graph.json。
• 工具集精简：只向 Agent 提供它们实际需要的工具。如果人类工程师无法说清某项任务应该使用哪个工具，AI Agent 也不会做得更好。从少量工具开始；按需扩展。
• 优先使用解析器，而非不断累加：当热层开始为处理新的边缘情况而不断扩张时，优先采用指针式解析器（根据描述匹配选择技能），按需加载正确的文档。参见 references/context-resolver-pattern.md。

2026 年 5 月验证原则

当前的上下文工程应将上下文视为一个不断演进的系统，而不是更长的提示词。由来源支持最充分的原则包括：

• 上下文是有限的工作记忆：优先优化为能够影响结果的最小高信号 token 集合，然后在恰当时机加载更深入的依据。
• 上下文适配是一流的工程循环：生成、反思、整理和验证更新，同时避免迭代摘要丢失细节。
• 原始证据必须始终可检索。摘要、记忆和图节点是路由层，不能替代源文件、对话记录、产物或原始文档。
• 记忆需要生命周期语义：来源、时效性、取代关系、矛盾处理，以及用户或租户范围。只有在时间推理、关系变化或跨会话连续性很重要时，才使用时间图记忆。
• 图检索应视情况使用。简单查询应直接读取或进行词法搜索；仅在涉及关系、多跳或全局理解的问题中使用图遍历、PPR 或社群摘要。
• 工具和上下文接口应保持精简并纳入治理。除非选择边界明确，否则增加工具或始终生效的规则只会带来歧义。

多工具组合

最快交付成果的团队会为每项任务选择合适的工具，而不是强迫一个 Agent 包办所有工作。截至 2026 年 5 月，最有效的模式是：

工具	最适合	上下文模型
Cursor / IDE agent	日常编辑、行内补全、按 Tab 接受建议、快速重构	IDE 原生：打开的文件 + 项目索引
Claude Code	复杂的 Agent 任务、多文件更改、Agent 团队、代码审查、架构设计	命令行：AGENTS.md + .claude/rules + 技能 + 子 Agent
Codex	并行后台工作、批量处理、与 CI 相邻的任务	线程：AGENTS.md + .codex/agents + 沙箱化工作进程

如何在不同工具之间保持上下文一致：

1. AGENTS.md 是可移植的基线——这三个工具都会读取它。
2. 特定运行时的层（.claude/rules/、.codex/agents/、.cursor/rules/）可针对每种工具的优势扩展基线。
3. 仓库中的 docs/ 可供所有工具读取——应将知识沉淀在这里，而不是工具专属的记忆中。
4. 使用 dev-context-multi-repo 让多仓库上下文在不同工具之间保持一致。

反模式：在 Cursor 规则、Claude 规则和 Codex Agent 中重复相同约定。将其写入 AGENTS.md 或 docs/ 一次，然后引用即可。

当规范执行出现偏差或功能定义模糊成为瓶颈时，在 IDE 层之上叠加其他层：

层级	作用	可选项
L0 可移植基线	跨工具约定	AGENTS.md
L1 特定运行时	工具专属扩展	.claude/rules/、.codex/agents/、.cursor/rules/、.github/copilot-instructions.md、.clinerules/、Aider CONVENTIONS.md
L2 能力 / 方法论	按需启用或强制执行规范	Claude Code Skills · superpowers (obra/superpowers) · GSD (gsd-build/get-shit-done)
L3 工件流水线	规范 → 计划 → 任务 → 代码	GitHub Spec Kit (.specify/specs/) · OpenSpec (Fission-AI, openspec/changes/)

L0 是必需的；对于原生不读取 AGENTS.md 的工具，L1 是必需的；当出现相应的症状时，L2 和 L3 是可选项，但能带来显著收益。完整的决策矩阵、技术栈方案和反模式组合，请参阅 references/framework-selection-matrix.md。

工作流

1. 确定工具链、仓库结构，以及需要影响的行为。
2. 定义可移植基线、编译后的知识层，以及所需的最少特定运行时层。
3. 将热指令与温的编译知识、冷的原始证据区分开，供 Agent 按需检查。
4. 安装合适的辅助工件：规范、计划、钩子、规则、子 Agent、文档和索引页，让编译后的知识层便于导航。
5. 确定哪些答案或分析应转化为持久的 Markdown 文件、图表或报告，而不是一次性的聊天输出，并根据仓库的文档治理模型将其归档。
6. 当仓库中的工件足以支撑时，生成并验证上下文图。
7. 对上下文系统运行健康检查，排查过期依赖、缺少摘要、声明不一致和失效链接。
8. 评估成熟度，然后决定下一步是入门引导、精简还是自动化。

ASCII 流程图

context engineering request
  -> identify toolchain, repo shape, and target agent behaviors
  -> define portable baseline in AGENTS.md
  -> split layers
     +-- hot -> non-inferable execution policy
     +-- warm -> compiled docs, hubs, indexes, context graph
     +-- cold -> raw evidence and primary artifacts
  -> add runtime-specific rules only where they unlock capability
  -> run docs placement and context hygiene gates
  -> validate graph, freshness, links, and contradictions
  -> decide onboarding, pruning, automation, or maturity next step

核心决策

跨工具上下文模型

有意地使用分层：

• AGENTS.md 用于高频共享执行策略
• CLAUDE.md 和 .claude/* 仅用于 Claude 特定行为
• .github/* 仅用于 GitHub 或 Copilot 特定行为
• 已编译的 Markdown 信息中心、索引页和上下文图，用于可复用的代码库知识
• 原始证据包，用于文章、代码库、文字稿、屏幕截图及其他来源记录
• 文档和规范，用于按需提供上下文
• 通过技能、MCP 或运行时检索获取外部知识

不要假定一种工具的记忆模型可以直接映射到另一种工具。

对于小型和中型语料库，维护良好的索引加上简明摘要通常就够了；不要仅仅因为存在知识库就加入 RAG。

上下文中应包含的内容

始终保留以下上下文：

• 自定义命令和代码库工作流
• 安全或合规约束
• 脆弱的架构边界
• 已知故障模式和审批规则
• 难以从本地推断的跨代码库数据流

将以下内容保留在已编译的知识库中：

• 领域摘要和概念页面
• 跨代码库映射和架构视图
• 需要重新核查但仍值得保留的易变工具或产品发现
• 应随时间不断积累的衍生成果，例如报告、图表和幻灯片备注

不要纳入：

• README 风格的摘要
• 大型文件清单
• Agent 可以自行检查的依赖项列表
• 重复的编码风格理念
• 不会增加执行约束的文档
• 应放在证据文件夹而非高频指令层中的原始来源转储

文档归档位置判定器

创建上下文资料前，选择最精简且持久的存放位置：

• 高频指令：AGENTS.md / CLAUDE.md，仅用于简短的执行策略和指引
• 规范文档：docs/tech/、docs/architecture/、docs/api/ 或同类目录，用于记录稳定事实
• 运维文档：docs/operations/ 或 docs/runbooks/，用于流程以及事件处理／发布步骤
• 报告和计划：docs/reports/、docs/specs/ 或 docs/plans/，需注明生命周期状态和集成路径
• 生成的上下文：docs/context/ 或 context/，包含结构化输入和重建命令
• 原始证据：raw/、evidence/ 或代码库专用记录目录，并从高频上下文中排除

如果资料没有负责人、生命周期、索引链接或重建路径，就不要新建 Markdown 文件。更新最接近的规范文档，或将结果保留在任务讨论串中。

知识库模式

最可靠的默认方案是采用三层原生代码库系统：

• 高频层：可移植指令和执行策略
• 编译层：由大模型维护的 Markdown，包含摘要、反向链接、概念页面和索引文件
• 原始层：来源记录和证据，当需要重新核实编译后的主张时，Agent 可以回查

人类主要应编辑高频层并审阅编译层。如果设有验证和审查关卡，编译层和原始层大部分可以由 Agent 维护。

对于组合式信息中心，另加一条实用规则：

• 结构化资料（如个人资料 JSON、图谱 JSON 和新鲜度报告）应作为 Markdown 页面的编译器输入，而非各自独立、逐渐偏离的伴随文件

这样才能在大规模场景下保持代码库描述、概念笔记和系统映射同步。

上下文图谱

使用上下文图谱映射以下内容之间的关系：

• 指令
• 规则
• 规范
• 计划
• 钩子
• 子 Agent
• 参考资料和资产

当代码库达到 L2+ 成熟度时生成图谱，并在更改核心制品前用它评估加载层级、影响范围和过时依赖。

上下文图谱是对编译后的 Markdown 层的补充。使用图谱检查关系完整性并分析加载层级，然后将有用的发现整理回 Markdown 笔记或报告。

当代码库是原生或移动端代码库时，将此技能与以下技能配合使用：

• dev-context-multi-repo，根据 project.yml、.xcodeproj 或 Package.swift 等项目文件正确分类代码库
• dev-context-code-graph，在排除生成的构建目录后，从 Swift 或混合语言源代码构建单一代码库的符号图谱

规范驱动开发

当存在歧义、否则可能导致 Agent 偏离目标时，使用完整的规范驱动开发流程：

• 明确要做什么
• 规划如何实现
• 分解为范围明确的任务
• 附上适当的上下文后再实现

对于小型修复和低歧义工作，直接使用提示词。

对于定期维护中心站点，将页面生成视为一次编译器流程：

• 定义源制品
• 定义目标页面的结构
• 定义增量重新生成的内容
• 定义阻止发布的 lint 或健康检查

受监管环境

在受监管环境中，上下文工程必须维护：

• 可审计性
• 职责分离
• 敏感数据边界
• 提供商可移植性
• 明确到人的责任归属

如果这些要求确实存在，就应将上下文制品视为控制面的一部分，而不只是辅助文档。

输出模式

默认使用以下其中一种：

• 代码库上下文包： 可移植基线、特定运行时层和配套制品映射。
• 知识库运营模型： 热指令、编译后的 Markdown 层、原始证据布局和维护循环。
• 中心站点编译器设计： 源制品、生成的页面类型、增量重建策略和验证关卡。
• 迁移计划： 当前问题、目标结构、分阶段推出和验证步骤。
• 成熟度评估： 当前级别、阻碍因素和下一项基础设施步骤。
• 受监管环境推出简报： 控制要求、制品放置位置和审查关卡。

已知陷阱

• 将过多策略、流程和代码库知识塞入始终生效的指令，直到 Agent 忽略或截断真正重要的那一层。
• 在可移植基线稳定之前构建特定运行时的规则栈，这必然会导致不同工具之间出现偏差。
• 将编译后的 Markdown 中心站点当作静态文档，而不是需要通过新鲜度和验证循环来维护的产品。
• 在缺乏明确加载层级模型的情况下发布大规模上下文变更，导致热指令与冷证据混杂。
• 默认认为工具越多越好，而不是将工具集缩减到团队实际能够治理的最小规模。
• 为每个有用的答案都创建一个新的 Markdown 文件，而不是将其纳入现有文档、报告或生成上下文生命周期。
• 混杂运维手册、Agent 热记忆、规范文档和生成上下文，导致没有文件拥有明确的权威性。
• 在检索原始证据前先用大模型进行摘要。已测得的失败模式：在 LongMemEval 上，逐字文本检索的 R@5 得分为 96.6%，而在 ConvoMem 上，大模型提取记忆系统的得分为 30–45%——预先摘要会丢弃让答案能够被找到的上下文。保持原始层的原始状态。(来源 benchmarks/BENCHMARKS.md)

反模式

• 把所有内容塞进一个巨大的上下文文件。
• 将 AGENTS.md 当作通用知识库，而不是高优先级的指令层。
• 不加筛选地根据文档生成上下文。
• 不修正状态和结构，只是一味增加文本。
• 将策略锁定为某个供应商的格式。
• 把上下文当作静态内容，而不是需要维护的系统。
• 将执行关键指南保留在仓库之外。
• 让有用的答案消失在聊天记录中，而不将其归档到编译层。
• 将有用的答案存为未编入索引的一次性 Markdown 文件，且没有负责人、生命周期状态或规范上级文件。
• 在维护索引、摘要和基本健康检查之前，就引入繁重的检索基础设施。
• 将 JSON、图和 Markdown 页面视为彼此独立的事实来源，而不是编译流水线。

导航

• 核心参考资料：references/fast-track-guide.md、references/framework-selection-matrix.md、references/information-routing-rules.md、references/context-resolver-pattern.md
• 上下文图谱与多仓库策略：references/context-graph-guide.md、references/multi-repo-strategy.md
• 受监管及受治理环境的推行：references/regulated-environment-patterns.md、assets/ai-agent-governance.md、assets/data-handling-gdpr-pci.md、assets/compliance-fca-emi.md、assets/pr-template-ai-disclosure.md、assets/fca-compliance-gate.yml
• 脚本与架构：scripts/scan_context_artifacts.py、scripts/validate_context_graph.py、scripts/query_context_graph.py、schemas/context-graph.schema.json
• 相关技能：agents-memory 技能、docs-ai-prd、dev-workflow-planning、agents-hooks、agents-mcp、agents-subagents、agents-swarm-orchestration、dev-context-multi-repo、dev-context-code-graph

事实核查

• 已知 bug、回归问题、框架／编译器／运行时陷阱，以及特定版本的崩溃或变通方案指南，在作为当前事实使用前，必须通过当前的一手网络来源核实。
• 外部来源映射位于 data/sources.json。
• 产品功能、运行时语义和监管机构指南都可能变化；在对工具或合规时间表作出确定性说明前，请核实当前的一手来源。
• 删除或标注任何无法通过一手来源重新核实的说法。