Techniques for Making CLAUDE.md Human-Friendly

Introduction

In projects using Claude Code, you can communicate project information to Claude Code via a file named CLAUDE.md. Furthermore, this file can serve as an important information source not just for AI, but for human developers as well.

However, if written normally, it tends to become a document that is understandable by AI but difficult for humans to use. In this article, I will introduce techniques for writing a CLAUDE.md that is easy for both to read using simple adjustments.

Basic Role of CLAUDE.md

CLAUDE.md is used for memory management in Claude Code. For details, please refer to the official documentation.

What we are focusing on this time is importing additional files using the @path/to/import syntax. If you specify a file in CLAUDE.md using the @path/to/import syntax, that file will also be loaded when Claude Code starts. For explanatory purposes, I am writing it as @path/to/import, but when actually writing it in CLAUDE.md, you write it without enclosing it in ` as shown below:

# Correct way
@path/to/import

# Incorrect way
`@path/to/import`

This is because, as stated in the official documentation, @path/to/import is ignored within ` (code spans) and ``` (code blocks).

To avoid potential conflicts, imports are not evaluated inside markdown code spans and code blocks.
https://docs.anthropic.com/en/docs/claude-code/memory

Techniques to Make It Human-Readable

CLAUDE.md is useful not only for Claude Code but also as onboarding documentation for humans. However, when a human reads it, they cannot "import" files using the @path/to/import syntax.

Therefore, by utilizing the specifications of the @path/to/import syntax and the fact that CLAUDE.md is a Markdown file, we can make the files imported via the @path/to/import syntax easier to read when humans read them.

The key is to effectively leverage the following two specifications:

• The @path/to/import syntax is ignored within code spans and code blocks.
• In Markdown files, links can be represented with [title](link).

In other words, even if you write it as follows, you can create an expression that is valid as both a CLAUDE.md instruction and a Markdown file.

[@path/to/import](path/to/import)

Written this way, it functions as the @path/to/import syntax for Claude Code, while in Markdown previews like Cursor or GitHub, it is displayed as a link that shows the file when clicked.

Practical Usage Example

For example, when using this technique in a Rails project, you can write it as follows:

- The Ruby version is [@.ruby-version](.ruby-version).
- The database schema is [@db/schema.rb](db/schema.rb).

Notes on Usage

• Specify the file path as a relative path from CLAUDE.md.
• Verify if it has been correctly imported using the /memory command in Claude Code.
• Confirm that the links function correctly in your Markdown preview.

Summary

By using the notation [@path/to/import](path/to/import), you can make CLAUDE.md human-readable. With this simple technique, a configuration file for AI can simultaneously serve as excellent project documentation.

I post updates about Claude Code and AI on X, so please follow me if you are interested.

@_smasato_