Mortdecai
9ff8e915b8
User-agnostic, shareable AI-assisted development workflow distilled from 26+ real projects. Includes 9 composable rules, 4 project templates, pre-push secret scanning hook, 3 methodology guides, and customization docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
80 lines
4.3 KiB
Markdown
80 lines
4.3 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.
|
|
|
|
## 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, and CONTEXT.md are persistent. Every decision, discovery, and convention should be written to the appropriate file so the next session starts informed, not cold.
|
|
|
|
### 2. Dynamic Composition Over Rigid Process
|
|
|
|
A single rigid process doesn't work across debugging, feature development, research, code review, and architecture. Instead, rules activate based on what you're doing:
|
|
|
|
- Debugging activates Five Whys and systematic debugging
|
|
- New features activate brainstorming and TDD
|
|
- Research activates documentation tiers and source attribution
|
|
- Security work activates deny lists and injection guards
|
|
|
|
The rules layer like a stack. See `workflows/dynamic-methodology.md`.
|
|
|
|
### 3. Proactive, Not Reactive
|
|
|
|
The AI should be a co-pilot that knows where the project is, suggests what's next, and detects when you're stuck. It shouldn't wait passively for instructions.
|
|
|
|
This means: ending every response with direction, auto-invoking tools when context signals they're needed, detecting scope creep, and breaking down overwhelming tasks.
|
|
|
|
### 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 `.ssh/`, `.aws/`, and `.env` 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. Every file read, every documentation query, every conversation turn adds to the budget.
|
|
|
|
Token-conscious habits (tiered lookups, selective reads, sub-agent delegation) are not premature optimization -- they're 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. No batching unrelated changes. No squashing. Push immediately for backup.
|
|
|
|
This creates a fine-grained git history that's searchable, revertible, and meaningful. It also means you never lose more than 15-30 minutes of work.
|
|
|
|
### 7. Honest About Uncertainty
|
|
|
|
Separate fact from inference. Cite sources. Flag single-source claims. Mark speculation as speculation. Cross-reference critical claims.
|
|
|
|
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, estimate velocity, or assign work to people.
|
|
- **Not a CI/CD pipeline.** It doesn't build, test, or deploy your code. It guides the AI assistant working alongside you.
|
|
- **Not prescriptive about stack.** It works with any language, framework, or deployment target.
|
|
- **Not AI-specific in philosophy.** Most of these principles (commit often, document decisions, security by default) apply to human-only teams too. The AI-specific parts are context management, session discipline, and the authority hierarchy.
|
|
|
|
## Origin
|
|
|
|
This workflow wasn't designed top-down. It accumulated bottom-up across 26+ real projects:
|
|
|
|
- Multi-agent AI systems with 50+ tools
|
|
- Infrastructure management (70+ services on a 4-node cluster)
|
|
- Game server operations and plugin development
|
|
- ML model training and evaluation pipelines
|
|
- Hardware control systems (3D printers, IoT devices)
|
|
- Human-AI collaborative research papers
|
|
- Web applications and API servers
|
|
|
|
Every rule exists because something broke without it. The session discipline rules exist because AI assistants kept losing context. The security rules exist because secrets were almost committed. The reasoning patterns exist because first-idea-wins produced inferior architectures.
|
|
|
|
Nothing here is theoretical. It all earned its place.
|