docs(agents): port SOLID and code-standard rules from Infrahub

[ogenstad]

Why

The Infrahub repository carries four agent rules under .agents/rules. This repository carried only two of the four, and both were narrower than their Infrahub counterparts, so agents working in the SDK get materially less guidance on component design and code standards than agents working in the backend.

Goal: the same overall structure on both sides, written for the SDK rather than copied from Infrahub.

Non-goals: no code changes, no refactors to make existing code conform. Where existing code diverges from a new rule (an optional console on the JSON exporter, the module-level PROCESSOR_PER_KIND registry), it is left alone - the rules say explicitly not to drive-by refactor.

What changed

Two new rules:

• component-design.md - the SOLID/DI counterpart to Infrahub's backend-component-design.md, scoped to infrahub_sdk/**/*.py. Constructor injection, required rather than optional dependencies, building near the entry point, single entry point operating on arguments, SRP, interfaces for multiple implementations, interfaces to invert an out-of-domain dependency, runtime dispatch. Every example is drawn from this codebase: RateLimitRetryHandler for configuration resolving at the entry point, ExporterInterface / ImporterInterface and DataProcessor for interfaces, Recorder and InfrahubLogger for dependency inversion, ctl/exporter.py as the composition root.
• python-module-layout.md - constants.py holds constants only, imports stay at the top (PLC0415, which ruff already enforces everywhere but tasks.py), and the async/sync pair stays in one module.

Two extended rules:

• code-comments.md - adds "no references to other code" and a "what good documentation looks like" section. The SDK-specific carve-out: docs-generate publishes public docstrings to the reference docs, so those legitimately cross-reference other public API and get the full google-convention contract treatment, while inline comments stay minimal.
• python-testing.md - adds exact-expectation assertions, don't-test-the-framework, cheapest-test-tier, no-process-global-leakage, Recording* / Failing* doubles in place of mocks, and full-message anchored match= on pytest.raises. The duplicated assertion sentence in python-testing-unit.md now points at the shared rule.

Deliberately not ported

Infrahub content with no SDK analogue: db/branch constructor conventions tied to Neo4j, the Repository/Query persistence pattern, Prefect flows as entry points, StandardNode legacy notes, freezegun (not a dependency here - the SDK's now= parameter convention is documented instead), and GraphQL-response error assertions.

Also

tests/AGENTS.md's async example called client.execute(...), which does not exist, and asserted result is not None, which is the exact non-assertion the new testing rule forbids. Corrected to execute_graphql with a real expected value, so the example and the rules agree.

How to review

Read component-design.md first - it is the bulk of the diff and the one place where a claim about the codebase could be wrong. Each named example was checked against the source; the async/sync section is the one part with no Infrahub counterpart.

How to test

uv run rumdl check .

Passes on all 131 files. Documentation only, so there is nothing else to exercise.

Impact & rollout

• Backward compatibility: none affected, documentation only.
• Config/env changes: none.

Checklist

• Tests added/updated
• Changelog entry added (uv run towncrier create ...)
• External docs updated (if user-facing or ops-facing change)
• Internal .md docs updated (internal knowledge and AI code tools knowledge)

[cubic-dev-ai]

All reported issues were addressed across 6 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	92d0687
Status:	✅  Deploy successful!
Preview URL:	https://084717f1.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://pog-agent-rules-solid-standa.infrahub-sdk-python.pages.dev

View logs

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".agents/rules/component-design.md">

<violation number="1" location=".agents/rules/component-design.md:70">
P3: The claim that DataProcessor 'keeps ujson and the file layout out of the ctl command that drives them' is inaccurate for DataProcessor: it is driven by infrahub_sdk/spec/object.py via DataProcessorFactory.process_data, not by ctl, and involves neither ujson nor file layout. Scope that justification to ExporterInterface/ImporterInterface, or give DataProcessor its own reason (its processors are injected/selected in DataProcessorFactory rather than hard-coded into spec/object.py).</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The claim that DataProcessor 'keeps ujson and the file layout out of the ctl command that drives them' is inaccurate for DataProcessor: it is driven by infrahub_sdk/spec/object.py via DataProcessorFactory.process_data, not by ctl, and involves neither ujson nor file layout. Scope that justification to ExporterInterface/ImporterInterface, or give DataProcessor its own reason (its processors are injected/selected in DataProcessorFactory rather than hard-coded into spec/object.py).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .agents/rules/component-design.md, line 70:

<comment>The claim that DataProcessor 'keeps ujson and the file layout out of the ctl command that drives them' is inaccurate for DataProcessor: it is driven by infrahub_sdk/spec/object.py via DataProcessorFactory.process_data, not by ctl, and involves neither ujson nor file layout. Scope that justification to ExporterInterface/ImporterInterface, or give DataProcessor its own reason (its processors are injected/selected in DataProcessorFactory rather than hard-coded into spec/object.py).</comment>

<file context>
@@ -58,15 +58,22 @@ The corollary is a design test: if a rule can only be exercised through an await
 
 A single implementation does not need an interface yet; introduce one when the second implementation arrives. Note that the second implementation can be either a no-op version or a testing version of a component.
 
+`ExporterInterface` / `ImporterInterface` (`infrahub_sdk/transfer/`) and `DataProcessor` (`infrahub_sdk/spec/processors/`) each have exactly one implementer today, so they are not examples of this reason to declare an interface. They earn their place under the next heading instead: they keep `ujson` and the file layout out of the `ctl` command that drives them.
+
 ## Interfaces to keep an out-of-domain dependency out
</file context>

Suggested change

	`ExporterInterface` / `ImporterInterface` (`infrahub_sdk/transfer/`) and `DataProcessor` (`infrahub_sdk/spec/processors/`) each have exactly one implementer today, so they are not examples of this reason to declare an interface. They earn their place under the next heading instead: they keep `ujson` and the file layout out of the `ctl` command that drives them.
	`ExporterInterface` / `ImporterInterface` (`infrahub_sdk/transfer/`) each have exactly one implementer today, so they are not examples of this reason to declare an interface; they earn their place under the next heading instead by keeping `ujson` and the file layout out of the `ctl` command that drives them, and the transfer modules stay the only place that touches the filesystem.