规范驱动开发

为 AI 编码助手（Codex、Cursor、Claude Code）编写具备代码库感知能力的规范，以防止其偏离轨道。

LLM 代理状态： API 状态：

📦 安装

请在下方选择您的操作系统，并点击查看安装说明：

# 使用 Homebrew
brew install uv

# 或者使用 curl
curl -LsSf https://astral.sh/uv/install.sh | sh

uvx shotgun-sh@latest

curl -LsSf https://astral.sh/uv/install.sh | sh

uvx shotgun-sh@latest

# 设置执行策略（仅需一次）
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

💡 安装完成后请重启终端

为什么选择 uv？ 它比 pip 快 10 到 100 倍，并且能可靠地处理二进制轮子包——不会出现 cmake 或构建工具相关的错误。

需要帮助吗？查看 uv 安装文档

3. 开始使用

当你启动 Shotgun 时，它会引导你完成以下步骤：

小贴士： 在 IDE 的终端中运行 Shotgun，体验更佳。

🎥 演示

点击上方图片即可在 YouTube 上观看完整演示

🎯 使用方法

在项目目录中启动 Shotgun：

请先参阅适用于您平台的 安装说明！

uvx shotgun-sh@latest

计划模式与草稿模式

TUI 会自动打开。按 Shift+Tab 可在计划模式和草稿模式之间切换，或按 / 打开命令面板。

路由器的内部工作原理

在底层，路由器依赖于专门的子代理。你无需手动选择或管理它们。

计划模式和草稿模式是你唯一可以控制的执行模式；其余部分均由路由器自动处理。

模式切换： 按 Shift+Tab 可循环切换模式

⌨️ 键盘快捷键

获得更好结果的提示

结果： 你的 AI 编码代理将获得完整的上下文——现有内容、原因以及要构建的内容。

注意： CLI 已在 docs/CLI.md 中提供，但建议使用 TUI。

Context7 文档查找（实验性）

Research 代理可以通过 Context7 获取最新的库文档。配置后，代理在查找文档时会优先使用 Context7 而不是网络搜索。

要启用它，请设置你的 Context7 API 密钥：

shotgun config set-context7 --api-key <your-context7-api-key>

要移除它：

shotgun config clear-context7

🤝 与团队共享规格说明

在 付费 Shotgun 方案 上可以将规格说明共享到工作区。

Shotgun 允许你通过将其发布到 工作区 来对外共享规格说明。这会创建一个版本化的可共享快照，你的团队可以在仓库之外访问。

如何共享规格说明

1. 按下 / → 选择 将规格说明共享到工作区
2. 选择以下选项之一：

• 创建新规格 — 从当前 .shotgun/ 文件中发布一份全新的规格
• 添加新版本 — 发布现有规格的更新版本

3. 等待上传完成。完成后，你可以：

• 在浏览器中打开 — 查看工作区中的共享规格
• 复制 URL — 将链接分享给你的团队
• 完成 — 返回 Shotgun

你本地的 .shotgun/*.md 文件保持不变。
工作区包含的是规格说明的 可共享、版本化快照。

✨ 功能

使 Shotgun 不同之处

案例研究 - 实际例子：

我们曾需要实现支付功能。Cursor、Claude Code 和 Copilot 都建议构建自定义支付代理——这将需要 3-4 周的开发时间。

⭐ 而 Shotgun 的研究发现了一个名为 LiteLLM Proxy 的解决方案——仅需 30 分钟发现，5 天部署完成，第一个客户在 14 小时内接入。

开发时间减少了 80%。技术债务几乎为零。

📖 阅读完整案例研究

使用场景

• 🚀 新员工入职 - 新开发者？Shotgun 会绘制你的整个架构图，并生成与代码实际匹配的文档。
• 🔧 重构 - 在动手之前先了解所有依赖关系。避免重构变成重写。
• 🌱 新项目 - 在写下第一行代码之前，先调研全球范围内已有的解决方案。
• ➕ 添加功能 - 准确知道你的功能应该放在哪里。防止功能重复。
• 📦 迁移 - 绘制旧系统的架构图，规划新系统，跟踪差异。将迁移过程分解为安全的步骤。

📚 想看详细示例吗？ 请查看我们的 案例研究，其中展示了 Shotgun 在实际项目中的应用。

常见问题解答

问：Shotgun 会收集任何统计数据或数据吗？

答：我们只收集极少量的匿名事件（例如安装、服务器启动、工具调用）。我们不会收集具体内容——只记录事件的发生。我们使用 PostHog 进行分析和错误报告，以提高稳定性。

问：索引代码时，我的代码会离开我的电脑吗？

答：不会。当你索引代码库时，所有的索引操作都在你的本地机器上进行。索引存储在 ~/.shotgun-sh/codebases/ 中，永远不会发送到任何服务器。你的代码始终留在你的电脑上。

问：本地 LLM 支持？

答：正在计划中。我们会发布兼容性说明和本地提供商集成信息。

问：支持哪些 LLM 提供商？

答：目前支持 OpenAI、Anthropic（Claude）和 Google Gemini。本地 LLM 支持也在计划中。

问：我可以在离线状态下使用 Shotgun 吗？

答：你需要互联网连接来进行 LLM API 调用，但你的代码库仍然保留在本地。

问：代码图是如何工作的？

答：Shotgun 使用 tree-sitter 对你的代码库进行索引，以实现准确的解析，并创建一个可搜索的代码结构、依赖关系和相互关系图。

贡献

Shotgun 是开源项目，我们欢迎各方贡献。无论是修复 bug、提出功能建议、改进文档，还是传播消息——我们都期待你成为社区的一员。

贡献方式：

• Bug 报告： 发现问题了吗？创建 Bug 报告
• 功能请求： 有让 Shotgun 更好的想法吗？提交功能请求
• 文档： 发现文档中缺少内容吗？请求补充文档

不确定从哪里开始？ 加入我们的 Discord，我们会帮助你入门！

开发资源

• 贡献指南 - 环境搭建、工作流程与规范
• Git 钩子 - Lefthook、trufflehog 及安全扫描
• CI/CD - GitHub Actions 与自动化测试
• 可观测性 - 遥测、Logfire 与监控
• Docker - 容器化部署与运行

🚀 准备好阻止 AI 助手失控了吗？

规划 → 起草 — 两种执行模式为 AI 助手提供全局视角，并辅以内部阶段：研究 → 明确需求 → 规划 → 任务分解 → 导出。

uvx shotgun-sh@latest

⭐ 在 GitHub 上给项目加星

星标历史

许可证： MIT | Python： 3.11+ | 官网： shotgun.sh

卸载

uv tool uninstall shotgun-sh

Shotgun 快速上手指南

Shotgun 是一款专为 AI 编程助手（如 Cursor、Claude Code、Codex）设计的规范驱动开发工具。它能读取整个代码库，生成感知上下文的开发规范，并将大型功能拆解为可执行的阶段性任务，防止 AI 在复杂任务中“跑偏”。

环境准备

系统要求

• 操作系统：macOS, Linux, Windows (x64)
• Python 版本：3.11 - 3.13 (Windows 用户推荐 3.12)
• 终端环境：
  • macOS/Linux: 任意标准终端
  • Windows: 必须使用 PowerShell (不支持 CMD 或 VS Developer Shell)

前置依赖

Shotgun 依赖 uv 包管理器进行安装和运行。uv 比传统 pip 快 10-100 倍，且能可靠处理二进制轮文件。

💡 国内加速提示：如果直接安装 uv 速度较慢，可尝试配置国内镜像或使用代理网络。

安装步骤

请根据您的操作系统选择对应的安装命令：

macOS

# 1. 安装 uv (推荐使用 Homebrew)
brew install uv

# 或者使用 curl 安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 运行 Shotgun
uvx shotgun-sh@latest

Linux

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 运行 Shotgun
uvx shotgun-sh@latest

Windows (PowerShell)

请以管理员身份打开 PowerShell，依次执行以下命令：

# 1. 设置执行策略 (仅需执行一次)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# 2. 安装 uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 3. 将 uv 添加到当前会话的 PATH (或重启终端)
$env:Path = "C:\Users\$env:USERNAME\.local\bin;$env:Path"

# 4. (可选) 启用代码索引所需的运行时库
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

# 5. 运行 Shotgun
uvx --python 3.12 shotgun-sh@latest

注意：安装完成后，建议重启终端以确保环境变量生效。

基本使用

1. 启动工具

进入您的项目根目录，运行以下命令启动 Shotgun 的交互式界面 (TUI)：

uvx shotgun-sh@latest

2. 初始化流程

启动后，工具将自动引导您完成以下步骤：

1. 代码库索引 (Codebase Indexing)：构建整个仓库的可搜索图谱。
2. LLM 配置：设置您的 API Key (支持 OpenAI, Anthropic, Gemini 等)。
3. 首次研究：开始生成感知代码库的开发规范。

💡 最佳实践：建议在 IDE (如 VS Code, Cursor) 内置的终端中运行 Shotgun，以获得最佳体验。

3. 核心模式切换

Shotgun 提供两种主要执行模式，可通过快捷键随时切换：

4. 常用操作与快捷键

• 打开命令面板：按下 / 键，可输入指令或选择功能（如分享规范）。
• 取消操作/停止 Agent：按下 Escape 键。
• 查看使用统计：按下 Ctrl+U。
• 复制文本：选中文本后按 Ctrl+C (未选中时为中途中断)。

5. 使用技巧

为了获得最佳结果，建议遵循以下交互方式：

• ✅ 先研究后构建：输入 "Research how we handle auth" (研究我们如何处理认证)，让 AI 先理解现有架构。
• ✅ 提供上下文：明确告知背景，例如 "I'm working on payments, need refunds" (我在做支付模块，需要退款功能)。
• ✅ 利用规划模式：先在 Planning 模式下让 Shotgun 提出并细化计划，确认无误后再执行。
• ❌ 避免模糊指令：不要直接输入 "Add refunds" (添加退款) 而不提供任何上下文。

通过这种方式，您的 AI 编程助手将获得完整的上下文信息（现有代码、架构原因及构建目标），从而生成高质量的代码。