Skip to content

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

Merged
rmems merged 7 commits into
mainfrom
docs/claude-md-rm-2185
Oct 26, 2026
Merged

rmems merged 7 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, importing AGENTS.md via @AGENTS.md to avoid duplication. Closes RM-2185.

The guide covers a verified command table, an architecture map, invariants and non-goals, and gotchas. It 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. It 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 f464ca9. Summary will update on new commits.

View guided diff Turn on auto-fix


CodeAnt-AI Description

Add Claude guidance for repository checks and GPU workflows

What Changed

  • Adds a Claude-specific guide with verified CPU checks, GPU-only tasks, a repository map, and project rules.
  • Clarifies which GPU workflow jobs use the self-hosted runner and how to avoid running untrusted fork code on it.
  • Excludes CLAUDE.md from Codacy analysis.

Impact

✅ Clearer CPU checks to run before pushing
✅ Clearer GPU runner safety requirements
✅ Fewer Codacy findings from Claude guidance

💡 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.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0135NF9znw5wkTjtATyd1n52
@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 f464ca9 Oct 24, 2026 · 04:27 04:27
✅ 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

RM-2177

@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 →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration
Commits

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

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

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

Walkthrough

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

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.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0135NF9znw5wkTjtATyd1n52
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 benchmark commands use the correct paths under build/kernels/src.
  • The GPU-runner note accurately distinguishes excluded fork code from same-repository PR heads selected by the gate.

Assessed commit: f464ca9e7024

…M-2185)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0135NF9znw5wkTjtATyd1n52
coderabbitai[bot]

This comment was marked as resolved.

claude and others added 2 commits October 18, 2026 18:18
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Comment thread .codacy.yml Resolved
…RM-2185)

Docs-only; no build run.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0135NF9znw5wkTjtATyd1n52
@rmems rmems added the docs label Oct 23, 2026 — with Cursor
@rmems rmems self-assigned this Oct 23, 2026
@rmems
rmems merged commit a275580 into main Oct 26, 2026
12 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in Blackwell Kernel Lab Oct 26, 2026
@rmems
rmems deleted the docs/claude-md-rm-2185 branch October 26, 2026 08:01
@rmems rmems changed the title docs: add CLAUDE.md (RM-2185) docs: add CLAUDE.md (RM-2185) (RM-2177) Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

Development

Successfully merging this pull request may close these issues.

2 participants