Mortdecai
ea3cf45953
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>
75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
# Philosophy
|
|
|
|
Why this workflow exists and the principles behind it.
|
|
|
|
## The Problem
|
|
|
|
AI coding assistants are powerful but amnesiac. They forget everything between sessions. They can't tell when they're running low on context. They don't know your project's conventions unless told. They'll happily commit secrets, skip tests, or propose architectures that contradict last week's decisions.
|
|
|
|
This workflow exists because these problems are solvable with structure.
|
|
|
|
## The Two-Tier Reality
|
|
|
|
This workflow has two tiers because that's what actually works in practice:
|
|
|
|
**Core practices** (used everywhere): The document hierarchy, the Superpowers plugin, the memory system, backup-before-edit, commit-and-push discipline, and the pre-push hook. These run in every project without any `.claude/rules/` files. The plugin enforces the workflow; the documents provide continuity; the memory system learns corrections.
|
|
|
|
**Advanced rules** (used in complex projects): Formal `.claude/rules/` files that provide explicit governance — session discipline protocols, authority hierarchy, proactive steering patterns, reasoning frameworks. These only make sense when a project is complex enough that implicit conventions break down.
|
|
|
|
Most projects never need the advanced tier. The core practices handle everything from small utilities to moderately complex web apps. The advanced tier exists for projects that span multiple domains, have multiple contributors, or where mistakes are expensive.
|
|
|
|
## Core Principles
|
|
|
|
### 1. Files Are Memory
|
|
|
|
The most important principle: **if it's not in a file, it doesn't exist next session.**
|
|
|
|
Conversation history is ephemeral. CLAUDE.md, SESSION.md, CONTEXT.md, and memory files are persistent. Every decision, discovery, and convention should be written to the appropriate file so the next session starts informed, not cold.
|
|
|
|
### 2. The Plugin Does the Enforcing
|
|
|
|
The Superpowers plugin is not optional tooling — it's the primary workflow enforcement mechanism. It drives brainstorming before building, TDD before implementation, systematic debugging before guessing at fixes, and verification before completion claims.
|
|
|
|
Without it, these practices are just suggestions. With it, they're enforced automatically. This is why the core workflow doesn't need `.claude/rules/` files — the plugin is the rules engine.
|
|
|
|
### 3. Feedback Over Configuration
|
|
|
|
The memory system learns from corrections. When you say "don't do X," that correction persists across sessions. Over time, the AI's behavior evolves based on your actual preferences, not a configuration file you wrote once and forgot about.
|
|
|
|
This is more powerful than static rules because:
|
|
- It captures the "why" behind each correction
|
|
- It adapts to your specific context
|
|
- Confirmations are captured too (not just corrections)
|
|
- It handles edge cases that rules can't anticipate
|
|
|
|
### 4. Security by Default
|
|
|
|
Secret scanning, file deny lists, and injection guardrails are not optional add-ons. They're default behavior. The pre-push hook catches secrets. The deny list blocks reads of sensitive files. The injection guardrails treat all external content as untrusted.
|
|
|
|
### 5. Context Is Finite
|
|
|
|
AI context windows are large but not infinite. Startup overhead (tool definitions, rules, plugins, CLAUDE.md) consumes 35-45k tokens before any work begins. Token-conscious habits (tiered lookups, selective reads, sub-agent delegation) are how you stay productive in long sessions.
|
|
|
|
### 6. Commit Early and Often
|
|
|
|
Every completed function, bug fix, or test addition gets its own commit with a conventional commit message. Push immediately. No batching. No squashing.
|
|
|
|
### 7. Honest About Uncertainty
|
|
|
|
Separate fact from inference. Cite sources. Flag single-source claims. Mark speculation as speculation. An AI that confidently states wrong information is worse than one that says "I'm not sure, let me check."
|
|
|
|
## What This Workflow Is NOT
|
|
|
|
- **Not a project management system.** It doesn't track sprints or estimate velocity.
|
|
- **Not a CI/CD pipeline.** It doesn't build, test, or deploy your code.
|
|
- **Not prescriptive about stack.** It works with any language, framework, or deployment target.
|
|
- **Not all-or-nothing.** The core practices work alone. The advanced rules are optional layers.
|
|
|
|
## Origin
|
|
|
|
This workflow wasn't designed top-down. It accumulated bottom-up across 26+ real projects. The core practices emerged because they worked everywhere — every project uses the document hierarchy, every session benefits from the Superpowers plugin, every correction saved to memory prevents future mistakes.
|
|
|
|
The advanced rules emerged from one project that was complex enough to need them. They're a formalization of patterns that the core practices handle implicitly in simpler contexts.
|
|
|
|
Nothing here is theoretical. It all earned its place.
|