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.
This commit is contained in:
28
CLAUDE.md
Normal file
28
CLAUDE.md
Normal file
@@ -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
|
||||||
259
README.md
Normal file
259
README.md
Normal file
@@ -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._
|
||||||
22
docs/status.md
Normal file
22
docs/status.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user