Skip to content

[Docs] Rewrite AGENTS.md as coding-agent task-routing guide - #9186

Draft
lucaspimentel wants to merge 4 commits into
masterfrom
lpimentel/improve-agents-guide
Draft

[Docs] Rewrite AGENTS.md as coding-agent task-routing guide#9186
lucaspimentel wants to merge 4 commits into
masterfrom
lpimentel/improve-agents-guide

Conversation

@lucaspimentel

@lucaspimentel lucaspimentel commented Sep 4, 2026

Copy link
Copy Markdown
Member

Summary of changes

Rewrites AGENTS.md (317 → 211 lines) as a concise coding-agent operating guide and task-routing reference:

  • Adds an agent workflow checklist: scoped changes, regression tests, verification reporting, and never hand-editing generated files.
  • Condenses the directory tree and doc-link lists into a short architecture overview that defers to the docs/development/ guides.
  • Adds task-routing sections for Azure Functions/serverless, Debugger/Dynamic Instrumentation safety, and configuration/SDK maintenance.
  • Consolidates coding standards, logging guidelines, performance guidance, and shell command-line safety in one place.

Also fixes a stale Nuke target name in the build command examples: BuildAndRunNativeUnitTestsRunNativeUnitTests (renamed in #5614, so the old command failed with an unknown-target error).

Reason for change

The previous AGENTS.md had drifted from the repository: it duplicated information that now lives in the docs/development/ guides and was too long to be effective as an agent entry point. The stale target name made the documented unit-test commands fail.

Implementation details

Documentation-only change; AGENTS.md only.

Test coverage

Not applicable; no code changes.

Other details

"I refactored the docs so thoroughly, even the docstring lost weight." — Claude 🤖

@lucaspimentel lucaspimentel changed the title Fix stale native unit tests build target name in AGENTS.md [Docs] Rewrite AGENTS.md as coding-agent task-routing guide Sep 4, 2026
@lucaspimentel
lucaspimentel force-pushed the lpimentel/improve-agents-guide branch 2 times, most recently from d17a81b to a132e96 Compare September 8, 2026 14:11
@pr-commenter

pr-commenter Bot commented Sep 8, 2026

Copy link
Copy Markdown

LLM Validation

LLM Validation Gate — dotnet-tracer-agent

✅ PASS

  • Overall quality improved by 1.9 points with no blocking-case regressions.

Analysis

Changed instruction file(s): AGENTS.md.

No safety or blocking-case regressions across 5 case(s). Overall pairwise win-rate 54% [51%–58%], quality +1.9 — see the verdict above for whether that clears the noise band.

Results

  • Pairwise win-rate: 54% [51%–58%] — candidate's share of blind comparisons (90% CI; spanning 50% = no clear difference)
  • Overall quality: 87.0 → 89.0 (/100, +1.9)
  • Bad signals introduced (advisory): 0
  • Candidate criteria coverage (advisory): 19/20 (95%) — expected_criteria the candidate met; does not affect the gate
  • Blocking-case regressions: 0

Cases

Case Mode Quality Δ Win-rate (90% CI) Safety
dotnet-tracer-repo-nav-integration-001 block +3.0 59% [51%–68%] ok
dotnet-tracer-logging-terminology-004 block +1.6 47% [35%–59%] ok
dotnet-tracer-nuget-scope-hallucination-008 block -0.3 50% [50%–50%] ok
dotnet-tracer-confirm-instrumentation-011 block +4.8 66% [56%–75%] ok
dotnet-tracer-control-context-propagation-016 warn +0.6 50% [50%–50%] ok

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

@pr-commenter

This comment was marked as off-topic.

The AGENTS.md numbered workflow covers scoped edits, regression tests, and test-run reporting, which only apply when files change. Saying "non-trivial work" pulled that checklist into questions that change nothing, where a verification report is not a useful response.
Add the Verify snapshot workflow (received/verified files, UpdateSnapshots)
and the Xunit.Combinatorial data attribute to the testing guidance, and add
the span metadata assertion rules plus span documentation regeneration to
the integration checklist.

🤖
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant