Restructure agent documentation into hub-and-spoke architecture

[Valpertui]

Summary

Replaces the monolithic AGENTS.md + CLAUDE.md (510 combined lines, significant duplication) with a lean entry-point (AGENTS.md, 79 lines) linking to 5 focused docs under docs/. CLAUDE.md is trimmed to a minimal pointer + skills table.

Files changed: 7 (2 modified, 5 created) — AGENTS.md, CLAUDE.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/KNOWN_CONCERNS.md

Why — Experimentally Validated

We ran 18 identical engineering tasks on both branches (this branch vs develop), giving Claude Code the same PM-style spec and comparing the code it produced. The structured docs consistently improved output quality and efficiency:

Metric	develop (old docs)	This branch (new docs)	Delta
Tasks won	0 / 18	6 / 18	New docs never produced a worse result
Tasks tied	6 / 18	6 / 18
Avg tool calls	61.8	54.3	-12% fewer tool calls
Avg source files read	~24	~19	-21% less exploration
Docs files read	2–3 (CLAUDE, AGENTS, maybe a FEATURE.md)	5–7 (hub → spoke navigation)	Docs substitute for blind exploration

What the new docs teach that the old docs didn't

docs/ARCHITECTURE.md — Message Bus Patterns (highest-impact addition)

Documents .context vs .payload message patterns, CombinedFeatureMessageReceiver short-circuit semantics, and RUMCoreContext propagation flow. Validated by Task B (Logs-RUM enrichment): the new-docs agent chose the architecturally correct .context(RUMCoreContext) pattern (matching Session Replay's existing RUMContextReceiver), while the develop agent chose .payload(RUMViewEvent) — a tighter coupling that doesn't match established SDK patterns. The new-docs agent also found LogEventSanitizer reserved attributes (a data integrity issue the develop agent missed).

docs/CONVENTIONS.md — Lint Rules & UIApplication Safety (catches silent failures)

Explicitly documents UIApplication.dd.managedShared (KVC workaround for app extension safety), required_reason_api_name banned property names, and explicit_top_level_acl. Validated by Task A (scroll instrumentation): the new-docs agent implemented ObjectIdentifier-based de-duplication to prevent spamming user action events on every scroll callback; the develop agent had no de-duplication — a correctness bug that would corrupt RUM metrics.

docs/TESTING.md — Mock Selection & ApplicationLaunch View (prevents false-positive tests)

Documents when to use DatadogCoreProxy vs PassthroughCoreMock vs FeatureScopeMock, with a DatadogCoreProxy code example including dropApplicationLaunchView() and RUMSessionMatcher. Validated by Tasks B and C: mock selection was consistently correct with new docs; dropApplicationLaunchView() was reliably discovered (previously a coin flip).

docs/DEVELOPMENT.md — Step-by-Step Recipes (prevents dead code)

Recipes for adding RUM commands, context publishers, instrumentations, and features — including registration steps that are invisible from the code alone. Validated by Task E (thermal state publisher): the new-docs agent completed the task in 57 tool calls vs 70 for develop (-19%), because the recipe directed it to the right files immediately.

docs/KNOWN_CONCERNS.md — Fragile Areas

Lists areas where changes have caused production incidents: SwiftUI view name extraction (Mirror reflection), 100ms user action window, 500 concurrent operation cap, unbounded message bus queue, KSCrash report parsing format dependency.

Detailed Task Results

Round 3 (6 PM-style tasks, 12 agents)

Task	Scope	Winner	Key Differentiator
A: Scroll-to-bottom instrumentation	7 files, swizzling + registration	New-docs	De-duplication mechanism (ObjectIdentifier Set)
B: Logs-RUM view name enrichment	10 files, cross-feature messaging	New-docs	LogEventSanitizer reserved attribute; 35% fewer tool calls
C: Event mapper integration tests	1 file, 5 test scenarios	Tie	Both used dropApplicationLaunchView() reliably
D: Vital operation step mapper	9 files, full mapper pipeline	New-docs (slight)	Exception scenario in tests (ARCHITECTURE.md: "callbacks caught and logged")
E: Thermal state context publisher	7 files, cross-module wiring	Tie	Identical implementations; new-docs 19% more efficient
F: Session Replay hang snapshot	7 files, message bus + receiver ordering	Tie	Both architecturally correct

Earlier Rounds (12 additional task-pairs confirming the pattern)

• Round 1 (3 tasks): 1 new-docs win, 2 ties
• Round 2 (3 tasks): 2 new-docs wins, 1 tie

Cumulative: 6 wins for new-docs, 6 ties, 0 wins for develop across 18 task-pairs.

How it works

AGENTS.md (79 lines)          ← Entry point: philosophy, critical rules, "where to look" table
  ├── docs/ARCHITECTURE.md    ← Module structure, data flow, message bus, error handling
  ├── docs/CONVENTIONS.md     ← Naming, lint rules, UIApplication safety, banned symbols
  ├── docs/DEVELOPMENT.md     ← Recipes for adding features/commands/providers
  ├── docs/TESTING.md         ← Mock infrastructure, DatadogCoreProxy, ApplicationLaunch view
  └── docs/KNOWN_CONCERNS.md  ← Fragile areas requiring extra caution

CLAUDE.md (25 lines)          ← Minimal: project overview, pointer to AGENTS.md, skills table

Agents read AGENTS.md first, then follow the "Where to Look First" table to the relevant doc for their task. This hub-and-spoke navigation replaces blind codebase exploration.

Review checklist

• Feature or bugfix MUST have appropriate tests — N/A (documentation only)
• Make sure each commit and the PR mention the Issue number or JIRA reference — N/A (documentation improvement)
• Add CHANGELOG entry for user facing changes — N/A (internal documentation)
• Add Objective-C interface for public APIs — N/A
• Run make api-surface when adding new APIs — N/A

[maxep]

Looks good, well organised 👍