# /learn - Claude Code Best Practices & Learning Capture
Learn Claude Code best practices and capture lessons into persistent memory.
## Usage
- `/learn` — Show best practices guide
- `/learn <topic>` — Show practices for a specific topic (e.g., `/learn context`, `/learn prompting`)
- `/learn save` — Capture a lesson from this session into the database
## Best Practices
### Sessions & Context
- Every Claude Code invocation is a session. Claude reads your project on start.
- Context window is finite (200k tokens). Use `/context` to check usage.
- Use `/compact` at task boundaries — after planning, after a feature, when >70%.
- Don't compact mid-task. You lose working context.
- Plan mode now survives compaction (fixed in 2.1.49).
- **Docs:** https://code.claude.com/docs/common-workflows
- **Pattern:** Context Discipline (Pattern 7)
### CLAUDE.md & Memory
- CLAUDE.md is persistent project memory. It loads every session.
- Put: project structure, build commands, conventions, constraints, gotchas.
- Don't put: entire file contents, obvious things, rapidly changing info.
- For complex projects, split into AGENTS.md, SOUL.md, LEARNED.md.
- **Docs:** https://code.claude.com/docs/settings
- **Pattern:** Split Memory (Pattern 4)
### Modes
- **Normal** — Claude asks before edits (default)
Creates an isolated git worktree automatically. Subagents support `isolation: worktree` in frontmatter.
### Prompting
Good prompts have four parts:
1. **Scope** — What files/area to work in
2. **Context** — Background info Claude needs
3. **Constraints** — What NOT to do
4. **Acceptance criteria** — How to know it's done
Bad: "Add rate limiting"
Good: "In src/auth/, add rate limiting to the login endpoint. We use Express with Redis. Don't change session middleware. Return 429 after 5 failed attempts per IP in 15 min."
### Writing Rules
Rules in CLAUDE.md prevent Claude from going off-track.
- Good: "Always use snake_case for database columns"
- Good: "Run pytest -x after any Python file change"
- Bad: "Write good code"
- Bad: "Be careful"
- **Pattern:** Self-Correction Loop (Pattern 1)
### Skills
Skills are reusable commands defined in markdown with frontmatter. Create one when you repeat the same prompt pattern >3 times.
- **Docs:** https://code.claude.com/docs/settings
- **Pattern:** Learning Log (Pattern 8)
### Subagents
Subagents run in separate context windows for parallel work.
- Use for: parallel exploration, background tasks, independent research.
Replace `<project>` with the current project name (from `basename $PWD`), or `NULL` if unknown. Escape single quotes in values by doubling them (`''`).
Alternatively, use the store API:
```bash
node -e "const p = require('path'); const {createStore} = require(p.join(process.env.HOME, '.claude/plugins/marketplaces/pro-workflow/dist/db/store.js')); const s = createStore(); const l = s.addLearning({project: '<project>', category: '<category>', rule: '<rule>', mistake: '<mistake>', correction: '<correction>'}); console.log('Saved as learning #' + l.id); s.close();"
```
### Step 3: Confirm to user
After saving, output a confirmation with the learning ID:
```
Saved as learning #<id>. Use /search <keyword> to find this later.
```
### Auto-capture via [LEARN] tags
You can also emit `[LEARN]` blocks in your response, which the Stop hook will auto-capture:
```
[LEARN] Category: Rule text here
Mistake: What went wrong
Correction: How it was fixed
```
### Example
```
Category: Claude-Code
Rule: Use plan mode before multi-file changes
Mistake: Started editing 5 files without a plan, had to redo
Correction: Enter plan mode first, get approval, then execute
```
After user confirms → run the sqlite3 INSERT → output:
```
Saved as learning #42. Use /search plan to find this later.
```
Learnings are stored in `~/.pro-workflow/data.db` and persist across sessions.
Use `/search <keyword>` to find past learnings.
Use `/list` to see all learnings.
---
**Trigger:** Use when user says "learn", "teach me", "best practices", "remember this", or after making a mistake.
