[FEATURE] Add "comment" syntax to claude.md file format

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

A large code base contains multiple claude.md files for different use cases and for different components of the application.
Some of the files contain claude instructions that are rather complex. For example, gradle commands on how to execute certain tests.

To a reader (i.e., a developer reading the claude.md file) it is not obvious why the claude instruction was written this way, what different parts of the instruction mean, which simpler variants of the instruction were already tried and did not work, ...

Proposed Solution

I would like to add comments in claude.md files to explain the reasoning behind some claude code instructions. The target audience of these comments would be other developers, not claude code.

In specifically want that claude code ignores these comments in the .md file. They should not become part of the reasoning context/memory.

As to the format of the comments, I come from Java/C++, so the // or /* */ format would feel like home. But any other format is good, too.

I think this would be a really easy feature.

Alternative Solutions

Of course I can just put a Claude.comment.md file next to my Claude.md file. But the links from comment to paragraph would be lost and the comment file would not be visible enough in daily work.

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

I'm giving claude specific instructions for how to test a class. The test setup is complex for ... reasons. Claude would not be able to discover how to test this on its own.

For testing a class with simple class name `XYZ`, start the tests like this:
`folderName=XYZ ./gradlew :server:myFancyTest.test:test --tests "fancyTest.MyTest --info`.

This is not the way we start tests in our normal dev workflow but it is the most efficient way for claude code. Therefore I want to document for my fellow developers why I write the instructions that way.

Additional Context

_No response_