From 048eab3624c1e7955a6a87bb8dbc3cd133c5f90c Mon Sep 17 00:00:00 2001 From: Christian Nennemann Date: Tue, 31 Mar 2026 15:22:46 +0000 Subject: [PATCH] feat: initial 24 principles extracted from real multi-project AI dev work Grouped into 7 themes: Architecture & Design, Cost & Efficiency, Execution & Error Handling, Autonomy & Agents, Documentation, Capture & Learning, Content Production. Each principle grounded in observed patterns, not theory. --- CLAUDE.md | 28 ++++++ README.md | 259 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/status.md | 22 +++++ 3 files changed, 309 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/status.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..07526b7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,28 @@ +# AI Dev Principles — Project Instructions + +## What is this + +A living collection of principles for building software with AI agents. Extracted from real multi-project work, not theorized. Each principle has an origin story. + +## Content Rules + +- Every principle must come from real experience (observed pattern, correction, or confirmed approach) +- Include **Origin** where possible — what happened that led to this principle +- No aspirational fluff — if it's not practiced, it doesn't belong here +- Principles can evolve or be retired — mark deprecated ones rather than deleting + +## Structure + +- `README.md` — The principles document (canonical, numbered, grouped by theme) +- `docs/examples/` — Concrete examples and case studies for select principles +- `docs/status.md` — Session log + +## Language + +- English for everything (these principles are language-independent) + +## Commits + +- `feat:` for new principles +- `docs:` for examples, refinements, rewordings +- `fix:` for corrections to existing principles diff --git a/README.md b/README.md new file mode 100644 index 0000000..1c0e7b3 --- /dev/null +++ b/README.md @@ -0,0 +1,259 @@ +# 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._ diff --git a/docs/status.md b/docs/status.md new file mode 100644 index 0000000..9e16163 --- /dev/null +++ b/docs/status.md @@ -0,0 +1,22 @@ +# Status Log + +## 2026-03-31 — Project Created + +### Completed +- Extracted 24 principles from workspace configs, memory files, CLAUDE.md files, and observed patterns +- Grouped into 7 themes: Architecture, Cost, Execution, Autonomy, Documentation, Capture, Content +- Each principle grounded in real usage, not theory + +### Sources Mined +- Global CLAUDE.md (user instructions) +- Workspace CLAUDE.md (autonomous agent rules) +- 12 memory files (feedback, projects, user context) +- Project-specific CLAUDE.md files (claudine, affordance, 3sets) +- control-center.md, agent-handbook.md +- Colette virtual publisher plans + +### What's Next +- Add concrete examples for key principles (docs/examples/) +- Cross-reference with industry patterns (12-factor app, etc.) +- Consider blog post or talk format +- Keep extracting from ongoing sessions