How to Encode Project Conventions into AI Memory with CLAUDE.md

Problem

AI code assistants (e.g., Cursor, Claude Code, Codex) often forget project‑specific conventions such as naming style, directory layout, or prohibited types, requiring developers to repeat these rules in every prompt.

Limitations of .cursorrules

Loading scope : recognized only by Cursor.

File‑size limit : recommended < 500 lines.

Structure : plain text, no hierarchical support.

Multi‑file support : cannot be split; no import mechanism.

CLAUDE.md Overview

CLAUDE.md is a project‑wide AI specification readable by multiple tools (Claude Code, Cursor, Codex). It serves as a reusable “project survival guide” for the AI.

Structure of CLAUDE.md

# Project Overview
## Development Guidelines
## Directory Structure
## Common Commands
## Known Pitfalls
## Delivery Criteria

The hierarchy guides the AI from project shape to coding rules to completion criteria.

Vue 3 + TypeScript Example

# Project Overview

This is an enterprise WeChat SaaS admin built with Vue 3, TypeScript, and Element Plus. Core features: customer management, message templates, data dashboards.

## Tech Stack
- Framework: Vue 3 (Composition API + <script setup>)
- State: Pinia (Vuex prohibited)
- Router: Vue Router 4
- UI: Element Plus (no other UI libraries)
- Request: Axios via @/utils/request.ts (direct import prohibited)
- Styles: SCSS (Tailwind prohibited)

## Directory Structure
src/
├── api/          # API definitions per module
├── components/   # Shared components
├── composables/  # Composition functions (useXxx.ts)
├── layouts/      # Layout components
├── pages/        # Page components (one folder per page)
├── router/       # Routing config
├── stores/       # Pinia stores (xxxStore.ts)
├── styles/       # Global styles
├── utils/        # Utility functions
└── types/        # TypeScript type definitions

## Code Guidelines
### Naming Conventions
- Component names: PascalCase (CustomerTable.vue)
- Composition functions: camelCase prefixed with use (useCustomerList.ts)
- Type definitions: PascalCase + Type suffix (CustomerType.ts)
- Constants: UPPER_SNAKE_CASE
- File names: kebab-case (customer-detail.vue)

### Prohibited Practices
- ❌ Do not use any; prefer concrete types or unknown.
- ❌ Do not embed business logic directly in page components; extract to composables.
- ❌ Do not hard‑code API URLs; use environment variables.
- ❌ Do not leave console.log in production code.

### Import Order
1. Vue core
2. Third‑party libraries
3. Project internal modules (@/ alias)
4. Type imports (import type …)

```typescript
import { ref, computed } from 'vue'
import { ElMessage } from 'element-plus'
import type { CustomerType } from '@/types/customer'
import { useCustomerStore } from '@/stores/customerStore'
import { formatDate } from '@/utils/date'
```

Common Pitfalls and Correct Patterns

Pitfall 1: Too Long, AI Can’t Remember

❌ Embedding the entire 800‑line ESLint config exceeds the AI’s context window.

✅ List only actionable rules (e.g., forbid any, forbid console.log). This keeps the rule set short enough for the AI to retain.

Pitfall 2: Contradictory Rules

❌ Stating both PascalCase for component names and kebab‑case for file names without clarification confuses the AI.

✅ Separate file‑name convention (kebab‑case) from component name property (PascalCase) and explain the mapping.

Pitfall 3: Missing Delivery Criteria

❌ Providing only “implement customer list page” leaves the AI without a clear stop condition.

✅ Enumerate concrete acceptance items such as page rendering, API integration, pagination, filtering, TypeScript type‑check, and ESLint pass.

Pitfall 4: Exposing Sensitive Information

❌ Writing real API keys in the file leaks secrets.

✅ Reference the existence of environment variables and point to an example .env file instead of including values.

Splitting Large CLAUDE.md Files

When the main file exceeds 500 lines, use @import to include topic‑specific sub‑files.

# CLAUDE.md (main, < 100 lines)

@import ./docs/ai-context/coding-standards.md
@import ./docs/ai-context/directory-map.md
@import ./docs/ai-context/api-patterns.md
@import ./docs/ai-context/testing-rules.md

Each sub‑file focuses on a single theme, allowing the AI to load only the relevant sections.

Summary

CLAUDE.md is a cross‑tool AI project specification; a single file can be read by Cursor, Claude Code, and Codex.

Hierarchical sections (overview → tech stack → directory → guidelines → delivery criteria) guide the AI step by step.

Rules must be actionable: use explicit ❌ markers and concrete examples.

Define clear delivery standards so the AI knows when a task is complete.

Avoid embedding secrets; reference them instead of writing values.