The running-sum helper from the previous chapter has a specification, a check and a reproducible artifact. Now a second request arrives: clamp every value of a list between a low and a high bound. A reviewer reads both functions and leaves a comment that sounds like good engineering: "These are the same thing. Both walk a list and build a new one. Write one generic transform and pass the step in."
Someone does. The generic version is eight lines long, both helpers become one-liners on top of it, and six of the seven examples in the two specifications pass. The seventh asks what happens when the low bound is greater than the high bound. The specification says: raise ValueError. The generic version returns [2, 2].
Nothing in the generic version is buggy in the usual sense. It has no place for a rule that refuses bad input, because the running sum never needed one. The abstraction was built from what the two requests had in common and quietly deleted what made one of them different.
The learner's question: when two requests look alike, what should be shared once, what belongs to each request, and what must never be merged even though it looks the same?
Two requests, side by side#
Plain English. A pattern is the part of the work you would do the same way for every request of this kind. Everything else is the request's own business, and some of that business only looks shared.
Before deciding anything, put the two requests next to each other and compare them field by field. Example A (examples/a-assembly-line/) keeps both as JSON files, so the comparison can be done by a script instead of by impression. The script below was written for this page and run on a scratch copy of the example; it prints each top-level field of the two specs and whether the values are identical.
field running-sum clamp-list same
schema_version "1.0" "1.0" True
spec_id "SPEC-ALGO-101" "SPEC-ALGO-102" False
problem_name "running-sum" "clamp-list" False
function_name "running_sum" "clamp_list" False
params ["xs"] ["xs", "lo", "hi"] False
pattern {"id": "PAT-ALGO-UNIT", "versio... {"id": "PAT-ALGO-UNIT", "versio... True
body_template "prefix_sum" "clamp_each" False
requirements ["Return a new list where item ... ["Return a new list where every... False
examples [{"input": [[1, 2, 3, 4]], "out... [{"input": [[-3, 0, 4, 12], 0, ... False
acceptance_criteria [{"id": "AC-1", "text": "Every ... [{"id": "AC-1", "text": "Every ... True
acceptance checks identical: True ['all_examples_pass', 'input_not_mutated']
examples that expect an error: 0 vs 1
Three fields are identical: the schema version, the pattern they ask for, and the acceptance criteria. Seven differ. The last line is the one the reviewer missed: one request has an example that expects an error and the other has none. That single difference is where the generic transform broke.
Invariants: what every request of this kind shares#
An invariant is a part of the work that is the same for every request of a kind, so it can be written once and owned by one team. In Example A the invariants are the schema version, the four stations, the shape of the generated files (a module with a docstring and one function, and a test file with one method per example), and the two acceptance checks.
The analogy is a car platform: the chassis, the safety tests and the assembly order stay; the body and the trim change. The consequence is leverage: a fix to an invariant, say a better test generator, improves every future product at once. The trade-off is the same fact read the other way: a mistake in an invariant reaches every product, and changing it later needs a version and a migration (Factory learning loop handles that).
Variation points: where each request is allowed to differ#
A variation point is a declared place where a request supplies its own value, and the pattern says exactly what kind of value it accepts. In Example A the variation points are the spec id, the names, the parameters, the requirements, the examples, and the body template, which must be one of the names in the pattern's catalog.
The analogy is the order form at a print shop: paper size, quantity and colour are boxes on the form; the machine does the rest. The consequence is that the factory can check a request before work starts: a body template that is not in the catalog is rejected at station 1. The trade-off is rigidity: a request that needs something no box offers cannot be served by filling in the form, and someone has to change the pattern.
Diagram: Two requests sorted into pattern, spec and leave-alone
Rows are the three choices for every field of the running-sum and clamp-list requests. Columns are structure, behavior and checks. The top row is what the pattern PAT-ALGO-UNIT owns once. The middle row is what each spec supplies in boxes the pattern declares. The bottom row is the trap: two behaviors that look like one shape but carry different rules, so the pattern shares the line and the checks and keeps the logic apart.
- Invariant (pattern)
- module + test file shape: Every unit is one module with a docstring and one function, plus one test file.
- four stations: The same line runs every request of this kind.
- two acceptance checks: The checks every unit must pass, declared by the pattern.
- Variation point (spec)
- names + params: Each spec names its function and parameters.
- body template: Chosen from the pattern's catalog; a name outside it is rejected at station 1.
- examples + requirements: Each spec states its own cases; they become its tests.
- Do not abstract
- refuse lo > hi: A rule only the clamp has; a generic transform has no place for it.
- error cases as examples: Because the refusal is an example, the over-abstraction fails a test instead of shipping.
Read the rows. The top row is what the pattern owns once for both requests. The middle row is what each spec supplies, in the boxes the pattern declares. The bottom row is the reviewer's trap: two pieces of behavior that look like one shape (walk a list, build a new one) but carry different rules. The pattern shares the line and the checks; it does not share the logic.
What Example A's pattern file actually holds#
The pattern is a file too, examples/a-assembly-line/pattern.json, quoted as it is:
{
"pattern_id": "PAT-ALGO-UNIT",
"version": "1.3.0",
"description": "Algorithm unit pattern: one pure Python function plus a unittest file generated from the spec's examples. Teaching pattern; synthetic.",
"accepted_schema_versions": ["1.0"],
"templates": {
"module": "templates/module.py.tmpl",
"test": "templates/test_module.py.tmpl"
},
"bodies": {
"clamp_each": "templates/bodies/clamp_each.py.tmpl",
"prefix_sum": "templates/bodies/prefix_sum.py.tmpl"
},
"acceptance_checks": ["all_examples_pass", "input_not_mutated"]
}
Notice where the logic lives. Each request's real behavior is a separate body template in a catalog: prefix_sum for the running sum and clamp_each for the clamp. The clamp body keeps its own rule, templates/bodies/clamp_each.py.tmpl:
if lo > hi:
raise ValueError("lo must be less than or equal to hi")
return [min(max(x, lo), hi) for x in ${first_param}]
The pattern shares the module shape, the test generator, the stations and the checks. It refuses to share the bodies. That is the corrected state of the opening story: one line for both requests, two separate pieces of logic.
The pattern also carries a version, 1.3.0. Station 4 of Example A records a digest computed over this file and every template it names (factory.py : pattern_digest), so a change to any template changes the digest in every later manifest. A pattern is something you release, not something you edit in place.
Pattern, template, archetype: three words that get mixed up#
A pattern is the reusable reference solution: structure, interfaces, conventions, constraints and the station graph. A template is a concrete starting file the pattern may ship; module.py.tmpl is one. An archetype is a named starting shape for a whole project or unit, from which new instances are created.
Before AI. Maven archetypes and Spring Initializr are archetypes in this sense: pick a shape, fill a few fields, receive a generated project. They give you the starting files. They do not keep checking that the project still follows the shape a year later, and they do not hold the per-product logic. A factory pattern adds the checks and the station graph around the starting files.
The difference matters in the next decision. A template generator answers "how do I start?"; a pattern with stations and checks answers "how do I know every product built this way is still right?"
The trap: things that only look alike#
Premature abstraction is merging two things into one shared mechanism before you know they change for the same reasons. The opening story is the classic case. The code below is that mistake, labelled as one and kept so you can run it. It was written for this page and run against Example A's real spec files in a scratch folder.
def transform(xs, step, state=0):
"""Generic: carry a state, emit one value per item."""
out = []
for x in xs:
state, value = step(state, x)
out.append(value)
return out
def running_sum(xs):
return transform(xs, lambda s, x: (s + x, s + x))
def clamp_list(xs, lo, hi):
return transform(xs, lambda s, x: (s, min(max(x, lo), hi)))
running-sum example 1: returned [1, 3, 6, 10] expected [1, 3, 6, 10] pass
running-sum example 2: returned [] expected [] pass
running-sum example 3: returned [5, 3, 10] expected [5, 3, 10] pass
clamp-list example 1: returned [0, 0, 4, 10] expected [0, 0, 4, 10] pass
clamp-list example 2: returned [] expected [] pass
clamp-list example 3: returned [5, 5] expected [5, 5] pass
clamp-list example 4: returned [2, 2] expected raises ValueError FAIL
The mechanism of the failure is worth stating precisely. The generic transform was designed from the overlap of the two requests: iteration and accumulation. Input validation was not in the overlap, so it had nowhere to go. Whoever wrote clamp_list on top of it had to remember to add the check by hand, and did not. The abstraction did not cause a crash; it removed a natural place for the rule, which made forgetting it easy.
The spec's own examples caught it, which is the argument for writing error cases as examples. Without example 4 the generic version would have passed every check and shipped.
Common confusion. Similar code is not the same thing as a shared rule. Two blocks of code belong in one abstraction when they must change together for the same reason. The running sum and the clamp will change for different reasons (a new accumulation rule, a new bounds policy), so their bodies stay apart even though their shapes match.
Glance ahead: two insurance intake products#
The same sorting work appears at enterprise scale in Part III, where a factory builds intake services for a synthetic insurer. The pattern there is PAT-INTAKE-API 2.1.0 in examples/c-insurance-service/pattern.json. Its invariant skeleton has eight steps, listed in the file: request parsing, authentication, role check, schema validation, idempotency key, audit record, event emission, and a trace correlation id. It declares eleven extension points that a product spec must fill, among them roles, submission schemas, routes, workflow, events and underwriting. The one product spec in the example, SPEC-INTAKE-001 (broker-submission-intake), fills them for commercial property submissions.
Teaching reconstruction: imagine a second product on the same pattern, an intake for another line of business, which this page invents and Example C does not contain. Its skeleton is the same eight steps. Its fields, routes and events differ, and they go in its own spec. Its eligibility rules also differ, and here the trap returns. Commercial property has R-ROOF-01 (a roof older than 25 years in wind zone C is not eligible). The second product might have a rule that reads almost the same, "an asset older than N years is not eligible". Merging them into one shared "age rule" would look tidy. It would also tie two rules owned by different underwriting teams, changed on different schedules and reviewed against different guidelines, into one release. Those rules belong in each product's own business-rule module, never in the pattern.
What the pattern must own, in the other direction, is anything that must never vary. Example C's pattern lists the constraint human_decision_roles: ["underwriter"]: only a person with the underwriter role may record a decision. That is not a per-product choice, so no product spec gets to change it. Pattern versus configuration versus business logic is the enterprise home of this split.
When a script or a repository template is enough#
This page owns one of the site's recurring decisions. Many teams reach for an agentic factory when a smaller tool would produce the same artifact more reliably. The question is the one the whole site keeps asking: what is the least machinery that produces this artifact reliably, and what evidence would justify more?
The question. For a family of similar requests, which of four options is enough?
Diagram: When is a script or template enough · the least machinery that works
Read the decision lane top to bottom: three questions, each answered before the next. Each answer points to the option in the right lane. A request that will not repeat is hand-written and tested. One that repeats with only parameters changing gets a template or generator. One whose logic comes from a known catalog gets a deterministic factory with checks, like Example A. Only when each instance needs new logic that nobody can write ahead of time does a model staff one station, with every other station kept as plain code and with independent checks.
- Ask in order
- will this request repeat?: Count expected instances before building anything.
- do instances differ only in parameters?: Names, settings and module choices are parameters; new behavior is not.
- can the logic come from a known catalog?: If every needed body can be written ahead of time, choose from a catalog.
- Least machinery
- hand-written code + its tests: Lowest cost; the acceptance check from chapter 1 still applies.
- template or generator: A consistent start in seconds; generated copies drift unless re-checked.
- deterministic factory with checks: Validated input, generated tests, a manifest per artifact, byte-identical reruns.
- model at one semantic station: Interprets variable business logic; brings non-determinism, so checks must be independent and stronger.
The diagram reads top to bottom as three questions. If the request will not repeat, write it by hand and test it. If it repeats but only parameters change, a template or a generator is enough. If it repeats and each instance needs new logic, but the logic can be chosen from a catalog, a deterministic factory with checks is enough. Only when each instance needs new logic that nobody can write ahead of time does a model at one station earn its place, and even then every other station stays plain code.
| Option | Choose it when | It gives you | It does not give you |
|---|---|---|---|
| Hand-written code and its tests | The request is one-off, or the shape is still unclear | Lowest cost, full freedom | Repetition, consistency across instances |
| Repository template or generator | Instances differ in parameters (names, settings, which modules) | A consistent start in seconds | Checks after generation; generated copies drift apart |
| Deterministic factory with checks (Example A) | Instances repeat and logic comes from a known catalog | Validated input, generated tests, a manifest per artifact, reruns | New logic that is not in the catalog |
| Factory with a model at semantic stations | Each instance needs new logic written from a business description | Interpretation of variable logic at scale | Determinism at that station; it needs stronger independent checks |
The criteria, in the order to ask them: how often the request repeats; whether instances differ in parameters or in logic; how expensive a defect is once it escapes; and whether someone needs evidence per artifact (an auditor, a reviewer, a customer).
Product (Cookiecutter, as documented on 2026-11-20): Cookiecutter generates a project from a template whose fields are declared in cookiecutter.json. It runs hooks, including pre_gen_project after the questions and before rendering, and a hook that exits non-zero stops generation and cleans up the generated directory. A validating hook of that kind is a small station 1. What the tool, as documented, leaves to you is everything after generation: re-checking the project later, and keeping generated copies in step with a changed template.
The counterexample, from this site's own examples. Example A needs no model, because every body it can produce is already a template in its catalog. The rejected third spec shows the edge: it asks for a body called median_sorted, which is not in the catalog, and station 1 refuses it. A factory that served such requests every day would need someone, or something, to write new logic. That is where Example B puts a scripted stand-in for a model (AI enters the factory), and it is the shape of WatchAlgo, where each of thousands of problems needed its own solution and visualization.
The failure modes. A template chosen where logic varies turns into hand edits in generated files, which the next regeneration overwrites; Example A's generated module says "Do not edit by hand" for this reason. A factory chosen for a one-off request spends days on a pattern that runs once. A model placed where parameters were enough adds non-determinism and review cost and buys nothing. And an abstraction chosen too early, as in the opening story, removes the place a rule should live.
In a coding agent. A coding agent such as Claude Code or Codex running as a station worker is the fourth option, and only at the station that writes new logic. The pattern decides which files it may touch, the spec gives it one work item, and the factory's own tests, not the agent's, decide whether the work advances. The controls around that run belong to Harness Engineering.
What this is not. This page sorts two small requests. The full enterprise version, a pattern file with users, roles, APIs, data, events and extension points against a specific product spec, is Pattern versus configuration versus business logic. Organization-wide golden paths and template catalogs are Platform foundations. Writing the instructions a model receives at a semantic station is Prompt Engineering.
Try it#
The lab shows the two specs of Example A side by side (preset algo) or two synthetic intake products (preset intake). Mark each field as invariant (it goes to the pattern), variation point (it stays in each spec) or do not abstract, and read the resulting split and any over-abstraction warnings.
The table is the algo comparison for a reader without JavaScript. The values come from the two real spec files; the suggested choices are this site's recommendation.
| Field | running-sum | clamp-list | Same? | Suggested choice |
|---|---|---|---|---|
schema_version | 1.0 | 1.0 | yes | invariant (the pattern accepts 1.0) |
pattern | PAT-ALGO-UNIT 1.3.0 | PAT-ALGO-UNIT 1.3.0 | yes | invariant (named by the spec, owned by the pattern) |
acceptance_criteria | AC-1, AC-2 | AC-1, AC-2 | yes | invariant checks; each spec still lists them |
function_name, params | running_sum, xs | clamp_list, xs lo hi | no | variation point |
body_template | prefix_sum | clamp_each | no | variation point, chosen from the catalog |
requirements, examples | 3 requirements, 3 examples | 3 requirements, 4 examples | no | variation point |
| error rule | none | ValueError when lo is greater than hi | no | do not abstract: it lives in clamp_each |
No model takes part in this comparison or in Example A. Where later examples put one at a station, the agent is a scripted stand-in, so those results show how the factory mechanics work, not how good any model is.
WatchAlgo in practice#
WatchAlgo is a large instance of this page's question, and its repository shows both the invariant and the parts that must stay apart.
Observed in the repository (zenalgo-frontend, HEAD 1b183564): every one of the 3,246 production units is a folder wa-NNNNNN with up to three JSON files: problem.json, solution.json and visualization.json. That file contract is the invariant. Two independent axes vary inside it. A flavor is a narrative style (technical, fun, spiritual) and a language is a programming language (javascript, python, java). They are counted separately and never merged: "three flavors" means three narrative styles, not three languages (Flavors and languages is the home of that distinction).
The repository also shows what was deliberately not shared. The flavors are not one text with three skins: they carry different fields (the spiritual problem has a koan; the technical one has constraints and follow_up_questions). A visualization, by contrast, has one set of test cases and states shared by all three flavors; only its explanatory text is per flavor. And the shape drifts where nothing checks it: the inventory finds one solution with its sections at the wrong level (wa-002025) and four without the top-level visualization_spec (wa-000001, wa-002157, wa-002158, wa-002159). A pattern without a validator is a convention, and conventions drift. The evidence notes are docs/evidence/inventory.md (sections 2 and 3) and examples/watchalgo-adapter/README.md.
Reported by the author: specialized agents handled individual station responsibilities across the 3,246 problems. The repository does not show a single pattern file for the unit; the shape lives in the data, the validators and the prompts (The WatchAlgo story).
Enterprise translation#
In an organization the split on this page becomes a split of ownership. A platform team owns the pattern: PAT-INTAKE-API, its eight-step skeleton, its templates and its constraints, released under a version. Domain teams own product specs: the fields, routes, workflow states and business-rule modules of each intake service. The pattern declares the extension points; a product spec fills them; the factory refuses a spec that leaves one empty.
Two rules make that arrangement safe. Anything that must not vary, such as "only the underwriter role records a decision", lives in the pattern and is enforced in code, never left as a default a spec could override. Anything that varies for business reasons, such as an eligibility rule, lives in the product's own module even if it looks like another product's rule. The pattern shares plumbing and checks; it never shares judgement that belongs to a domain team. What dominates the timeline in that setting is rarely generation; it is agreeing which rules are truly shared, which Classify the enterprise demand and Platform foundations take up.
Failure test#
The failure: two behaviors that only look alike are merged into one generic mechanism, and a rule that belonged to one of them disappears.
How the factory catches it: in this case, by an example. Clamp example 4 (lo 3, hi 2, expects ValueError) is turned into a test at station 3 and fails on the generic version, as the output above shows. A factory cannot catch a missing rule that no example or criterion mentions; that is why error cases belong in the spec as examples.
What to run or toggle: run the over-abstraction script above against Example A's specs, or in the lab mark the error rule as invariant and read the warning. A second, quieter coupling is in the folded block "A variation point with a hidden dependency" below: rename two parameters of the clamp spec and every test fails, although station 1 passes.
Where to go deeper#
- The specification as an executable contract (next): how each request's variable part is checked before any station runs.
- Pattern versus configuration versus business logic: the enterprise pattern file against a product spec.
- Platform foundations: golden paths, repository templates and catalogs across an organization.
- Factory learning loop: versioning a pattern and the blast radius of a template change.
- Schema Engineering: typed contracts, validation and repair, the machinery under a variation point.
- Prompt Engineering: writing the instructions for the one station where a model writes new logic.
Checklist for Monday#
- Before abstracting, put two instances side by side and list, field by field, what is identical and what differs.
- Ask of every shared piece: will both instances change for the same reason? If not, keep them apart.
- Write error cases and refusals as examples in the spec, so an over-abstraction fails a test.
- Give the pattern a version and a digest; never edit a released pattern in place.
- Keep business rules in per-product modules, and put rules that must never vary into the pattern as enforced code.
- Pick the least machinery from the decision table; write down what evidence would justify the next level.
Exercises#
- A third request arrives: "absolute value of every element". Which option from the decision table, and what changes in Example A?
Answer 1A new body in the catalog
A deterministic factory is still enough: add a body template (say abs_each) to the pattern's catalog, release a new pattern version, and write the spec. No model is needed, because the logic can be written ahead of time.
- Two intake products both mask the broker's email in logs. Pattern or product spec?
Answer 2Pattern constraint, product data
The masking mechanism and the rule "logs mask personal data" belong to the pattern (Example C lists logs_mask_pii: true as a constraint). Which fields count as personal data is product data, declared in each spec (observability.pii_fields).
- Why is "the code looks the same" a weak reason to merge two functions?
Answer 3Reasons to change
Shared code ties two things to one release. If they change for different reasons, every change to one risks the other, and rules that only one needs lose their natural place.
Advanced perspective#
Software product lines: the older name for this workCore assets, product development, and what a product line is not
A software product line is a family of products built from a shared, managed set of assets in a prescribed way. Guideline (SEI Software Product Lines, read 2026-11-20): the SEI defines it as a set of software-intensive systems sharing a common, managed set of features for a market segment or mission, developed from a common set of core assets in a prescribed way. The framework names three essential activities: core asset development, product development, and management. Its alternate terms map onto this site's words: core assets are the platform, core asset development is domain engineering, product development is application engineering.
Two points from the SEI material are directly useful here. First, a product line is explicitly not clone-and-own, not fortuitous small-grained reuse, and not a configurable architecture alone; copying the running-sum file and editing it is clone-and-own. Second, it names three adoption approaches: proactive (build the core assets first, with up-front investment), reactive (start from existing products, lower entry cost) and incremental (build the core asset base in stages). Example A grew reactively: two products first, then a catalog. The newest framework version shown is 5.0, dated 31 December 2012, and the material read does not connect product lines to AI agents; the vocabulary is older than the tools, which is the point.
Where and when a variation is boundParameter, catalog, extension point, generated code
Variation points differ in how much freedom they allow and when they are fixed. A parameter (a name, a setting) is bound when the spec is written and checked by type. A catalog choice (Example A's body_template) is bound at station 1 against a closed list. An extension point (Example C's underwriting section) is bound to a product module that the pattern calls but does not contain. Generated logic, written by a person or a model for one instance, is bound at a semantic station and can only be checked afterwards, by tests.
Moving down that list buys flexibility and costs verifiability. A design rule that follows: push each variation as far up the list as the business allows. If a product's need fits a catalog entry, do not let a model write it fresh. Birgitta Böckeler's article on harness engineering (martinfowler.com, read 2026-11-20) makes a related argument for coding agents: committing to a fixed topology reduces the variety an agent can produce, which makes a complete set of checks more achievable. A factory pattern is that commitment, made explicit and versioned.
Estimating the decision without confusing volume and valueCount accepted units, defects avoided and review effort
The tempting way to justify a factory is output volume: how many files, functions or services it generated. That number rises fastest at the option with the least checking. A sounder estimate counts three things per option: the cost to produce one accepted artifact (including rework and review), the cost of the defects that escape, and the one-time cost of building the pattern, spread over the expected number of requests.
A template wins when requests differ only in parameters, because its per-artifact cost is near zero and its defects are few. A deterministic factory wins when defects are expensive and evidence is required per artifact. A model at a semantic station wins only when writing the logic by hand is the bottleneck and the independent checks are strong enough to keep escapes low; otherwise its review cost can exceed what it saves. Factory quality engineering works the arithmetic, including a case where adding agents makes the line slower and more expensive.
In one breath#
A pattern is what every request of a kind shares, written once, versioned and owned: in Example A, the stations, the file shapes and the checks. Variation points are the declared boxes each request fills, and some differences, like the clamp's refusal of bad bounds, must stay in each request's own logic even when the code looks alike. Choose the least machinery that produces the artifact reliably: hand-written code, a template, a deterministic factory, and a model only at the station that must write new logic.
Example A's pattern now separates what is shared from what each request supplies. But a pattern can only build what the request states, and a request can be incomplete, vague, or contain instructions it should not. The specification as an executable contract shows how the factory checks the request itself before any station runs.