s
shotgun-sh/shotgun
Spec Driven Development 🤠 Write codebase-aware specs for AI coding agents so they don't derail.
clicodebase-indexingdeveloper-toolsprdspec-driven-developmentspecification-generationtechnical-documentation
PythonMIT创建于 2025/8/5更新于 3 天前
README
由 Gemini 翻译整理
Spec-Driven Development (规范驱动开发)
为 AI 编码助手（如 Codex、Cursor、Claude Code）编写具备代码库感知能力的规范，防止它们偏离目标。
LLM Proxy 状态: 
API 状态: 
AI Agent 在处理小任务时表现出色，但在处理大型功能时往往会失控。 它们会丢失上下文、重复构建已有的功能，并在执行中途偏离规范。
Shotgun 解决了这个问题。 它会读取你的整个代码库，预先规划完整的功能实现，然后将其拆分为分阶段的 PR（Pull Request）——每个 PR 都包含 AI Agent 可以切实执行的逐文件指令。
你不再需要面对那种无人愿意审查的“万行代码怪兽级 PR”，而是得到 5 个目标明确、可直接交付的 PR。
它可以与 Cursor、Claude Code、Antigravity 或 Codex 完美协作。你可以自带 API Key (BYOK) 或使用 Shotgun 积分（10 美元 = 10 美元的使用额度）。
📦 安装
请根据你的操作系统点击下方链接查看安装说明：
► MacOS 安装说明（点击展开）
第一步：安装 uv
# 使用 Homebrew
brew install uv
# 或使用 curl
curl -LsSf https://astral.sh/uv/install.sh | sh
第二步：运行 Shotgun
uvx shotgun-sh@latest
► Linux 安装说明（点击展开）
第一步：安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
第二步：运行 Shotgun
uvx shotgun-sh@latest
► Windows 安装说明（点击展开）
打开 PowerShell 并运行以下命令：
# 设置执行策略（仅需执行一次）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
# 安装 uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 添加到 PATH（或重启终端）
$env:Path = "C:\Users\$env:USERNAME\.local\bin;$env:Path"
# 可选：启用代码索引（请以管理员身份运行）
Import-Module BitsTransfer
Start-BitsTransfer -Source "https://aka.ms/vs/17/release/vc_redist.x64.exe" -Destination "$env:TEMP\vc_redist.x64.exe"
Start-Process -FilePath "$env:TEMP\vc_redist.x64.exe" -ArgumentList "/install", "/quiet", "/norestart" -Wait
# 运行 Shotgun
uvx --python 3.12 shotgun-sh@latest
| 支持 | 不支持 |
|---|---|
| Windows x64 (普通 PC) | 32-bit Python |
| Python 3.11-3.13 | Python 3.14+ (尚未提供 wheels) |
重要提示： 请在 PowerShell 中运行，不要使用命令提示符 (CMD) 或 VS Developer shell。
💡 安装完成后请重启终端
为什么选择 uv？ 它比 pip 快 10-100 倍，并能可靠地处理二进制 wheels —— 告别 cmake/构建工具错误。
需要帮助？查看 uv 安装文档
3. 开始使用
当你启动 Shotgun 时，它会指引你完成以下步骤：
| 步骤 | 说明 |
|---|---|
| 1. 代码库索引 | 构建整个仓库的可搜索图谱 |
| 2. LLM 设置 | 配置 OpenAI、Anthropic 或 Gemini |
| 3. 初次调研 | 开始生成具备代码库感知能力的规范 |
💡 专业建议： 在 IDE 的终端中运行 Shotgun 以获得最佳体验。
🎥 演示
点击上方图片在 YouTube 上观看完整演示
🎯 用法
在项目目录下启动 Shotgun：
请先参考安装说明完成环境配置！
uvx shotgun-sh@latest
规划模式 (Planning) vs 草稿模式 (Drafting)
| 模式 | 工作原理 | 适用场景 |
|---|---|---|
| 规划 (默认) | Shotgun 会提出执行计划，展示每个步骤，并在执行修改文件的 Agent 前请求确认。你可以获得检查点，并在执行前优化计划，确认或跳过连锁更新。 | 当你需要控制权、可见性，以及在执行前优化计划时。 |
| 草稿 | Shotgun 一次性运行完整计划，无需中间确认。进度仍会在内部跟踪，但不会在每一步进行提示。 | 当你对计划充满信心，且希望快速、端到端地执行时。 |
TUI 会自动打开。按 Shift+Tab 可在规划模式与草稿模式之间切换，按 / 可打开命令面板。
Router 的内部工作原理
在底层，Router 依赖于专门的子 Agent。你无需手动选择或管理它们。
🔬 研究 (Research) -> 探索并理解 → 📝 规范 (Specify) -> 定义需求 → 📋 规划 (Plan) -> 创建路线图 → ✅ 任务 (Tasks) -> 拆分为步骤 → 📤 导出 (Export)