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

Infrastructure

25. Tool Auto-Provision

When an agent needs a tool that isn't installed, it should install it automatically — not block and ask.

Container should support on-demand tool installation (apt, npm, go install, curl binary)
Dockerfile covers the 80% case; auto-install covers the long tail
Log what was installed so it can be baked into the Dockerfile later
Never let a missing jq or go derail a 30-minute sprint

Origin: "Wenn irgendwas fehlt wie go — wir brauchen die Möglichkeit ein Tool passthru oder auto-install zu ermöglichen"

(inbox — unsorted ideas)

Drop new principles here. They get organized on next pass.

README.md Unescape Escape

AI Dev Principles