How Agents Should Use This Reference

Purpose

This reference describes design patterns, refactoring techniques and code smells in a fixed, predictable shape so that an AI coding agent can look one up mid-task and act on it. It is a set of tools with warning labels, not a list of things to add.

Apply an entry only when the code in front of you shows the problem that entry names, and only after reading why you should not.

Read in this order

1. The exclusions. On a pattern page, read ## Do not use it when first. On a technique page, read ## Watch out. On a smell page, read ## When to ignore. If any bullet matches your situation, stop and use the simpler alternative it names.
2. The trigger. ## Use it when (pattern), ## Problem (technique) or ## Signs (smell). Match it against actual code, not a hypothetical future.
3. The procedure. ## Implementation steps or ## Steps. Follow them in order.
4. The checklist. ## Agent checklist. Verify each item before and after.

How each kind of page is structured

Headings are fixed so you can jump straight to a section.

Kind	Sections, in order
Pattern	Intent, Forces, Therefore, Structure, Use it when, Do not use it when, Implementation steps, Example, Trade-offs, Relations, Agent checklist
Technique	Problem, Solution, Before, After, Why, Steps, Watch out, Related, Agent checklist
Smell	Signs, Why it happens, Example, Treatment, Payoff, When to ignore, Agent checklist
Category, guide	Free structure; category pages list every member with a one-line summary

Frontmatter carries machine-readable links: related on every entry, fixes on techniques (the smells a technique treats) and treatments on smells (the techniques that fix it).

Apply only when

• The user asked for the change, or the change is required to complete what the user asked. Do not refactor unrelated code because it looks wrong. Report it instead.
• You can name the smell or problem, with a file and symbol. "Could be cleaner" does not qualify.
• The code is in the path of the current task. See When to refactor.
• Tests cover the behavior you will touch, or you add characterization tests first.
• For patterns, there are at least three real variants or a concrete third on the way. Two variants rarely justify an interface. See Choosing a pattern.
• The language does not already provide the mechanism. Functions, generators, union types and built-in events replace many classic patterns.

Verify with tests

Every structural change follows the same loop. How to refactor covers it in depth.

1. Run the full relevant test suite and the type checker. Record the exact command. If anything is red before you start, stop and report it.
2. Make one named change: one technique, or one step of a pattern's implementation steps.
3. Run the same command. Compare results with the baseline.
4. Green: continue or commit. Red: revert to the last green state and take a smaller step. Do not debug a refactoring forward.
5. Keep behavior changes out of refactoring steps. If you must fix a bug, do it in its own step with its own failing test.
6. At the end, run the whole suite once more and state in your report which commands you ran and what passed.

If no tests exist and you cannot add them, restrict yourself to tool-assisted transformations (language-server rename, extract and move) and say so in your report.

Navigating

• From a symptom: open the smell category, such as Bloaters, OO abusers, Change preventers, Dispensables or Couplers. Each smell lists its treatments.
• From a desired transformation: open a technique category, such as Composing methods or Simplifying conditional expressions.
• From a design problem: open Choosing a pattern, or a pattern family: Creational, Structural, Behavioral.

A common path: you see a growing switch on a type code. Open Switch Statements, follow its treatment to Replace Conditional with Polymorphism, and, if the variants are algorithms, read Strategy starting at ## Do not use it when.

Reporting

When you finish, tell the user:

• Which smell you identified and where.
• Which technique or pattern you applied, by name and link.
• Which exclusions you checked and why they did not apply.
• Which tests you ran, before and after.
• What you noticed but deliberately did not change.

Agent checklist

• You read the exclusion section of every entry you applied before applying it.
• Each change maps to a named smell in code you were already changing.
• Tests and type checks were green before the first edit and after the last.
• No refactoring step also changed behavior.
• Your report names the entries used, the tests run and the issues left alone.