1.5 KiB
Template Context
This file defines the shared meta-language used by engineers and AI agents when discussing and developing within this template repository.
Language
Bounded seam: A reviewable boundary in the code where a human cares about the contract (intent, authority, protected invariants) and can treat the inside implementation as a black box. Avoid: Interface, abstraction, boundary (when used generically)
Three-alternatives rule: A design constraint requiring the generation of three plausible names or seams to expose hidden assumptions before settling on an implementation choice. Avoid: Brainstorming, ideation
Intent-first name: A name given to a seam, workflow, or type that focuses on the caller's explicit goal rather than the shape of the current underlying implementation. Avoid: Implementation-shaped name, structural name
Example dialogue
Reviewer: "This module exposes a lot of internal helpers. Where is the actual Bounded seam?" Developer: "Right now it's just a folder. I'll consolidate the exports so the Bounded seam presents a clear, Intent-first name like
getNextTask." Reviewer: "Great! Don't forget to apply the Three-alternatives rule before finalizing the name."
Flagged ambiguities
- "Interface" was previously used to describe a structural typing concept as well as a psychological code boundary. Resolved: Use Bounded seam when discussing psychological boundaries and contracts, and reserve "interface" for TypeScript structural typings.