Skip to content

Add guidance for coding agents - #84

Merged
acollins3 merged 7 commits into
mainfrom
acollins/agents-md
Nov 3, 2026
Merged

acollins3 merged 7 commits into
mainfrom
acollins/agents-md

Conversation

@acollins3

Copy link
Copy Markdown
Collaborator

Describe the repository layout, the lint/test/docs commands, runtime requirements, and how the profiler runs benchmark code. Document known pitfalls found while profiling Triton kernels with the NCU and CUPTI backends: autotuning inside annotations, kernel-count rules, CUPTI activation order relative to importing torch, mangled kernel names under CUPTI, and how to interpret result columns including normalize_against.

Some passages describe the error messages from #83, so this builds on it.

Comment thread AGENTS.md Resolved

@nvssatoor nvssatoor left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be submitted after #83 as some updates may be needed

@acollins3

Copy link
Copy Markdown
Collaborator Author

I've made some improvements to the guidance, the main things are:

  • the file is now in two sections: one for agents using nsight-python, one for agents developing nsight-python
  • removed version numbers etc. so they don't go stale, and pointed to where to find these in the source instead
  • generalized the advice accross both linux and windows

@nvssatoor please re-review

@acollins3
acollins3 requested a review from nvssatoor November 2, 2026 12:03
acollins3 and others added 6 commits November 2, 2026 12:04
Describe the repository layout, the lint/test/docs commands, runtime
requirements, and how the profiler runs benchmark code. Document known
pitfalls found while profiling Triton kernels with the NCU and CUPTI
backends: autotuning inside annotations, kernel-count rules, CUPTI
activation order relative to importing torch, mangled kernel names under
CUPTI, and how to interpret result columns including normalize_against.

Some passages describe the error messages from the
acollins/errors-and-terminal-output branch, so this builds on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
Separate guidance for using Nsight Python from guidance for working on
the repository, generalize the Triton-specific pitfalls, and point to
the docs and code for versions, result columns and CI details instead
of restating them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
Print the full result table, and explain how to profile a candidate made
of several PyTorch ops, including that summing is wrong for percentage
metrics.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Nov 2, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
@nvssatoor

Copy link
Copy Markdown
Collaborator

It may be useful to review and update the nsight python document - if any of these points mentioned in agents.md are not included. This can be done in a separate change.

@acollins3

Copy link
Copy Markdown
Collaborator Author

It may be useful to review and update the nsight python document - if any of these points mentioned in agents.md are not included. This can be done in a separate change.

Agreed, I'll do it in a follow-up PR.

Here's my current list of omissions from the docs that we should add:

  • warming up autotuned or first-call code before profiling
  • kernel names are mangled under CUPTI but demangled under NCU (which affects ignore_kernel_list)
  • the CUPTI/torch import-order issue
  • Windows exit code 0xC0000409 after NCU runs
  • MPLBACKEND=Agg on Windows
  • summing with combine_kernel_metrics is wrong for percentage or rate metrics

Once those are in the docs, AGENTS.md can point to them instead of repeating them.

State why CUPTI timings vary more, limit the MPLBACKEND advice to
Windows where it is needed, and explain what the default exception
behavior inside annotations means for a sweep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alex Collins <acollins@nvidia.com>
@acollins3
acollins3 merged commit 8fa3ebc into main Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants