NetBox Best Practices for AI Coding Agents

We’re seeing something awesome in the NetBox community: engineers are increasingly turning to AI coding agents like Claude Code and Cursor to build automations and integrations with NetBox. Whether you’re pulling device inventories into a compliance system, syncing IPAM data with a cloud provider, or building custom workflows, these AI tools can accelerate development dramatically.

But here’s the thing – building integrations that work is different from building integrations that work well at scale. The difference between a weekend prototype and a production-ready automation often comes down to understanding NetBox’s API quirks, performance characteristics, and data model nuances. Over the years, we’ve seen teams hit the same stumbling blocks: GraphQL queries that crawl because they forgot to paginate nested relationships, REST calls that timeout because they’re fetching config_context on thousands of devices, or integrations that break during upgrades because they relied on v1 tokens.

We want to make building with NetBox as easy as possible. So today, we’re publishing a repository of best practices for NetBox integrations, packaged for both AI coding agents and human engineers.

What’s in the Repository?

This repository captures years of lessons learned from supporting users in the NetBox community and working with customers at NetBox Labs. The content is organized into practical rules covering:

• Authentication – v2 token migration, provisioning endpoints
• REST API – pagination, brief mode, filtering, bulk operations
• GraphQL – query optimization, complexity budgets, depth limits
• Data modeling – dependency ordering, hierarchies, custom fields
• Performance – config_context exclusion, brief mode at scale
• Integration patterns – Diode for simplified ingestion, webhooks, pynetbox

Each rule includes the rationale (why it matters), incorrect and correct patterns (so your agent knows what to look for), and exceptions (because context matters).

Three Formats, One Source of Truth

We’ve packaged this content for different audiences:

The detailed rules in skills/*/references/rules/ are the authoritative source. The other formats are derived from these, so everything stays aligned.

Getting Started

For Claude Code Users

Clone the repository anywhere on your machine:

Claude Code will automatically discover the skills. When working on a NetBox integration, try asking:

“Check this repository against NetBox integration best practices and tell me what improvements we should make.”

Or when starting a new integration:

“I’m building a script to generate a weekly capacity report from NetBox data. What should I consider based on NetBox best practices?”

For Cursor IDE Users

Clone the repository and open it alongside your project, or copy the .cursor/rules/ directory into your own repo:

Cursor will apply rules based on file patterns as you work.

For Engineers

Start with HUMAN.md – it’s a concise orientation covering all the key practices. When you need more detail on a specific rule, the individual rule files in skills/*/references/rules/ have the full rationale and examples.

Best Practices are Always Evolving

The NetBox ecosystem is evolving rapidly. We’re shipping new capabilities regularly – Diode for simplified data ingestion, enhanced GraphQL features, v2 tokens for better security – and the best practices need to evolve with them.

We’ll keep this repository current as we ship new capabilities. If you hit an edge case we haven’t covered, or find a pattern that works well for your team, let us know. Open an issue, submit a PR, or drop into the NetBox community Slack. We’d love to hear what you’re building. xGet started: github.com/netboxlabs/netbox-best-practices