# AI Dev Principles > Living document. Principles discovered while building with AI agents. > Extracted from CLAUDE.md files, memory, project configs, and observed patterns. > Drop ideas in chat — they land here. --- ## Architecture & Design ### 1. Single Source of Truth One file, one config, one definition. Never maintain the same information in two places. - Dockerfile: one shared by all agents - Queue: `queue.json` is canonical, markdown table is a view - Voice profiles: YAML is source, generated text is output **Test:** If you change something, how many files do you need to touch? If >1, you have a SSOT violation. ### 2. Vertical Spike Before Framework Validate architecture through working code, not docs. Don't write 1000 lines of specs for zero lines of working code. Frameworks are extracted from spikes, not theorized upfront. **Origin:** afet validation strategy — spike first, then extract. Dogfood with a real project. ### 3. Convention Over Configuration Reduce decisions by establishing patterns that just work. - Conventional commits everywhere (`feat:`, `fix:`, `docs:`) - `docs/status.md` in every project (same format) - Queue priority: P0 > P1 > P2 > P3 - Agent picks up work without being told which item is next ### 4. Agent-First Design Build frameworks and tools that agents can use, not just humans. Measure agent ergonomics. - Schema-free entities (type + status + JSON meta) — agents don't need to learn fixed schemas - Config-driven: new types/statuses/fields = TOML, never code changes - Standard tool interfaces (MCP) so any agent can plug in **Origin:** tool.affordance — 380 tests, agent ergonomics testing built in. ### 5. Don't Make Me Think (About Infrastructure) Dev environment changes propagate automatically. No manual rebuild, no "remember to also update X". - One Dockerfile, auto-detected by all consumers - devcontainer features for language runtimes - post-create scripts for project-specific setup - If a human has to remember a step, it will be forgotten --- ## Cost & Efficiency ### 6. Cheapest Model per Task Don't use Opus for what Haiku can do. | Task | Model | Cost | |------|-------|------| | Validation, guardrails, diff | Haiku | $0.80/MTok | | Creative writing, rewrites | Sonnet | $3/MTok | | Architecture, complex reasoning | Opus | When needed | Two-pass approach: Haiku draft + Sonnet polish = 80% savings vs Sonnet throughout. ### 7. Budget-aware by Default Track every token. No surprise bills. - `--dry-run` before expensive operations - Cost estimation before fan-out - CostGuard with hard limits per session - Batch API for bulk (50% discount) - Prompt caching for repeated system prompts (90% on reads) - Report estimated vs actual after runs - Budget decisions >$10 require user consent ### 8. Batch, Cache, Deduplicate Before implementing any API operation, proactively optimize: - **Batch**: group N items per call (100 rows/insert, not 1) - **Cache**: static reference data between runs - **Dedup**: hash-based skip of already-processed items - **Incremental**: upserts and delta syncs, not full re-processing - **Parallelize**: async/concurrent where rate limits allow - **Respect limits**: throttle proactively, don't react to 429s State the optimization strategy when proposing a workflow. --- ## Execution & Error Handling ### 9. Checkpoint / Resume Every long-running operation must be interruptible and resumable. - Save progress incrementally, not all at the end - Hash-based dedup so restarting skips completed work - JSONL for append-only progress logs - Killing a stuck task must not lose completed work ### 10. Diagnose Before Retrying When something fails, understand why before trying again. - Read the error message. Check logs. Understand the cause. - Never retry the same command hoping for a different result - Never add broad `try/except` or `|| true` to suppress errors - Never sleep-loop waiting for things to work - Fix the root cause, then try once more ### 11. Fail Forward Don't block on one broken thing. Document it, next item. - Error → log it → move to next queue item - Missing dependency → note it → work on something else - Rate limit → save progress → switch tasks - Unsolvable error → document in status, move on ### 12. Read Before Write Understand existing code before changing it. Match the project's patterns, don't invent new ones. - No `todo!()`, `unimplemented!()`, `pass` in production code - Fix lint/test failures before committing - If a pre-commit hook fails, make a NEW commit (never `--amend` after failure) - Never silence warnings to make code compile — fix the root cause --- ## Autonomy & Agents ### 13. Autonomous but Auditable Agents work independently. Humans can always follow what happened. - Status logs updated after every sprint - Control center as handoff document between sessions - Conventional commits with meaningful messages - No silent failures — document and move on ### 14. Parallel by Default Never sit idle when there's work that can run concurrently. - Multiple agents on independent projects simultaneously (up to 4-5) - Background scouts while foreground work continues - If blocked on one thing, pick up the next queue item - Use idle time productively — check the task list ### 15. Dual-Agent Routing Different agents for different task shapes. Route to strengths. - **Claude Code**: long-running, autonomous, shell-native, writing, research, tests - **Cursor**: interactive, codebase-aware, multi-file edits, UI/web, PR-scoped - Each queue item has an `agent` field. Agents only pick their own items. - Handoff protocol between agents to avoid collisions ### 16. Session Handoff Protocol Every session writes a handoff so the next session can resume without re-discovery. - Fill "Letzte Session" in control-center before ending - Update project's `docs/status.md` with what was done - Fields: date, channel, projects touched, completed, blocked, next step - Read handoff at session start — this IS the context ### 17. Worktree Safety When agents work in isolated worktrees, protect uncommitted work. - Agents must commit before finishing - Check for uncommitted changes before deleting worktrees - Save work as named branches before cleanup - Never use TeamDelete as a shortcut — it destroys worktrees --- ## Documentation & Knowledge ### 18. Documentation as First-Class Deliverable Not an afterthought — parallel to code. - Every architectural decision gets an ADR - Master Prompts and Book docs updated alongside code - Security by design, not bolted on - New concepts captured immediately, not retroactively ### 19. Script Everything Multi-step workflows, automations, reusable commands → save as scripts in `scripts/`. Never just execute ephemeral commands. - Include a brief comment header explaining what the script does - Reproducibility, auditability, handoff clarity - If you did it twice, it's a script ### 20. Memory as Institutional Knowledge Persistent memory bridges sessions. Only save what a future session would need. - API quirks, DB schemas, key architectural decisions - Not routine operations or task progress - Check at session start to avoid re-discovery - Update or remove stale memories --- ## Capture & Learning ### 21. Zero-Friction Capture Ideas, principles, and decisions are capturable in the moment without switching tools. - The conversation is the inbox - Agent triages and routes automatically - Principles are extracted proactively from observed patterns - User validates by not objecting ### 22. Proactive Principle Detection When a decision is made, a pattern repeats, or an approach is confirmed — check if there's an underlying principle worth capturing. Don't ask. Just add it and mention briefly. --- ## Content Production ### 23. Voice Profile Consistency Writing follows defined voice profiles with guardrail enforcement. - Kombi B: essayistic + provocative-analytical - No fictional characters, no coaching language, no listicles - "Follow the money" in every chapter - Structure: Strukturanalyse → Philosophie → Daten → Praktische Übung - Automated guardrail checks before publishing ### 24. Persona / Series / Volume Hierarchy Content scales through structured inheritance. - Persona (author identity) → Series (universe rules) → Volume (individual book) → Fan-Out (publisher × language variants) - Volume override > series default > persona default > global default - One persona can write multiple series; each series has shared terminology and rules --- ## (inbox — unsorted ideas) _Drop new principles here. They get organized on next pass._