## Engineering terms: all terms

From Vibe Coding 101 (https://vibe-coding-101.brighteng.org/). When a request describes one of these problems, use the named technique, say its name, and run its check. Each term's page has the full entry and a prompt.

### development workflow

- **test-driven development**: Let one failing example drive the next implementation. Use when: You can describe the behavior before writing it. Do: Choose one observable example. Run red, green, then refactor. Check that red failed for the missing behavior. Avoid: A syntax error is mistaken for proof that the test detects the missing behavior. Worked example: https://vibe-coding-101.brighteng.org/examples/tdd.md
- **refactoring**: Change internal structure while preserving observable behavior. Use when: A working implementation is becoming hard to change. Do: Name the behavior to preserve and the scope to improve. Check those behaviors before and after. Avoid: Changing assertions to accept a behavior change conceals a regression.
- **minimal reproduction**: The smallest repeatable case that still shows the bug. Use when: A bug report says something is broken but cannot show how. Do: Remove unrelated setup until the failure is small and repeatable. Check it from a clean starting state. Avoid: Removing the condition that causes the failure produces a different test case. Worked example: https://vibe-coding-101.brighteng.org/examples/repro.md
- **root cause analysis**: Find the mechanism that produces the failure. Use when: Fixes keep moving the same bug to another place. Do: Trace the input across boundaries. Change one suspected cause. Check whether the original failure changes as predicted. Avoid: Several simultaneous changes hide which explanation was correct.
- **git worktree**: A separate checkout and index sharing the same Git repository. Use when: You need another branch without disturbing unfinished edits. Do: Create the checkout and identify shared ports and data. Check git status in both directories. Avoid: A separate directory still connects to the same database.
- **verification**: Check the claimed result against fresh evidence. Use when: The agent says a fix is done, but only describes its edits. Do: Choose the check that would expose the failure. Run it after the final edit and report its actual outcome. Avoid: An earlier passing result is reused after further edits.
- **reverse engineering**: Recover a behavioral specification from an existing system. Use when: You need compatibility with an existing product or undocumented module. Do: Record representative interactions and turn the observations into executable examples. Avoid: Assuming an unobserved edge case behaves like the happy path.
- **characterization test**: Record the behavior an existing implementation exhibits. Use when: You need to change legacy code whose intended behavior is poorly documented. Do: Capture representative inputs and outputs; label known defects separately from behavior to preserve. Avoid: Freezing incidental output so every harmless edit breaks the suite.
- **spike**: A short investigation answers one technical unknown. Use when: You cannot choose an approach until an integration or performance assumption is tested. Do: Name the question, time limit, and evidence needed. Record what the experiment does not prove. Avoid: Treating a successful toy example as proof of production readiness.
- **walking skeleton**: A minimal working path connects the application’s essential layers. Use when: The UI, backend, persistence, and deployment have never worked together. Do: Implement one small persistent action and deploy it to an isolated preview. Avoid: Mocking away the integration the skeleton is supposed to establish.
- **vertical slice**: Implement one usable behavior across the layers it requires. Use when: Work is divided into complete UI and backend layers with nothing usable yet. Do: Choose one user outcome and trace it through every required layer. Avoid: Calling a collection of disconnected components a finished slice.
- **strangler fig**: Replace an existing system incrementally by routing selected behavior to a new implementation. Use when: A large rewrite needs smaller, reversible releases. Do: Move one boundary at a time, compare behavior, and define when the old path will be removed. Avoid: Keeping two implementations indefinitely with no owner for their divergence.
- **executable specification**: An executable specification makes requirements checkable. Use when: The agent keeps filling gaps with different interpretations. Do: Write observable examples and constraints before implementing the uncertain behavior. Avoid: A document describes the intended behavior but no check exercises it.
- **behaviour-driven development**: Describe behavior through concrete examples shared by developers and domain experts. Use when: Product rules are understood differently by different contributors. Do: Choose examples with observable outcomes, including rejection and boundary cases. Avoid: Treating scenario syntax alone as proof that the requirement is understood.
- **ubiquitous language**: Use a shared domain vocabulary in requirements, code, and conversations. Use when: Order, booking, and reservation refer to the same thing in different files. Do: Define the domain terms and map existing names before making scoped renames. Avoid: Renaming distinct business concepts into one word because they look similar.
- **YAGNI**: Avoid implementing capabilities before a current requirement justifies them. Use when: The proposed change adds extension points and configuration with no current consumer. Do: Separate required behavior from hypothetical future variation and implement the required part. Avoid: Calling necessary error handling or access checks speculative work.
- **contract-first design**: Define an interface before implementing its producers and consumers. Use when: Frontend and backend implementations disagree on request or response formats. Do: Agree on a small contract and run checks from both sides of the boundary. Avoid: Changing the producer’s contract without checking existing consumers.
- **partial staging**: Partial staging selects changes within a file for the next Git commit. Use when: A working directory contains an unrelated experiment beside a completed fix. Do: Review the staged diff independently from the remaining working-tree diff. Avoid: Running a later blanket add that includes the previously excluded changes.

### agents and AI

- **context engineering**: Select and maintain the information an agent needs for the current task. Use when: The agent keeps overlooking repository rules or working from obsolete assumptions. Do: Provide the requirement, relevant code, exact failure, and durable decisions; refresh them when context changes. Avoid: Restricting context so tightly that a relevant caller is never inspected.
- **tool calling**: Tool calling lets a model request a defined operation from an application. Use when: An assistant needs to query data or perform a bounded application action. Do: Expose a narrow schema, validate on the host, and return explicit success or failure. Avoid: Treating model-generated arguments as trusted application input.
- **human in the loop**: A person reviews a decision at a defined point in an automated workflow. Use when: An automated step needs human judgment before an external or irreversible action. Do: Place the gate immediately before the consequential action and show the concrete proposed change. Avoid: Asking for so many low-value confirmations that meaningful approvals become automatic.
- **evals**: An evaluation measures an AI system on a defined set of tasks and criteria. Use when: A prompt improvement helps a demo but may regress other cases. Do: Keep representative cases, failure cases, and held-out examples; compare under the same conditions. Avoid: Tuning repeatedly to the same examples while calling them unseen evaluation.
- **guardrails**: Enforce explicit limits around automated actions. Use when: An agent can reach tools or data beyond the task’s intended scope. Do: Decide which operations are allowed and enforce those decisions outside the model. Avoid: Describing a restriction in prose while leaving the underlying tool unrestricted.
- **diff review**: Review the changes introduced by a patch, including tests and configuration. Use when: A change looks correct in the final file but may have removed safeguards. Do: Inspect additions, deletions, affected callers, and the evidence for the intended behavior. Avoid: Reviewing only additions and overlooking a deleted validation check.
- **few-shot prompting**: Few-shot prompting provides worked examples of the desired task behavior. Use when: A natural-language instruction leaves the expected output format ambiguous. Do: Use a small consistent set and evaluate on different inputs. Avoid: Reusing the demonstrations as the entire evaluation set.
- **structured output**: Constrain model output to a defined structure and validate it at the boundary. Use when: Another program must consume the model’s output reliably. Do: Use supported schema constraints, then validate structure and task-specific rules before consuming the result. Avoid: Treating schema-valid claims as verified facts.
- **MCP**: Model Context Protocol standardizes how applications expose tools and context to AI clients. Use when: An AI client needs a reusable integration with an existing service. Do: Expose a small integration surface and enforce identity, validation, and permissions at execution. Avoid: Assuming protocol compatibility provides the service’s authorization policy.
- **sandbox**: A sandbox restricts the resources a process can access. Use when: Untrusted code or an agent must run with limited access. Do: Choose the allowed resources and verify both intended operations and blocked ones. Avoid: Disabling the entire boundary to work around one missing permission.
- **embedding**: An embedding represents data as a numerical vector for a particular model and task. Use when: An application needs semantic retrieval or similarity matching. Do: Keep compatible vectors together and evaluate retrieval with permissions and real examples. Avoid: Mixing vectors from incompatible models in one similarity space.
- **retrieval-augmented generation**: Retrieval-augmented generation supplies retrieved material to a model before it answers. Use when: An assistant must answer using private or changing application information. Do: Enforce retrieval access rules and evaluate both retrieved evidence and the resulting answer. Avoid: Using prompt instructions as the only tenant filter.
- **holdout set**: A holdout set is reserved for evaluating behavior beyond the examples used for development. Use when: An AI change needs evidence of generalization beyond its demonstrations. Do: Choose a split that matches deployment and protect it from iterative tuning. Avoid: Calling a repeatedly inspected and optimized set an untouched holdout.
- **baseline**: A baseline is a credible comparison under the same evaluation conditions. Use when: A new model or optimization reports a result with no useful comparator. Do: Run the current or simple alternative using the same cases, metrics, and resource accounting. Avoid: Weakening the baseline so the proposed approach wins by construction.
- **quantization**: Quantization represents model values with reduced numerical precision. Use when: A local model exceeds the available memory or latency budget. Do: Compare supported representations on the target runtime with representative tasks. Avoid: Testing quality on a tiny calibration sample that misses important production inputs.
- **repository instructions**: Repository instructions document conventions and commands an agent should use. Use when: Every new coding session rediscovers the same setup and checks. Do: Keep the instructions concise and verify the documented commands in the actual repository. Avoid: Treating an instruction file as a system-enforced security boundary.

### code design

- **deep module**: A small interface hides a substantial useful implementation. Use when: Callers must understand too many implementation details. Do: Compare the caller contract with the hidden work. Check whether a caller can complete a task with less knowledge. Avoid: A one-line forwarding wrapper adds another interface to learn.
- **seam**: A place where behavior can be replaced without editing its consumer. Use when: Tests need an alternative clock, storage system, or external service. Do: Introduce the smallest useful substitution point. Check the same consumer with two implementations. Avoid: Adding an interface everywhere creates indirection without useful substitution.
- **composition**: Build a variation by assembling smaller parts. Use when: A component accumulates flags for every screen that uses it. Do: Extract the shared parts and compose two real variants. Check that each arrangement remains understandable. Avoid: Tiny parts still depend on a single giant component full of mode checks.
- **compound components**: Related components cooperate through a shared parent. Use when: Callers need different arrangements of tabs, menus, or editors. Do: Define the parent contract and compose two layouts. Check coordination and accessible relationships in both. Avoid: Shared state works but the trigger and panel lose their accessible relationship.
- **component variants**: Name the supported forms of a component explicitly. Use when: Independent flags allow contradictory appearances or behaviors. Do: List valid configurations and encode them. Check that an invalid combination cannot be requested. Avoid: Every visual detail becomes a separate variant and the API grows again.
- **dependency injection**: Supply a collaborator through a contract instead of constructing it inside. Use when: The same behavior needs local, remote, or test implementations. Do: Name the operations the consumer needs. Check it with two implementations of that contract. Avoid: The interface copies every method of the underlying library.
- **type-driven development**: Type-driven development uses types to express a design before filling in its implementation. Use when: Invalid state combinations keep spreading through the code. Do: Model valid states and transitions, then implement against those contracts. Avoid: Assuming a type assertion validates data received at runtime.
- **separation of concerns**: Separate responsibilities that change for different reasons. Use when: One handler mixes transport, business rules, and persistence details. Do: Extract the responsibility that has multiple callers or independent reasons to change. Avoid: Moving code into more folders without changing its dependencies.
- **leaky abstraction**: An abstraction exposes details callers still need to understand. Use when: Application code repeatedly handles vendor-specific details despite a wrapper. Do: Identify the caller contract and translate the implementation detail at its boundary. Avoid: Wrapping every method while returning the underlying client through an escape hatch.
- **technical debt**: A design shortcut creates a continuing cost for future changes. Use when: A deliberate shortcut will make a known follow-up task harder. Do: Name the shortcut, its concrete cost, and the condition that would justify changing it. Avoid: Calling every stylistic disagreement debt without identifying a cost.
- **semantic versioning**: Semantic versioning communicates compatibility of a declared public API. Use when: A library release needs a version that reflects its effect on consumers. Do: Identify the public contract and evaluate compatibility before choosing the version. Avoid: Assuming version numbers prove compatibility without checking actual consumers.
- **breaking change**: A change requires an existing consumer to adapt. Use when: An API, file format, or shared function is changing. Do: Identify consumers, preserve compatibility where needed, and plan migration for intentional breaks. Avoid: Checking only the exported function signatures.
- **observability**: Expose evidence that helps explain a system’s behavior. Use when: Failures cannot be traced from a user action to the operation that caused them. Do: Choose a concrete diagnostic question and instrument only the evidence needed to answer it. Avoid: Collecting full sensitive payloads instead of the diagnostic fields needed.
- **architecture decision record**: An architecture decision record captures a consequential choice and its context. Use when: A design choice is likely to be revisited after its context is forgotten. Do: Record the decision when it is made and link it to the constraint or evidence behind it. Avoid: Writing a retrospective justification that omits the real tradeoff.
- **invariant**: A condition must remain true across permitted operations. Use when: Several paths must preserve the same business rule. Do: State the rule precisely, identify all writers, and test attempts to violate it. Avoid: Writing the rule only in a comment or form validation.
- **strategy pattern**: A strategy supplies interchangeable behavior behind a shared contract. Use when: The same workflow supports several algorithms or output formats. Do: Extract the varying behavior and verify callers against more than one implementation. Avoid: Building a class hierarchy when a small function parameter would express the variation.
- **adapter pattern**: An adapter translates an existing interface into the interface its caller expects. Use when: An application must support another vendor or an incompatible external API. Do: Define the application contract and translate external data and failures at the boundary. Avoid: Returning the raw vendor client to every caller for convenience.
- **service layer**: An application service coordinates a use case across entry points. Use when: HTTP endpoints and background jobs duplicate the same business workflow. Do: Extract the shared operation and keep its dependencies explicit. Avoid: Introducing unrelated persistence abstractions merely because a service was extracted.
- **repository pattern**: A repository exposes persistence operations needed by the application. Use when: Domain code depends on storage details that must change independently. Do: Define a small application-facing contract and test its required behavior against the real persistence implementation. Avoid: Re-exporting every query-builder method through another object.
- **feature-based organization**: Feature-based organization keeps related implementation close to the capability it serves. Use when: Changing one feature requires searching many unrelated global folders. Do: Identify the feature boundary and move related code without changing behavior or creating import cycles. Avoid: Assuming every internal subfolder is wrong even when the feature remains cohesive.
- **ownership**: Ownership defines which part of a program controls a value’s lifetime. Use when: A Rust change encounters ownership or lifetime errors. Do: Identify who should own the value and how long each borrower needs access. Avoid: Using shared ownership to avoid deciding which component actually owns the resource.
- **state machine**: A state machine describes states and permitted transitions driven by events. Use when: A workflow can become both saving and failed, or process an event in the wrong phase. Do: List states, events, and transition effects; decide how unexpected events are handled. Avoid: Maintaining a second set of flags that can disagree with the machine’s state.

### frontend and browser state

- **lifting state**: Move shared state to the nearest owner that can coordinate its users. Use when: Sibling controls must edit and display the same value. Do: Find the smallest shared owner. Check that editing either control updates both views. Avoid: Moving all state to the application root makes a local interaction global.
- **derived state**: Calculate a value from state you already have. Use when: A total, filtered list, or count falls out of sync. Do: Remove the redundant stored value. Check that one input change updates every dependent display. Avoid: A stored duplicate survives under a different name.
- **effect dependencies**: The reactive inputs that determine when an effect must resynchronize. Use when: A subscription or request keeps using an old value. Do: Identify the external system and its inputs. Check cleanup and resubscription when an input changes. Avoid: A new object on every render causes unnecessary resubscriptions.
- **functional state update**: Compute the next state from the previous state supplied by the framework. Use when: Rapid updates lose increments or append to an old list. Do: Use an updater when the next value depends on the previous one. Check several queued updates. Avoid: The updater performs a side effect or mutates the previous object.
- **request waterfall**: Requests form a sequence that adds their waiting times. Use when: A page loads several resources one after another. Do: Map actual dependencies and start independent reads together. Check the network timeline and failure behavior. Avoid: Requests that require an earlier result are parallelized incorrectly.
- **request deduplication**: Share equivalent requests within a defined scope. Use when: Several components request the same data at the same time. Do: Include all result-changing inputs in the key. Check one request for equivalent callers and separate results for different users. Avoid: An overly broad key shares data between different users or filters. Worked example: https://vibe-coding-101.brighteng.org/examples/request-deduplication.md
- **code splitting**: Load a separate code bundle when a feature needs it. Use when: A rarely opened editor inflates the first page download. Do: Move the feature behind a loading boundary. Check the first-load bundle and opening the feature. Avoid: A second eager import keeps the module in the initial bundle.
- **Suspense boundary**: Keep a useful shell visible while supported child content is waiting. Use when: One slow region blocks an otherwise useful React page. Do: Place the boundary around the slow region. Check loading, successful content, and error handling separately. Avoid: An ordinary fetch in an effect is assumed to activate Suspense automatically.
- **serialization**: Encode state so it can cross a storage or process boundary. Use when: A draft must survive a restart or data must reach another process. Do: Choose the fields and encoding deliberately. Check a round trip in a fresh instance. Avoid: A file is written successfully but cannot reconstruct the original state.
- **schema evolution**: Change a stored format while handling older data deliberately. Use when: An app update makes existing drafts or settings unreadable. Do: Version the format and define the old-data path. Check a previous-version fixture without losing the original. Avoid: A failed migration overwrites the only copy of the old data.
- **subscription cleanup**: Release listeners and subscriptions when their owner stops using them. Use when: Opening a screen repeatedly causes duplicate events or growing memory. Do: Pair each registration with cleanup using the same identity. Check repeated mount and unmount cycles. Avoid: Removing a newly created callback leaves the original listener registered.
- **optimistic UI**: Show an expected change before the server confirms it. Use when: A reversible interaction feels slow while waiting for the network. Do: Choose a reversible operation, track its pending state, and define rollback or reconciliation. Avoid: Rolling back an old request overwrites a newer successful edit.
- **rendering strategy**: Rendering strategy determines when and where initial HTML is produced. Use when: A route’s initial content, indexing, or authenticated data needs a deliberate rendering choice. Do: Classify public and personalized routes by freshness and interaction needs, then inspect their initial response. Avoid: Putting private user content into a shared static or cached response.
- **hydration**: Hydration connects client-side behavior to server-rendered HTML. Use when: A server-rendered page flashes different content or reports a hydration mismatch. Do: Find the differing inputs and isolate genuinely client-only behavior. Avoid: Suppressing warnings while leaving incorrect event or state behavior.
- **tree shaking**: Tree shaking removes unused code that a bundler can prove is unnecessary. Use when: A bundle contains a large dependency even though the app uses little of it. Do: Inspect the bundle graph and side-effect metadata before changing import structure. Avoid: Assuming every barrel export prevents tree shaking or marking real side effects as removable.
- **controlled input**: A controlled input gets its current value from application state. Use when: A form’s displayed value and submitted value disagree. Do: Choose an owner for the draft and test typing, reset, and submission. Avoid: Waiting for a server response before updating the local typing state.
- **progressive enhancement**: Provide a useful baseline and improve it when additional browser capabilities are available. Use when: A basic form or navigation action fails when its enhancement script does not load. Do: Keep the baseline action meaningful and test both enhanced and fallback paths. Avoid: Calling preventDefault without providing either a working replacement or recovery.
- **focus management**: Move and restore keyboard focus deliberately as interface context changes. Use when: Opening or closing a dialog leaves keyboard users in the wrong place. Do: Use the platform’s modal behavior where appropriate and test entry, navigation, exit, and restoration. Avoid: Moving focus on every render and interrupting typing.
- **client state vs server state**: Distinguish a local interaction draft from cached data owned by a server. Use when: Editing a form unintentionally changes other views before saving. Do: Give the draft a lifecycle and reconcile the server cache after the mutation resolves. Avoid: Overwriting an unsaved draft whenever background data refreshes.
- **islands architecture**: Islands architecture adds interactive components to an otherwise server-rendered or static page. Use when: Only a small part of a content page needs JavaScript. Do: Keep static content outside client boundaries and hydrate only the widgets that need it. Avoid: Passing the whole document into an island when it only needs a small input.
- **rules of hooks**: React Hooks follow rules about where they can be called. Use when: A component calls useState or useEffect conditionally. Do: Keep stateful Hooks in components or custom Hooks at valid call sites and retain the lint checks. Avoid: Applying an oversimplified rule to APIs with documented exceptions instead of checking the API contract.
- **list key**: A list key identifies an item across renders. Use when: Editing a row affects another row after sorting or inserting. Do: Choose a stable identity that survives the item’s lifecycle and test reordering. Avoid: Changing an optimistic item’s key when the server assigns its permanent ID.
- **stale closure**: A callback retains values from the environment where it was created. Use when: A timer or listener repeatedly uses an old prop or state value. Do: Decide which values should trigger resubscription and which should be read at execution time. Avoid: Putting everything in refs merely to hide missing dependencies.
- **CSS specificity**: Specificity ranks competing selectors within the relevant cascade context. Use when: A style change works only after repeatedly increasing selector strength. Do: Inspect the winning declaration and fix the cascade or component boundary intentionally. Avoid: Assuming a higher z-index or more specific selector can solve every visual layering problem.
- **stacking context**: A stacking context groups elements into a local stacking order. Use when: A menu appears behind another region despite a large z-index. Do: Find the relevant contexts and choose the intended overlay boundary, portal, or top-layer primitive. Avoid: Moving an overlay into a portal without preserving its anchor or focus behavior.
- **server components**: React Server Components run outside the client bundle and can prepare UI close to server data. Use when: A data-heavy page sends unnecessary code or sensitive data to the browser. Do: Keep server-only dependencies protected and pass only the data allowed across the client boundary. Avoid: Confusing the module dependency boundary with every visual descendant in the rendered tree.
- **event delegation**: A parent listener handles suitable events from descendants. Use when: A dynamic list needs shared handling for events from its rows. Do: Handle the relevant event at a stable ancestor and resolve the intended target within that boundary. Avoid: Assuming every event bubbles or trusting a target outside the intended container.
- **service worker**: A service worker can intercept requests and manage offline behavior. Use when: An offline-capable site keeps serving outdated or incompatible assets. Do: Define cache strategies by resource and test update transitions as well as the first installation. Avoid: Activating new cached assets before existing pages can safely use them.
- **web storage**: Browser storage APIs offer different persistence and access models. Use when: Browser data must survive reload without blocking interactions or exposing credentials. Do: Choose storage by data size and access pattern; validate stored values and handle failed writes. Avoid: Treating browser storage as inaccessible to scripts running on the same origin.
- **structural typing**: Structural typing compares the shape of types rather than only their declared names. Use when: Two values with similar shapes are being treated as interchangeable. Do: Use explicit boundary validation and strengthen domain types where similar shapes have different meanings. Avoid: Assuming naming two interfaces differently makes their values incompatible.
- **shadow DOM**: Shadow DOM provides a component subtree with scoped DOM and styling behavior. Use when: A reusable web component needs predictable styling inside different pages. Do: Define the internal styles and supported customization surface, including inherited values and exposed parts. Avoid: Using a closed root as protection for secrets or privileged operations.
- **container query**: A container query adapts styling to a containing context. Use when: The same component appears in a narrow sidebar and a wide content region. Do: Establish the query container and test the component at independently varying container sizes. Avoid: Querying the wrong ancestor and overlooking its effect on sizing.
- **headless UI**: Headless UI separates reusable interaction behavior from a particular visual presentation. Use when: Several screens need the same control behavior with different markup or styling. Do: Share the behavior and render two concrete presentations against its contract. Avoid: Replacing semantic controls with decorative elements while retaining only visual behavior.
- **state colocation**: Keep state near the components that own its lifecycle. Use when: Local temporary state is unnecessarily shared across independent panels. Do: Identify readers, writers, and lifetime before choosing the state owner. Avoid: Duplicating a genuinely shared value and trying to synchronize the copies.
- **custom Hook**: A React custom Hook extracts reusable stateful logic. Use when: Components repeat the same subscription, cleanup, or interaction logic. Do: Define the Hook’s inputs and lifecycle, then test multiple consumers and cleanup. Avoid: Sharing mutable module state unintentionally between Hook consumers.
- **reducer**: A reducer computes the next state from the current state and an action. Use when: Related state fields are updated inconsistently by separate event handlers. Do: Describe the allowed actions and test transition sequences independently of side effects. Avoid: Using a reducer to centralize side effects instead of state transitions.
- **composable**: A Vue composable encapsulates reusable stateful logic through the Composition API. Use when: Vue components repeat subscriptions or asynchronous behavior. Do: Define whether state is local or shared and use the appropriate lifecycle cleanup. Avoid: Translating a React Hook mechanically without checking Vue’s reactivity rules.
- **scoped slots**: A Vue scoped slot lets a child provide data to caller-supplied content. Use when: A reusable table needs different cell markup on different pages. Do: Expose the smallest useful slot data and verify multiple renderings of the same behavior. Avoid: Exposing unrestricted mutable internals as the customization API.
- **computed vs watch**: In Vue, computed values derive data while watchers respond with side effects. Use when: A watcher copies a total into another piece of state. Do: Derive pure values with computed and reserve watchers for the needed external synchronization. Avoid: Starting network requests inside a computed getter.
- **query keys**: A query key identifies cached data and the inputs that distinguish it. Use when: Changing a filter shows data from the previous selection. Do: Include the relevant resource identity and parameters, with deliberate authorization scoping. Avoid: Omitting tenant or user context from a cache whose results depend on it.
- **freshness and cache retention**: Freshness describes when cached data should be reconsidered; retention describes how long unused data remains available. Use when: A query refetches too often or unused cached results remain longer than intended. Do: Choose the permitted staleness and inactive retention separately and test the triggers that use them. Avoid: Keeping data permanently fresh without updating or invalidating it after writes.
- **mutation invalidation**: Query invalidation marks affected cached reads stale after a change. Use when: A successful mutation leaves detail or list screens displaying old data. Do: Map the mutation to affected keys and verify active and inactive views. Avoid: Invalidating a plausible key that no actual reader uses.
- **route loader and query cache**: A route loader prepares data for navigation. Use when: A route and its component fetch the same resource independently. Do: Share the data contract and define loading, error, and cancellation behavior across navigation. Avoid: Inventing a separate loader cache that the component never reads.
- **sticky positioning**: Sticky positioning keeps an element in normal flow until it reaches an offset in its scrolling context. Use when: A section toolbar should remain visible only while its section is scrolling. Do: Identify the scroll container and set the intended offset and containment. Avoid: Changing an ancestor’s overflow and silently changing the sticky behavior.
- **autosave**: Autosave persists edits without an explicit save command. Use when: A draft should survive navigation or interruption with minimal user effort. Do: Choose when edits persist, protect write ordering, and expose pending and failed states accurately. Avoid: Showing saved when a request was merely queued.
- **event handler**: Run interaction-triggered work in the code that handles that event. Use when: A form submission runs again when an unrelated theme or state value changes. Do: Identify the initiating event and move its action there. Keep effects for necessary synchronization. Avoid: Removing required ongoing synchronization together with the interaction-specific effect.

### APIs and data

- **query plan**: The operations a database chooses to answer a query. Use when: A query is slow and adding indexes would be guesswork. Do: Inspect a representative query and data set. Check actual rows, loops, and timing; use a safe environment for executing analysis. Avoid: EXPLAIN ANALYZE is run on a write under the assumption that it only explains.
- **database index**: A data structure that can make matching rows cheaper to find. Use when: A frequent selective query scans far more rows than it returns. Do: Start from the actual filter and ordering. Check the query plan before and after. Avoid: The query’s expression or ordering does not match the proposed index.
- **composite index**: One index covers an ordered combination of columns. Use when: A query repeatedly filters and sorts by several fields. Do: Match key order to the measured filter and sort. Check the actual plan with representative values. Avoid: Choosing column order from the table definition instead of the query.
- **partial index**: Index only rows that satisfy a predicate. Use when: A frequently queried subset is small compared with the whole table. Do: Choose the subset and verify that the planner can match the query to its predicate. Avoid: The query condition does not imply the index predicate, so the index is unusable.
- **N+1 query**: One list query triggers another query for every result. Use when: A page becomes slower in proportion to the number of displayed rows. Do: Trace database calls for a realistic list. Check that query count remains bounded as the list grows. Avoid: One enormous join replaces the round trips but multiplies the result rows.
- **keyset pagination**: Continue a list after the last returned sort key. Use when: Deep offset pages are slow or inserts shift the page boundaries. Do: Define a stable ordering and matching index. Check repeated sort values and inserts between page loads. Avoid: A changing sort field invalidates assumptions about traversal. Random page jumps may need another approach.
- **connection pool**: Reuse a bounded set of database connections. Use when: Traffic spikes exhaust the database’s connection limit. Do: Count pools across instances and define wait limits. Check concurrent load and cleanup after errors. Avoid: A sensible per-instance limit exceeds database capacity when multiplied by replicas.
- **parameterized query**: Keep SQL structure separate from input values. Use when: A database query includes values supplied by a user. Do: Bind values and allowlist variable identifiers. Check that hostile input is treated as data. Avoid: Parameters are incorrectly expected to substitute table or column names.
- **transaction**: Commit related database changes together or roll them back. Use when: A failed step leaves an object only partly saved. Do: Keep the database unit short. Check failure between writes and concurrent access to shared records. Avoid: An external API call is assumed to roll back with the database. Worked example: https://vibe-coding-101.brighteng.org/examples/transaction.md
- **deadlock**: Operations wait on resources held by one another. Use when: Concurrent transactions sometimes block until the database aborts one. Do: Inspect the competing operations and establish an order. Check the contention case and bounded retry handling. Avoid: Retrying forever hides the underlying cycle and increases load.
- **unique constraint**: The database rejects duplicate values for a declared key. Use when: Two simultaneous requests can create the same logical record. Do: Choose the true business key, including tenant scope when needed. Check simultaneous conflicting inserts. Avoid: The constraint omits tenant scope or conflicts with existing duplicate data. Worked example: https://vibe-coding-101.brighteng.org/examples/unique-constraint.md
- **upsert**: Insert a row or update the row that conflicts with its key. Use when: Importing or saving a setting may encounter an existing record. Do: Choose the conflict key and allowed updates. Check new rows, existing rows, and simultaneous submissions. Avoid: A stale request overwrites newer data; upsert alone does not resolve version conflicts.
- **database migration**: A recorded transition from one database schema to another. Use when: A schema change must preserve existing rows and deployed callers. Do: Exercise the migration on a representative older schema. Check data preservation and the recovery path. Avoid: A destructive change is called reversible even though its discarded data cannot be reconstructed.
- **row-level security**: Database policies control which rows a role may access. Use when: Users or tenants share tables but must not access each other’s rows. Do: Define read and write policies using trusted identity. Check them as the actual runtime role with two users. Avoid: Tests use an administrative role that bypasses the policies.
- **least privilege**: Give each runtime identity only the permissions its job needs. Use when: The application runs with an administrative database credential. Do: List required operations and grant those. Check that ordinary work succeeds and administrative operations fail. Avoid: A restricted role inherits broad permissions through another role.
- **webhook**: A service sends an HTTP request when an event occurs. Use when: Your application must react to changes in an external service. Do: Verify authenticity, persist or enqueue reliably, and handle duplicate or reordered deliveries. Avoid: Acknowledging an event before it is durably accepted, then losing it on a crash.
- **REST**: REST is an architectural style for resource-oriented interactions through a uniform interface. Use when: An HTTP API needs predictable resource and operation behavior. Do: Define resources and method semantics, then verify safety, idempotency, and error responses. Avoid: Assuming every valid API operation must fit a simple CRUD endpoint.
- **rate limit**: Limit how often a caller can perform an operation. Use when: A costly endpoint can be overwhelmed by repeated requests. Do: Choose the caller identity and limit policy; test bursts and multiple instances. Avoid: One global bucket lets a noisy caller block everyone else.
- **cache invalidation**: Mark cached data stale, remove it, or refresh it when its assumptions change. Use when: Users keep seeing old data after a successful edit. Do: List cache keys, dependencies, and freshness expectations; connect relevant writes to their invalidation path. Avoid: A correct invalidation event uses a different key from the reader.
- **job queue**: A queue separates accepting work from processing it. Use when: Slow work should continue independently of the request that created it. Do: Choose durable acceptance, bounded retry, and idempotent processing; make terminal failures visible. Avoid: Returning success before the work has been durably accepted.
- **circuit breaker**: Temporarily stop calls to a failing dependency and probe for recovery. Use when: Repeated upstream failures consume the application’s remaining capacity. Do: Define which failures count, when calls are rejected, and how recovery is tested. Avoid: Counting every client validation error as evidence that the dependency is down.
- **graceful shutdown**: Stop accepting new work and finish or hand off existing work before exiting. Use when: Deployments interrupt active requests or background jobs. Do: Stop admission, drain or checkpoint work, close resources, and enforce an exit deadline. Avoid: Waiting forever for one stuck task to complete.
- **minor units**: Represent money using integer minor units or an appropriate decimal representation with an explicit currency. Use when: Totals drift because prices are calculated with unsuitable arithmetic. Do: Choose scale and rounding explicitly; verify sums, allocation, and currency-specific cases. Avoid: Assuming every currency has two decimal places or every integer fits safely in a JavaScript number.
- **UTC vs local time**: Distinguish an instant from a calendar date and a local scheduled time. Use when: Dates shift by a day or recurring times move unexpectedly around daylight-saving changes. Do: Choose the value’s meaning first, then its storage format and conversion boundary. Avoid: Turning a birthday into a UTC instant and later rendering it on another date.
- **optimistic concurrency**: Accept an update only if the version being replaced still matches the version the caller read. Use when: Two editors can overwrite each other’s changes. Do: Include the version condition in the atomic write and test competing writers. Avoid: Incrementing the version without checking it in the write condition.
- **partial update**: A partial update changes only the fields identified by its contract. Use when: Editing one field unexpectedly clears other stored values. Do: Define patch semantics and validate presence separately from value. Avoid: Applying create-time defaults to every update request.
- **transaction isolation**: Transaction isolation defines how concurrent transactions may observe and affect one another. Use when: A transaction is atomic but still violates a rule under concurrent access. Do: Identify the required invariant, choose the isolation strategy, and test conflicting transactions. Avoid: Retrying only the final statement after the database requires the whole transaction to restart.
- **DTO**: A data transfer object defines the fields crossing an application boundary. Use when: An endpoint exposes private fields or accepts writable fields the caller should not control. Do: Define explicit input and output contracts and map only the permitted fields. Avoid: Inheriting the full persistence model and calling it a restricted DTO.
- **WebSocket**: A WebSocket provides a persistent bidirectional connection. Use when: The client and server must exchange ongoing updates in both directions. Do: Define message schemas, access checks, bounded buffers, and reconnect behavior. Avoid: Treating the connection’s initial authentication as permission for every future operation.
- **error as value**: Represent expected failures explicitly in a function’s result. Use when: Callers cannot tell not-found from validation failure or an unavailable dependency. Do: Define a small result type and require callers to handle its relevant cases. Avoid: Converting every unexpected exception into an ordinary empty result.
- **option type**: An option type represents a value that may be absent. Use when: Missing data is represented by a misleading default value. Do: Keep optionality at the boundary where it exists and handle it before requiring a value. Avoid: Assuming one optional value automatically represents absent, null, and empty as three distinct states.
- **DataLoader**: DataLoader batches related loads and can memoize results within a chosen scope. Use when: Related resolvers repeat loads for the same entities. Do: Share a loader within the authorized request scope and handle missing keys explicitly. Avoid: Sharing a loader cache across users without the required authorization boundaries.
- **middleware order**: Middleware ordering determines which request and response processing runs before another step. Use when: Authentication, parsing, or error handling runs too late or is skipped. Do: Trace the actual request and error paths, including short-circuits and preflight requests. Avoid: Sending an error response and then continuing to the protected handler.
- **data access layer**: A data access layer centralizes access rules and data retrieval at a boundary. Use when: Several server entry points duplicate sensitive reads and permission checks. Do: Derive identity from trusted context, enforce access, and shape the allowed response. Avoid: Trusting a caller-provided identity because the function lives in a server-only file.
- **server action**: A server action exposes a framework-supported server operation to the client. Use when: A form needs to invoke server work through the framework’s action mechanism. Do: Check identity and permission inside the operation and validate its arguments before mutation. Avoid: Relying on a protected page or hidden button as the action’s authorization.
- **ETL and ELT**: ETL transforms extracted data before loading it; ELT loads data before transformation. Use when: A report imports and transforms data from another system. Do: Define source identity, transformation rules, and rerun behavior with representative fixtures. Avoid: Transforming away source information needed to correct a later rule.
- **table partitioning**: Table partitioning divides a logical table into physical parts. Use when: A large table needs efficient bounded scans or lifecycle operations. Do: Check pruning and operational cost on representative queries before adopting the layout. Avoid: Assuming partitioning replaces indexes or guarantees every query is faster.
- **backfill**: A backfill populates or recomputes existing data after a rule or schema change. Use when: A new field works for new records but is missing from historical ones. Do: Process bounded ranges, persist progress, and define how concurrent writes interact with the job. Avoid: Overwriting a newer live value with a value computed from an older snapshot.
- **denormalization**: Denormalization duplicates or precomputes data to serve a read pattern. Use when: A measured read bottleneck motivates storing a value near its consumer. Do: Choose whether the value is a historical snapshot or a maintained projection and test that policy. Avoid: Maintaining the same copy through several independent update paths.
- **batch vs stream**: Batch processing operates on bounded input; streaming processes ongoing input. Use when: A data workflow is acquiring a broker despite only needing periodic results. Do: State the latency requirement and choose the simplest model that meets it. Avoid: Treating processing time as event time when late-arriving records change the result.
- **runtime validation**: Check untrusted values when the program receives them. Use when: An API or file supplies data that TypeScript types merely assume is valid. Do: Validate at the boundary, then pass the validated value inward. Check both malformed shapes and domain constraints. Avoid: Validating the shape but trusting a caller-supplied identity or ownership claim.
- **physical row clustering**: Place related rows near each other to reduce scattered reads. Use when: A range query fetches related rows from many storage pages. Do: Measure page reads for the target range query. Check engine semantics, locking, and free disk before reorganizing. Recheck after representative updates. Avoid: A one-time rewrite can lose its benefit as rows change; clustered-index behavior varies by engine.
- **normalization**: Store facts according to their keys to reduce update anomalies. Use when: Changing a customer’s current address requires editing many inconsistent copies. Do: Identify each fact’s key, split independent entities, and add references and constraints. Check one update changes the current fact everywhere it is read. Avoid: Splitting every value into a table without considering meaning or query cost is not a useful goal.
- **leader–follower replication**: Send writes through a leader and replicate them to followers. Use when: You need read capacity or a standby while keeping one write authority. Do: Define write and read routes, acknowledgement guarantees, and promotion rules. Check replica lag and read-after-write behavior during a failover drill. Avoid: One leader simplifies write ownership but does not eliminate data loss, lag, or split-brain risk.
- **multi-leader replication**: Allow multiple write authorities with explicit conflict handling. Use when: Disconnected sites or multiple regions need to accept writes. Do: Identify overlapping keys and constraints. Choose ownership or conflict rules. Test concurrent edits, retries, and recovery after disconnection for the selected product. Avoid: Last-write-wins can discard valid work; extra writers do not guarantee linear write scaling.
- **BASE**: Design for availability with temporary state and eventual convergence. Use when: A non-critical projection can stay usable while updates propagate. Do: Name the data that may lag, how it converges, and what still requires atomic changes. Check delayed, duplicate, and failed updates against those rules. Avoid: An eventually updated view can coexist with ACID transactions. Product categories do not establish exact guarantees.
- **ACID**: Specify atomicity, consistency, isolation, and durability for transactions. Use when: A transfer or order must preserve invariants across several database changes. Do: Define constraints, isolation, and commit durability. Check rollback and competing transactions. Keep external side effects outside the claimed local atomic boundary. Avoid: ACID consistency is invariant preservation, not CAP consistency. A local transaction cannot roll back an already sent email.
- **strong consistency**: Make the exact freshness and ordering guarantee explicit. Use when: A permission revocation or inventory decision must not use an older acknowledged value. Do: Identify the data scope and real-time ordering requirement. Use the supported consistent read or atomic conditional write. Check reads after acknowledged writes and overlapping updates. Avoid: A fresh read alone does not make a later write atomic; caches and unsupported indexes can change the read path.
- **write-ahead logging (WAL)**: Persist the recovery log before the corresponding data pages. Use when: A database must recover committed changes after a crash without flushing every changed page at commit. Do: Inspect log flush and commit settings. Run a crash-recovery drill on a disposable instance and reconcile acknowledged commits with recovered data. Avoid: WAL is not a standalone backup. Losing required log segments or the underlying durable storage can prevent recovery.
- **checkpointing**: Record a recovery boundary after making the required state durable. Use when: Recovery replays too much log or periodic flushing causes latency spikes. Do: Check checkpoint duration, write load, and recovery time on representative data. Tune the interval and WAL budget together. Verify backups separately. Avoid: A checkpoint does not replace backup retention or prove that a snapshot in another system is transactionally consistent.
- **storage compaction**: Merge storage runs and reclaim obsolete versions when safe. Use when: An LSM store accumulates files, tombstones, or background write pressure. Do: Measure pending compaction bytes, read/write amplification, disk headroom, and latency. Check tombstone and snapshot retention before expecting space to return. Avoid: Compaction consumes I/O and may need extra space before reclaiming any. It is different from a recovery checkpoint.
- **data locality**: Place related data and computation close to reduce remote work. Use when: A request crosses regions or shards repeatedly to join related records. Do: Map request hops, key placement, and transaction participants. Compare local and remote paths under the chosen durability and failure policy. Avoid: Local reads do not imply local writes, regulatory compliance, or survival of a regional failure.
- **hot partition**: One partition receives more work than its capacity can handle. Use when: One tenant or current-time bucket is throttled while the rest of the database is idle. Do: Measure traffic and throttling per key or partition. Choose a better key or split hot-key work where semantics allow. Verify query fan-out and distribution afterward. Avoid: More partitions do not divide a single key automatically. Balanced storage size does not guarantee balanced traffic.
- **caching**: Reuse a stored result with explicit freshness and failure rules. Use when: Repeated requests recompute the same expensive result or reread the same data. Do: Define the key and acceptable staleness. Test hits, misses, invalidation, tenant separation, eviction, and a cache outage. Measure origin load as well as latency. Avoid: A cache can amplify outages through miss storms. Fast stale data can still be wrong.
- **materialized view**: Persist a query result and define how it becomes current again. Use when: A dashboard repeats an expensive aggregate that can tolerate some lag. Do: Choose a freshness budget, refresh method, and failure handling. Change source data, verify the view’s documented lag, then verify the refreshed aggregate. Avoid: A normal view does not persist results. A materialized view can become stale and its refresh can be expensive.
- **secondary index**: Provide another access path besides the table’s primary organization. Use when: Queries use an email or status rather than the primary lookup key. Do: Choose an index for a real filter or ordering. Inspect the plan and table accesses, then measure write overhead and index size. Avoid: Secondary indexes add work to writes and are not necessarily unique or covering.
- **covering index**: Include the values a query needs so fewer table-row fetches may be necessary. Use when: An indexed query still spends time fetching columns from the table. Do: Check filters, ordering, and selected columns. Compare index size, write overhead, and actual heap fetches on representative data and update rates. Avoid: Coverage is relative to a query. Visibility, unsupported access methods, or changed projections can remove its benefit.
- **Bloom filter**: Reject definite misses cheaply while allowing possible false matches. Use when: Most lookups test keys absent from an expensive storage layer. Do: Choose a false-positive budget and memory size. Check all inserted keys, measure false positives for absent keys, and define update and rebuild behavior. Avoid: A standard Bloom filter cannot safely delete a key by clearing shared bits. A stale filter can reject valid new data.
- **LSM tree**: Buffer writes and organize persisted data as sorted runs. Use when: You are choosing storage for sustained writes and ordered key reads. Do: Measure the actual mix of writes, point reads, range scans, and deletions. Inspect compaction debt, cache use, and disk headroom before tuning. Avoid: Sequential ingestion does not mean every write is cheap; compaction rewrites data and can stall foreground work.
- **B-tree**: Keep keys ordered in a balanced tree for lookups and range scans. Use when: Queries filter by equality, compare ranges, or request indexed ordering. Do: Match the operator and key order to real queries. Inspect plans for equality, range, and ordering cases and measure write cost. Avoid: An index can be slower than a scan for a large result set; existence does not guarantee selection.
- **query planner**: Choose an executable access path and join strategy for a query. Use when: A database picks a surprising scan or join even though an index exists. Do: Compare estimated and actual row counts and inspect scans and joins. Refresh appropriate statistics before forcing a strategy. Use a safe environment for EXPLAIN ANALYZE, which executes the query. Avoid: A plan for one parameter or tiny fixture may not represent production. Planner costs are not elapsed milliseconds.
- **cost-based optimizer**: Choose among query plans using estimated resource costs. Use when: A join order performs badly because the database misestimates intermediate row counts. Do: Find the largest estimate-versus-actual mismatch. Check statistics, data distribution, and cost assumptions. Compare candidate plans under the same representative workload. Avoid: Cost units are model units, not milliseconds. Correlated columns and changing workloads can defeat simple estimates.
- **data skew**: Uneven values or partition sizes make some units of work much larger than others. Use when: One join task runs long after every other task finishes. Do: Inspect key frequencies, partition bytes, and task durations. Consider skew-aware joins or splitting heavy work. Check result correctness and the slowest task afterward. Avoid: Hashing distributes different keys; it does not divide all rows with the same key unless the algorithm explicitly supports that split.
- **change data capture (CDC)**: Publish source-data changes so downstream systems can follow them. Use when: A search index or warehouse must follow database updates without repeated full scans. Do: Define the snapshot-to-stream handoff and durable offsets. Test restart, duplicate delivery, deletes, schema changes, and reconciliation with the source. Avoid: CDC is not an automatic end-to-end exactly-once guarantee or an application business-event contract.
- **logical replication**: Replicate logical table changes rather than a physical copy of storage. Use when: A reporting database needs selected tables or a migration crosses compatible database versions. Do: Choose published data and row identity. Check initial synchronization, lag, updates, deletes, and schema compatibility before cutover. Avoid: Logical replication is not automatically multi-leader conflict resolution or a complete database clone.
- **physical replication**: Keep a standby aligned with the primary’s physical database changes. Use when: You need a compatible whole-database standby for read offload or recovery. Do: Check version and storage compatibility, base backup, retained WAL, and replay lag. Drill promotion and prevent the old primary from remaining writable. Avoid: A lagging standby can lose acknowledged asynchronous writes on failover. Replication does not replace independently retained backups.
- **query federation**: Query independently managed data sources through a shared interface. Use when: A report joins local records with data owned by another database. Do: Inspect pushdown and transferred rows. Restrict credentials and define remote failure handling. Check whether the required cross-source consistency is supported. Avoid: One SQL statement across sources does not automatically provide a single global snapshot or atomic distributed writes.
- **data lake**: Retain diverse data for later processing and analysis with governance. Use when: You need to preserve raw events and files for several future analytical uses. Do: Define ownership, formats, metadata, partitions, permissions, and retention. Verify a consumer can discover, read, and reconcile a sample dataset. Avoid: A lake is not inherently schema-free or transaction-free; table formats and lakehouse systems can add transaction semantics.
- **data warehouse**: Integrate and model data for reliable analytical queries and reporting. Use when: Reporting needs consistent business definitions across several operational systems. Do: Define fact grain, dimensions, freshness, and reconciliation rules. Check one metric against source records and test late or corrected data. Avoid: A warehouse is not automatically current, correct, or cheaper; ingestion, modeling, and query costs still matter.
- **columnar storage**: Store values by column to suit selective analytical scans. Use when: A report scans a few columns across many rows. Do: Benchmark the report and the actual insert/update mix. Measure scanned bytes, compression, latency, and maintenance work. Compare a row-oriented path for point access. Avoid: Columnar storage is not universally faster. Fetching many columns of one row or frequent small updates can favor other layouts.
- **row-based storage**: Keep a row’s fields together for record-oriented access. Use when: Requests frequently fetch or update complete individual records. Do: Measure point reads, updates, and analytical scans on realistic rows. Inspect indexes and bytes read; consider a separate analytical layout when needed. Avoid: Rowstore can still support efficient analytics with suitable indexes or mixed layouts. Storage orientation alone does not define transaction guarantees.
- **time-series partitioning**: Partition timestamped records into explicit time intervals. Use when: Retention cleanup or bounded-time queries scan a growing events table. Do: Choose the timestamp, UTC boundaries, interval, and late-data policy. Check boundary routing, pruning, retention, and traffic concentrated in the current partition. Avoid: Partitioning by time does not automatically distribute current writes across machines or accelerate queries missing the time filter.
- **hash partitioning**: Use a hash of the partition key to assign records to buckets. Use when: Independent keys should spread across partitions without maintaining range boundaries. Do: Choose the key and mapping. Check distribution with real key frequencies, query fan-out, and the migration procedure for changing the layout. Avoid: Uniform hashing does not remove skew caused by one heavily used key. Table partitions are not necessarily separate server shards.
- **range partitioning**: Assign rows to partitions by ordered key intervals. Use when: Queries and retention operations target a bounded date or key range. Do: Define lower and upper bounds and a missing-partition policy. Test boundary values, pruning for actual queries, and distribution of current writes. Avoid: Partitioning does not replace useful indexes, and a range layout can create a hot partition.
- **consistent hashing**: Limit key reassignment when the set of storage nodes changes. Use when: Adding a cache or storage node should not remap nearly every key. Do: Compare key assignments before and after a node change. Measure moved keys, per-node load, and replica placement, and plan any state transfer. Avoid: Fewer moved keys does not mean zero migration, balanced hot-key traffic, or safe membership changes.
- **data migration**: Move or transform existing records with validation and a controlled cutover. Use when: An application must move from one database or data layout to another. Do: Define snapshot, change capture or write pause, mappings, reconciliation, cutover, and rollback. Check counts, sampled values, deletes, and critical invariants before routing traffic. Avoid: Matching row counts alone does not establish equivalent data. A rollback after new target-only writes needs a recovery strategy.
- **schema registry**: Version message schemas and enforce a chosen compatibility policy. Use when: Producers and consumers deploy separately and disagree on event fields. Do: Choose the format and backward, forward, or full compatibility policy. Test old/new producer-consumer combinations and retained messages with the actual serializers. Avoid: Compatibility rules depend on format and mode. A registry does not migrate existing records or prove semantic compatibility.

### performance

- **memoization**: Reuse a computed result while its inputs are unchanged. Use when: Profiling shows repeated expensive computation during rendering. Do: Measure the expensive operation first. Check both correctness after input changes and actual work avoided. Avoid: A cache with incomplete dependencies displays a stale result.
- **layout thrashing**: Alternating DOM reads and writes forces the browser to recalculate layout repeatedly. Use when: An interaction stalls while repeatedly measuring and resizing elements. Do: Measure the interaction, group compatible reads and writes, and recheck after content changes. Avoid: Caching geometry that becomes stale when the layout changes.
- **critical rendering path**: The critical rendering path is the work needed before the browser can render content. Use when: A page waits for unrelated resources before showing useful content. Do: Trace the initial load and remove or defer work that does not support the initial content. Avoid: Preloading everything and reducing the relative priority of important resources.
- **tail latency**: Tail latency describes the slow end of a response-time distribution. Use when: Average latency looks healthy while some users wait much longer. Do: Measure a representative distribution and trace the operations behind slow requests. Avoid: Reporting p99 from too few samples to support a useful estimate.
- **cold start**: A cold start includes initialization work before a new instance can serve its first operation. Use when: Initial requests are much slower than requests to an already-running instance. Do: Measure cold and warm paths separately and move only safe reusable initialization into the appropriate lifecycle. Avoid: Optimizing a warm benchmark and reporting it as cold-start improvement.
- **list virtualization**: Render a window of list items instead of every item at once. Use when: A long list spends too much time or memory rendering off-screen rows. Do: Measure the list, preserve stable identity, and test scrolling, focus, and variable content. Avoid: Recycling a row without resetting state that belongs to a different item.
- **memory leak**: A memory leak retains memory beyond its useful lifetime. Use when: Memory grows after repeatedly opening and closing a feature. Do: Reproduce the lifecycle repeatedly and compare retained objects or allocations. Avoid: Declaring a leak fixed because garbage collection temporarily lowered one sample.
- **lock contention**: Lock contention occurs when operations wait to acquire the same synchronization boundary. Use when: Many independent operations queue behind one protected section. Do: Measure hold and wait time, then reduce unnecessary shared work without losing the invariant. Avoid: Creating a per-key lock map that grows forever.
- **game loop**: A game loop coordinates repeated input, simulation, and rendering. Use when: Gameplay updates are spread across unrelated timers. Do: Choose the engine’s supported update phases and keep state changes separate from drawing. Avoid: Adding another timer that mutates the same simulation state outside its update phase.
- **delta time**: Delta time is elapsed time between updates. Use when: Movement speed changes when frame rate changes. Do: Express rates consistently and choose a bounded fixed or variable timestep strategy. Avoid: Allowing one unusually long timestep to cross obstacles or destabilize the simulation.
- **object pool**: An object pool reuses instances instead of creating a new one for each use. Use when: Profiling shows frequent allocations or expensive resource creation causing pauses. Do: Measure the allocation cost, define exhaustion behavior, and reset all reusable state. Avoid: Adding pooling where normal allocation was inexpensive and the extra retained memory is larger.
- **frame budget**: A frame budget allocates the time available for responsive rendering at a target cadence. Use when: An interaction drops frames during updates or rendering. Do: Trace representative frames and identify the work exceeding the chosen target. Avoid: Moving work off the main thread but waiting synchronously for its result each frame.

### security

- **authentication and authorization**: Authentication establishes identity; authorization decides whether that identity may perform an operation. Use when: Signed-in users can request records belonging to other users. Do: Derive identity from trusted authentication and check the requested action at the authoritative boundary. Avoid: Trusting an owner or role field supplied in the request body.
- **cross-site scripting**: Cross-site scripting lets untrusted content execute in another user’s browser. Use when: User-provided text or rich content is rendered on a page. Do: Keep text escaped; sanitize deliberately allowed markup and validate URL contexts. Avoid: Applying one hand-written escaping rule to HTML, attributes, URLs, and JavaScript.
- **cross-site request forgery**: Cross-site request forgery induces an authenticated browser to send an unwanted request. Use when: A browser automatically sends cookies to state-changing endpoints. Do: Use the framework’s CSRF protection and trusted-origin policy; verify state-changing requests from another origin. Avoid: Assuming CORS prevents every cross-origin request from being sent.
- **server-side request forgery**: Server-side request forgery causes a server to contact an unintended destination. Use when: A server downloads content from URLs supplied by users. Do: Constrain destinations and protocols, validate redirect targets, and enforce network-level egress restrictions where possible. Avoid: Checking only the submitted hostname while the eventual connection reaches another address.
- **insecure direct object reference**: An insecure direct object reference exposes an object without checking access to it. Use when: A request contains the ID of an object to read, edit, or delete. Do: Apply the resource authorization rule to every operation and test with two users. Avoid: Treating an unpredictable identifier as an access-control mechanism.
- **password hashing**: Store a salted password hash using a purpose-built password hashing function. Use when: A service must support password authentication. Do: Use the maintained authentication library’s password storage and upgrade path; keep raw passwords out of logs. Avoid: Replacing a password hash with reversible encryption as the primary storage mechanism.
- **OAuth and OpenID Connect**: OAuth delegates access to resources; OpenID Connect adds identity information for login. Use when: An application integrates a third-party account or delegated API access. Do: Use the provider-supported flow and maintained client; verify redirect, request binding, token validation, and expiry handling. Avoid: Treating an access token as proof of identity without the provider’s identity contract.
- **content security policy**: Content Security Policy restricts resources and execution in the browser. Use when: A site needs to limit script execution and external resource access. Do: Inventory required resources, use appropriate nonces or hashes, and test before enforcing the policy. Avoid: Mistaking report-only monitoring for an enforced policy.
- **CORS**: Cross-Origin Resource Sharing controls which cross-origin responses browser scripts may read. Use when: A browser frontend calls an API on another origin. Do: Allow only intended origins and credential behavior; test preflight and actual requests. Avoid: Testing only with a command-line client that does not enforce browser CORS.
- **threat model**: Identify assets, adversaries, entry points, and plausible failure paths. Use when: A new feature changes who can access valuable data or operations. Do: Describe the sensitive operation and the least-privileged caller who could misuse it. Avoid: Listing only anonymous attackers while ignoring another authenticated customer.
- **software supply-chain security**: Software supply-chain security addresses risks in dependencies, build inputs, and distribution. Use when: A patch adds a package, build plugin, or downloaded executable. Do: Verify the package identity, review installation behavior, and preserve reproducible dependency resolution. Avoid: Assuming a pinned version is necessarily safe because it is reproducible.
- **session cookie**: A session cookie carries a session credential in browser requests. Use when: A web application maintains a signed-in browser session. Do: Use appropriate Secure, HttpOnly, and SameSite settings; define expiry, rotation, and invalidation. Avoid: Believing HttpOnly prevents an injected script from acting through the victim’s session.
- **prompt injection**: Untrusted content attempts to redirect an AI system’s instructions or actions. Use when: An agent reads content supplied by another user, page, or external service. Do: Keep trusted instructions separate, constrain available actions, and require host-side permission checks. Avoid: Relying on one prompt sentence as the entire security boundary.

### testing

- **end-to-end test**: Check a user journey through the running application. Use when: Unit tests pass but users cannot finish a real workflow. Do: Choose one critical journey, use realistic data, and assert the user-visible outcome. State which external services are substituted. Avoid: Mocking the entire backend removes the integration the test claims to cover.
- **test isolation**: Each test controls its own state and can run independently. Use when: A test passes alone but fails in the full suite or in parallel. Do: Give each test independent state and cleanup. Run the affected tests alone, together, and in parallel. Avoid: A fresh browser still points at database records shared by every test. Worked example: https://vibe-coding-101.brighteng.org/examples/test-isolation.md
- **test fixture**: Reusable setup gives a test a known starting state and owns cleanup. Use when: Tests repeat setup or leave records behind after a failure. Do: Extract the repeated resource lifecycle. Pick its scope deliberately and ensure teardown runs after failures. Avoid: A suite-wide fixture shares mutable state that should belong to one test.
- **auto-waiting**: Wait for an observable condition instead of a fixed delay. Use when: A browser test needs sleeps to pass on slower machines. Do: Replace fixed sleeps with locators and assertions for the state that makes the next step valid. Avoid: A visible button is not proof that the preceding save has completed.
- **semantic locator**: Find an element by its role, label, or other user-facing meaning. Use when: A small markup change breaks many browser tests. Do: Use role and accessible name first, scope to the relevant region, and require an unambiguous match. Avoid: Using the first match hides ambiguous or duplicated controls.
- **test double**: A controlled substitute makes a dependency predictable in a test. Use when: You need to exercise a timeout or rejection that is hard to trigger reliably. Do: Substitute the smallest boundary needed for the scenario. Keep separate coverage of the real integration. Avoid: The substitute returns a response the real service would never produce. Worked example: https://vibe-coding-101.brighteng.org/examples/test-double.md
- **visual regression test**: Compare rendered output with an intentionally reviewed baseline. Use when: Behavioral tests pass while spacing, clipping, or typography breaks. Do: Fix viewport, fonts, and data; capture important states; inspect differences before accepting a new baseline. Avoid: Automatically accepting new snapshots turns regressions into expected output.
- **static analysis**: Static analysis inspects code without exercising the application. Use when: A generated patch contains type errors or suspicious patterns. Do: Run the relevant analyzer, understand its diagnostic, and check the affected behavior after fixing it. Avoid: Treating a clean analyzer result as proof that the application works.
- **snapshot test**: Compare serialized output with a reviewed expected snapshot. Use when: Stable structured output is easier to review as a whole than through many individual assertions. Do: Keep snapshots focused and deterministic; pair them with assertions for essential behavior. Avoid: Updating every baseline to make a failing suite green.
- **property-based testing**: Generate inputs to test a general property rather than only handpicked examples. Use when: A parser or transformation has many combinations and boundary cases. Do: Define a useful invariant, generate representative inputs, and keep discovered regressions. Avoid: Choosing a property so weak that a broken implementation satisfies it.
- **flaky test**: A test produces inconsistent outcomes without an intentional relevant change. Use when: A check intermittently fails under the same expected conditions. Do: Capture the failure conditions, control suspected inputs, and verify the underlying cause before changing expectations. Avoid: Deleting the assertion or increasing retries while leaving the cause unexplained.
- **network panel**: The browser network panel shows requests and responses made by the page. Use when: Clicking Save appears to do nothing and the failing boundary is unknown. Do: Reproduce the action and inspect the relevant request, status, timing, and safely redacted data. Avoid: Filtering out fetch requests and concluding that the page sent nothing.

### concurrency

- **structured concurrency**: Child tasks finish within the lifetime of their enclosing operation. Use when: Background work survives the screen or request that started it. Do: Use scoped child tasks for related work. Define failure behavior and verify that cancellation reaches the children. Avoid: An unstructured task created inside a function is assumed to share its lifetime.
- **cooperative cancellation**: Work must observe cancellation and stop safely. Use when: An old search or upload keeps running after the user leaves. Do: Propagate cancellation, check it between work units, and prevent obsolete completions from updating current state. Avoid: A catch-all handler swallows cancellation and continues the operation. Worked example: https://vibe-coding-101.brighteng.org/examples/cancellation.md
- **actor isolation**: An actor protects its mutable state through an isolation boundary. Use when: Concurrent Swift tasks read and write the same mutable object. Do: Give the state one isolation owner and expose operations through it. Check assumptions across suspension points. Avoid: Assuming actor isolation makes a multi-step operation atomic across await.
- **actor reentrancy**: Other work can change actor state while an operation is suspended. Use when: An actor checks a condition, awaits a request, then acts on a stale assumption. Do: Recheck assumptions after await or reserve the operation before suspending. Test overlapping calls deliberately. Avoid: The test runs calls sequentially and never exercises the suspension window.
- **debounce**: Wait for a quiet interval before acting on repeated input. Use when: A search field sends a request on every keystroke. Do: Replace the pending action on new input. Handle cancellation and obsolete responses separately from the delay. Avoid: Debouncing input is treated as protection against out-of-order responses. Worked example: https://vibe-coding-101.brighteng.org/examples/debounce.md
- **backpressure**: Let consumer capacity constrain how fast producers send work. Use when: An event queue grows faster than the application can process it. Do: Select a bounded buffer and decide whether producers wait, reject, or drop specified work when it is full. Avoid: Dropping events silently when every event is required.
- **race condition**: An outcome depends on the timing of concurrent operations. Use when: Two overlapping operations can update the same state. Do: Identify the shared invariant and exercise competing operations with controlled ordering. Avoid: Fixing the visible order while leaving the underlying write unprotected. Worked example: https://vibe-coding-101.brighteng.org/examples/race-condition.md
- **event loop**: An event loop schedules work and callbacks around the runtime’s execution model. Use when: One expensive request freezes unrelated interactions or requests. Do: Profile the blocking segment and move or divide it according to the workload. Avoid: Replacing synchronous syntax with async syntax while keeping the same blocking computation.
- **mutex**: A mutex provides mutually exclusive access to a protected critical section. Use when: Concurrent operations must update shared memory without interleaving. Do: Choose the appropriate synchronization primitive and release it on every path. Avoid: Assuming an in-process mutex coordinates independent servers.
- **async vs parallel**: Asynchronous work can yield while waiting; parallel work executes simultaneously. Use when: I/O waits and CPU work need different execution strategies. Do: Classify the workload and choose bounded overlap or worker execution as appropriate. Avoid: Starting an unbounded task for every item and exhausting a downstream resource.
- **thread pool**: A thread pool reuses worker threads to execute submitted work. Use when: Blocking or CPU-heavy work must run without unbounded thread creation. Do: Size workers for the workload and dependencies, then define overload behavior. Avoid: Blocking pool workers on tasks that need the same exhausted pool to finish.
- **atomic operation**: An atomic operation takes effect indivisibly with respect to the relevant observers. Use when: Concurrent read-modify-write operations lose updates. Do: Choose the atomic primitive or database operation that protects the complete required update. Avoid: Assuming atomicity also supplies every required memory-ordering or transaction-isolation guarantee.
- **goroutine**: A goroutine is a lightweight unit of concurrent execution in Go. Use when: Go background work survives its request or becomes stuck on a channel. Do: Define who starts, stops, and waits for the goroutine, including blocked sends and receives. Avoid: Checking cancellation only after a channel operation that can block forever.
- **quorum**: Require a defined set of replicas or voters before accepting an operation. Use when: An operation must continue after some nodes fail without accepting conflicting decisions. Do: State membership, read/write counts, version rules, and failure assumptions. Check quorum loss and overlapping operations; distinguish acknowledgement counts from consensus. Avoid: A majority is common, but not every quorum is a majority and intersection alone is not consensus.
- **consensus**: Make participating nodes agree on decisions despite specified failures. Use when: Nodes must agree on a leader or committed log instead of inventing competing histories. Do: Use a proven implementation. Define crash versus Byzantine assumptions, membership changes, and commit rules. Check leader loss, partitions, and rejoining nodes. Avoid: Safety and progress are different properties. A safe system can stop accepting writes when it cannot decide.
- **CAP theorem**: During a network partition, atomic consistency and availability cannot both be guaranteed. Use when: You must decide what isolated replicas do when they cannot communicate. Do: Describe one partitioned read/write scenario. Choose whether to reject or delay an operation or allow potentially divergent results. Test that policy. Avoid: CAP availability differs from a monthly uptime percentage. ACID consistency means something else again.
- **snapshot isolation**: Read a stable transaction snapshot while detecting conflicting writes. Use when: A multi-query report mixes values from different committed moments. Do: Check the database’s snapshot boundary and conflict behavior. Test a stable report and a two-writer invariant. Use serializable execution or explicit coordination when required. Avoid: Isolation names vary by product. PostgreSQL Repeatable Read uses snapshot isolation, with stronger phantom protection than the SQL minimum.
- **MVCC**: Keep multiple row versions so reads can use a consistent snapshot. Use when: Readers and writers need concurrency without ordinary reads waiting on every write. Do: Document snapshot visibility and version cleanup. Check concurrent reads and writes, long-running transactions, and retained-version growth. Avoid: Explicit locks still exist; old snapshots can delay cleanup and increase storage use.
- **two-phase commit (2PC)**: Coordinate prepare and commit decisions across transaction participants. Use when: One transaction must commit or abort across multiple supporting resource managers. Do: Verify native participant support and a durable coordinator. Check crash recovery with a prepared participant and confirm unresolved transactions are monitored and resolved. Avoid: A coordinator failure can leave participants blocked. Arbitrary HTTP services are not automatically 2PC participants.
- **three-phase commit (3PC)**: Add a pre-commit phase to reduce blocking under restricted failure assumptions. Use when: You are comparing atomic commit protocols and their failure models. Do: Compare protocol states and assumptions using the cited recovery model. Analyze coordinator failure and a partition separately before selecting a supported implementation. Avoid: Classic 3PC does not make arbitrary partitions safe simply by adding timeouts. It is not a substitute for proven consensus-based coordination.
- **lock escalation**: Replace many fine-grained locks with a coarser lock in engines that support it. Use when: A large SQL Server update unexpectedly blocks unrelated rows in the same table. Do: Capture the lock-escalation event and blocking chain. Reduce the scan or batch size where appropriate, then verify lock footprint and transaction semantics. Avoid: A table lock can have other causes. Batching changes atomicity; do not split an all-or-nothing operation casually.
- **pessimistic locking**: Lock the protected rows before making a competing update. Use when: Several workers try to claim the same job or modify the same inventory row. Do: Keep read, decision, and write inside one transaction. Lock the necessary rows in consistent order. Test two competing sessions and lock timeouts. Avoid: Locking existing rows does not automatically protect every predicate or a missing row; constraints or stronger isolation may be needed.
- **dirty read**: Read a value another transaction has written but not committed. Use when: A report might include an update that is later rolled back. Do: Use two sessions: pause an uncommitted update, read from the other session, then roll back. Verify the behavior under the actual engine and isolation level. Avoid: Dirty reads differ from stale committed reads on a replica and from read skew across separate committed moments.
- **phantom read**: Repeat a predicate query and observe a changed set of matching rows. Use when: Two counts inside one transaction disagree after another transaction inserts a matching row. Do: Coordinate two sessions around the predicate read and competing insert. Check the chosen isolation level, then protect the invariant with constraints or appropriate transaction coordination. Avoid: An empty result locks no ordinary rows. Preventing phantoms alone does not establish serializability.
- **read skew**: Read related facts from different committed moments and combine an inconsistent view. Use when: A report reads an account before a transfer and the other account after it. Do: Interleave a transfer between the report’s two reads. Use a suitable transaction snapshot or one consistent query, then verify the reported invariant. Avoid: Read skew does not require a dirty read. Stable reads still do not prevent write skew in other transactions.
- **write skew**: Concurrent decisions update different rows and jointly violate an invariant. Use when: Two on-call doctors each see the other available and both go off duty. Do: Synchronize two decisions in a test. Use serializable execution with retries, a suitable constraint, or a shared lock boundary. Verify the invariant survives both attempted changes. Avoid: No lost update on a single row does not mean the transaction set is serializable.
- **throttling**: Bound how often work runs while events continue arriving. Use when: Continuous scroll events trigger expensive work faster than the UI needs it. Do: Choose leading and trailing behavior and a maximum rate. Check continuous events, the final value, and teardown using a controlled clock. Avoid: A client-side throttle does not enforce a server quota. Dropping intermediate work is unsafe when every event must be processed.

### native apps

- **offline-first**: Design a useful local workflow that tolerates missing connectivity. Use when: Users need to keep reading or editing while disconnected. Do: Persist local intent, show pending state, and reconcile with the authoritative service when available. Avoid: Calling local data universally authoritative when the server must still enforce access or business rules.
- **deep link**: A deep link addresses a particular location or action in an application. Use when: A shared link should open a specific record or screen. Do: Parse and validate the target, preserve it across sign-in, and test app lifecycle states. Avoid: Using a link’s parameters as trusted commands or access permission.
- **safe area**: Safe-area insets describe regions where important content can remain unobscured by system UI or display features. Use when: Controls overlap the home indicator, cutout, or system bars. Do: Use the platform’s current inset information at the appropriate layout boundary. Avoid: Padding every nested container and creating unnecessary empty space.
- **navigation stack**: A navigation stack records a sequence of destinations. Use when: A multi-screen workflow loses its place when navigating back. Do: Model destinations and state ownership explicitly, including tab and modal boundaries. Avoid: Resetting navigation state on an unrelated view update.
- **push notification**: A push notification delivers an external event through a platform notification service. Use when: An app must notify users when it is not actively displaying the relevant screen. Do: Handle token changes, permission states, and payload validation; test notification entry paths. Avoid: Treating one device token as a permanent user identifier.
- **app lifecycle**: Applications move between active, inactive, background, and terminated states according to their platform. Use when: Returning to an app loses a draft or leaves stale work running. Do: Persist important intent promptly and define resume reconciliation without resetting unrelated UI state. Avoid: Depending on a final shutdown callback to save the only copy of user data.
- **OS permission**: Operating-system permissions mediate access to protected capabilities. Use when: A feature needs camera, location, files, or another protected resource. Do: Ask in context, explain the feature need, and provide usable denied and restricted states. Avoid: Looping the request when the OS will no longer show another prompt.
- **OTA update**: An over-the-air update replaces supported application assets or code without a full binary install. Use when: A deployed mobile app needs a compatible code or asset update. Do: Identify compatible runtimes and use a staged update with a recovery path. Avoid: Treating every source change as eligible for an OTA release.
- **main process vs renderer**: Desktop shells such as Electron separate privileged application work from the renderer. Use when: A desktop UI needs filesystem or operating-system access. Do: Keep privileged operations behind narrow validated messages and trusted process boundaries. Avoid: Exposing the entire filesystem or shell API through a convenience bridge.
- **IPC**: Inter-process communication exchanges data or requests between processes. Use when: A renderer or worker must request work from another process. Do: Expose specific operations, validate inputs at the receiving side, and preserve structured errors. Avoid: Assuming messages are trusted because both processes are part of the same application.
- **context isolation**: Electron context isolation separates the page’s JavaScript environment from privileged preload code. Use when: An Electron renderer needs a small amount of privileged integration. Do: Keep isolation enabled and expose only specific validated operations through the supported bridge. Avoid: Assuming context isolation alone supplies every sandbox or authorization property.
- **single instance**: Single-instance behavior routes subsequent launches to an existing application instance. Use when: Launching an app twice starts competing windows or local services. Do: Acquire the instance boundary early and handle subsequent activation messages explicitly. Avoid: Focusing the old window but discarding the new launch payload.
- **code signing**: Code signing binds an artifact to a signing identity and detects covered modifications. Use when: A native release must establish its publisher and artifact integrity. Do: Use the target platform’s release signing workflow and verify the final packaged artifact on that platform. Avoid: Checking a locally signed build while distributing a different unsigned package.
- **desktop auto-update**: Desktop auto-update retrieves and installs a new application release through a defined trust and lifecycle process. Use when: A shipped desktop app must update safely on user machines. Do: Use the framework’s supported updater and verify authenticity, failure handling, and user-data compatibility. Avoid: Letting untrusted renderer content choose the update source.
- **app sandbox**: An application sandbox restricts access to system resources. Use when: A native app needs protected resources without unrestricted system access. Do: Identify the smallest required access and test real signed builds with allowed and denied operations. Avoid: Assuming a remembered path always retains the operating system’s access grant.
- **webview**: A WebView embeds web content in a native application. Use when: A native app displays remote content alongside privileged local features. Do: Separate trusted application content from remote content and validate navigation and message origins. Avoid: Disabling web security to fix a request without understanding the boundary removed.
- **secure storage**: Use the platform’s protected storage for suitable credentials or keys. Use when: An application must retain a credential between launches. Do: Choose the protected storage API and lifecycle policy, then test access and deletion. Avoid: Keeping a second plaintext copy in preferences, diagnostics, or a migration file.
- **app link**: A verified app link associates an HTTPS domain with an application through platform verification. Use when: Shared web URLs should open an installed app when the platform permits. Do: Configure the association and test platform verification, installed and uninstalled behavior, and cold start. Avoid: Testing only an in-app URL handler while the OS association file is unreachable.
- **background execution**: Background execution uses the operating system’s supported scheduling or execution model. Use when: Work needs to resume or complete despite application suspension. Do: Choose the platform mechanism and checkpoint work so it tolerates interruption. Avoid: Assuming a background scheduling request guarantees an exact start time.
- **adaptive layout**: An adaptive layout responds to available space and presentation context. Use when: A phone layout becomes unusable in a tablet pane or resized window. Do: Use current layout constraints and test transitions between narrow and wide presentations. Avoid: Measuring size once at launch and treating it as permanent.
- **in-app purchase**: In-app purchases exchange a store transaction for a defined entitlement. Use when: An application unlocks paid content or a subscription. Do: Follow the store’s supported verification path and handle restore, renewal, expiry, and revocation. Avoid: Granting permanent access from an unverified local premium flag.
- **build variant**: A build variant selects a deliberate combination of configuration and packaging. Use when: Testing must use different services or identity without changing the production app. Do: Define variant-specific identity, configuration, and signing, then inspect the produced artifacts. Avoid: Assuming different display names alone create separate installed applications.
- **dynamic type**: Dynamic Type adapts text to the user’s preferred size on Apple platforms. Use when: A native screen clips text at accessibility sizes. Do: Use supported text styles and flexible layout, then test the largest relevant sizes. Avoid: Disabling font scaling to preserve a screenshot’s original layout.
- **biometric authentication**: Biometric authentication can authorize a local operation through the operating system. Use when: A sensitive local action needs device-user verification. Do: Use the platform authentication and key-access policy with explicit fallback and invalidation behavior. Avoid: Showing a biometric prompt while the protected key remains accessible without it.
- **sync conflict**: A synchronization conflict occurs when changes cannot be combined safely under the chosen policy. Use when: Two offline or concurrent editors change the same record. Do: Track versions or the required causal information and choose merge, rejection, or user resolution. Avoid: Showing a conflict message after one version has already been discarded.

### delivery and operations

- **continuous integration**: Run repeatable checks when code changes are integrated. Use when: Changes pass locally but break the shared branch. Do: Use a clean install, required checks, and retained failure artifacts. Confirm the checks run on the actual proposed revision. Avoid: A successful check belongs to an older revision of the change.
- **request-scoped state**: Keep user-specific mutable state within the request that owns it. Use when: A warm server process reuses variables across different users. Do: Pass request context explicitly. Share only safe reusable resources, and test interleaved requests for different users. Avoid: A shared cache key omits the user or tenant even after globals are removed.
- **streaming**: Process or forward data incrementally as it arrives. Use when: A download buffers the entire response before sending any bytes. Do: Keep the path incremental, respect backpressure, and test cancellation and errors after output has begun. Avoid: A later transformation reads the whole stream into a string.
- **idempotency**: Repeating an operation has the same intended effect as doing it once. Use when: A retried request or duplicate message repeats a side effect. Do: Choose a stable operation key and durable duplicate handling. Coordinate the recorded result with the side effect; use provider support for external effects. Avoid: Recording completion separately from the side effect leaves a crash window. Worked example: https://vibe-coding-101.brighteng.org/examples/idempotency.md
- **secret management**: Supply credentials through an appropriate secret store or runtime configuration. Use when: An integration needs a credential in development and deployment. Do: Document variable names, inject values at runtime, and inspect release output for accidental exposure. Avoid: Rotating the environment value while an older leaked credential remains valid.
- **feature flag**: A switch controls whether a behavior is enabled. Use when: A new behavior needs a staged rollout or a quick way to disable it. Do: Define the flag’s scope, default, owner, and removal condition; exercise both branches. Avoid: Treating a rollout switch as an authorization check.
- **rollback**: Return to an earlier working release or state after a failed change. Use when: A deployment needs a tested recovery path. Do: Identify a known working artifact and verify its compatibility with the state left by the new release. Avoid: Claiming a destructive data rewrite can be undone by redeploying old code.
- **load balancer**: A load balancer routes requests among service instances. Use when: A service runs on multiple instances that must share traffic safely. Do: Define readiness and state ownership, then test routing when an instance fails. Avoid: Sending traffic to a process that has started but is not ready.
- **horizontal scaling**: Increase capacity by running more service instances. Use when: One instance cannot handle the measured workload. Do: Find the bottleneck and account for shared resources before adding replicas. Avoid: Adding instances while a shared database, hot key, or serialized operation remains the bottleneck.
- **CDN**: A content delivery network serves content through distributed edge locations. Use when: Public assets or pages need lower latency for geographically distributed users. Do: Classify public and private responses and test cache keys, freshness, and invalidation. Avoid: Caching authenticated content under a key that omits its authorization context.
- **read replica**: A read replica serves a copy of database data. Use when: Read-heavy work competes with writes on the primary database. Do: Classify reads by consistency requirements and observe replication lag. Avoid: Sending a read-after-write to a lagging replica and treating missing data as a failed write. Replicas do not replace backups.
- **eventual consistency**: Replicas or projections converge when updates stop and propagation succeeds. Use when: A view updates asynchronously after the authoritative write. Do: Define which views may lag, how pending work appears, and how failed propagation is detected. Avoid: Calling permanently missing updates eventual consistency.
- **saga**: A saga coordinates a multi-step operation through local commits and explicit recovery actions. Use when: A business operation spans systems that cannot share one transaction. Do: Persist progress and define retries, compensation, and manual recovery for each step. Avoid: Assuming every external effect has an exact inverse.
- **transactional outbox**: A transactional outbox records an event alongside the business change in one database transaction. Use when: A database write and event publication must not drift apart. Do: Commit the business record and outbox record together, then publish with retry and duplicate handling. Avoid: Deleting the outbox record before publication has been safely acknowledged.
- **cache stampede**: Many callers rebuild the same missing or expired cache entry at once. Use when: A popular key’s expiration causes a burst of expensive work. Do: Choose refresh coordination and a bounded wait or stale-response policy. Avoid: Using an in-process lock while every instance independently rebuilds the same value.
- **dead-letter queue**: A dead-letter destination retains work that exhausted normal processing or retry policy. Use when: Repeatedly failing jobs block progress or disappear from view. Do: Keep the error context and stable identity; define ownership, retention, and replay behavior. Avoid: Collecting failed jobs without a way to inspect or recover them.
- **liveness and readiness**: Liveness asks whether a process should be restarted; readiness asks whether it should receive work. Use when: Deployments send traffic too soon or restart healthy processes during dependency failures. Do: Define separate probes and test startup, dependency loss, and recovery. Avoid: A probe depends on the same congested path whose health it should diagnose.
- **canary deploy**: A canary release exposes a new version to a limited portion of traffic first. Use when: A release needs production evidence before a full rollout. Do: Choose representative traffic and measurable failure thresholds while keeping versions compatible. Avoid: Comparing unequal workloads and calling the difference a release regression.
- **failover**: Failover transfers responsibility from an unavailable component to another. Use when: A primary service or datastore has a standby that must take over. Do: Use the platform’s supported mechanism and rehearse its failure and recovery boundaries. Avoid: Promoting a new writer while an old writer still accepts conflicting work.
- **pub/sub**: Publish/subscribe distributes events to interested subscribers. Use when: Several independent consumers need to react to the same event. Do: Define which consumers require durable delivery and how they handle repeated events. Avoid: Assuming pub/sub or a work queue guarantees exactly-once side effects.
- **timeout budget**: An operation’s total deadline must account for downstream calls, retries, and cleanup. Use when: A user-facing request takes far longer than its intended maximum. Do: Propagate a remaining deadline and define safe cancellation and retry behavior. Avoid: Retrying a timed-out write without knowing whether its side effect already happened.
- **graceful degradation**: Keep essential behavior useful when an optional dependency or capability is unavailable. Use when: An optional widget failure takes down an otherwise useful page. Do: Separate essential dependencies from optional ones and test the declared fallback. Avoid: Replacing a failed dependency with a more expensive fallback that overloads the system.
- **backend for frontend**: A backend for frontend adapts backend capabilities to a client’s needs. Use when: A client assembles one screen from many internal service calls. Do: Define a screen-oriented response and keep shared rules in their authoritative location. Avoid: Copying pricing or access rules into a client-specific layer.
- **infrastructure as code**: Infrastructure as code describes infrastructure in reviewable files. Use when: Environments depend on undocumented manual configuration. Do: Inspect the plan, protect state, and verify how existing resources are adopted. Avoid: Applying a replacement plan without accounting for the resource’s stored data.
- **container**: A container runs a process with a packaged filesystem and configured isolation. Use when: A service starts differently across development and deployment environments. Do: Build a reproducible image and test startup, shutdown, configuration, and persistent storage explicitly. Avoid: Assuming a container alone supplies durable storage or a complete security boundary.
- **multi-tenancy**: A multi-tenant application serves distinct customers through shared infrastructure. Use when: Several customer organizations share the same application. Do: Derive tenant context from trusted membership and trace it through every shared resource. Avoid: Accepting a tenant ID without checking the caller’s membership.
- **object storage**: Object storage stores data as objects addressed by keys. Use when: Uploaded files must outlive an application instance. Do: Choose ownership and access policy, index object references, and handle incomplete uploads and deletion. Avoid: Assuming an unguessable object key provides authorization.
- **blue-green deploy**: Blue-green deployment keeps old and new environments available during a traffic switch. Use when: A release needs a quick traffic switch with an available previous version. Do: Verify the new environment before switching and test the route back with shared state. Avoid: Calling a traffic switch a rollback when the previous application can no longer read the database.
- **configuration drift**: Configuration drift is a difference between intended and running configuration. Use when: An environment behaves differently despite using the expected application build. Do: Compare authoritative configuration with observed state and explain each meaningful difference. Avoid: Automatically overwriting an emergency change without understanding why it exists.
- **TLS**: TLS protects communication and authenticates peers according to the configured trust model. Use when: An application connects to a service over an untrusted network. Do: Use supported TLS clients and inspect the entire path, including proxies and trust configuration. Avoid: Assuming an encrypted connection is authentic when certificate validation is bypassed.
- **HTTP caching**: HTTP caching controls when clients and intermediaries can reuse a response. Use when: A response is unexpectedly stale or reused for the wrong user. Do: Classify responses, define validation and variants, and test the actual browser or shared cache. Avoid: Reading no-cache as a prohibition on storage; it requires validation before reuse.
- **reverse proxy**: A reverse proxy accepts client traffic and forwards it to application services. Use when: An application sits behind a gateway that handles TLS, routing, or limits. Do: Define trusted proxies and align path, timeout, body-size, and scheme handling. Avoid: Trusting client-supplied forwarding headers from connections that bypass the proxy.
- **port mapping**: Port mapping publishes a service port through another network boundary. Use when: A container runs but the browser cannot reach its service. Do: Trace the listener, published port, bind address, and each caller’s network context. Avoid: Publishing the wrong internal port or unintentionally binding a private service publicly.
- **bind mount vs volume**: A bind mount exposes a host path to a container; a managed volume has a separate storage lifecycle. Use when: Container replacement loses a database or development edits are not visible. Do: Choose the appropriate mount for source and data, then test replacement and cleanup. Avoid: Calling a mounted directory durable without checking its actual host lifecycle.
- **preview deployment**: A preview deployment exposes a particular proposed revision for review. Use when: Reviewers need to exercise a change outside the developer’s machine. Do: Identify the built revision and verify the environment before testing the feature. Avoid: Testing the wrong revision because the preview address points at an older artifact.
- **build ID**: A build ID identifies the artifact running in an environment. Use when: A fix is deployed but users may still be running an older release. Do: Embed a stable build identity and expose it through an appropriate diagnostic surface. Avoid: Using request time as a build ID so every response appears to be a new version.
- **database clustering**: Coordinate database nodes with explicit storage, replication, and routing roles. Use when: A single database node cannot meet your availability or capacity target. Do: Draw the node roles and failure domains. Define write routing, replication, and failover. Check a node-loss drill and verify acknowledged writes. Avoid: A cluster is not automatically highly available, strongly consistent, or faster for every workload.
- **rebalancing**: Move existing partitions or replicas to improve their placement. Use when: A newly added shard is idle while older shards carry most data. Do: Inspect bytes, traffic, and replica constraints per node. Move data gradually, then verify placement and request latency. Distinguish balancing bytes from balancing hot keys. Avoid: Moving an indivisible hot key to another node can merely move the bottleneck.
- **resharding**: Change the shard layout or assignment used to distribute data. Use when: The existing shard key or partition layout cannot spread the workload. Do: Plan copy, change capture, routing transition, and rollback. Check row reconciliation, writes during migration, and queries using the old key. Avoid: Online resharding still needs resources and can block writes briefly; product behavior and limits vary.
- **split-brain**: Competing nodes act as the same write authority after losing coordination. Use when: An old primary resumes writes after a standby has been promoted. Do: Use the platform’s election and fencing mechanisms. In a disposable drill, isolate the primary and verify the old authority cannot write after promotion. Avoid: A timeout shows that a node is unreachable, not that it is dead. Deliberate multi-leader replication has a different conflict contract.
- **high availability (HA)**: Keep the service usable through specified failures and recovery procedures. Use when: A single machine or zone failure must not exceed the service’s outage budget. Do: Define the availability objective and failure domains. Drill node and zone loss. Measure successful user operations and recovery duration, then restore redundancy. Avoid: An HA setup is not a backup strategy or a promise of zero downtime and zero data loss.
- **vertical scaling**: Give one instance more CPU, memory, or I/O capacity. Use when: One database instance is constrained by a measured resource bottleneck. Do: Identify the constrained resource, compare a larger instance under the same workload, and check resizing downtime, cost, and remaining headroom. Avoid: More CPU does not repair a serialized critical section, missing index, or remote dependency bottleneck.
- **geo-replication**: Replicate data across geographic regions with an explicit consistency policy. Use when: A regional outage or distant users require copies beyond one region. Do: Choose regions and consistency mode. Measure cross-region writes and lag, then drill regional loss and reconnection. Verify data residency requirements separately. Avoid: A remote copy is not proof of zero data loss, local write latency, or residency compliance.

### web interface

- **URL state**: Put shareable navigation state in the URL. Use when: Reloading or sharing a filtered page loses the selected view. Do: Define supported parameters and defaults. Check reload, shared links, and browser back navigation. Avoid: Private or sensitive values are exposed in URLs and history.
- **reduced motion**: Respect the user’s preference for less interface animation. Use when: A transition uses large motion or persistent animation. Do: Offer a restrained alternative while preserving state changes and feedback. Test with the preference enabled. Avoid: Removing an animation also removes the only indication that an action completed.
- **layout shift**: Visible content moves unexpectedly as the page loads or updates. Use when: Text or buttons jump when images, fonts, or embeds arrive. Do: Trace the moving elements, reserve appropriate space, and compare before and after under delayed loading. Avoid: A fixed placeholder height clips content on a smaller viewport.
- **accessibility**: Accessibility makes an interface usable by people with varied abilities and assistive tools. Use when: A feature works with a mouse but is difficult to use otherwise. Do: Use semantic controls and verify the complete task with keyboard and assistive technology. Avoid: Passing an automated scan while the main workflow remains unusable by keyboard.
- **empty state**: An empty state explains why expected content is absent and what action is available. Use when: A list appears blank and users cannot tell what happened. Do: Model the relevant states separately and keep the next useful action clear. Avoid: Displaying no records as if a failed request completed successfully.
- **progressive disclosure**: Reveal secondary choices when they become relevant. Use when: A form overwhelms users with rarely used options. Do: Separate required choices from optional detail and test the basic path without opening every section. Avoid: Hiding a required decision until after submission fails.
- **destructive action**: A destructive action removes or invalidates user value. Use when: A delete or revoke action can affect the wrong object or cannot be reversed. Do: Name the affected object and distinguish reversible actions from irreversible ones. Avoid: Showing an undo option when the underlying state cannot actually be restored.
- **undo**: Undo reverses a supported action according to a defined history and lifetime. Use when: A user needs to recover from an accidental reversible edit. Do: Define which actions are reversible and test recovery across the supported lifecycle. Avoid: Overwriting the only undo record when a second action happens.
- **skeleton screen**: A skeleton screen reserves the shape of content while it loads. Use when: A loading region appears blank or shifts substantially when content arrives. Do: Match the content’s layout and test slow, empty, and failed loads. Avoid: Animating an indefinite placeholder after the request has already failed.
- **error copy**: Error copy explains a failure in terms useful to the user. Use when: Users receive raw exceptions or the same message for unrelated failures. Do: Map known failures to actionable messages and keep diagnostic detail in the appropriate logs. Avoid: Offering retry for an operation that will repeat a successful side effect.
- **design tokens**: Design tokens name reusable visual decisions such as spacing and colors. Use when: The same visual role has many slightly different hardcoded values. Do: Define a small semantic set and replace the values for the targeted components. Avoid: Creating tokens but continuing to use raw values at the call sites.
- **split pane**: A split pane divides a workspace with an adjustable separator. Use when: Users need to resize a sidebar and primary work area. Do: Define size constraints, keyboard behavior, and narrow-window fallback. Avoid: Allowing a pane to collapse until its recovery control is unreachable.