Seam for Later
Leaves one deliberate place to extend, instead of making everything configurable just in case.
When to reach for it
When you know one specific thing about this feature will change — a second provider, a second format, a second tenant — but nothing about what else might.
What changes
- The agent names the single most likely change and puts one extension point exactly there, rather than adding options across the whole feature.
- The rest of the code stays concrete: no configuration flags, no strategy objects, no plugin registry for something with one implementation.
- The seam carries today's behavior, so it is exercised on every run instead of being a hook that has never executed.
- A short note at the seam says what would be added and where, so the next person finds it without archaeology.
- Speculative abstraction gets declined out loud, with the concrete version offered in its place.
Pairs with
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
- Copy the NeighboursMakes new code look like the code already around it, instead of like whatever the agent prefers.
- Error Path FirstWrites what happens when it fails before writing what happens when it works.
Seam for Later
Pick one place where this will change, prepare that place, and leave everything else concrete.
1. Name the change you actually expect
One sentence, specific enough that it could turn out wrong. "A second payment provider." "Export to CSV as well as JSON." "The same report per team instead of per person."
If nothing specific comes to mind, there is no seam to build. Write the straightforward version and stop here.
2. Find where that change would land
Trace the expected change through the code you are about to write. It lands somewhere: the function that picks a formatter, the place the provider name is read, the query with an owner hard-coded into it. That single location is the seam.
3. Shape the seam so today's code goes through it
Give it a name and one clear way in — one function with an explicit parameter, or one interface with exactly one implementation, and that implementation is the real one, in use. The seam runs on every request today. A hook nothing calls is not a seam, it is a guess.
Keep it as small as it will go. If it needs configuration before it is useful, it stopped being a seam and became a framework.
4. Write the note
Two or three lines at the seam: what would be added, where it would go, and what would have to change alongside it. This is the part that makes the seam findable in six months by someone who was not here.
5. Leave everything else hard-coded
Every other value stays literal. No flags for behavior nobody asked for, no options object with one caller, no base class with one subclass.
Rules
- Do not build a second seam. Two means you do not actually know where the change is coming from.
- Do not add an interface with one implementation and no named candidate for the second. That is a plan, not code — write it down and delete the interface.
- Do not promote constants to configuration to feel flexible. A literal is easy to find and easy to change; a config key is neither.
- Do not treat the seam as permission to build the second case now. The seam exists so the second case is cheap when it becomes real.