Learning Taxonomy

Expert reference for categorizing session learnings and routing them to appropriate targets for context improvement.

Learning Categories

Claude Code Memory Hierarchy

Claude Code uses a hierarchical memory system. Understanding this is critical for routing learnings correctly.

Memory Locations (Highest to Lowest Priority)

/Library/Application Support/ClaudeCode/CLAUDE.md

./CLAUDE.md

./.claude/CLAUDE.md

./.claude/rules/*.md

~/.claude/CLAUDE.md

~/.claude/rules/*.md

./CLAUDE.local.md

Memory Scope Decision

~/.claude/CLAUDE.md

./CLAUDE.local.md

./CLAUDE.md

./.claude/rules/{topic}.md

./.claude/rules/

paths:

Path-Specific Rules

For learnings that only apply to certain files:

---
paths: src/api/**/*.ts
---

# API Rules
- Validate all inputs with zod

Glob patterns:

**/*.ts

src/**/*

*.md

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

Import Syntax

CLAUDE.md files can import other files:

See @README for project overview.
Individual preferences: @~/.claude/my-prefs.md

Target Routing

By Learning Scope

./CLAUDE.md

./.claude/rules/{topic}.md

./.claude/rules/

paths:

~/.claude/CLAUDE.md

## My Preferences

./CLAUDE.local.md

## Local Setup

By Category (Default: Project Memory)

## Important Caveats

## Conventions & Patterns

## Troubleshooting

## Dependencies

## Common Commands

## Architecture

Secondary Targets

Suggestion Format Templates

Caveat Entry

### [Short Title]
- [Specific caveat or gotcha]
- [Workaround or required action if applicable]

Pattern Entry

### [Pattern Name]
- **When**: [When to use this pattern]
- **How**: [How to implement]
- **Example**: [Brief example if helpful]

Error Fix Entry

### [Error Name or Symptom]
**Symptoms:** [What the user sees]
**Cause:** [Root cause]
**Fix:**
```bash
[Commands to fix if applicable]

### Dependency Entry
```markdown
### [Package/Tool Name]
- **Version**: [Required version]
- **Purpose**: [Why it's needed]
- **Install**: `[install command]`

Command Entry

### [What the Command Does]
```bash
[command with arguments]

[Brief explanation if not obvious]

### Architecture Entry
```markdown
### [Component/Pattern Name]
- **Purpose**: [What it does]
- **Location**: [Where to find it]
- **Interactions**: [What it connects to]

Priority Calculation

High Priority

All of these must be true:

• Category is

  caveat

  or

  error_fix

• Confidence >= 0.8
• Target is primary (root CLAUDE.md)

Medium Priority

Any of these:

• Confidence >= 0.6
• Target is primary
• Category is

  dependency

  or

  architecture

Low Priority

Default when neither High nor Medium criteria met.

Source Analysis

Git Commits

• Prefix patterns boost confidence:

  • fix:

    ,

    bugfix:

    ,

    hotfix:

    → error_fix (0.85)

  • feat:

    ,

    feature:

    → pattern (0.60)

  • docs:

    ,

    doc:

    → pattern (0.70)

  • chore:

    ,

    deps:

    → dependency (0.75)

Git Diff Analysis

• Files modified 3+ times in session → potential caveat area
• TODO/FIXME comments added → high-confidence caveats
• New entries in package.json/requirements.txt → dependency

User Input

• Direct input always gets confidence 0.9
• User explicitly categorizes → use their category

Integration with Other Plugins

backlog-md / simbl

If these plugins are present, also extract learnings from:

• Task notes (

  --append-notes

  content)
• Implementation plans
• Acceptance criteria comments

Check for these directories:

• backlog/tasks/

  (backlog-md)

• .simbl/

  (simbl)

documentation-tools

After applying suggestions, consider running:

• /link-docs-to-claude

  - Update documentation links

• /sync-agents-md

  - Sync CLAUDE.md → AGENTS.md

Best Practices

When Extracting Learnings

1. Prefer specific over generic (not "be careful" but "restart server after config changes")
2. Include context (file paths, command examples)
3. Capture the "why" not just the "what"
4. Date-stamp session learnings for freshness tracking

When Generating Suggestions

1. Match learning to most specific target available
2. Use existing section if present, create if not
3. Format consistently with existing content
4. Keep suggestions atomic (one learning per suggestion)

When Reviewing Suggestions

1. Present highest priority first
2. Show diff preview with context
3. Allow modification before applying
4. Track applied vs discarded for learning

Common Mistakes to Avoid

source .env.local

~/.claude/CLAUDE.md

./CLAUDE.local.md

./CLAUDE.md

./CLAUDE.local.md

./.claude/rules/{topic}.md

./.claude/rules/