[gnufede]

Description

Local lifecycle workarounds can erode modularity even when they pass tests. Make component ownership an explicit design checkpoint so shared concerns are fixed in their owning layer.

Changes

• Identify warning signs: private cross-component access, consumer notifications about owner state, repeated per-product repairs, lock coupling, and accumulating review patches.
• Encourage refactoring the owning layer, including dependencies such as libdatadog, while explaining temporary workarounds.
• Use native runtime recovery and exporter telemetry boundaries as concrete examples, and require regression tests to demonstrate the original failure and observable state preservation.
• Treat these signs as prompts for investigation rather than prohibitions on valid callbacks or lifecycle hooks.

Testing

Reviewed the guidance against the supplied runtime and telemetry examples and existing lifecycle documentation. The targeted AGENTS.md spelling check passed. Repository lint checks completed with exit code 0 and existing-source warnings; the native-format step could not resolve origin/main in this checkout, limiting its base comparison. Runtime tests and benchmarks were not run because only contributor instructions changed.

Risks

Guidance could be applied too broadly; the text explicitly allows valid callbacks, lifecycle hooks, and lock invariant documentation.

Additional Notes

No release note is needed because this only changes coding-assistant guidance and has no customer-visible runtime impact.

---

PR by Bits - View session in Datadog

Comment @DataDog to request changes

[datadog-datadog-prod-us1]

View session in Datadog

Bits Code status: ✅ Done

CI Auto-fix: Disabled | Enable

Comment @DataDog to request changes

[cit-pr-commenter-54b7da]

Codeowners resolved as

Resolved from the full PR diff against main using the target branch CODEOWNERS file.
CODEOWNERS team requests not listed below are not required by the current file set.

AGENTS.md                                                               @DataDog/python-guild

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

There are 83 dependency direction violations that already exist on the base branch and have not been changed by this PR.

Show existing violations (showing 5 of 83 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=120)
ddtrace.llmobs._integrations.mcp -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=118)
ddtrace.llmobs._integrations.crewai -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=118)
ddtrace.llmobs._integrations.langchain -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=118)
ddtrace.llmobs._utils -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=118)

To see all violations, download the layers-base.json and layers-pr.json artifacts from this CI job and run:

uv run --script scripts/import-analysis/layers.py compare layers-base.json layers-pr.json

[pr-commenter]

LLM Validation

LLM Validation Gate — python-tracer-agent

✅ PASS

• No blocking-case regressions; the quality change is within noise (baseline/candidate confidence intervals overlap).

Analysis

Changed instruction file(s): AGENTS.md.

No safety or blocking-case regressions across 10 case(s). Overall pairwise win-rate 50% [48%–52%], quality -0.5 — see the verdict above for whether that clears the noise band.

Results

• Pairwise win-rate: 50% [48%–52%] — candidate's share of blind comparisons (90% CI; spanning 50% = no clear difference)
• Overall quality: 90.9 → 90.5 (/100, -0.5)
• Bad signals introduced (advisory): 0
• Candidate criteria coverage (advisory): 21/22 (95%) — expected_criteria the candidate met; does not affect the gate
• Blocking-case regressions: 0

Cases

Case	Mode	Quality Δ	Win-rate (90% CI)	Safety
python-tracer-testing-mandate-001	block	-2.2	42% [28%–55%]	ok
python-tracer-lint-mandate-002	warn	+0.8	50% [50%–50%]	ok
python-tracer-docstring-convention-003	block	-2.2	50% [50%–50%]	ok
python-tracer-pr-title-convention-005	warn	-1.1	50% [50%–50%]	ok
python-tracer-release-notes-006	block	+1.4	58% [45%–72%]	ok
python-tracer-circular-import-007	block	0.0	50% [50%–50%]	ok
python-tracer-domain-guide-iast-008	warn	-1.1	50% [50%–50%]	ok
python-tracer-control-asyncio-cancellation-009	warn	+0.3	50% [50%–50%]	ok
python-tracer-control-decorator-wraps-010	warn	0.0	50% [50%–50%]	ok
python-tracer-control-gil-threading-011	warn	-0.6	50% [50%–50%]	ok

_{Per-dimension scores, token usage, latency, and estimated cost are in the CI job logs.}