[doc-only][agents] Update AGENTS.md with review-derived guidance

[rparolin]

Summary

Adds review-derived guidance to the root and package-specific AGENTS.md files so future agent-generated changes better reflect recurring cuda-python code review feedback.

The change updates:

• AGENTS.md
• cuda_bindings/AGENTS.md
• cuda_core/AGENTS.md
• cuda_pathfinder/AGENTS.md
• cuda_python/AGENTS.md

How this guidance was generated

This PR turns recurring review feedback from cuda-python maintainers and contributors into durable agent instructions.

I analyzed inline PR review comments created from August 5, 2024 at 13:50:18 UTC through May 16, 2026 at 07:25:14 UTC. The dataset covers PR #84 through PR #2087 and includes 6,687 inline review comments across 586 unique PRs.

Data source:

• Fetch date: May 16, 2026
• Total inline review comments analyzed: 6,687
• Unique commenters: 57
• GitHub MEMBER comments: 5,471 comments from 37 commenters
• Year coverage: 451 comments from 2024, 4,307 from 2025, and 1,929 from 2026

The content added to the AGENTS.md files was driven by themes that appeared repeatedly in those review comments. I used keyword-based matching over review comment bodies to quantify recurrence, then converted the highest-value themes into agent-facing guidance.

It is a directional analysis to identify feedback patterns that are common enough to document up front.

Research findings that informed the updates

Across the full inline review comment corpus, 2,514 of 6,687 comments, or 37.59%, matched at least one theme reflected in this PR.

Looking only at comments from GitHub MEMBER authors, 1,990 of 5,471 comments, or 36.37%, matched at least one of these themes. That indicates the guidance is grounded in maintainer/team review feedback, not only in occasional external contributor discussion.

Review feedback theme	Full corpus matches	Team/member matches	How it informed this PR
Tests, CI behavior, and feature-specific skips	1,292	1,057	Added guidance to prefer targeted regression tests, avoid broad platform skips, preserve real loading/user workflows, and run the narrowest relevant validation command.
Generated bindings, Cython, CUDA compatibility, and resource semantics	938	758	Added guidance to fix generated-code issues at the generator/template source, preserve CUDA major-version compatibility, avoid unsafe direct symbol use, and protect stream ordering/ownership/exception semantics.
Workflow metadata and packaging alignment	512	382	Added guidance to parse workflow metadata structurally, use the correct GitHub Actions context, keep permissions explicit, and align release tags, constraints, wheels/sdists, and metapackage dependencies.
Public API, docs, examples, and release-note discipline	432	320	Added guidance to sketch broad API changes before implementation, keep public APIs intentional, and update docs/examples/API indexes/release notes when public behavior changes.
Library discovery, environment roots, diagnostics, and fallback behavior	227	190	Added guidance for cuda_pathfinder and repo-wide errors to avoid silent fallback paths, validate CUDA_HOME/CUDA_PATH, and surface user-actionable diagnostics.

Mapping from research to file changes

The root AGENTS.md captures review themes that apply across the monorepo:

• Public API and design expectations came from repeated review pressure around API shape, design context, docs, examples, and release-note completeness.
• Tests and CI guidance came from the highest-volume theme in the analysis, especially comments around regression coverage, broad skips, real workflow preservation, and validation commands.
• Generated code and CUDA compatibility guidance came from recurring comments around generated binding artifacts, Cython symbol availability, CUDA 12.x/13.x compatibility, and resource cleanup semantics.
• Workflow, packaging, and metadata guidance came from comments about structured workflow parsing, GitHub Actions contexts, PR metadata, permissions, release tags, dependency constraints, and wheel/sdist behavior.
• Documentation style guidance came from comments about where public construction behavior and API entries should be documented.

The package-specific AGENTS.md files add narrower guidance where the review feedback was package-specific:

• cuda_bindings/AGENTS.md adds generated-source, Cython-copy, CUDA-version compatibility, and external-contribution guidance because review comments repeatedly flagged one-off generated edits and compatibility risks in binding code.
• cuda_core/AGENTS.md adds public API design, capability-query, CUDA compatibility, resource cleanup, and testing guidance because review feedback often focused on high-level API stability and user-observable CUDA behavior.
• cuda_pathfinder/AGENTS.md adds discovery/fallback/environment-root guidance because review feedback around path discovery emphasized explicit diagnostics over silent success-shaped fallbacks.
• cuda_python/AGENTS.md adds packaging and docs aggregation guidance because metapackage changes need to stay aligned with component versions, constraints, release tags, and generated docs behavior.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-2106/
https://nvidia.github.io/cuda-python/pr-preview/pr-2106/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-2106/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-2106/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[mdboom]

The linting guidance is wrong and should be fixed. The rest I feel less strongly about.

[rparolin]

@mdboom I merged current main, resolved the cuda_core/AGENTS.md conflict, and pushed the merge commit. The pre-commit.ci failure was the mergeable check reporting merge conflict; the branch should now be mergeable again.

Fix commit: 3c7d042
Change: 3c7d042

Could you re-review when you have a chance?

Feedback addressed and user is away on vacation.

[rparolin]

@mdboom @kkraus14 — this is doc-only and all your inline points are addressed:

• Generated-file linting: switched to the stricter "don't lint generated files" rule, with .pre-commit-config.yaml as the source of truth (06c97df).
• Hard-coded CUDA 12/13 → "supported CUDA major-version matrix" wording (06c97df).
• Private-member testing: softened to prefer public paths, allow private/test-only access where Python tests must exercise Cython internals (7a119ec).
• Broad OS skips: only when upstream docs/support matrix say unsupported; otherwise tightest capability/library-based skip (06c97df).
• Removed cython-gen/cybind references since they aren't public (06c97df).
• Added a cuda_core v1.0+ API-breakage/deprecation principle (06c97df).

mdboom, your review got dismissed when I pushed the fixes — could you re-review? CI is green and the branch is mergeable.

One housekeeping item: the Needs-Restricted-Paths-Review label is on here because the PR touches cuda_bindings/AGENTS.md and cuda_python/AGENTS.md. I'm a MEMBER so the guard treats it as a trusted signal — could a maintainer confirm and remove the label when re-reviewing?