Rayk Lucid Toolkit Create Adr

Examples: adr-001-use-protocol-buffers.md adr-002-adopt-event-sourcing.md adr-003-schema-org-boundaries.md

Numbers are sequential and never reused. Superseded ADRs keep their number.
</naming_convention>

<template>
```markdown
# ADR-NNN: {Title}

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Deciders**: [list of people involved]
**Technical Story**: [ticket/issue reference if applicable]

## Context and Problem Statement

[Describe the context and problem. What forces are at play? Why is this decision needed now?]

## Decision Drivers

* [Driver 1: e.g., Performance requirements]
* [Driver 2: e.g., Team expertise]
* [Driver 3: e.g., Maintenance burden]

## Considered Options

1. [Option 1]
2. [Option 2]
3. [Option 3]

## Decision Outcome

**Chosen option**: "[Option N]" because [justification].

### Consequences

**Positive:**
* [Benefit 1]
* [Benefit 2]

**Negative:**
* [Drawback 1]
* [Drawback 2]

**Neutral:**
* [Side effect that is neither good nor bad]

## Pros and Cons of Options

### Option 1: [Name]

* Good, because [argument]
* Good, because [argument]
* Bad, because [argument]

### Option 2: [Name]

* Good, because [argument]
* Bad, because [argument]
* Bad, because [argument]

### Option 3: [Name]

[etc.]

## Links

* [Link to related ADRs]
* [Link to architecture documentation]
* [Link to external references]

To change a decision:

1. Create new ADR with next number
2. Reference original: "Supersedes ADR-NNN"
3. Update original status: "Superseded by ADR-XXX"

This preserves the decision trail and reasoning evolution.

Technical:

• Performance requirements (latency, throughput)
• Scalability needs (horizontal, vertical)
• Reliability requirements (uptime, fault tolerance)
• Security constraints (compliance, data protection)

Organizational:

• Team expertise and capacity
• Time-to-market pressure
• Budget constraints
• Existing technology investments

Operational:

• Maintenance burden
• Monitoring and observability
• Deployment complexity
• Rollback capabilities

Strategic:

• Vendor lock-in considerations
• Future flexibility needs
• Integration requirements
• Standards compliance

1. "What problem is this decision solving?"
2. "What happens if we don't make this decision?"
3. "What constraints are non-negotiable?"
4. "Who will be affected by this decision?"
5. "How long do we expect this decision to remain valid?"

Positive consequences: What improves? What becomes easier? Negative consequences: What gets harder? What new problems emerge? Neutral consequences: What changes without clear good/bad valence?

Use: ++ (strong positive), + (positive), 0 (neutral), - (negative), -- (strong negative)

• Learning curve: Time for team to become proficient
• Migration path: Effort to move from current state
• Operational overhead: Ongoing maintenance burden
• Technical debt: Future refactoring this creates
• Lock-in: Difficulty switching away later

Boundary Decisions:

• "Where should the Conduit boundary be?"
• "What Protocol Buffer version to use?"
• "How to version the API?"

Composition Decisions:

• "How to decompose this into Atoms?"
• "What should the Composite orchestrate?"
• "Where does this logic belong?"

Data Strategy Decisions:

• "What Schema.org types at boundaries?"
• "How to model this internally?"
• "Where is the mapping layer?"

Performance Tunnel Decisions:

• "Is this bottleneck proven by profiling?"
• "What optimization approach?"
• "How to encapsulate complexity?"

Status: Accepted Date: 2025-01-15 Deciders: Architecture team

Context and Problem Statement

Our product catalog API needs to be consumable by AI agents and third-party integrations. We need a data format that is self-describing and follows industry standards.

Decision Drivers

• AI agents need to understand our data semantically
• Third-party integrations should work without custom documentation
• Internal models need to remain optimized for computation

Considered Options

1. Custom JSON schema with documentation
2. Schema.org/Product with JSON-LD serialization
3. GraphQL with custom types

Decision Outcome

Chosen option: "Schema.org/Product with JSON-LD serialization" because it provides semantic interoperability for AI consumers while following established web standards.

Consequences

Positive:

• AI agents can parse and understand our data without training
• Follows LCA principle of Schema.org at boundaries
• SEO benefits from structured data

Negative:

• Schema.org types are verbose compared to internal models
• Mapping layer adds complexity
• Some product attributes don't map cleanly

Neutral:

• Team needs to learn JSON-LD serialization

Links

• Relates to ARCHITECTURE.md#data-strategy
• Schema.org Product: https://schema.org/Product

</example_adr>
</lca_specific_adrs>

<directory_structure>
<placement>
ADRs live in a dedicated directory at the architecture level they affect:

project/ ├── ARCHITECTURE.md ├── adr/ │ ├── adr-001-initial-architecture.md │ ├── adr-002-use-protocol-buffers.md │ └── adr-003-schema-org-boundaries.md └── services/ └── order-service/ ├── architecture.md └── adr/ └── adr-001-caching-strategy.md

</placement>

<index>
Maintain an index file for discoverability:

```markdown
# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [001](adr-001-initial-architecture.md) | Initial Architecture | Accepted | 2025-01-01 |
| [002](adr-002-use-protocol-buffers.md) | Use Protocol Buffers | Accepted | 2025-01-05 |
| [003](adr-003-schema-org-boundaries.md) | Schema.org at Boundaries | Accepted | 2025-01-15 |

• Clear problem statement (why now?)
• Decision drivers listed with rationale
• At least 2 options considered
• Chosen option clearly stated with justification
• Positive consequences documented
• Negative consequences documented (mandatory—no free lunches)
• Neutral consequences considered
• Links to related architecture docs
• Proper numbering (adr-NNN format)
• Date and deciders recorded

• A future reader can understand WHY the decision was made
• Trade-offs are explicit, not hidden
• Alternative options are documented for historical context
• Links connect to relevant architecture documentation
• Status accurately reflects decision state

Converted and distributed by TomeVault — claim your Tome and manage your conversions.