claude-memory

Original：🇺🇸 English

Translated

Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Comprehensive guidance on file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness.

7installs

Sourcemelvynx/aiblueprint

Added on2026-03-09

NPX Install

npx skill4agent add melvynx/aiblueprint claude-memory

SKILL.md Content

View Translation Comparison →

<core_principle> Memory files consume tokens from the context window. ~100-150 instruction slots available for your customizations. Keep files minimal — only include what the agent cannot discover on its own.

Two approaches:

CLAUDE.md — Single file, best for small projects (< 100 lines)
.claude/rules/ — Modular files with optional path-scoping, best for large projects </core_principle>

<quick_start> Run

/init

to auto-generate a CLAUDE.md. Or create manually:

markdown

# Project Name

## Tech Stack
- [Primary framework]
- [Key non-obvious libraries]

## Commands
- `npm run dev` - Dev server
- `npm test` - Run tests
- `npm run build` - Build

## Rules
- [2-3 critical project-specific rules]

Press
```
#
```
during a session to add memory items quickly
Use
```
/memory
```
to open CLAUDE.md in your editor </quick_start>

<file_hierarchy>

Priority	Location	Scope
1 (Highest)	Enterprise policy (managed by IT)	All org users
2	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team via git
2	`./.claude/rules/*.md`	Team via git
3	`~/.claude/CLAUDE.md`	All your projects
3	`~/.claude/rules/*.md`	All your projects
4 (Lowest)	`./CLAUDE.local.md` (auto-gitignored)	Just you

Claude recurses UP from current directory, loading all CLAUDE.md files found. Also discovers CLAUDE.md in subtrees when reading files in those directories.

Monorepo strategy: Root file defines WHEN; subtree files define HOW.

root/CLAUDE.md           # Universal: tech stack, git workflow
apps/web/CLAUDE.md       # Frontend-specific
apps/api/CLAUDE.md       # Backend-specific

</file_hierarchy>

<rules_directory> The

.claude/rules/

directory splits instructions into focused markdown files.

Use
.claude/rules/
when: many concerns, different rules for different file types, team maintains different areas. Use CLAUDE.md when: small project, universal rules, single source of truth.

Path-scoped rules use YAML frontmatter:

yaml

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation

Supported patterns:

**/*.ts

src/**/*

src/**/*.{ts,tsx}

{src,lib}/**/*.ts

Rules without

paths

frontmatter load unconditionally.

See references/rules-directory-guide.md for complete guide including symlinks, user-level rules, and migration. </rules_directory>

<content_structure> Structure CLAUDE.md with only these sections:

Project purpose (1-3 lines) — What the project is
Tech stack (compact) — Only non-obvious technologies
Commands — Non-obvious dev, build, and test commands
Important files — Architecture-critical, non-obvious files only
Rules — Prohibitions and constraints that prevent mistakes (highest-value lines)
Workflow (optional) — Only if non-standard

Do NOT include:

Repository overviews (agent discovers structure itself)
Code style rules (linters enforce these)
Generic best practices ("write clean code", "DRY", "SOLID")
Redundant specs (copies of config files, env vars, schema descriptions)
Marketing/goals (vision statements, KPIs, roadmaps)
Verbose explanations (paragraphs where one line suffices)

See references/section-templates.md for ready-to-use templates. See references/project-patterns.md for framework-specific patterns. </content_structure>

<writing_rules> Golden rule: If someone with zero project context reads your CLAUDE.md and gets confused, Claude will too.

Be specific, never vague:

❌ "Format code properly" / "Write good tests" / "Follow best practices"
✅ "Run `pnpm lint` before committing" / "Tests in `__tests__/` using Vitest"

Prohibitions > positive guidance:

❌ "Try to use TanStack Form for forms"
✅ "NEVER use native form/useState for forms — ALWAYS use TanStack Form"

Show, don't tell: When format matters, show a concrete example (3-5 lines max).

Emphasis hierarchy: CRITICAL > NEVER > ALWAYS > IMPORTANT > YOU MUST

Put critical rules first in each section
Use bold + keyword for non-negotiable rules:
```
**CRITICAL**: Never commit secrets
```

See references/prompting-techniques.md for advanced techniques. </writing_rules>

<size_limits>

Ideal: < 100 lines
Maximum: 150 lines before performance degrades
Over 200 lines: directives start getting lost

When exceeding limits, split into

.claude/rules/

files or link to separate docs:

markdown

- **API patterns**: See [docs/api-patterns.md](docs/api-patterns.md)
- **Testing guide**: See [docs/testing-guide.md](docs/testing-guide.md)

CLAUDE.md supports importing:

@docs/coding-standards.md

(relative/absolute paths,

expansion, up to 5 levels deep, not evaluated inside code blocks). </size_limits>

<workflow> **ALWAYS ASK FIRST: Storage Strategy**

Before creating or updating memory files, use AskUserQuestion:

Option 1: Single CLAUDE.md — < 100 lines, simple project, universal rules
Option 2: Modular .claude/rules/ — 100+ lines, different rules for different files

Creating new memory:

Start with
```
/init
```
or minimal template
Add tech stack and commands first
Add rules only as you encounter friction
Test with real tasks, iterate based on Claude's behavior

Maintaining:

Review quarterly or when project changes significantly
Remove outdated instructions
Add patterns that required repeated explanation
Use
```
#
```
for quick additions during work

Troubleshooting:

Problem	Solution
Claude ignores instructions	Reduce file size, add emphasis (CRITICAL, NEVER)
Context overflow	Use `/clear` , split into .claude/rules/
Instructions conflict	Consolidate, use hierarchy (root vs subtree)
Path rules not applying	Verify glob pattern matches target files

</workflow>

<init_workflow>

/claude-memory init

— Create Minimal CLAUDE.md

When the user argument contains "init", execute this workflow to scaffold a CLAUDE.md with only the essential sections.

Step 1: Detect project context

Read

package.json

(or equivalent:

pyproject.toml

Cargo.toml

go.mod

, etc.) to detect:

Project name
Tech stack (framework, language)
Available scripts/commands (dev, build, test)

Also check for existing linter configs (ESLint, Biome, Prettier, tsconfig) — do NOT include rules they already enforce.

Step 2: Identify important files

Scan for non-obvious architecture-critical files. Look for:

Auth config files
Server action wrappers, API helpers
Database schema files
Custom middleware or shared utilities
Skip standard framework files (package.json, tsconfig, next.config, etc.)

Step 3: Generate CLAUDE.md

Create the file with ONLY these sections. Each section should be compact — the whole file should be under 50 lines.

markdown

# [Project Name]
[One-line description of what this project is]

## Tech Stack
- [Only non-obvious technologies — skip deps detectable from config files]

## Commands
- `[dev command]` - Dev server
- `[build command]` - Build
- `[test command]` - Tests
- [Any non-obvious commands like db:push, seed, etc.]

## Important Files
- [Only files the agent wouldn't discover naturally]

## Rules
- [Leave empty with a comment: "Add project-specific rules as you encounter friction"]

Step 4: Present and write

Show the generated file to the user. Write it to

./CLAUDE.md

after approval.

Rules:

NEVER include directory structure, code style rules, generic best practices, or marketing text
NEVER include anything a linter or TypeScript already enforces
Target: 20-50 lines. If it's longer, you're including too much
The Rules section starts empty — it gets populated over time as mistakes happen </init_workflow>

<optimize_workflow>

/claude-memory optimize

— Deep CLAUDE.md Cleanup

When the user argument contains "optimize", execute this workflow.

CRITICAL — Step 0 is MANDATORY. Do NOT skip it. Do NOT start optimizing without reading the guide first.

Step 0: Read the optimization guide (REQUIRED FIRST)

YOU MUST use the Read tool on

{SKILL_PATH}/references/optimize-guide.md

BEFORE doing anything else. This file contains the research data (ETH Zurich study), the 6 bloat categories with specific examples, target metrics, and before/after examples. Without reading it, you will miss removal criteria and produce a subpar optimization.

Step 1: Inventory

Read every CLAUDE.md, CLAUDE.local.md, and

.claude/rules/*.md

in the project. Count total lines.

Step 2: Read linter configs

Read ESLint/Biome/Prettier/TypeScript configs. Any CLAUDE.md line duplicating an enforced rule → delete.

Step 3: Apply the 6 bloat categories from the guide

For each line ask: "Can the agent discover this by reading the project, or does a linter enforce this?" If yes → delete.

Remove everything matching:

Linter-enforced rules (ESLint, Prettier, Biome, TypeScript strict)
Marketing / goals / vision (zero code value)
Obvious info the agent discovers itself (directory structure, framework defaults, deps from package.json)
Verbose explanations (paragraphs where 1 line suffices, tutorials, history)
Redundant specs (copies of config files, schema descriptions, env var lists)
Generic best practices ("write clean code", "DRY", "SOLID")

Step 4: Keep only essentials

Project purpose (1-3 lines)
Tech stack (compact, non-obvious only)
Core commands (non-obvious only)
Testing commands
Important files (non-obvious only)
Project-specific rules (prohibitions + constraints)
Workflow (only if non-standard)

Step 5: Compress

Paragraphs → bullet points
3-line rules → 1-line rules
Zero filler words ("In order to", "It's important to note that")
Merge related items

Step 6: Present diff

Show before/after with line counts. For each removal, cite which bloat category it falls under. Let user approve before applying changes.

Target: < 100 lines ideal, < 150 max. </optimize_workflow>

<reference_guides>

Optimization guide: references/optimize-guide.md — Research-backed bloat checklist, 6 removal categories, before/after examples
Rules directory: references/rules-directory-guide.md — Complete .claude/rules/ guide with path-scoping, YAML syntax, symlinks, migration
Prompting techniques: references/prompting-techniques.md — Emphasis strategies, clarity techniques, constraint patterns
Section templates: references/section-templates.md — Copy-paste templates for each section type
Comprehensive example: references/comprehensive-example.md — Full production SaaS CLAUDE.md
Project patterns: references/project-patterns.md — Next.js, Express, Python, Monorepo patterns </reference_guides>

claude-memory

NPX Install

Tags

SKILL.md Content

`/claude-memory init`
— Create Minimal CLAUDE.md

Step 1: Detect project context

Step 2: Identify important files

Step 3: Generate CLAUDE.md

Step 4: Present and write

`/claude-memory optimize`
— Deep CLAUDE.md Cleanup

Step 0: Read the optimization guide (REQUIRED FIRST)

Step 1: Inventory

Step 2: Read linter configs

Step 3: Apply the 6 bloat categories from the guide

Step 4: Keep only essentials

Step 5: Compress

Step 6: Present diff