Design the Environment, Not the Agent

Stop writing instructions. Start designing worlds.

When implementation becomes cheap, the bottleneck moves to thinking. But most people respond to faster execution by just… executing faster. More prompts, more sessions, more context juggling.

This is backwards.

The Micromanagement Trap

Watch how people work with AI agents today. They nurse context windows, clinging to sessions and scared of ‘compaction’. They install dozens of skills and plugins based on how many github stars they have. They hold the next steps of the master plan in their head while the agent holds the code.

Or they drown in markdown files. CLAUDE.md, AGENTS.md, README.md, ARCHITECTURE.md, PLAN.md, PLAN_2.md—an earnest attempt to be principled, to avoid losing context. But it degenerates. The files drift out of sync with reality. The agent appends to AGENTS.md endlessly while adherence suffers. You wanted persistent context; you got archaeological layers of half-truths.

This is micromanagement. You’ve delegated the typing but kept all the cognitive load. The agent is fast but you’re still the bottleneck, now for attention instead of keystrokes.

The Reframe

Here’s the shift: observe your own behavior while using AI. Identify the loops and patterns. Then reshape the environment to make those patterns more likely, less effortful, or automatic.

Don’t tell the agent what to do. Design the world it operates in.

The emergent behaviour is a combination of: the base model, the prompting, user input, the available skills, and—crucially—the shape of information revealed as the agent probes its environment. You control most of these layers. Use them.

The goal: maximize signal-to-noise for the single task at hand¹. No irrelevant skills and MCP servers. No stale information. Just the goal, the process, and the success criteria. Make it easy for your agents to understand their “win condition”.

The Levers

What does “design the environment” actually mean? Four concrete things:

Information architecture. A well-structured wiki has just the right links in just the right places—readers find interesting connections without being overwhelmed or hitting dead ends. Your codebase, docs, skills, AGENTS.md, your folder structure: these speak before you type a word.

Domain modeling. The concepts you name become the concepts the agent thinks in. Define a schema with Plans, Steps, and Breadcrumbs and suddenly the agent can plan, execute, and reflect. The vocabulary you provide shapes what’s thinkable.

API and tool design. The agent is formless until you give it tools. Define a plan command and it can plan. Define a checkpoint command and it can save state. The tools you offer become the actions available.

Context composition. What persists across sessions? What gets loaded automatically? What requires explicit retrieval? The answers determine whether the agent has memory or amnesia, context or confusion.

The Text Adventure Test

Here’s a useful frame: how would you design a good text adventure for your agents to play?

Good text adventures don’t script the player. They create rooms with interesting objects, doors that lead somewhere, puzzles with satisfying solutions. The player explores; the designer shaped what exploration feels like.

Bad text adventures are boring and confusing. The environment makes it hard to orient. What are my choices? What is important? Constraining the player to one path is boring but too many paths is confusing. The more you explore, the clearer the path ahead should become.

Your agent environment is the same. Are you designing a world worth exploring, or writing a script and hoping the agent follows it?

Blackboard: A Worked Example

Blackboard applies these levers to multi-threaded coding work. It’s designed as an alternative to beads, you plan one or more threads of work broken down to steps, then during implementation agents write breadcrumbs.

Threads are implemented by blackboard:implementer subagents. Each receives only the thread ID and step ID it is responsible for as well as the last 3 breadcrumbs. All context is retrieved from the database as needed, rather than being dictated verbatim by the orchestrating agent, massively reducing the tokens used. Agents see only the relevant context for their task.

• Information architecture: A SQLite database that outlasts any context window. Session-independence by design, plans and tasks are automatically captured via hooks.

• Domain modeling: Plans decompose into Steps. Agents leave Breadcrumbs as they work. Reflections synthesize patterns. These aren’t arbitrary, they’re the concepts that make planning and execution legible, extracted from my own process.

• Tool design: the blackboard CLI allows humans and agents a shared interface. thread list shows recent activity. thread steps fetches the remaining tasks. nextup create records a note for future work. Each tool is a verb the agent or user can speak².

• Context composition: The blackboard dashboard shows all active threads. History loads automatically. You see the whole board, not just the current move.

• Flexibility: threads can be loaded interactively via /blackboard:thread or worked on passively via a containerized agent using blackboard thread work. Need to take control? Pause the worker, resume the session interactively.

The result: agents that plan before acting, efficiently subdivide work, and leave trails you can follow. Not because they’re forced to, but because the environment makes it natural.

Incentives, Not Rules

The art of environmental design is to constrain behaviour without removing flexibility. You’re not writing rules the agent must follow. You’re designing incentives that make desirable behaviour easy and undesirable behaviour hard. Rules explicitly say “always do X.” Incentives signal “X is available, rewarded, and easier than the alternatives.”

A concrete example, an ergonomic kitchen is not made of rules. The utensils are within reach while at the cooktop. If you look for a fork, you also find the spoons. Toxic cleaning products do not go in the food pantry! This seems obvious but when it comes to the virtual environment we are not so thoughtful in our arrangement. We effectively fill one drawer with every possible tool in it and ask the agent to “read the manual and work it out”.

The difference matters. Rules fight the model’s generality. Incentives harness it. Filling your AGENTS.md with “ALWAYS do X” and “NEVER do Y” is a recipe for a both maintenance hazard and confused agents.

How does a kitchen become this way? Through in-situ design: endless iterative tweaks and tacit understanding of usage.

1. “Each iteration = one fresh context window = one task from IMPLEMENTATION_PLAN.md = one commit” from how-to-ralph-wiggum

2. And blackboard self documents via blackboard --help