---

name: claude-code-project-memory description: Configure CLAUDE.md project memory files for persistent context, coding standards, architecture decisions, and team conventions. Reference for the 4-tier memory hierarchy, cross-platform AGENTS.md compatibility, and quick-add commands.

Claude Code Project Memory — Meta Reference

This skill provides the definitive reference for configuring CLAUDE.md project memory. Use this when setting up project context that persists across sessions.

Modern Best Practices (January 2026): Cross-platform documentation via AGENTS.md standard (supported by Codex, Cursor, Copilot, Gemini), symlink strategy for single-source-of-truth, hierarchical documentation for large codebases (100K-1M LOC), context packing tools (gitingest, repo2txt), and <300 line file size recommendation with @references for depth.

---

Quick Reference

Memory Hierarchy

Copy4-Tier Precedence (highest to lowest):

1. Enterprise settings     (managed by admin)
2. Project memory          (CLAUDE.md, .claude/CLAUDE.md)
3. User global             (~/.claude/CLAUDE.md)
4. Local overrides         (CLAUDE.local.md)

Recursive Loading

Claude reads memories recursively from cwd up to (but not including) root. This enables hierarchical memory in monorepos.

On-Demand Loading

Subdirectory CLAUDE.md files are only loaded when Claude accesses files in those directories. This keeps context focused and prevents token waste on irrelevant parts of your codebase.

---

CLAUDE.md Template

Copy# Project Name

Brief description of the project.

## Architecture

- **Stack**: [technologies]
- **Structure**: [monorepo/microservices/etc]
- **Key patterns**: [patterns used]

## Code Standards

- [Standard 1]
- [Standard 2]
- [Standard 3]

## Development Workflow

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Testing Requirements

- [Testing standard 1]
- [Testing standard 2]

## When Working on This Project

- [Guideline 1]
- [Guideline 2]

## Agent Preferences

- Use `agent-name` for [task type]
- Prefer [approach] over [alternative]

---

Content Categories

Architecture Documentation

Copy## Architecture

### Tech Stack
- **Frontend**: Next.js 16, React 19, TypeScript, Tailwind CSS
- **Backend**: Node.js, Express, Prisma, PostgreSQL
- **Infrastructure**: Docker, Kubernetes, AWS

### Directory Structure
\`\`\`
src/
├── app/           # Next.js app router
├── components/    # React components
├── lib/           # Utilities
├── server/        # API routes
└── prisma/        # Database schema
\`\`\`

### Key Decisions
- ADR-001: Using App Router over Pages Router
- ADR-002: Prisma over raw SQL for type safety

Code Standards

Copy## Code Standards

### TypeScript
- Strict mode enabled
- Use `unknown` over `any`
- Prefer interfaces over types for objects

### Naming
- Components: PascalCase
- Functions: camelCase
- Constants: SCREAMING_SNAKE_CASE
- Files: kebab-case

### Imports
- Absolute imports via @/ alias
- Group: external → internal → relative

### Testing
- Test files: `*.test.ts` or `*.spec.ts`
- Minimum 80% coverage for new code
- E2E tests for critical paths

Workflow Instructions

Copy## When Working on This Project

1. Always run `npm run typecheck` before committing
2. Use conventional commits: `feat:`, `fix:`, `chore:`
3. Create PR for all changes (no direct push to main)
4. Request review from @team-lead for architecture changes
5. Update CHANGELOG.md for user-facing changes

## Agent Preferences

- Use `backend-engineer` for API changes
- Use `test-architect` for test coverage improvements
- Prefer Vitest over Jest for new tests
- Always run `npm run lint` after code changes

---

Quick-Add Commands

# Quick Memory Syntax

Start any input with # to instantly add to memory:

Copy# Always run tests before committing
# Use TypeScript strict mode
# Prefer Vitest over Jest

You'll be prompted to select which memory file to store in.

/init Command

Creates initial CLAUDE.md by analyzing project:

Copy/init

Generates memory from:

• package.json / pyproject.toml
• Directory structure
• Existing docs
• Git history

/memory Command

Manage project memory files:

Copy/memory           # Open memory file in system editor (for extensive edits)
/memory add "Always use TypeScript strict mode"   # Quick-add instruction
/memory show      # Display currently loaded memory files

Editor mode: Running /memory without arguments opens the memory file in your system editor (VS Code, Vim, etc.) for extensive multi-line editing. This is faster than adding instructions one-by-one.

Verification: Use /memory show to verify which rules are loaded, especially when using path-specific rules.

---

Session Management

/clear Command

Reset context for a new task:

Copy/clear

Use /clear when switching tasks instead of /compact. Starting fresh is faster and avoids context confusion.

/compact Command

Compress context when needed:

Copy/compact

Note: /compact is slow (1+ minutes). Prefer /clear for new tasks. Only use /compact when you need the previous context but are running low on tokens.

---

Rules Directory

For larger projects, organize instructions into multiple files using .claude/rules/:

Copyproject/
├── .claude/
│   ├── CLAUDE.md           # Main project memory
│   └── rules/              # Auto-loaded rule files
│       ├── code-style.md   # Coding standards
│       ├── testing.md      # Testing requirements
│       ├── security.md     # Security policies
│       └── workflows.md    # Team workflows
└── src/

Key behavior:

• All .md files in .claude/rules/ are automatically loaded as project memory
• Same priority as .claude/CLAUDE.md
• Enables team collaboration (different members maintain different rule files)
• Better organization for complex projects
• Supports symlinks for sharing rules across projects

Path-Specific Rules (Claude Code 2.0.64+)

Scope rules to specific files using YAML frontmatter with paths::

Copy---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{ts,tsx}"
---

# API Development Rules

These rules only apply when working on API files.

- Use Zod for request validation
- Return RFC 7807 Problem Details for errors
- Document all endpoints with OpenAPI comments

Important: Quote glob patterns starting with * or {:

Copy# ❌ Wrong - YAML syntax error
paths:
  - **/*.ts

# ✅ Correct - quoted patterns
paths:
  - "**/*.ts"
  - "src/**/*.{ts,tsx}"

Behavior:

• Rules without paths: apply globally (loaded in every session)
• Rules with paths: only load when Claude works on matching files
• Run /memory to verify which rules are currently loaded

Supported glob patterns:

---

Location Strategies

Single CLAUDE.md (Simple)

Copyproject/
├── CLAUDE.md    # All context here
└── src/

Best for small projects.

Split Memory (Modular)

Copyproject/
├── CLAUDE.md           # High-level overview
├── .claude/
│   ├── CLAUDE.md       # Detailed standards
│   └── ...
└── src/

Best for larger projects with detailed standards.

Monorepo

Copymonorepo/
├── CLAUDE.md           # Shared standards
├── packages/
│   ├── web/
│   │   └── CLAUDE.md   # Web-specific
│   ├── api/
│   │   └── CLAUDE.md   # API-specific
│   └── shared/
│       └── CLAUDE.md   # Shared lib specific

---

Local Overrides

Copy<!-- CLAUDE.local.md (git-ignored) -->

# Local Development Overrides

## My Preferences
- Use verbose logging
- Skip slow tests with --skip-e2e

## Local Environment
- DATABASE_URL points to local Docker
- Using Node 20 instead of 18

---

Enterprise Settings

Copy~/.claude/settings.json
/Library/Application Support/ClaudeCode/managed-settings.json

Enterprise admins can set organization-wide defaults that override project memory for:

• Security policies
• Approved tools
• Forbidden patterns

---

Cross-Platform Compatibility (January 2026)

AGENTS.md is the cross-platform standard for AI coding assistants, now supported by 20+ tools:

Claude Code still requires CLAUDE.md. Use symlinks for single-source-of-truth.

Option 1: New Project (Create Both from Scratch)

Copy# 1. Create AGENTS.md as the single source of truth
cat > AGENTS.md << 'EOF'
# Project Name

Brief description.

## Quick Start

- Build: `npm run build`
- Test: `npm test`

## Architecture Overview

[3-5 sentences, link to ARCHITECTURE.md]

## Key Conventions

- [Convention 1]
- [Convention 2]

## Directory Structure

- `/src` - Source code
- `/tests` - Test files

@ARCHITECTURE.md
EOF

# 2. Create symlinks for each platform
ln -s AGENTS.md CLAUDE.md      # For Claude Code
ln -s AGENTS.md GEMINI.md      # For Gemini (optional)

# 3. Verify symlinks work
ls -la *.md

Option 2: Existing CLAUDE.md (Migrate to Cross-Platform)

Copy# 1. Rename existing CLAUDE.md to AGENTS.md
mv CLAUDE.md AGENTS.md

# 2. Create symlinks back
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

# 3. Verify
cat CLAUDE.md  # Should show AGENTS.md content

Option 3: Using Claude Code /init (Claude-First)

Copy# 1. Let Claude Code generate CLAUDE.md
/init

# 2. Then migrate to cross-platform
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

Platform Comparison

File Size Guidelines (January 2026)

Sources: OpenAI AGENTS.md Guide, Anthropic Claude Code Best Practices

---

Large Codebase Strategy (100K-1M LOC)

For large codebases, the key principle is: LLMs don't need to remember everything—they need the right context at the right time.

Context Packing Tools

Before LLM sessions, extract relevant context using:

Hierarchical Documentation Pattern

Copyproject-root/
├── AGENTS.md              # Main entry point (~300 lines max)
├── CLAUDE.md → AGENTS.md  # Symlink for Claude Code
├── DESIGN.md              # Features, requirements, goals
├── ARCHITECTURE.md        # Data structures, data flow, modules
│
├── api/
│   └── AGENTS.md          # API-specific conventions
├── frontend/
│   └── AGENTS.md          # Frontend patterns, components
├── services/
│   └── AGENTS.md          # Service boundaries, dependencies
└── docs/
    ├── adr/               # Architecture Decision Records
    └── runbooks/          # Operational procedures

Working Strategy for Large Repos

1. Scope tasks narrowly — One function, one bug, one feature at a time
2. Context pack — Provide relevant files + AGENTS.md before each task
3. Iterate in small steps — Commit often, test thoroughly
4. Update docs as you go — Tell LLM to update AGENTS.md after changes while it has context

Root File Template (Keep Under 300 Lines)

Copy# Project Name

Brief description (1-2 sentences).

## Quick Start

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Architecture Overview

[3-5 sentences max, link to ARCHITECTURE.md for details]

## Key Conventions

- [Convention 1]
- [Convention 2]
- [Convention 3]

## Directory Structure

- `/api` - REST endpoints, see api/AGENTS.md
- `/frontend` - React app, see frontend/AGENTS.md
- `/services` - Business logic, see services/AGENTS.md

## Domain Terms

- **Term1**: Definition
- **Term2**: Definition

@ARCHITECTURE.md
@docs/coding-standards.md

Sources: Anthropic Claude Code Best Practices, OpenAI AGENTS.md Guide

---

Best Practices

DO

Copy## Good Memory Content

- Specific, actionable instructions
- Link to detailed docs: @docs/architecture.md
- Include examples where helpful
- Keep updated as project evolves
- Keep under 300 lines (use @references for depth)
- Update after completing features (while LLM has context)

DON'T

Copy## Avoid

- Vague guidelines ("write good code")
- Outdated information
- Duplicate information from code comments
- Overly long documents (use @references)
- Feeding entire codebase to LLM (scope tasks narrowly)

Performance Warnings

Token optimization: Memory files load at the start of every session. Each line costs tokens. Prioritize what's needed in every session; move the rest to @ referenced files.

---

File References

Use @ to reference other files:

Copy## Architecture

See @docs/architecture.md for detailed diagrams.

## API Patterns

Follow patterns in @src/api/README.md.

## Shared Rules

Include @~/.claude/shared-rules.md for personal standards.

Claude loads referenced files as additional context.

Import Constraints

Example of chained imports:

CopyCLAUDE.md → @docs/standards.md → @docs/api/conventions.md → ...
   (1)            (2)                    (3)              (max 5)

---

Validation Checklist

CopyCLAUDE.md VALIDATION

[ ] Describes project purpose
[ ] Lists tech stack
[ ] Defines code standards
[ ] Specifies testing requirements
[ ] Includes workflow instructions
[ ] Agent preferences documented
[ ] File references are valid (@paths exist)
[ ] Updated within last 30 days
[ ] No sensitive data (secrets, tokens)

---

Navigation

Resources

• references/memory-patterns.md — Common patterns
• references/memory-examples.md — Full examples
• data/sources.json — Documentation links

Related Skills

• ../claude-code-skills/SKILL.md — Skill creation
• ../claude-code-agents/SKILL.md — Agent creation
• ../docs-codebase/SKILL.md — Documentation patterns