Skip to main content

Creating CLAUDE.md Files

This guide explains how to create and integrate CLAUDE.md files into your projects to provide AI coding assistants with project-specific context and instructions.

What is CLAUDE.md?​

CLAUDE.md is a markdown file that contains Agent Instructions for AI coding assistants like Cursor and Claude Code. These files help AI assistants understand your project's conventions, patterns, and best practices.

Why Use CLAUDE.md?​

  • Consistent AI behavior across team members
  • Project-specific knowledge without relying on global settings
  • Version-controlled instructions that evolve with your project
  • Compatibility between Cursor and Claude Code CLI

Basic Structure​

Use the /qs/init-agent command in Cursor to let you guide through the creation (or update) of a CLAUDE.md file. Create a CLAUDE.md file in your project root. Here's a minimal example:

# Project Guidelines

## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Follow the existing naming conventions

## Testing
- Write unit tests for all new features
- Use Jest with the patterns from our Jest guide
- Aim for 80% code coverage

## Architecture
- Keep components small and focused
- Use dependency injection for testability

Cursor Integration​

Cursor can read CLAUDE.md files when the compatibility layer is enabled:

  1. Open Cursor Settings
  2. Go to Cursor Settings (not VS Code Settings)
  3. Enable "Use CLAUDE.md compatibility layer" or similar option

This allows Cursor to automatically use CLAUDE.md files from your repositories, making them work seamlessly with Claude Code CLI.

Team Knowledge​

For global rules and commands that apply across all Quatico projects, we maintain shared knowledge in the config repository:

  • Rules: Global coding rules and agent behavior guidelines
  • Commands: Reusable prompts accessible via slash commands (e.g., /research)

These are automatically available to all team members with Quatico accounts.

Best Practices​

  1. Keep it focused: Only include project-specific guidelines
  2. Link to detailed docs: Reference Confluence pages or other documentation for details
  3. Update regularly: Keep CLAUDE.md in sync with your project's evolution
  4. Version control: Commit CLAUDE.md to your repository so it's available to all team members

Example: Project-Specific Guidelines​

# MyProject Guidelines

## Setup
- Run `pnpm install` to install dependencies
- Use Node.js 20.x
- See [project README](./README.md) for detailed setup

## Code Conventions
- Follow our [commit notation guide](https://docs.quatico.dev/internal/development-practices/commit-notation)
- Use ESLint configuration from `@quatico/eslint-config`
- Prefer async/await over promises

## Testing
- See [Jest guide](https://docs.quatico.dev/internal/development-practices/jest-guide) for testing patterns
- Run tests with `pnpm test`
- Mock external dependencies using `jest.mock()`

## Architecture
- This project uses a microservices architecture
- Each service should be independently deployable
- See [architecture docs](./docs/architecture.md) for details

Resources​