---
title: "Principles"
description: "These working principles govern how SDK teams collaborate, review, and ship. They build on the SDK philosophy, which governs what we build and how our SDKs should behave."
url: https://develop.sentry.dev/sdk/getting-started/principles/
---

# Principles

## [Every line has an owner](https://develop.sentry.dev/sdk/getting-started/principles.md#every-line-has-an-owner)

Whether code is written by a human, an AI tool, or a collaboration, a human is accountable for every line that merges. The author's name on the PR is the owner. "The AI suggested it" is never a justification in review.

## [Raise the floor](https://develop.sentry.dev/sdk/getting-started/principles.md#raise-the-floor)

Guidelines exist to make the minimum quality of all contributions higher - internal and external, human and AI-assisted. A rising floor is more valuable than a rising ceiling.

## [Automate the obvious, judge the nuanced](https://develop.sentry.dev/sdk/getting-started/principles.md#automate-the-obvious-judge-the-nuanced)

If a rule can be checked by a machine, it must be checked by a machine. Human review time is the scarcest resource on the team - reserve it for decisions that require judgment: architecture, API design, user impact.

## [Alignment before implementation](https://develop.sentry.dev/sdk/getting-started/principles.md#alignment-before-implementation)

For non-trivial changes, agree on the approach before writing code. This applies to internal engineers as much as external contributors. An issue before a PR, and in important cases a spec before a PR. This is more important in the AI era, not less - generating code is cheap, but generating the wrong code wastes reviewer time. PRs without prior alignment will be closed without review.

## [Tests prove behavior, not coverage](https://develop.sentry.dev/sdk/getting-started/principles.md#tests-prove-behavior-not-coverage)

Tests exist to verify the SDK does what users expect. A test that asserts nothing meaningful is worse than no test - it creates false confidence. This matters doubly for AI-generated tests, which frequently look correct but verify nothing. In the end, coverage is a diagnostic tool, not a goal in itself.

## [Document the why](https://develop.sentry.dev/sdk/getting-started/principles.md#document-the-why)

Code shows what. Commit messages, PR descriptions, and design docs explain why. This context is essential for future humans and AI tools working in the codebase. A commit with no explanation is a debt on every future reader.

## [Consistency across SDKs, idiom within each](https://develop.sentry.dev/sdk/getting-started/principles.md#consistency-across-sdks-idiom-within-each)

Users of multiple Sentry SDKs should recognize the same concepts, behaviors, and terminology. But each SDK should feel native to its language and ecosystem. Cross-SDK standards define the concept, while per-SDK standards define the expression. Deviations from cross-SDK standards require explicit justification.

## [Ship small](https://develop.sentry.dev/sdk/getting-started/principles.md#ship-small)

Small changes are easier to review, easier to revert, and easier for AI tools to generate correctly. Prefer multiple small PRs over one large one. A PR that does one thing well is worth more than a PR that does three things adequately.

## [Every change needs a reason](https://develop.sentry.dev/sdk/getting-started/principles.md#every-change-needs-a-reason)

Changes must solve a real problem. No speculative refactors, no "improvements" without a linked issue or measurable benefit. This gives engineers standing to reject changes - from humans or AI tools - that lack clear motivation. See [Customer Value Matters](https://develop.sentry.dev/sdk/getting-started/philosophy.md#customer-value-matters) for more information.

## [Never capture your own exceptions](https://develop.sentry.dev/sdk/getting-started/principles.md#never-capture-your-own-exceptions)

SDKs must never capture Sentry events for exceptions happening within the SDK itself, including within user-defined [callbacks and hooks](https://develop.sentry.dev/sdk/foundations/client/hooks.md) such as `before_send` or `traces_sampler`. We are already in an event capturing flow where the [scope](https://develop.sentry.dev/sdk/foundations/state-management/scopes.md) has been applied - capturing another event at that point would lead to undefined behavior. In the worst case, it creates a busy loop of creating and sending events repeatedly until the system crashes. If the SDK throws, swallow gracefully and emit an error-level log. In mobile SDKs, unhandled crashes will still make it to Sentry via crash handlers. See [SDK Crash Detection](https://github.com/getsentry/sentry/tree/master/src/sentry/utils/sdk_crashes#sdk-crash-detection) for more details.

## [Integrate at the lowest level](https://develop.sentry.dev/sdk/getting-started/principles.md#integrate-at-the-lowest-level)

SDKs should integrate on the lowest level possible to capture as much of the runtime as they can. Hooking the runtime or a framework directly is preferred over requiring users to subclass specific base classes or mix in helpers. For example, the Python SDK monkey-patches core functionality in frameworks to automatically pick up on errors and integrate scope handling.

## [Async-first](https://develop.sentry.dev/sdk/getting-started/principles.md#async-first)

Work must be understandable without attending a meeting. Decisions, context, and outcomes belong in issues, docs, and PRs — not in someone's memory or a Slack thread.

## [Meetings are accelerators, not storage](https://develop.sentry.dev/sdk/getting-started/principles.md#meetings-are-accelerators-not-storage)

A meeting may clarify and unblock, but it is never the record of what was decided. Every meeting that produces a decision must produce a written summary. The conversation ends; the document persists.

## [If it's not written, it's not a rule](https://develop.sentry.dev/sdk/getting-started/principles.md#if-its-not-written-its-not-a-rule)

If you expect engineers (or AI tools) to follow a practice, it must be in a document that's discoverable and machine-readable. Verbal norms and tribal knowledge don't scale, and AI tools can't read them at all. See [Write Down the Rules](https://develop.sentry.dev/sdk/getting-started/philosophy.md#write-down-the-rules) for more information.