Agent System Design
Patterns, techniques, and mental models for designing and configuring agent systems — organized by the domain of practice they belong to. Applies regardless of which harness (Claude Code, Cursor, Devin, etc.) you use.
Sub-domains
Instruction Design — CLAUDE.md, agents.md & Behavioral Configuration
The practice of defining agent behavior through persistent markdown instruction files.
- Structured Context Loading — Purpose-built files loaded before each interaction to align agent behavior
- Knowledge Capture as Side Effect — Design agent systems so knowledge capture is a byproduct of corrections
solid
Skills — Discrete Agent Capabilities
Reusable, composable agent procedures packaged as files. How to design, bootstrap, and scale them.
- Meta-Skill Pattern — Build a “skill that builds skills” to bootstrap agent capabilities consistently
Supervision — Human Governance of Agent Execution
Patterns for staying in control without micromanaging — approval gates, execution pacing, capability gating, and behavioral observation.
- Stepwise Task Execution — One-task-at-a-time execution with pause-and-approve checkpoints
- Progressive Tool Disclosure — Revealing MCP tools in layers to combat choice paralysis and hallucination
- Agent-Mediated Self-Reflection — Using agents to observe behavioral patterns from digital exhaust
Architecture — Structural Foundations
Where state lives, how agents connect to external systems, what the chassis looks like.
- Filesystem as Agent State — Agent architecture = filesystem (state) + LLM (orchestrator)
- Agent as Cross-Tool Workflow Hub — Local agent + MCP integrations as orchestration layer