⚡

上下文漂移检测 ctx-drift

上下文漂移检测技能是一个用于管理和维护开发项目上下文文件的工具。它能够自动检测和修复项目文档中的过时路径、损坏引用、违反章程等问题，同时通过智能体分析识别语义层面的漂移，如过时的约定、被取代的决策和不相关的学习记录。该工具帮助开发团队保持项目文档与实际代码库的一致性，提高开发效率和协作质量。关键词：上下文管理、文档维护、代码一致性、开发工具、项目文档、自动化检测、语义分析、结构检查。

DevOps 0 次安装 0 次浏览 更新于 2/27/2026

name: ctx-drift description: “检测和修复上下文漂移。用于在.context/文件中查找过时路径、损坏引用和违反章程的情况。” allowed-tools: Bash(ctx:), Bash(diff:), Bash(mktemp:*), Bash(rm:cleanup temp), Read

在两层检测上下文漂移：通过ctx drift进行结构层（过时路径、缺失文件、违反章程）检测，以及通过智能体分析进行语义层（过时约定、被取代的决策、不相关的学习记录）检测。语义层才是真正有价值的地方——CLI无法做到这一点。

何时使用

  • 在会话开始时，开始工作前验证上下文健康状态
  • 重构、重命名或重大结构变更之后
  • 当用户询问“我们的上下文干净吗？”、“有没有过时的内容？”或“检查漂移”时
  • 当您注意到ARCHITECTURE.md或CONVENTIONS.md中的路径与实际文件树不匹配时，主动检查
  • 发布或里程碑之前，确保上下文准确

何时不使用

  • 当您刚运行过/ctx-status且一切看起来正常时（状态已显示漂移警告）
  • 在同一会话中重复运行，中间没有变化
  • 当用户正在执行任务中途时；不要用未经请求的维护工作打断用户

使用示例

/ctx-drift
/ctx-drift (重构后)

执行

漂移检测有两层：结构层（程序化）和语义层（智能体驱动）。始终执行两者。

第1层：结构检查

运行CLI工具进行快速程序化检查：

ctx drift

这会捕获死路径、缺失文件、过时指示符和违反章程的情况。这些检查是必要但不充分的——它们只检测结构问题。

第2层：语义分析

结构检查后，自己阅读上下文文件，并将其与您对代码库的了解进行比较。这是您增加真正价值的地方——CLI工具无法做到这一点。

检查：

  • 过时约定：CONVENTIONS.md描述的模式是否代码不再遵循？阅读相关区域的一些源文件进行验证。
  • 被取代的决策：DECISIONS.md是否包含被后续工作隐式覆盖的条目？查找其理由不再适用的决策。
  • 过时的架构描述：ARCHITECTURE.md描述的模块用途是否已更改？路径可能仍然存在，但其描述可能是错误的。
  • 不相关的学习记录：LEARNINGS.md是否包含关于已修复的错误或不再适用的模式的条目？
  • 矛盾：是否有任何上下文文件相互矛盾或与实际代码矛盾？

报告

两层检查后，不要转储原始输出。而是：

  1. 按严重性总结发现（结构警告、语义问题），使用通俗语言
  2. 解释每个发现：哪个文件、哪一行、为什么重要
  3. 区分结构和语义：结构问题可以自动修复；语义问题需要用户判断
  4. 提供自动修复结构问题的选项： “我可以运行ctx drift --fix来清理死路径引用。需要我这样做吗？”
  5. 为语义问题提出具体编辑建议： “CONVENTIONS.md仍然说‘使用fmt.Printf进行输出’，但我们三周前已切换到cmd.Printf。需要我更新它吗？”
  6. 在适当时建议后续命令：
    • 重构后有许多过时路径 → 建议ctx sync
    • 任务杂乱 → 建议ctx compact --archive
    • 文件数周未修改 → 建议审查内容

结果解读

发现 含义 建议操作
路径不存在 上下文引用了已删除的文件/目录 删除引用或更新路径
目录为空 引用的目录存在但没有文件 删除引用或填充目录
许多已完成的任务 TASKS.md杂乱 运行ctx compact --archive
文件30+天未修改 内容可能已过时 审查并更新或确认当前状态
违反章程 可能违反了硬性规则 立即修复
必需文件缺失 核心上下文文件不存在 使用ctx init或手动创建

自动修复

当用户同意自动修复时：

ctx drift --fix

修复后，再次运行ctx drift以确认剩余问题需要手动处理。报告已修复的内容和仍需要用户判断的内容。

技能模板漂移

运行ctx drift后，检查项目的已安装技能（.claude/skills/）是否与ctx附带的规范模板匹配。

步骤

  1. 创建临时目录并在其中运行ctx init --force以获取最新模板：

    CTX_TPL_DIR=$(mktemp -d)
cd "$CTX_TPL_DIR" && ctx init --force 2>/dev/null

  2. 将项目中的每个技能与模板进行比较：

    diff -ru "$CTX_TPL_DIR/.claude/skills/" .claude/skills/ 2>/dev/null

  3. 清理临时目录：

    rm -rf "$CTX_TPL_DIR"

技能漂移解读

发现 操作
项目中缺少技能 提供安装选项：从模板复制
技能与模板不同 显示差异；提供更新到最新模板的选项
项目有额外技能（无匹配） 这些是自定义的——不要动它们
无差异 技能是最新的；报告干净

报告技能漂移时，区分：

  • ctx管理的技能（存在于模板中）：这些通常应该匹配；差异意味着用户的副本已过时或是有意自定义的
  • 自定义技能（仅在项目中）：这些是用户添加的，不应标记为漂移

如果技能是有意自定义的，记下并继续。仅提供更新ctx管理技能的选项，并在覆盖前始终显示差异。

权限漂移

检查技能后，验证.claude/settings.local.json是否具有预期的ctx权限。此文件被git忽略，因此独立于代码库漂移。

步骤

  1. 读取.claude/settings.local.json并提取允许列表。

  2. 检查缺少的ctx默认权限。DefaultClaudePermissions（在internal/config/file.go中定义）中的每个条目都应存在。当前预期的集合是：

    • Bash(ctx:*) — 覆盖所有ctx子命令
    • Skill(ctx-*) — 每个ctx附带的技能一个条目

    要获取权威列表：

    ctx init --force 2>/dev/null  # 在临时目录中

    然后将生成的settings.local.json中的权限与项目的副本进行比较。

  3. 检查过时的技能权限。如果Skill(ctx-*)条目引用了.claude/skills/中不再存在的技能，标记它。

  4. 检查缺少的技能权限。如果ctx-*技能存在于.claude/skills/中，但在允许列表中没有相应的Skill(ctx-*)，标记它。

权限漂移解读

发现 操作
缺少Bash(ctx:*) 建议添加 — ctx工作所需
缺少Skill(ctx-*)条目 建议添加 — 技能每次都会提示
过时的Skill(ctx-*)条目 建议删除 — 死引用
细粒度的Bash(ctx <sub>:*) 建议合并到Bash(ctx:*)
一次性/会话垃圾条目 记下为卫生问题（参见hack/runbooks/sanitize-permissions.md）

重要

不要直接编辑settings.local.json。报告发现并让用户进行更改。此文件控制智能体权限——自我修改是安全问题。请用户参考hack/runbooks/sanitize-permissions.md了解手动清理过程。

主动使用

在以下情况下无需请求即可运行漂移检测：

  • 您在会话开始时加载上下文，并注意到路径引用与文件树不匹配
  • 用户刚完成重命名或移动文件的重构
  • TASKS.md明显杂乱（阅读时可见20多个已完成项目）

主动运行时，保持报告简洁：

重构后我运行了快速漂移检查。ARCHITECTURE.md中有两个过时路径引用——需要我清理它们吗？

质量检查清单

运行漂移检测后，验证：

  • [ ] 用通俗语言总结了发现（没有仅仅粘贴原始CLI输出）
  • [ ] 解释了每个发现为什么重要
  • [ ] 在运行前为可修复的问题提供了自动修复选项
  • [ ] 建议了适当的后续命令
  • [ ] 未经用户确认未运行--fix