Introduction

Nowadays, with development powered by Artificial Intelligence—and with Claude being one of the most widely used tools—it is important to understand what this file is and the best way to maintain it within a project.

The claude.md file is generally used to document the project, and this documentation is passed as context to Claude in every chat.

Where to place the claude.md file

This file can be used to document general project rules, user preferences, and even company-wide guidelines.

Here, I’ll focus on project and module instructions, which is what I’ve used and tested the most.

Ideally, you should place the claude.md file at the root of the project or inside the .claude/claude.md directory.

Best practices

Keep the file short

Ideally, the claude.md file should be around 200 lines or less. Since it is loaded into every chat, a large context can take up too much space and leave less room for other relevant information.

Split into multiple files

To address the previous point, it’s best to reference other files inside claude.md, for example:

Project rules
- [Commit rules](./claude/rules/commits.md)
- [Code styles](./claude/rules/code-styles.md)
- [Database](./claude/rules/database.md)
- [Tests](./claude/rules/tests.md)

This way, Claude will only load these subfiles when necessary for implementation.

Another approach is to create additional claude.md files within each module, for example:

- modules
  - auth
    - claude.md
  - users
    - claude.md
- database
    - claude.md

With this structure, Claude will load the module-specific claude.md only when needed, instead of the general project file, which may be longer and contain irrelevant information for that specific module.

This helps save tokens and keeps the context more relevant to the task being implemented.

The larger the context, the more tokens are used.

Agents and Skills

If your repository includes agents and skills, it’s important to clearly indicate in claude.md that these tools exist and can be used.

For example:

Agents

- [Frontend Agent](.\claude\agents\frontend.md)

Skills

- [Commit helper](.\claude\skills\commit-helper\SKILL.md)

Comments

You can add comments in the claude.md file using Markdown comment syntax: <!-- comment -->.

This is useful for humans to leave notes and additional information.

These comments do not consume tokens and are not included in the context.

Writing style

Ideally, write the claude.md file in a clear and objective way, using simple and direct language to improve understanding and avoid ambiguity.

Avoid long paragraphs—prefer lists, tables, and other visual structures to organize information more clearly and make it easier to read.

Conclusion

This topic is quite extensive, and new approaches and improvements in AI usage emerge every day.

The key is to keep the claude.md file always up to date with new rules and, at the same time, concise to ensure the best results.

If you have any suggestions to improve this article, feel free to reach out to me on LinkedIn :)