feat: add core/ tier reflecting actual universal workflow
The original repo presented everything as equal rules. In reality, the workflow has two tiers: core practices (used in every project) and advanced rules (only in complex projects like Mortdecai). Core tier adds: - backup-before-edit (global CLAUDE.md rule) - superpowers-workflow (the actual workflow engine) - memory-system (persistent feedback and project memories) - document-hierarchy (CLAUDE.md/SESSION.md/CONTEXT.md/IDEA.md) - commit-and-push discipline - feedback-driven behaviors Updated README, docs, and dynamic-methodology to reflect the two-tier reality instead of presenting advanced rules as universal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,121 @@
|
||||
# Memory System
|
||||
|
||||
AI assistants forget everything between sessions. The memory system provides persistent, file-based memory that carries context forward.
|
||||
|
||||
## How It Works
|
||||
|
||||
Claude Code maintains a memory directory at `~/.claude/projects/<project-path>/memory/`. Each memory is a markdown file with frontmatter metadata, indexed by a `MEMORY.md` file.
|
||||
|
||||
## Memory Types
|
||||
|
||||
### User Memories
|
||||
Information about who you are — role, expertise, preferences. Helps the AI tailor its approach.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: user_role
|
||||
description: User is a senior infrastructure engineer with deep Linux/networking expertise
|
||||
type: user
|
||||
---
|
||||
|
||||
Senior infrastructure engineer. Deep expertise in Linux, ZFS, Proxmox, networking.
|
||||
New to React frontend work — frame frontend explanations in terms of backend analogues.
|
||||
```
|
||||
|
||||
### Feedback Memories
|
||||
Corrections and confirmed approaches — what to do and what NOT to do. **The most important type.** These prevent the AI from making the same mistake twice.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: feedback_subagent_safety
|
||||
description: Never use subagents for destructive server operations
|
||||
type: feedback
|
||||
---
|
||||
|
||||
Never use subagents for destructive server operations (git history changes,
|
||||
bare repo operations, database modifications). Do these manually, one at a time.
|
||||
|
||||
**Why:** A subagent running destructive ops in parallel caused data loss.
|
||||
The main conversation can't intervene if a subagent goes wrong.
|
||||
|
||||
**How to apply:** Before dispatching any agent, check if the task involves
|
||||
destructive operations. If yes, do it in the main conversation sequentially.
|
||||
```
|
||||
|
||||
### Project Memories
|
||||
Ongoing work, decisions, and context that isn't derivable from code or git history.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: project_auth_rewrite
|
||||
description: Auth middleware rewrite driven by legal compliance, not tech debt
|
||||
type: project
|
||||
---
|
||||
|
||||
Auth middleware rewrite is driven by legal/compliance requirements around
|
||||
session token storage, not tech-debt cleanup.
|
||||
|
||||
**Why:** Legal flagged the current implementation for non-compliant token storage.
|
||||
**How to apply:** Scope decisions should favor compliance over ergonomics.
|
||||
```
|
||||
|
||||
### Reference Memories
|
||||
Pointers to where information lives in external systems.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: reference_bug_tracker
|
||||
description: Pipeline bugs tracked in Linear project INGEST
|
||||
type: reference
|
||||
---
|
||||
|
||||
Pipeline bugs are tracked in Linear project "INGEST".
|
||||
API monitoring alerts go to #oncall-api Slack channel.
|
||||
```
|
||||
|
||||
## MEMORY.md Index
|
||||
|
||||
`MEMORY.md` is a one-line-per-entry index of all memory files. It's loaded into every conversation.
|
||||
|
||||
```markdown
|
||||
# Memory Index
|
||||
|
||||
- [user_role.md](user_role.md) — Senior infra engineer, new to React
|
||||
- [feedback_subagent_safety.md](feedback_subagent_safety.md) — No subagents for destructive ops
|
||||
- [project_auth_rewrite.md](project_auth_rewrite.md) — Auth rewrite is compliance-driven
|
||||
- [reference_bug_tracker.md](reference_bug_tracker.md) — Bugs in Linear INGEST project
|
||||
```
|
||||
|
||||
Keep entries under 150 characters. MEMORY.md is truncated after 200 lines.
|
||||
|
||||
## What NOT to Save
|
||||
|
||||
- Code patterns or architecture (derivable from reading current code)
|
||||
- Git history (use `git log` / `git blame`)
|
||||
- Debugging solutions (the fix is in the code, context in the commit message)
|
||||
- Anything already in CLAUDE.md
|
||||
- Ephemeral task details (use task tools instead)
|
||||
|
||||
## When to Save
|
||||
|
||||
- **Immediately** when the user explicitly asks to remember something
|
||||
- **Proactively** when you learn about the user's role, preferences, or expertise
|
||||
- **After corrections** — if the user says "don't do X", save it as feedback
|
||||
- **After confirmed approaches** — if something non-obvious worked, save that too
|
||||
- **When project context emerges** that won't be in code (deadlines, stakeholder decisions, compliance requirements)
|
||||
|
||||
## When to Read
|
||||
|
||||
- At conversation start (MEMORY.md index is auto-loaded)
|
||||
- When the user references prior-conversation work
|
||||
- Before making decisions that prior feedback might inform
|
||||
- When the user says "check", "recall", or "remember"
|
||||
|
||||
## Stale Memory
|
||||
|
||||
Memories can become outdated. Before acting on a memory:
|
||||
- If it names a file path: check the file exists
|
||||
- If it names a function or flag: grep for it
|
||||
- If the user asks about *current* state: prefer `git log` or reading code over recalling a snapshot
|
||||
|
||||
"The memory says X exists" is not the same as "X exists now."
|
||||
Reference in New Issue
Block a user