为什么 AI 编码代理会"跑偏"？

如果你用过 Cursor、Claude Code 或 GitHub Copilot，大概率遇到过这种情况：AI 很擅长写小功能，但一遇到大需求就"脱轨"——忘记上下文、重复造已经存在的轮子，或者写一半就不按需求来了。

Shotgun就是为解决这个问题而生的：它是一个Spec Driven Development（规格驱动开发）CLI 工具，专为 AI 编码代理（Codex、Cursor、Claude Code）编写"代码库感知"的规格说明，让它们不再跑偏。

Shotgun 的工作方式很简单：先读懂你的整个代码库，提前规划完整功能，再拆成多个带阶段检查点的 PR——每个 PR 都附带逐文件的执行说明，AI 代理可以直接照着做。与其得到一个没人能 review 的万行巨型 PR，不如得到 5 个能顺利合入的小 PR。

真实案例：支付系统，3-4周变5天

这个案例来自 Shotgun 团队自己的真实项目（完整案例见 docs/CASE_STUDY.md），团队只有 3 个人，时间点是 2025 年 10 月。

需求背景

他们正在开发一个 AI Agent 平台，用户通过平台调用 LLM API。需要为用量收费，且不能暴露自己的 API Key。具体需求：

• 对 LLM 调用做实时用量追踪
• 基于用量的计费
• API Key 保护（用户永远看不到真实密钥）
• 全局、团队、用户三级预算限制
• 与现有 Pydantic AI 架构兼容

传统做法：AI 集体建议"自建"

他们先后咨询了 Cursor、Claude Code 和 GitHub Copilot——三个 AI 给出了一模一样的答案：自己写一个定制 LLM 代理，工作量 3-4 周：

这些建议在技术上"说得通"，但没有任何一个 AI 问过那个最关键的问题："这个东西是不是已经存在了？"

秘诀：先 Research，再写代码

团队决定让 Shotgun 先做调研，而不是直接让 AI 写代码。他们只给了一个不带预设方案的问题描述，把需求列清楚，不给任何架构假设。

Shotgun 的 Research 阶段跑了四条并行轨道：

1. 代码库分析：读取整个仓库，理解现有模式、依赖和架构——找到了他们的 Pydantic AI 配置和认证模式
2. 外部调研：搜索现有解决方案，覆盖免费和付费、成熟和实验性方案
3. 交互式澄清：主动提问缩小范围，例如"实时追踪还是批量处理就够？""预算约束是开发人时还是基础设施成本？"
4. 方案评估：把候选方案对照你的约束条件逐一比较

总耗时：30 分钟，其中大部分是 Shotgun 在读取一些他们从没听说过的解决方案的文档。

30 分钟找到 LiteLLM Proxy

调研结果：LiteLLM Proxy——团队成员此前完全不知道它的存在。它正好覆盖了他们本想全部自建的能力：

• ✅ 用量追踪：每次请求的实时花费指标，内置
• ✅ 预算限制：全局/团队/用户三级，触顶即停，内置
• ✅ API Key 保护：虚拟 Key 机制，用户看不到真实密钥
• ✅ Pydantic AI 兼容：改一下 endpoint URL 即可
• ✅ 基础设施成本：自托管约 $100/月
• ✅ 需要写的代码：一份 58 行的配置文件（精确到行）

对比一下差点做成的方案：

💡 上图展示了 Shotgun 的本地索引流程：索引存储在~/.shotgun-sh/codebases/，全程在本机完成，代码不会发送到任何服务器。

结果：5 天上线，14 小时收到第一笔付费

最终账本：

• 开发时间：5 天 vs 3-4 周，减少 80%
• 测试量：减少 90%（用成熟基础设施替代自定义代码）
• 新增代码：58 行配置 vs 代码库规模翻倍
• 基础设施：约 $100/月 vs 数千美元的开发人力 + 持续维护
• 技术债：接近零

团队把省下的时间全部投回了核心产品功能，而不是基础设施。

上手指南：安装 Shotgun 的最快路径

一键安装步骤

Shotgun 基于 Python 3.11+，通过uv安装（比 pip 快 10-100 倍，且可靠处理二进制依赖）。

macOS：

brew install uv uvx shotgun-sh@latest

Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh uvx shotgun-sh@latest

Windows（在 PowerShell 中执行）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex" uvx --python 3.12 shotgun-sh@latest

首次启动的 3 个引导步骤

在你的项目目录下运行 Shotgun 后，它会引导你完成三件事：

📌 提示：在 IDE 的内置终端里运行体验最佳；Windows 用户记得安装后重启终端。

内部机制：Router 驱动的 5 阶段流水线

Shotgun 的架构核心是Router（路由器）代理，它负责理解用户意图、创建执行计划，并把工作委派给 5 个专业子代理——你不需要手动管理它们：

🔬 Research（调研）→ 📝 Specify（规格）→ 📋 Plan（计划）→ ✅ Tasks（任务拆分）→ 📤 Export（导出）

每个阶段由独立的专用代理执行，配有量身定制的 prompt。核心实现分别在：

• Router 编排逻辑：router.py（委派工具注册处）
• Research 代理工厂：research.py
• 规划、任务、导出代理：plan.py、tasks.py、export.py

Planning 与 Drafting 两种执行模式

TUI 中按Shift+Tab即可切换模式，/打开命令面板。

产出物：落在 .shotgun/ 目录

每轮工作流结束后，结果以 Markdown 形式写入项目根目录的.shotgun/：

最后这个AGENTS.md可以直接被 Cursor、Claude Code、Windsurf、Lovable 等工具读取——不被锁定在任何一个 IDE 或代理上。

日常使用技巧：让效果最好的 4 个习惯

日常自动化可以用 CLI（完整命令见 docs/CLI.md）：

# 非交互模式跑调研+规划（适合 CI/CD） shotgun run -n "Research OAuth2 best practices and create an implementation plan" # 查看 token 用量 shotgun context --format markdown

什么时候该用"先调研后编码"？

案例研究总结了 5 类典型场景（详见 docs/CASE_STUDY.md）：

• 🚀 新人上手：生成真正匹配代码的架构文档，而非过时的 wiki
• 🔧 重构：动手前看清所有依赖，防止"重构变重写"
• 🌱 绿地项目：写第一行代码前先全局调研现有方案——LiteLLM 就是这样的收获
• ➕ 新增功能：精确知道功能该放哪，防止功能重复
• 📦 迁移：映射旧系统、规划新系统、跟踪差异，拆成安全的小阶段

判断标准：影响代码库多处、产生持续维护负担、可能存在现成方案、或准备写超过 500 行新代码时，先调研。修 bug、小 UI 调整、直接 CRUD 则不需要。

总结：AI 让你建得快，不让你知道该建什么

这个案例最大的启示是：AI 编码工具让你快速"建造"，但不让你快速知道"该建什么"。

• Cursor、Claude Code、Copilot 都能秒出方案，但没有一个会问"这东西是不是已经存在了"
• Shotgun 把"读整个代码库 + 调研外部方案 + 写带上下文的规格 + 交付给 AI 代理"这套流程自动化了——手工做这件事比直接写代码还耗时，这正是它存在的意义
• 支付系统的结果：30 分钟调研找到 LiteLLM Proxy，5 天上线，14 小时收到第一笔付费，研发时间减少 80%，技术债接近零

下一个大功能动手前，先问自己两个问题：

"这东西已经存在了吗？它和我们现有的东西怎么集成？"

如果答不上来，那就先用 Shotgun 把 Research 阶段跑完。参考文档：docs/CASE_STUDY.md（完整案例）、docs/CLI.md（CLI 命令）、README.md（项目总览）。