Project Memory (CLAUDE.md)
Relevant source files
The following files were used as context for generating this wiki page:CLAUDE.md is a foundational configuration file that serves as the persistent, high-level memory for the Claude Code AI assistant. It is automatically loaded at the beginning of each session to provide Claude with essential context about the project's architecture, conventions, and critical rules. This file ensures that the AI's behavior and generated code align with the project's specific standards from the outset.
This document is the starting point for Claude's understanding of the codebase, acting as a "bootstrapping" script that informs its interactions. It works in concert with other configurations like Skills, Agents, and Hooks to create a highly customized and automated development environment.
Sources: README.md:129-131, CLAUDE.md:1-3
Architecture and Loading Precedence
The CLAUDE.md file is loaded based on a specific order of precedence, allowing for global, project-level, and more specific overrides. The system searches for the file in three locations and uses the first one it finds.
Sources: README.md:133-137
This diagram illustrates the search order for the CLAUDE.md file.
Sources: README.md:133-137
The locations are checked in this order:
.claude/CLAUDE.md: Project-specific, located within the.claudeconfiguration directory. This is the most specific and preferred location../CLAUDE.md: Project root. An alternative location for project-specific memory.~/.claude/CLAUDE.md: User-level global memory, applied across all projects for a given user.
Sources: README.md:134-137
File Structure and Content
The CLAUDE.md file is structured with markdown headings to organize information logically. The goal is to provide a quick and comprehensive overview for the AI.
Sources: CLAUDE.md:1-55
Key Sections
The example CLAUDE.md is divided into several key sections, each serving a distinct purpose.
| Section | Purpose | Example Content |
|---|---|---|
| Quick Facts | Provides high-level technical stack and primary commands. | Stack: React, TypeScript, Node.js; Test Command: npm test |
| Key Directories | Maps important source code directories to their functions. | src/components/ - React components |
| Code Style | Defines stylistic rules and preferences. | Prefer interface over type; No any |
| Git Conventions | Outlines branching and commit message formats. | Branch: {initials}/{description}; Commits: Conventional Commits |
| Critical Rules | Lists non-negotiable rules for development, especially for UI and error handling. | Always handle loading, error, empty states; Never swallow errors. |
| Skill Activation | Instructs Claude on which specialized skills to use for specific tasks. | Creating tests → testing-patterns skill |
| Common Commands | A reference for frequently used shell commands. | npm run dev, gh pr create |
Sources: CLAUDE.md:5-55, README.md:104-114
Example: Critical Rules
This section is vital for ensuring application quality and robustness. It provides explicit instructions on handling mutations, UI states, and errors.
UI State Handling Rules:
- Always handle
loading,error,empty, andsuccessstates. - Loading indicators should only be shown when no data is present.
- All lists must have a defined empty state.
Mutation Rules:
- Disable buttons during asynchronous operations.
- Show a loading indicator on the button performing the action.
- Implement an
onErrorhandler that provides user feedback.
Sources: CLAUDE.md:31-41
Integration with the Claude Ecosystem
CLAUDE.md does not operate in isolation. It is the entry point that guides the AI to use other, more specialized tools and knowledge bases like Skills and Agents.
Skill Activation
A key function of CLAUDE.md is to direct the AI to activate specific "Skills" based on the task at hand. This creates a direct link between a high-level project rule and a detailed, actionable knowledge document.
The following sequence diagram shows how CLAUDE.md's "Skill Activation" rules are used when a developer gives a prompt.
This flow demonstrates how the general directive in CLAUDE.md (Creating tests → testing-patterns skill) connects the user's intent to the specific implementation details found in .claude/skills/testing-patterns/SKILL.md.
Sources: CLAUDE.md:43-49, README.md:116-120, README.md:310-313
Informing Agents and Commands
The context from CLAUDE.md also provides a baseline for more complex workflows managed by Agents and Commands. For example, the code-reviewer agent would use the "Code Style" and "Critical Rules" from CLAUDE.md as part of its review checklist.
This diagram shows that CLAUDE.md provides the core project context that informs all other specialized skills, agents, and commands.
Sources: README.md:330-333, README.md:351-353, CLAUDE.md:19-41
Summary
The CLAUDE.md file is the cornerstone of the Claude Code configuration, acting as the project's persistent memory. It provides the essential, high-level context required for the AI to operate effectively and in alignment with project standards. By defining the technical stack, key directories, coding styles, and critical rules, it ensures consistency. Furthermore, its role in directing the AI to use specific Skills for given tasks makes it a crucial orchestrator within the broader automation ecosystem, bridging the gap between high-level project standards and detailed implementation guidelines.
Sources: README.md:129-131, CLAUDE.md:1-3