Shotgun: AI Agents That Actually Follow Specs
The Problem
AI coding agents are great at cranking out code, but they’re also loose cannons. Ask them for a feature, and you’ll get a Frankenstein PR with broken specs, redundant code, and files nobody asked for. Reviewing a 10k-line PR? Good luck. Most agents treat your codebase like a sandbox, not something with rules and structure.
What This Does
Shotgun fixes the chaos. It reads your entire codebase, understands the structure, and plans features upfront like a real engineer. Then it splits the work into bite-sized, codebase-aware PRs with detailed instructions for AI agents like Codex, Claude Code, or Cursor.
The src/shotgun/agents directory is where the magic happens. For example, agents/autopilot/stagemonitor.py orchestrates staged tasks while agents/config/manager.py handles codebase config parsing. Shotgun doesn’t blindly guess—it builds a dependency graph (agents/autopilot/dependencygraph.py) and uses structured prompts (agents/autopilot/prompts) to keep the AI on track.
Testing isn’t just an afterthought either. The evals/ folder has files like routerevaluators.py and clarifyingquestionscases.py, which simulate scenarios to ensure agents understand what the hell they’re doing.
Real-World Use
Say you need to refactor a messy utils.py. Normally, you’d ask an AI agent, and it might rewrite half your project in the process. With Shotgun, it scans your codebase, understands dependencies, and breaks the refactor into stages. First, it’ll document the changes (docs/CONTRIBUTING.md), then handle file-by-file updates (agents/tools/codebase/directorylister.py), and finally write tests in tests/. Instead of one bloated PR, you get a manageable flow of incremental changes.
Here’s a typical workflow:
The Bottom Line
Shotgun is a niche tool with specific use cases. If you’re juggling complex features or working with AI agents on a production codebase, it’s a lifesaver. But for small projects or one-off scripts, it’s probably overkill. The staged PRs are great for collaboration, but the setup can feel heavy. Use it if you’re tired of AI agents derailing your codebase. Otherwise, stick to manual reviews or simpler tools.