Selvedge 实战：让 AI 编程 Agent 为每次修改记录「为什么」

半年后回看自己的项目，git blame 只告诉你哪一行被谁改了——但永远不告诉你为什么改。如果那行代码是 AI 编程 Agent 写的，这个问题就更棘手了——Agent 的上下文窗口已经关闭，prompt 早已蒸发，留下的只有一条”Update schema”的 commit message。

Selvedge 就是来解决这个问题的：一个本地 MCP 服务器，让 Claude Code、Cursor、Copilot 等 AI 编程 Agent 在每次修改代码时，把为什么改记录下来。数据存在项目根目录的 .selvedge/selvedge.db（SQLite）中，纯本地、零依赖。

快速上手

安装非常简单：

pip install selvedge
cd your-project
selvedge setup

selvedge setup 是一个交互式向导，它会：

• 检测你使用的 AI 工具（Claude Code / Cursor / Copilot）
• 将 MCP 配置写入对应工具的配置文件中
• 把 Agent 指令块写入项目的 CLAUDE.md
• 初始化 SQLite 数据库
• 安装 git post-commit hook

如果你熟悉手动配置，也可以用四步法：selvedge init 初始化数据库，再按文档配置 MCP 和 prompt 文件。

核心 CLI 命令

Selvedge 的核心操作是记录和查询变更事件的”为什么”。以下是最常用的 CLI 命令：

记录变更

当 Agent 修改代码时，它会调用 log_change MCP 工具记录变更事件。你也可以手动记录：

selvedge log users.email modify \
  --diff "NOT NULL → NULL" \
  --reasoning "允许新用户注册时 email 可选，适配 GDPR 合规需求" \
  --changeset gdpr-compliance

--changeset 参数可以将多个跨文件的变更归一到同一个功能/任务名下，后续可通过 selvedge changeset 一网打尽。

查询历史

selvedge diff users.email

selvedge blame payments.amount

selvedge history --since 7d
selvedge history --since 15m  # 支持 m/h/d/mo/y 单位

selvedge blame 是核心功能——它输出的不是代码行，而是 Agent 当时记录的理由。比如：

$ selvedge blame users.email

  users.email
  Changed     2026-07-09 14:22:01
  Agent       claude-code
  Commit      abc1234
  Reasoning   User asked to add a grandfathering flag for legacy free-tier
              users during the pricing migration. Stores the original tier
              so we can backfill discounts without touching billing history.

功能/任务视角

大型功能往往涉及多个文件的修改。使用 --changeset 可以把关联变更一键归组：

selvedge changeset --list

selvedge changeset add-stripe-billing

全文搜索

selvedge search "stripe"

支持前缀查询，搜索 users 会匹配 users、users.email、users.created_at 等所有 users. 命名空间下的实体。

状态与健康检查

selvedge status       # 最近活动概览
selvedge stats        # 各 Agent 的 log_change 调用覆盖率
selvedge doctor       # 一键健康检查

MCP 工具（8 个）

当作为 MCP 服务器运行时，Selvedge 向 Agent 暴露 8 个工具：

其中 stale_decisions 是 v0.3.8 新增的功能：Agent 在记录变更时可以设置 revisit_after（如 180d），到期后 stale_decisions 会返回需要重新审视的决策——但只有实体仍被活跃使用时才会触发，不会因为旧决策没人碰就骚扰你。

与同类工具的对比

Selvedge 的核心差异化在于两个点：

1. 推理来源是 Agent 实时的意图，而非事后从 diff 推断。相比之下，AgentDiff、Origin 等工具在 git hook 触发后调用第二个 LLM 来反向生成解释，属于”事后猜测”而非”现场记录”。

1. 实体级别的粒度：不按行号归因，而是按数据库列、环境变量、API 路由、依赖等有语义的实体归因。你搜索的是 users.email 的历史而非 users.py:40-48 的行历史。

最佳实践

• 在项目 CLAUDE.md 中加入 Selvedge 的 Agent 指令块，让 Agent 每次修改代码时自动调用 log_change
• 为大型功能（如迁移付费方案、重构数据库 schema）使用固定的 --changeset 名称
• 对关键依赖（如 Stripe SDK）设置 revisit_after: 180d，让 Agent 定期审视是否需要升级
• 通过 selvedge export --format agent-trace 导出兼容 Cursor Agent Trace 标准的归因数据，打通跨工具的审计链路

Selvedge 不替代 git blame（行级别的 what/when），而是在它之上增加了 Why 层——一个让六个月后的你不需要猜当时在想什么的保险。

相关链接

• Selvedge GitHub
• Selvedge 官网
• PyPI: selvedge
• Agent Trace 规范