gof-design-patterns
Chooses and implements a design pattern in Java and Spring from the symptom that justifies it.
gof-design-patterns, section by section
The sections of the skill's own SKILL.md, excerpted. Hover or click one to see which project rules, templates and references/ files it cites. The sections are also chips: click one to jump to it.
## Why this is a skill and not a rule
A pattern is not a rule. A rule says *always*; a pattern says *when*. That's why this is a skill and not rules/ — it only costs context when invoked. Form 2 (manual invocation) and not Form 1, because a catalog the model reaches on its own turns into a pattern applied without the symptom that justifies it, which is what the entry rule below exists to stop.
Entry rule: no pattern without a symptom observed in the code, or a force the approved spec already names. Applying a pattern preemptively is overengineering — a Factory for two lines, a Strategy for a single if, an interface with one implementation that will never have a second. A force named in the spec is not preemption: variants or rules the spec enumerates, a cross-cutting concern it applies over several implementations, construction it constrains with invariants, a predicate it uses both to decide and to query — code written from that spec would show the symptom on its first version, and choosing the pattern before writing it is how that first version is never written badly. The "When not" column binds either way. If you can point neither to the file and line that hurts nor to the spec line that names the force, the answer is "apply no pattern at all".
Pinned to opus: choosing a pattern against a growing chain is judgment, and the pin only raises the model for the rest of the turn (@.claude/decisions/0081-skill-model-required-per-class.md).
## Procedure
- Name the symptom in the actual code (
file:line), or the force in the approved spec - Look up the symptom in the table. No matching row, stop — write simple code.
- Confirm the pattern doesn't collide with the active blueprint's
packages.map. - Generate from the exemplar in
templates/, with the names from - Record it in an ADR if the pattern changes the shape of an entire module.
## Catalog
| Symptom in code | Pattern | When not |
|---|---|---|
switch/if-else over a type or enum, repeated in ≥ 2 places, growing with each new rule | Strategy | Two stable branches that have never grown · the branch needs nothing outside the value — a method of the enum or sealed type · a closed set one layer branches on once — a switch expression there; both per @.claude/rules/code-quality.md § Branching on a closed set |
| Construction with invariants, many steps, or possible invalid combinations | Static factory (of, from) | A record with validation in the compact constructor is already enough |
| ≥ 4 optional constructor parameters | Builder | Record + with*; Lombok @Builder on a domain object hides invariants |
| Cross-cutting behavior (retry, audit) repeated across implementations | Decorator | A Spring aspect already exists (@Transactional, @Retryable) that does the same thing — or the behavior is a cache, whose decorator shape @.claude/rules/caching.md owns |
| Business predicate duplicated between service and query | Specification | Predicate used only once |
| Output adapter with multiple technologies (JPA + external REST) behind the same port | Adapter (already the blueprint) | A single technology — the port is enough |
| Aggregate that emits ≥ 2 events consumed by several modules | Domain Events | A single consumer in the same module — direct call |
This table is the enforceable subset: seven rows, each with a symptom threshold and a "when not" column. For a symptom that doesn't match any row above, references/pattern-catalog.md covers the full GoF catalog — every pattern on <https://refactoring.guru/design-patterns/java>, each with a shape reference in templates/ and this repo's verdict on the ones that don't (forbidden, or already covered by the language/framework). It's triage, not a second menu: the entry rule below still gates every row in it the same way it gates the seven here — an exemplar existing is not permission to apply it without a real symptom.
## Design-time use
A pattern creates classes and interfaces, so when it is chosen decides whether the approved spec shows the code's real shape. Chosen by the executor after approval, it never does. So every design skill of the /new-feature pipeline runs this check for its own layer, before writing its partial, and records the answer there — the layer that owns the classes owns the pattern that shapes them. This section is read, never invoked: a design run cannot reach a build-class skill, and it needs no writer here.
- Forces in the spec. Read the lines of
00-use-case.mdand of the upstream partials - Symptoms on disk. The layer's existing code, already surveyed by the skill's own
- Match against § Catalog, then
references/pattern-catalog.mdfor what no row covers. - Write the
## Design patternssection of the partial — always present, one row per
… cut here, the rest is in the file
## Forbidden in this repository
- Singleton — the Spring container already gives singleton scope; the manual version
- Service Locator /
ApplicationContext.getBean— violates the composition set in Implsuffix, always —@.claude/rules/naming.md: the name says the role, not- Pattern name standing in for a role name that exists (
OrderStrategyinstead of
What it reads, writes and refuses
The skill's own contract, from SKILL.md, in the original wording.
Class
build — the territory is skill_classes.build's override for this skill in @.claude/schemas/extensions.json: the src/ tree, nothing else. It sits in build rather than with the design skills because it materializes Java code, and ArchHook.java guard therefore also makes it unreachable from inside a design run.
Reads
.claude/rules/code-quality.md, .claude/rules/naming.md, .claude/rules/architecture-ddd.md, the active blueprint's packages.map, and references/pattern-catalog.md when the symptom doesn't match any row of the curated table above.
Writes
domain and application code in the generated project. Doesn't touch the inbound REST adapter — the package the blueprint's packages.map assigns to that role, whether adapter.in.rest or infrastructure.rest — which is rest-api-architect's territory.
Three uses, one writer each
Design time — the pipeline's design skills read § Design-time use and write the decision into their own partial; this skill writes nothing and is not invoked (@.claude/decisions/0089-design-patterns-decided-at-design-time.md). Standalone — a human runs /gof-design-patterns against real code with an observed symptom; this skill is the sole writer for that turn, as above. Injected — in a generated project, ArchHook.java context subagent runs at SubagentStart and hands the sections listed in subagent_context of @.claude/schemas/extensions.json (this file's ## Why this is a skill and not a rule, ## Catalog and ## Forbidden in this repository) to every agent whose agent_classes entry declares pattern_catalog: true, before its first turn. The agent implements the patterns the spec already decided, and applies a row on its own only for a symptom already on disk, never as a separate invocation. In that mode this skill writes nothing itself: the agent remains the sole owner of src/** (invariant 2), and the catalog is reference material, the same role templates/*.example plays for the other four pipeline skills. Renaming one of those three headings empties the injection — ArchHook.java schema fails on it by name. @.claude/decisions/0077-pattern-catalog-injected-at-subagent-start.md, which supersedes 0025: a skill with disable-model-invocation: true cannot be preloaded through an agent's skills: field, so the catalog 0025 described never arrived.
Doesn't collide with the design skills
(domain-modeling, persistence-architect, rest-api-architect, messaging-architect, jobs-architect, cache-architect). They own the pattern decision for a use case being designed, each for its own layer, through § Design-time use; this skill owns the catalog and, invoked standalone, refactors code that already exists and already hurts, from a concrete file:line, outside any feature run.
Does not
create rules. If a new limit has to always hold, it goes to rules/code-quality.md, not here.
Source: SKILL.md § Contract, at nerviz e4cae27.
What the guard does with it
build is the skill's class, and the list on the left is its territory. The phase opens when the skill runs on a prompt of its own, and ArchHook judges every write against that list. The text on the right is the hook's own.
write_allow of gof-design-patterns
- ✓
src/** - ✓
**/src/** any path outside this list, when the skill opens the phase itself
A refusal exits with code 2 and the message goes back to the model.
> /gof-design-patterns … UserPromptSubmit guard prompt exit 0 # phase opened: gof-design-patterns (class build) # write_allow: src/**, **/src/**
PreToolUse Write(src/main/resources/application.yml) guard write exit 0
PreToolUse Write(pom.xml) guard write exit 2 ❌ `gof-design-patterns` is class `build` — pom.xml is outside its territory. write_allow: src/**, **/src/** Put the content in the spec as a code block, or finish the run and invoke the skill that owns this path. If the path is legitimately this skill's, widen skill_classes.build in .claude/schemas/extensions.json — retrying will not help.
Who calls it
It is not a step of a chain. It starts from a prompt of its own, /gof-design-patterns, and the guard treats it like any other skill: the phase opens, and the territory of its class applies.