shuxueshuxue/Spexcode

解决的问题

SpexCode 解决了「规范漂移」问题，即 AI 编码代理修改源代码的速度快于描述这些代码的文档（规范）更新的速度。这通常会导致文档不再准确反映系统的实际行为。

工作原理

SpexCode 创建了一个基于 Git 的系统，将规范存储在 .spec/ 目录中的 Markdown 文件中。每个规范都「锚定」到代码中的特定文件或函数。通过分析 Git 提交记录，SpexCode 能检测到某个提交修改了锚定范围内的代码，但未更新对应的规范。这种情况被识别为「锚定漂移」（anchor-drift）。

要解决漂移问题，用户必须要么更新规范以匹配代码，要么明确承认（ack）实现变更仍然满足现有契约。

该系统分为三个层级：

1. L0（规范-代码图）：Git 中规范与代码之间的核心绑定关系。
2. L1（代理会话）：为每个代理创建独立的 worktree 和分支，确保变更被追踪并关联到其所影响的规范。
3. L2（仪表板）：用于审查会话和管理规范的 GUI。

适用人群

使用 AI 编码代理（如 Claude Code 或 Codex）并希望严格保持技术规范与实现同步的开发者。

主要亮点

• 确定性漂移检测：利用 Git 历史精确计算出规范停止描述代码的时间点。
• 原生 Git 支持：不存储独立数据库；所有漂移和版本控制数据均来自 Git 提交。
• 代理隔离：通过 tmux 在独立分支和 worktree 中运行代理，防止相互干扰。
• 集成支持：提供 Claude Code 和 Codex 的插件，以及 CLI 和专用仪表板。
• 强制执行：若检测到锚定漂移，可通过 Git 钩子阻止提交。