Skip to main content

Artifact Templates

These templates are intentionally compact. Expand them only when the added detail changes a decision or avoids a real implementation mistake.

ADR Template​

# ADR-00X: <Decision title>

## Status
Proposed | Accepted | Superseded

## Context
- What problem exists?
- What constraints matter?
- What change pressure is driving the decision?

## Options Considered
1. Option A
2. Option B
3. Option C

## Decision
What was chosen and why now?

## Trade-offs
- Cost we are accepting
- Risk we are accepting
- What becomes easier
- What becomes harder

## Consequences
- Immediate implications
- Migration implications
- Signals that would tell us to revisit this

RFC Template​

# RFC: <Change title>

## Problem
What is broken, slow, risky, or constrained?

## Proposal
Describe the new direction at system level.

## Non-Goals
What this RFC does not try to solve.

## Affected Surfaces
- Routes
- APIs
- Modules
- Teams
- Release process

## Alternatives
What else was considered and why it is not preferred.

## Risks
- Runtime risk
- Migration risk
- Organizational risk

## Rollout
- Adoption path
- Backward-compatibility policy
- Success metrics

Performance Budget Template​

# Frontend Performance Budget

## Route / Surface
- Name:
- Audience:
- Device/network profile:

## Budgets
- LCP:
- INP:
- CLS:
- Initial JS:
- Hydration time:

## Enforcement
- CI check:
- Production monitoring:
- Owner:

## Exception Process
- Who approves a temporary exception?
- When does it expire?

Migration Plan Template​

# Migration Plan: <Capability or surface>

## Current State
- What exists today?
- What pain does it create?

## Target State
- What boundary or behavior should exist after migration?

## Phases
1. Stabilize current usage
2. Introduce new path
3. Migrate consumers
4. Remove legacy path

## Safety Checks
- Compatibility checks
- Observability checkpoints
- Rollback criteria

## Owners
- Primary owner
- Supporting teams

Deprecation Checklist​

  • Name the deprecated artifact clearly.
  • Publish the replacement path.
  • Mark the compatibility window.
  • Add tooling warnings where possible.
  • Track remaining consumers.
  • Remove only after the communicated deadline or explicit migration completion.

Integrity Note for Public Artifacts​

When publishing architecture artifacts externally, label them honestly:

  • Real, sanitized: based on shipped work with private details removed
  • Composite: combines several real experiences into one teaching example
  • Illustrative: invented example used to explain a pattern

Credibility improves when the reader can tell which kind of artifact they are looking at.

Review prompts​

  • Does the artifact name the decision, owner, and review date?
  • Does it separate facts, assumptions, tradeoffs, and open risks?
  • Does it include a verification signal rather than only intent?
  • Does it define what changes after the artifact is approved?
  • Does it avoid exposing private customer, employee, or vendor details?

Source lens​

Use these templates with Part XII completed examples, review packets, and capstone solution packs. The templates are intentionally generic; the completed artifacts show the expected level of specificity.