28 lines
1.5 KiB
Markdown
28 lines
1.5 KiB
Markdown
# 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.
|