Project Memory Skill

Set up and organize Claude Code's project memory system for consistent, context-aware assistance.

Core Principle

Project memory teaches Claude Code how to work with your specific codebase. Well-organized project memory leads to more accurate, consistent, and helpful responses.

Memory Hierarchy

Claude Code reads instructions in this order (higher = more precedence):

• Enterprise policy (managed, highest)

• User memory (~/.claude/CLAUDE.md )

• Project memory (CLAUDE.md in project root)

• Modular rules (.claude/rules/*.md )

• Local memory (CLAUDE.local.md , gitignored)

Later sources override earlier ones for conflicting instructions.

File Types

CLAUDE.md (Project Root)

Purpose: Primary project instructions, conventions, and context

Location: Project root directory

Visibility: Checked into git, shared with team

Contents:

• Project overview and architecture

• Development commands (build, test, lint)

• Coding conventions and patterns

• Important constraints or requirements

• Links to key documentation

.claude/rules/*.md

Purpose: Modular, path-specific rules

Location: .claude/rules/ directory

Visibility: Checked into git

Features:

• Automatically loaded based on file path

• Supports subdirectories

• Can use YAML frontmatter with globs for path-specific targeting

CLAUDE.local.md

Purpose: Personal, machine-specific instructions

Location: Project root directory

Visibility: Should be gitignored

Use cases:

• Personal preferences

• Local environment paths

• Machine-specific configurations

• Experimental instructions

Setting Up Project Memory

1. Create CLAUDE.md

Start with essential project information:

Project Name

Brief description of what this project does.

Development Commands

# Build
npm run build

# Test
npm test

# Lint
npm run lint

Architecture

• src/ - Source code
• tests/ - Test files
• docs/ - Documentation

Conventions

• Use TypeScript for all new code
• Follow existing patterns in the codebase
• Run tests before committing

Key Files

• src/index.ts - Main entry point
• src/config.ts - Configuration handling

2. Add Modular Rules (Optional)

Create path-specific rules in .claude/rules/ :

.claude/ rules/ api.md # Rules for API code tests.md # Rules for test files components/ forms.md # Rules for form components

3. Path-Specific Rules with Globs

Use YAML frontmatter to target specific paths:

paths: ["src/api//*.ts", "src/services//*.ts"]

API Development Rules

• All API functions must be async
• Always validate input parameters
• Use consistent error response format
• Include JSDoc with @throws annotations

4. Import Syntax

Reference other files from CLAUDE.md:

Project Instructions

See architecture: @docs/ARCHITECTURE.md See API guidelines: @docs/API_GUIDELINES.md

Imported files are treated as direct context.

CLAUDE.md Template

[Project Name]

[One-paragraph description of what this project does]

Quick Start

# Install dependencies
[command]

# Run development server
[command]

# Run tests
[command]

Architecture

[Brief overview of project structure]

Key Directories

• src/ - [Description]
• tests/ - [Description]
• config/ - [Description]

Key Files

• src/index.ts - [Description]
• src/config.ts - [Description]

Development Guidelines

Code Style

• [Style convention 1]
• [Style convention 2]

Testing

• [Testing convention 1]
• [Testing convention 2]

Git Workflow

• [Commit convention]
• [Branch convention]

Common Tasks

Adding a New Feature

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

Running Tests

[test command]

Important Notes

• [Critical constraint or requirement]
• [Security consideration]
• [Performance consideration]

Path-Specific Rules Examples

For API Code

paths: ["src/api/**/*.ts"]

API Development Rules

Request Handling

• Validate all input with zod schemas
• Return consistent error format: { error: string, code: string }
• Always set appropriate HTTP status codes

Authentication

• All endpoints require auth unless in ALLOWED_PUBLIC_ROUTES
• Use requireAuth() middleware

Response Format

// Success
{ data: T, meta?: { page, total } }

// Error
{ error: string, code: string, details?: object }

For Test Files

paths: ["/*.test.ts", "/*.spec.ts"]

Testing Rules

Structure

• Use describe() for grouping related tests
• Use it() with descriptive names: "should [action] when [condition]"
• One assertion per test when possible

Mocking

• Prefer dependency injection over mocking
• Mock at boundaries (API, database, file system)
• Clear mocks between tests

Coverage

• All public functions need tests
• Test happy path and error cases
• Include edge cases

For React Components

paths: ["src/components/**/*.tsx"]

Component Rules

Structure

• One component per file
• Export component as default
• Co-locate styles with component

Props

• Define props interface above component
• Use destructuring in function signature
• Document required vs optional props

State

• Prefer controlled components
• Lift state up when shared between components
• Use hooks for complex state logic

Best Practices

Keep It Concise

Bad:

Introduction

This project is a web application that allows users to manage their tasks. It was started in 2023 and has grown to include many features including task creation, task editing, task deletion, task filtering, task sorting, task searching, task sharing, and task exporting...

Good:

Task management web app. Users create, edit, filter, and share tasks.

Be Specific and Actionable

Bad:

Write good code and follow best practices.

Good:

• Use TypeScript strict mode
• Run npm run lint before committing
• All functions need JSDoc comments

Include Commands

Bad:

Build the project before deploying.

Good:

npm run build
npm run deploy

Use Imports for Long Content

Bad: Everything in one huge CLAUDE.md

Good:

Project

Quick overview here.

Detailed Documentation

Architecture: @docs/ARCHITECTURE.md API Guide: @docs/API.md Deployment: @docs/DEPLOYMENT.md

Path-Specific Over Generic

Bad:

CLAUDE.md

When writing tests, always use Jest. When writing API code, always validate input. When writing components, always use TypeScript.

Good:

.claude/rules/tests.md -> Jest rules .claude/rules/api.md -> Validation rules .claude/rules/components.md -> TypeScript rules

When to Update Project Memory

Add New Instructions

• Onboarding reveals missing context

• Repeated questions indicate gaps

• New conventions are established

• Architecture changes significantly

Review Existing Instructions

• Code changes make instructions outdated

• Team feedback indicates confusion

• Patterns evolve over time

Common Patterns

Monorepo Setup

Monorepo

Packages

• packages/core/ - Core library
• packages/cli/ - CLI tool
• packages/web/ - Web application

Commands

# Build all packages
npm run build

# Test specific package
npm run test --workspace=packages/core

Rules

See package-specific rules in each package's .claude/rules/ directory.

Environment-Specific Notes

Keep in CLAUDE.local.md (gitignored):

Local Setup Notes

Environment

• Using Node 20.x
• PostgreSQL running on port 5433 (not default)
• Redis running in Docker

Personal Preferences

• Prefer verbose test output
• Always run lint before suggesting changes

Integration with Han Plugins

Han plugins can contribute to project memory through hooks:

• SessionStart hooks can inject plugin-specific context

• UserPromptSubmit hooks can add reminders about conventions

• Blueprints complement CLAUDE.md with detailed system documentation

Troubleshooting

Claude Code ignores instructions

• Check file location (must be project root for CLAUDE.md)

• Check syntax (YAML frontmatter must be valid)

• Check glob patterns match the files you're editing

• More specific rules override general ones

Rules conflict between files

• Later in hierarchy wins

• More specific globs win over general

• Local overrides project

Performance with large CLAUDE.md

• Use imports for detailed docs

• Keep CLAUDE.md focused on essentials

• Move detailed rules to .claude/rules/

Remember

• Start small - Basic commands and conventions first

• Be specific - Actionable instructions, not vague guidelines

• Stay current - Update when code changes

• Use hierarchy - Modular rules for path-specific needs

• Test it - Verify Claude Code follows your instructions

Good project memory makes Claude Code a better collaborator.