275 lines
9.1 KiB
Markdown
275 lines
9.1 KiB
Markdown
# 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
|
||
|
||
---
|
||
|
||
## 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._
|