Engineering Decision Records

Engineering Decision Records (EDRs) are living documents that capture the rationale, trade-offs, and outcomes of significant engineering decisions. They matter when a team must align on a technical direction, when a decision is complex enough to warrant documentation, and when the decision’s impact spans multiple teams, systems, or release cycles. An EDR is not a meeting minutes document nor a project specification; it is a deliberate, structured narrative that answers *why* a decision was made, not just *what* was decided.

When to Create an EDR

An EDR is warranted for decisions that are non-trivial, irreversible, or likely to impact multiple teams. Use an EDR for:

Choosing a new backend framework (e.g., adopting gRPC over REST for service-to-service communication)
Selecting a distributed tracing solution across a microservices ecosystem
Deciding on a data model for a core domain (e.g., event sourcing vs. CQRS)
Introducing a new deployment strategy (e.g., blue-green with canary rollout)
Standardizing on a CI/CD pipeline tooling stack

An EDR is not needed for simple tasks like “add a new field to the user profile table.” It becomes essential when the decision has consequences beyond a single sprint or team.

Writing an EDR

1. Use the EDR Template

Each EDR must follow a canonical structure, defined in a shared templates/edr.md file in the organization’s documentation repository. The template includes:



**Status**: Draft | Review | Approved | Implemented | Rejected  
**Author**: Jane Doe  
**Reviewers**: John Smith, Alice Chen  
**Created**: 2024-05-10  
**Last Updated**: 2024-05-25  

## Context

Describe the problem space, business or technical drivers, and constraints.

## Decision

Summarize the core decision in one sentence.

## Options

List 3–5 viable approaches, including pros, cons, and estimated effort.

## Recommendation

Explain why one option was selected. Include trade-offs, assumptions, and risks.

## Consequences

Detail the impact of the decision: what changes, what breaks, what new responsibilities.

## Alternatives Considered

Document the options that were evaluated but not chosen. Include why they were rejected.

## References

Link to related documents, code, design specs, or tooling.

The Status field is updated during review; a decision is not final until it is Approved.

2. Craft a Clear Decision Statement

The Decision section must be a single, precise sentence. It should be self-contained and answer “What is being decided?” without reference to the rest of the document.

Example: > We will adopt an event-driven architecture using Apache Kafka for all real-time data pipelines, replacing the current pull-based batch jobs.

This statement is not a summary; it is a declaration. It should be visible at the top of the document and serve as a one-sentence contract.

3. Evaluate Options with Trade-Offs

In the Options section, each alternative must be described with:

A concise title (e.g., “Kafka + Confluent Cloud”, “RabbitMQ + Celery”, “AWS SQS + Lambda”)
A clear description of how it works
A table with columns: Pros, Cons, Effort (person-days), Risk, Assumptions

The table is rendered in Markdown and must include actual data, not just bullet points.

Example:

Option	Pros	Cons	Effort	Risk	Assumptions
Kafka + Confluent Cloud	High throughput, built-in monitoring, auto-scaling	Higher operational cost, learning curve	20	Medium	Team has prior Kafka experience; data is time-series
RabbitMQ + Celery	Mature, strong Python integration	Limited horizontal scaling, message durability challenges	15	High	Python is the dominant language; event processing is simple

4. Justify the Recommendation with Depth

The Recommendation section must go beyond “We chose X because it’s good.” It should:

Explain the trade-offs that led to the final choice
Identify key assumptions that, if false, invalidate the decision
Highlight risks and mitigation strategies
Include a decision matrix (table) summarizing scores across criteria

Criteria might include:

Throughput (events/sec)
Latency (end-to-end)
Operational complexity
Learning curve
Cost (infrastructure + team time)
Data consistency model

Each option is scored (1–5) on each criterion. The final choice is justified by cumulative scores and a narrative that explains why the top-ranked option wins.

5. Document the Consequences

The Consequences section captures the ripple effects of the decision. It answers: *What changes as a result?* It is not a list of “benefits” but a structured account of change.

Structure the section as a list of actionable consequences, each with:

Impact: Who or what is affected?
Action Required: What must be done to adopt the decision?
Risks: What could go wrong?
Success Metrics: How will we know it worked?

Example:

Impact: All microservices must produce and consume events in a defined schema format (Avro).
Action Required: New schema registry is deployed; all teams must register schemas and generate code.
Risks: Schema drift causes consumer breakage; backward compatibility is not enforced.
Success Metrics: 90% of services produce events; 95% of consumers handle schema changes without downtime.

Reviewing an EDR

1. Use the Review Checklist

An EDR must be reviewed by at least two engineers, one of whom is a domain expert. The review process uses a standard checklist, maintained in templates/edr-review-checklist.md:

- [ ] Decision statement is clear and complete
- [ ] Options are well-described and cover major alternatives
- [ ] Trade-offs are explicit and balanced
- [ ] Recommendation addresses assumptions and risks
- [ ] Consequences are actionable and measurable
- [ ] All references are valid and accessible
- [ ] Status is updated to "Review"
- [ ] Reviewers leave comments in the GitHub PR or in the document

The reviewer leaves comments directly in the EDR Markdown file, using GitHub-style comments or inline replies. A review is not complete until all checklist items are checked.

2. Track Review Status in Version Control

All EDRs are stored in a decisions/ directory in the main engineering repository. Each EDR is a file named edr-001-<slug>.md, e.g., edr-001-event-driven-architecture.md.

Version control is managed via Git. The review process is a pull request:

git checkout -b feature/edr-001-event-driven-architecture
git add decisions/edr-001-event-driven-architecture.md
git commit -m "EDR-001: Event-driven architecture with Kafka"
git push origin feature/edr-001-event-driven-architecture

The PR includes:

A description linking to the template and checklist
A draft EDR with initial content
A link to a preview of the document (via GitHub or a static site generator)
A review request to two reviewers

Reviewers comment directly on the PR. Comments are not just feedback but part of the decision record.

3. Approve and Implement

Once all reviewers approve, the EDR is merged into main. The Status field is updated to Approved.

The decision is now live and must be implemented. A separate issue is created in the project tracker (e.g., Jira, GitHub Issues) for implementation, with the EDR linked as the design document.

Maintaining EDRs

1. EDRs Are Living Documents

An EDR is not static. It evolves after approval. When a decision changes, the EDR is updated and versioned.

Each EDR includes a History section:

## History

- 2024-05-10: Initial draft created
- 2024-05-20: Review comments incorporated
- 2024-05-25: Approved; status set to "Approved"
- 2024-08-15: Implementation underway; added success metrics
- 2024-10-01: Decision re-evaluated; added new constraint: "support for 1M events/sec"

When a consequence fails or a trade-off is misunderstood, the EDR is updated with a new entry in the history.

2. Link EDRs Across the Organization

EDRs are discoverable via a central Decision Index. This is a Markdown file, decisions/index.md, which lists all EDRs:

# Engineering Decision Index

- [EDR-001] Event-driven architecture with Kafka
  - Status: Implemented
  - Author: Jane Doe
  - Created: 2024-05-10
  - Related: EDR-003 (Data Modeling), EDR-005 (CI/CD Pipeline)

- [EDR-002] Adopting GraphQL for public APIs
  - Status: In Review
  - Author: John Smith
  - Created: 2024-04-15

- [EDR-003] Data modeling with event sourcing
  - Status: Approved
  - Author: Alice Chen
  - Created: 2024-03-22

This index is updated automatically via a CI job that runs git ls-files decisions/*.md and generates the table.

3. Handle EDR Failures

Common failure modes in EDRs:

Assumptions are untested: A decision assumes “team has Kafka experience,” but no onboarding material is created. The result is inconsistent event schemas and frequent consumer breakages.
Consequences are ignored: The EDR specifies that “all services must register schemas,” but no enforcement is in place. Over time, services diverge in schema format.
Reviewers skip key sections: A reviewer only comments on the Decision and Options, but misses the Consequences and Alternatives, leading to a decision that is poorly understood.
Status is not updated: An EDR is approved but remains in “Draft” status, leading to confusion about which decisions are final.

To catch these, a quarterly EDR Audit is run:

# Run in CI or manually
git checkout main
find decisions/ -name "*.md" -exec grep -l "Status:" {} \; | while read file; do
  echo "Checking $file"
  if ! grep -q "Status: Approved" "$file"; then
    echo "  Status not set to Approved: $file"
  fi
  if ! grep -q "Consequences" "$file"; then
    echo "  Consequences section missing: $file"
  fi
done

The audit generates a report of all EDRs that are approved but lack key elements.

Example: EDR-001 – Event-Driven Architecture with Kafka

# [EDR-001] Event-driven architecture with Kafka

**Status**: Implemented  
**Author**: Jane Doe  
**Reviewers**: John Smith, Alice Chen  
**Created**: 2024-05-10  
**Last Updated**: 2024-10-01  

## Context

Our current data pipeline relies on nightly batch jobs. As user activity grows, real-time visibility is required. We need to support event-driven workflows such as order confirmation, inventory updates, and user onboarding. The existing architecture lacks a reliable, scalable messaging layer.

## Decision

We will adopt an event-driven architecture using Apache Kafka for all real-time data pipelines, replacing the current pull-based batch jobs.

## Options

| Option | Pros | Cons | Effort | Risk | Assumptions |
|--------|------|------|--------|------|-------------|
| Kafka + Confluent Cloud | High throughput, built-in monitoring, auto-scaling | Higher operational cost, learning curve | 20 | Medium | Team has prior Kafka experience; data is time-series |
| RabbitMQ + Celery | Mature, strong Python integration | Limited horizontal scaling, message durability challenges | 15 | High | Python is the dominant language; event processing is simple |
| AWS SQS + Lambda | Serverless, low operational overhead | Limited message ordering, no built-in consumer groups | 12 | Low | AWS is the primary cloud; event processing is stateless |

## Recommendation

Kafka was selected due to its ability to handle high-throughput, ordered events with strong durability guarantees. The decision is justified by a scoring matrix:

| Criterion | Kafka | RabbitMQ | SQS |
|---------|-------|----------|-----|
| Throughput | 5 | 3 | 4 |
| Latency | 4 | 3 | 3 |
| Operational Complexity | 3 | 5 | 5 |
| Learning Curve | 3 | 4 | 4 |
| Cost | 4 | 3 | 5 |

Kafka scores highest in throughput and cost, and its trade-offs align with our assumption of time-series data and team expertise.

## Consequences

- **Impact**: All microservices must produce and consume events in Avro format.
  - **Action Required**: Schema registry deployed; code generation tooling added to CI.
  - **Risks**: Schema drift causes consumer breakage; backward compatibility is not enforced.
  - **Success Metrics**: 90% of services produce events; 95% of consumers handle schema changes without downtime.

- **Impact**: New monitoring and alerting system for Kafka clusters.
  - **Action Required**: Prometheus + Grafana dashboard added; alerting on lag, broker failure, consumer group stability.
  - **Risks**: High consumer lag not detected early.
  - **Success Metrics**: 95% of consumers maintain lag < 1 minute; broker failure alerts reduce mean time to recovery.

## Alternatives Considered

- **RabbitMQ + Celery**: Chosen for its simplicity and Python integration. Rejected due to lack of scalable consumer groups and limited horizontal scaling.
- **AWS SQS + Lambda**: Chosen for serverless simplicity. Rejected due to weak message ordering and lack of consumer group coordination.

## References

- [Kafka documentation](https://kafka.apache.org/documentation/)
- [Avro schema specification](https://avro.apache.org/docs/current/spec.html)
- [Schema registry design](https://docs.confluent.io/platform/current/schema-registry/index.html)

This EDR is now a reference point for all teams adopting event-driven workflows.

This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.