Skip to content

docs: add CLAUDE.md (RM-2185) - #66

Open
rmems wants to merge 6 commits into
mainfrom
docs/claude-md-rm-2185
Open

rmems wants to merge 6 commits into
mainfrom
docs/claude-md-rm-2185

Conversation

@rmems

@rmems rmems commented Oct 18, 2026 •

Copy link
Copy Markdown
Owner

User description

Summary

Adds CLAUDE.md with Claude-specific notes: a command table with verified / not-run status, an architecture map, invariants and non-goals, and gotchas. It imports AGENTS.md instead of duplicating it. No other files are touched; there is no package manifest or publish list to update, and sources here use no SPDX headers.

Verified

Ran locally (Python 3.13, CMake 3.28, shellcheck 0.11.0, actionlint 1.7.12, no GPU or CUDA): the CUDA-OFF CMake configure, all ci-cpu.yml Python checks, the compute-sanitizer runner self-check, the "Kernel tree is complete" step, shellcheck on the recipe and kernel-tool scripts, and actionlint on the workflows.

Not run: the CUDA build, the GPU benchmarks, the Green Context report check, and Compute Sanitizer. They need nvcc, CUDA 13.3 and the RTX 5080.

Closes RM-2185

Generated by Claude Code

Devin Review


Summary by cubic

Adds CLAUDE.md with Claude-specific notes: a verified command table, architecture map, invariants and non-goals, and gotchas. It imports AGENTS.md via @AGENTS.md to avoid duplication and closes RM-2185.

The command table marks 13 commands as verified on a CPU-only machine and 6 as not run (they need nvcc, CUDA 13.3, and the RTX 5080), including full binary paths and the actionlint setup note. The "Kernel tree is complete" CI step was run by hand and passes. The guide also records which CI jobs run on the self-hosted GPU runner versus hosted ubuntu-latest runners, the CPU-only gate allowlist, the VRAM headroom floor, and the pull_request_target trust boundary. Adds .codacy.yml to exclude CLAUDE.md from Codacy analysis, since Codacy does not read .gitignore; because .codacy.yml is not in the gate's CPU allowlist, a PR touching it is flagged GPU-relevant.

Written for commit 29b5280. Summary will update on new commits.

View guided diff Turn on auto-fix


CodeAnt-AI Description

Document repository checks and safe GPU workflow practices

What Changed

  • Add Claude-specific repository guidance with a map of project areas and key development rules.
  • List CPU checks verified without a GPU and GPU checks that require CUDA 13.3 and an RTX 5080.
  • Clarify which GPU workflow jobs use self-hosted runners and how to avoid running untrusted fork code on them.

Impact

✅ Easier CPU-only validation
✅ Clearer GPU test requirements
✅ Safer guidance for self-hosted GPU checks

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

@codeant-ai

codeant-ai Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

🤖 CodeAnt AI — Review Status

Status Commit Started (UTC) Finished (UTC)
✅ Incremental review completed cb5bcc8 Oct 22, 2026 · 02:05 02:06
✅ Reviewed your PR 834f3ae Oct 18, 2026 · 23:04 23:08

@linear-code

linear-code Bot commented Oct 18, 2026

Copy link
Copy Markdown

RM-2185

@codeant-ai

codeant-ai Bot commented Oct 18, 2026

Copy link
Copy Markdown

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

@coderabbitai

coderabbitai Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 3792da20-ce29-410b-b870-512910747dc7
📥 Commits

Reviewing files that changed from the base of the PR and between bbd198c and 29b5280.

📒 Files selected for processing: 2
  • .codacy.yml
  • CLAUDE.md

Limit details: You’ve used all 10 included reviews currently available.

📜 Recent review details
⏰ Context from checks skipped due to timeout: 3
  • GitHub Check: Verify GPU validation policy
  • GitHub Check: Blocks PR Review
  • GitHub Check: Codacy Static Code Analysis
🧰 Additional context used
📚 Code guidelines: 1
CLAUDE.md — auto-discovered
📓 Path-based instructions: 1
Source excerpt: No manifest or publish list exists (no `Cargo.toml`, `pyproject.toml`, or `package.json`).

📄 CodeRabbit inference engine (CLAUDE.md)

Files:

  • .codacy.yml
🔍 Remote MCP Linear

Linear

  • Earlier review findings about GPU executable paths and the self-hosted runner trust boundary were marked addressed and verified against commit bbd198c. (Source: Linear · get_diff_threads)
  • An unresolved review note states that the documented CMake build requires CUDA tooling and a supported compiler, but not an attached RTX 5080; the current “needs … RTX 5080” wording may overstate the requirement. (Source: Linear · get_diff_threads)
  • A separate review note flags that ./actionlint is absent in a fresh checkout until workflow setup downloads it; the returned data does not independently verify the final setup instructions. (Source: Linear · get_diff_threads)
  • The latest automated review assessed the documentation change as low risk and described the GPU paths and runner boundary as accurate. (Source: Linear · get_diff_threads)
🔇 Additional comments: 2
.codacy.yml: 1

1-3: This repeats the previously reported GPU-CI concern.

.codacy.yml is not in CPU_FILES, so needs_gpu('.codacy.yml') returns True. This makes the PR GPU-relevant. The prior review raised this behavior and left it for maintainer decision.

CLAUDE.md: 1

35-35: LGTM!

Also applies to: 53-53

📝 Summary

Summary by CodeRabbit

  • Documentation
    • Added Claude-specific repository guidance covering architecture, project conventions, contribution practices, and command verification status. The notes also document GPU resource requirements, when GPU commands could not be run, and how to interpret missing NVML values. These details provide additional context for working with the project’s GPU workflows.

The pull request adds CLAUDE.md with a reference to AGENTS.md and repository-specific guidance on commands, project structure, GPU workflows, and contribution constraints. Codacy configuration excludes CLAUDE.md from analysis.

Changes: Claude repository guidance

Layer / File(s) Summary
Add repository-specific guidance
CLAUDE.md, .codacy.yml
CLAUDE.md records command verification status, repository architecture, GPU and CUDA constraints, and contribution notes. .codacy.yml excludes CLAUDE.md from Codacy analysis.

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: 🔵 Low · up to 29b52

Adding .codacy.yml schedules GPU validation for a Codacy configuration change, adding a hardware-dependent CI step. The PR is otherwise limited to guidance and configuration, so this is a bounded operational risk.

Architecture risk: 🔵 Low · up to 29b52

The change affects 1 system.

Changed systems: CLAUDE.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — CLAUDE.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in CLAUDE.md: Adds AGENTS.md as imported guidance and states that CLAUDE.md contains Claude-specific notes rather than duplicating repository-wide guidance.
  • observed — Modified behavior in CLAUDE.md: Adds a command table with verification status and environment, distinguishing CPU checks reported as verified from CUDA/GPU-dependent commands reported as not run. Also records additional CI checks and runner distinctions.
  • observed — Modified behavior in CLAUDE.md: Adds an architecture map describing the roles of the kernels/, tools/, fixtures/, recipes/, docs/, and results/ directories.
  • observed — Modified behavior in CLAUDE.md: Adds repository invariants and non-goals covering CUDA file placement, self-hosted GPU workflow restrictions, GPU relevance classification, a 2 GiB free-VRAM floor, NVML missing-value distinction, SPDX headers, and manifest/publish-list status.
Pre-merge checks: Passed 3 · Failed 2

Failed Failed checks: 2 warnings

Check name Status Explanation Resolution
Linked Issues check Warning RM-2185 requires build, test, and benchmark commands to run and be confirmed at HEAD, with GPU requirements identified. CLAUDE.md identifies the GPU requirements, but marks the CUDA build, GPU binar… Run the GPU-required build, benchmark, report-check, and Compute Sanitizer commands on the required CUDA 13.3 and RTX 5080 environment. Update CLAUDE.md with the confirmed HEAD results, or obtain a change to the linked acceptance requirem…
Out of Scope Changes check Warning The whole-PR diff adds .codacy.yml in addition to CLAUDE.md. The Codacy exclusion changes repository analysis configuration and does not document Claude-specific repository guidance. RM-2185 reque… Remove .codacy.yml from this pull request unless the linked issue is expanded to include Codacy configuration. Keep the requested guidance in CLAUDE.md.
Passed Passed checks: 3 passed
Check name Status Explanation
Description check Passed The description clearly relates to the changeset. It explains the new CLAUDE.md guidance, validation status, GPU requirements, and the .codacy.yml update.
Title check Passed The title clearly and concisely identifies the primary change: adding CLAUDE.md documentation. The issue reference is also relevant.
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

Full details: Linked Issues check

Explanation

RM-2185 requires build, test, and benchmark commands to run and be confirmed at HEAD, with GPU requirements identified. CLAUDE.md identifies the GPU requirements, but marks the CUDA build, GPU binaries and benchmarks, Green Context report check, and Compute Sanitizer as not run. The CPU command rows and architecture and invariant sections satisfy the corresponding documentation objectives. RM-2177 also requires verified commands and no unverifiable claims.

Resolution

Run the GPU-required build, benchmark, report-check, and Compute Sanitizer commands on the required CUDA 13.3 and RTX 5080 environment. Update CLAUDE.md with the confirmed HEAD results, or obtain a change to the linked acceptance requirement.

Full details: Out of Scope Changes check

Explanation

The whole-PR diff adds .codacy.yml in addition to CLAUDE.md. The Codacy exclusion changes repository analysis configuration and does not document Claude-specific repository guidance. RM-2185 requests a root-level CLAUDE.md with only Claude-specific notes, and RM-2177 lists CI changes as out of scope. The new file also causes .codacy.yml to be classified as GPU-relevant because it is not in CPU_FILES.

Resolution

Remove .codacy.yml from this pull request unless the linked issue is expanded to include Codacy configuration. Keep the requested guidance in CLAUDE.md.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Usage-based review receipt

  • Mode: Continue automatically
  • Reviewed files: 2
  • Waived: $0.50 (charged $0.00)
  • View usage details

Note

This review exceeded your plan’s limits and used usage-based reviews—free during trial, billed after paid activation unless disabled. Manage usage-based reviews.

A rabbit reads the notes at dawn
It checks which tests were run
It marks the GPU limits clear
And keeps the project map close near
Then hops away beneath the sun

Comment @coderabbitai help to get the list of available commands.

@amazon-q-developer amazon-q-developer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This PR adds a single documentation file, CLAUDE.md, containing Claude-specific operational notes for the repository. The file is well-structured, accurately describes the repo architecture, and correctly avoids duplicating content already in AGENTS.md by importing it with @AGENTS.md.

No logic errors, security vulnerabilities, crashes, or other merge-blocking defects were found. The command table is clear about what has and hasn't been verified, the invariants section accurately reflects CI security constraints (e.g., pull_request_target, persist-credentials: false, SHA-pinned actions), and the gotchas section correctly calls out the GPU serialization risk.

Verdict: No blocking issues. Ready to merge.


You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

@codeant-ai codeant-ai Bot added the size:M This PR changes 30-99 lines, ignoring generated files label Oct 18, 2026
@gitar-bot

gitar-bot Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Gitar is working

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

Auto-approval Not enabled

Set up

Gitar

@codacy-production

codacy-production Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

devin-ai-integration[bot]

This comment was marked as resolved.

codeant-ai[bot]

This comment was marked as resolved.

@codeant-ai

codeant-ai Bot commented Oct 18, 2026

Copy link
Copy Markdown

CodeAnt Nitpicks

2 code suggestions

1. This command fails in a fresh checkout because ./actionlint is downloaded by ci-lint.yml and is not present in the repository.

Api mismatch · CLAUDE.md:27


2. The CMake configure and build need CUDA tooling and a supported compiler, but not an attached RTX 5080; requiring one wrongly blocks GPU-less build validation.

Comment mismatch · CLAUDE.md:28

@codeant-ai

codeant-ai Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

CodeAnt PR Risk: Low Risk

  • The PR appears safe to merge; the documented executable paths and GPU-runner trust boundary now match the described behavior.

Assessed commit: cb5bcc8d0316

coderabbitai[bot]

This comment was marked as resolved.

Comment thread .codacy.yml
Comment on lines +1 to +3
# Codacy ignores (Codacy does not read .gitignore; paths are excluded here)
exclude_paths:
- "CLAUDE.md"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This new file makes the docs-only PR require a GPU run. tools/gpu_ci_gate.py::needs_gpu fails closed: it only skips *.md, LICENSE, paths in CPU_FILES, and the CPU fixtures. .codacy.yml is none of those, so the gate treats it as GPU-relevant:

$ python3 -c "import sys; sys.path.insert(0,'tools'); import gpu_ci_gate as g; print(g.needs_gpu('.codacy.yml'))"
True

So ci-gpu.yml will check out this PR head on the shared self-hosted RTX 5080, and verify fails unless that job succeeds. Every later PR that edits .codacy.yml will do the same. That conflicts with the "do not run GPU rows on a shared host" gotcha in this same CLAUDE.md.

The file also contradicts the docs:

  • CLAUDE.md:53 says "there is nothing to exclude CLAUDE.md from".
  • The PR body says "No other files are touched".

Suggested fix, pick one:

  • Drop .codacy.yml from this PR. Codacy's note on a Markdown file is not worth a GPU run.
  • Or add ".codacy.yml" to CPU_FILES next to .qlty/qlty.toml, as docs/CI.md describes for allowlist changes, then update CLAUDE.md:53 and the PR description. Note that this edits tools/gpu_ci_gate.py, which is itself in GPU_POLICY, so that change will also need a GPU run.

Severity 7/10 · View on dashboard · PR Review Settings

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Verified: needs_gpu('.codacy.yml') is True (not in CPU_FILES), so this file makes the PR GPU-relevant. I corrected CLAUDE.md:53 (it wrongly said there was nothing to exclude CLAUDE.md from) in 29b5280. I did not touch .codacy.yml (a maintainer commit) or tools/gpu_ci_gate.py (the GPU trust gate, which would itself need a GPU run): dropping the file or adding it to CPU_FILES is the maintainer's call. Docs-only, no build run. (Claude Code agent session)


Generated by Claude Code

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

Labels

size:M This PR changes 30-99 lines, ignoring generated files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants