/ 目录 / 演练场 / drift
● 社区 dadbodgeoff ⚡ 即开即用

drift

作者 dadbodgeoff · dadbodgeoff/drift

为 Claude 提供代码库约定和架构决策的长期记忆——跨越每个对话,而不仅仅是当前对话。

drift 是一个代码库智能 MCP 服务器。它会扫描你的代码库,提取模式和约定(命名、错误处理、分层),跨对话记住架构决策,这样每个新对话都能继承你团队的背景。还可以离线作为 CLI 使用。

为什么要用

核心特性

实时演示

实际使用效果

drift.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "drift": {
      "command": "uvx",
      "args": [
        "drift"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "drift": {
      "command": "uvx",
      "args": [
        "drift"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "drift": {
      "command": "uvx",
      "args": [
        "drift"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "drift": {
      "command": "uvx",
      "args": [
        "drift"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "drift",
      "command": "uvx",
      "args": [
        "drift"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "drift": {
      "command": {
        "path": "uvx",
        "args": [
          "drift"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add drift -- uvx drift

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: drift

让 AI 助手适应你代码库的约定

👤 那些厌倦了不断纠正 Claude('不,我们这里不用类')的技术负责人 ⏱ ~20 min beginner

何时使用: 处理新代码库的首个对话,或大重构改变约定后。

前置条件
  • drift 已安装 — uvx drift 或全局安装
步骤
  1. 运行初始扫描
    在这个代码库上运行 drift scan。告诉我你在错误处理、模块结构和命名方面检测到的模式。✓ 已复制
    → 具体约定总结及示例
  2. 记录你想保留的决策
    记录这些团队决策:我们使用 Result<T,E> 而不是异常,每个功能文件夹一个控制器,文件名使用 snake_case。标记为 'conventions'。✓ 已复制
    → 确认;稍后可查询条目
  3. 验证未来对话会接收
    在新对话中:这个代码库遵循什么约定?✓ 已复制
    → Claude 朗诵你记录的决策

结果: 每个未来的 AI 对话都会加载你团队的约定——更少纠正,更高效的对话。

注意事项
  • 模式从现有代码推断,包括不好的代码 — 审查初始扫描,删除任何实际上是你想摆脱的技术债的'约定'
  • 如果你忘记更新,决策记忆会与现实脱离 — 像对待文档一样对待记忆条目——定期审查
搭配使用: filesystem · github

在 PR 审查期间强制执行团队约定

👤 代码审查者 ⏱ ~10 min intermediate

何时使用: 批准 PR 前,检查它是否无声地破坏了团队模式。

步骤
  1. 加载这个 PR 的 diff
    加载 PR #213 的 diff,并与 drift 记录的约定进行比较。✓ 已复制
    → 约定匹配和偏差列表
  2. 为偏差起草审查评论
    对于每个偏差,起草一个礼貌的审查评论,引用约定。✓ 已复制
    → 每个发现的评论文本

结果: 一致的 PR 审查,而无需审查者记住每条不成文的规则。

注意事项
  • 新模式可能是有意的——不要教条 — 让作者用'新模式'决策覆盖,该决策会被记录供未来 PR 使用
搭配使用: github

维护一个轻量级的架构决策日志

👤 任何不断忘记为什么做出选择的团队 ⏱ ~5 min beginner

何时使用: 替代很少更新的正式 ADR 文件夹。

步骤
  1. 在做出决策时记录
    记录决策:我们选择 Postgres 而不是 DynamoDB,因为需要临时查询。日期:今天。标签:db、architecture。✓ 已复制
    → 条目已保存,带 ID
  2. 稍后当问题再次出现时查询
    我们为什么选择 Postgres?✓ 已复制
    → 存储的决策显示

结果: 跨越人员流动的制度记忆。

组合

与其他 MCP 搭配,撬动十倍杠杆

drift + filesystem

drift 了解约定,filesystem 进行编辑

使用 drift 记录的约定,重构 src/api/users.ts 以匹配。使用 filesystem 应用编辑。✓ 已复制
drift + github

根据记录的约定审查传入的 PR

获取 PR #88,根据 drift 约定进行检查,为任何偏差起草审查评论。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
scan_codebase path: str 首个对话,或大型重构后 free; CPU-bound
list_conventions tag?: str 在对话开始时加载上下文 free
record_decision title: str, body: str, tags?: str[] 当团队同意某些不显而易见的东西时 free
query_memory query: str 当 Claude 应该回忆过去的背景时 free (local embeddings)
detect_pattern area: str 临时'我们通常在这里怎样做 X?' free

成本与限制

运行它的成本

API 配额
无——完全本地
每次调用 Token 数
约定总结:~1k tokens。完整扫描转储可能 10k+
费用
免费开源
提示
在对话开始时加载摘要约定,而不是完整扫描。仅在重构时进行完整扫描。

安全

权限、密钥、影响范围

凭据存储: 仅限本地 SQLite 或文件系统
数据出站: 默认无——完全离线运行

故障排查

常见错误与修复

扫描在大型单仓库上挂起

通过 .driftignore 排除生成和供应商目录(语法与 .gitignore 相同)。

验证: drift scan --dry-run
内存查询不返回相关内容

重建本地嵌入索引;新决策在索引前不会显示。

验证: drift reindex
Claude 不使用记录的约定

确保 MCP 在你的客户端配置中排在第一位,这样它的上下文在每个对话开始时加载。

验证: claude mcp list

替代方案

drift 对比其他方案

替代方案何时用它替代权衡
MARM-Systems你想要不特定于代码的通用跨对话记忆代码感知更少;更一般的笔记
llm-context.py你想要规则驱动的代码捆绑而不是记忆无持久化层
代码库中的 ADR你更喜欢文档即代码AI 必须在每个对话中阅读它们——更高的 token 成本

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills