Code Design

Why this workflow exists

The enemy of design is not simplicity but unjustified complexity. Code Design requires naming the real design pressure before choosing a technique: no observed pressure means no new abstraction. Every uncommon construct pays a novelty tax in concrete benefit — correctness, measured performance, framework alignment, or lower total maintenance cost. The output is a proposal, never code.

How it runs, stage by stage

Every rule below is taken from the workflow definition in the source repository — this is what the agent is actually told to do.

1. 01

   Select the design mode

   Greenfield discovery and refinement ask different questions.

   • Greenfield / discovery: you have a goal or problem but no settled solution.
   • Refinement: you supply an existing proposal or design document that needs correction, completion, or simplification.
   • If the task is to implement an already accepted design, use Develop. If existing behavior is broken, use Diagnose.
2. 02

   Establish problem and local context

   Separate accepted requirements, repository facts, reversible choices, and open decisions.

   • Clarify the user problem, desired outcome, acceptance behavior, constraints, and out of scope.
   • Read applicable project instructions, authoritative documents, existing capabilities, representative code, and tests when a repository exists.
   • Ask only about unresolved decisions that materially change product behavior or the viable solution space.
   • Distinguish accepted requirements, repository facts, reversible design choices, and open product decisions.
3. 03

   Explore the design pressure

   Name the actual problem before reaching for a technique.

   • Look for real pressure: hard-to-follow control flow; hidden mutation, I/O, errors, or state transitions; semantic duplication that should change together; similar-looking rules that should stay independent; repeated conditionals along one real variation axis; an unstable external dependency; scattered ownership of one invariant; construction or lifecycle rules with real combinations; a missing stable public seam.
   • No observed pressure means no new abstraction.
   • For greenfield work, propose the smallest coherent architecture that satisfies known behavior and credible near-term variation.
   • For refinement, identify missing behavior, contradictions, unclear ownership, infeasible assumptions, accidental complexity, and decisions that lack evidence.
4. 04

   Develop and compare options

   Only genuinely different trade-offs deserve to be separate options.

   • Produce alternatives only when they represent materially different trade-offs.
   • Compare ownership, coupling, cohesion, state and failure behavior, compatibility, testability, operability, migration cost, and expected change pressure.
   • Prefer existing repository language, frameworks, and boundaries unless a concrete problem justifies change.
   • Recommend one option and state why it is the lowest necessary complexity.
   • Reject speculative extension points and unnecessary dependencies explicitly when they are tempting.
5. 05

   Apply the maintainability standard

   Familiar, explicit, named, local, debuggable, single-owner — and boring.

   • Prefer code that is familiar in the repository, explicit about branches and effects, named with domain concepts, locally understandable, easy to debug, and structured so one rule has one authoritative owner.
   • Novelty tax: an uncommon construct, reflection, metaprogramming, dense expression, implicit runtime behavior, new dependency, abstraction, or design pattern must provide concrete benefit. When justified, localize it, name the intent, keep effects observable, and explain why it exists rather than how the syntax works.
   • Reuse by semantics: share code only when it implements the same domain rule, every caller should change together, the owner holds the relevant data and invariant, parameterization does not obscure the result, and no existing abstraction already suffices.
   • Allow duplication when rules only happen to look alike and will evolve independently.
   • Use a pattern only under real pressure — Strategy for multiple real policies, an explicit state machine for distributed transitions, an Adapter for an unstable third-party interface, a factory or builder for real construction combinations, a pipeline for ordered independent stages. A pattern name is not evidence of quality.
   • Use the standard to shape module boundaries and contracts, not to prescribe internal classes prematurely.
6. 06

   Produce the proposal

   Deliver boundaries, contracts, trade-offs, and a sequence — not code.

   • Include only relevant sections: problem, goals, accepted behavior, constraints, and out of scope; existing context and reusable capabilities; recommended boundaries, responsibilities, contracts, data and state ownership, and dependency direction.
   • Cover failure, security, compatibility, migration, and operational behavior when material.
   • Record decisions, trade-offs, alternatives considered, and rejected unnecessary abstractions.
   • List open questions and assumptions, plus acceptance evidence and an implementation sequence.
   • Do not claim decisions are accepted when they remain assumptions, and do not implement the design in this invocation.

Rules that cannot be bypassed

A real invocation

What the conversation actually looks like, from the token you send to the evidence you get back.

1. Agent

   Selects greenfield/discovery mode and reads the existing notification and queue capabilities in the repository.

2. Agent

   Names the actual pressure: channels differ only in delivery, which is one real variation axis; the remaining rules should change together.

3. Agent

   Offers two options with materially different trade-offs, compares ownership, testability, and migration cost, and recommends the simpler one.

4. Agent

   Explicitly rejects a plugin registry for hypothetical future channels — no observed pressure, so no abstraction.

5. Agent

   Returns boundaries, contracts, data ownership, open questions, acceptance evidence, and an implementation sequence. No production code is written.

When to use it

• You have a goal or problem but no settled solution yet.
• An existing design or proposal needs correction, completion, or simplification.
• You want trade-offs compared and rejected options recorded before anyone writes code.
• You suspect a proposed architecture is more complex than the problem requires.

When to reach for something else

Questions