​
ADR Formatting Guide

This guide explains how to format Architecture Decision Records (ADRs) for optimal integration with Arc Memory.

​
What are ADRs?

Architecture Decision Records (ADRs) are documents that capture important architectural decisions made along with their context and consequences. They provide a record of the “why” behind code changes and system design.

​
Why Use ADRs with Arc Memory?

Arc Memory can parse and integrate ADRs into the knowledge graph, connecting them to:

  • Commits that implement the decisions
  • Pull requests related to the decisions
  • Issues that motivated the decisions
  • Code that was affected by the decisions

This creates a comprehensive view of not just what changed, but why it changed.

​
ADR Directory Structure

Arc Memory looks for ADRs in the following locations by default:

/docs/adr/
/adr/
/doc/adr/
/doc/arch/
/architecture/decisions/

You can specify a custom location with:

arc build --adr-path path/to/adrs

​
ADR File Naming

Arc Memory supports the following naming conventions:

  1. Numbered format: NNNN-title-with-dashes.md

    • Example: 0001-use-postgresql-for-database.md

  2. Date-based format: YYYY-MM-DD-title-with-dashes.md

    • Example: 2023-01-15-use-postgresql-for-database.md

  3. ADR prefix: adr-NNNN-title-with-dashes.md

    • Example: adr-0001-use-postgresql-for-database.md

​
ADR Content Format

Arc Memory supports multiple ADR formats, but the recommended format is:

# N. Title

Date: YYYY-MM-DD

## Status

[Proposed | Accepted | Deprecated | Superseded]

## Context

[Description of the problem and context]

## Decision

[Description of the decision made]

## Consequences

[Description of the consequences of the decision]

## References

[Optional: Links to related issues, PRs, or external resources]

​
Example ADR

# 1. Use PostgreSQL for Database

Date: 2023-01-15

## Status

Accepted

## Context

We need to choose a database system for our application. The requirements include:

- Support for complex queries
- ACID compliance
- Ability to handle relational data
- Good performance with our expected data volume

## Decision

We will use PostgreSQL as our primary database system.

## Consequences

### Positive

- PostgreSQL provides excellent support for complex queries
- It is fully ACID compliant
- It has strong community support and documentation
- It offers advanced features like JSON support and full-text search

### Negative

- Team members will need to learn PostgreSQL if they're not already familiar
- We'll need to set up and maintain PostgreSQL infrastructure

## References

- Issue #123: Database Selection Discussion
- PR #456: Initial Database Schema Implementation
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

​
Alternative ADR Formats

Arc Memory also supports these alternative formats:

​
Lightweight Format

# Title

Status: [Proposed | Accepted | Deprecated | Superseded]
Date: YYYY-MM-DD

## Context

[Description of the problem and context]

## Decision

[Description of the decision made]

## Consequences

[Description of the consequences of the decision]

​
MADR Format (Markdown Any Decision Records)

# [short title of solved problem and solution]

* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)]
* Deciders: [list everyone involved in the decision]
* Date: [YYYY-MM-DD when the decision was last updated]

## Context and Problem Statement

[Describe the context and problem statement, e.g., in free form using two to three sentences.]

## Decision Drivers

* [driver 1, e.g., a force, facing concern, …]
* [driver 2, e.g., a force, facing concern, …]

## Considered Options

* [option 1]
* [option 2]
* [option 3]

## Decision Outcome

Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].

### Positive Consequences

* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]

### Negative Consequences

* [e.g., compromising quality attribute, follow-up decisions required, …]

## Pros and Cons of the Options

### [option 1]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

### [option 2]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

## Links

* [Link type] [Link to ADR]

​
Linking ADRs to Code

To maximize the value of ADRs in Arc Memory, link them to code in the following ways:

​
1. Reference ADRs in Commit Messages

Implement PostgreSQL integration

See ADR-0001 for the decision to use PostgreSQL.

​
2. Reference ADRs in Pull Request Descriptions

This PR implements the PostgreSQL integration as decided in ADR-0001.

​
3. Reference ADRs in Code Comments

# Database connection setup as per ADR-0001
def setup_database_connection():
    # ...

​
4. Reference Issues and PRs in ADRs

In your ADR, include references to related issues and PRs:

## References

- Issue #123: Database Selection Discussion
- PR #456: Initial Database Schema Implementation

​
ADR Templates

You can create a new ADR using the Arc Memory CLI:

arc adr new "Use PostgreSQL for Database"

This will create a new ADR with the recommended format in your ADR directory.

​
Viewing ADRs in Arc Memory

After building the knowledge graph with ADRs:

# List all ADRs
arc list adrs

# Show a specific ADR
arc show adr 1

# Find code related to an ADR
arc relate node adr:1

​
Best Practices

  1. Keep ADRs concise: Focus on the key information
  2. Use a consistent format: Stick to one format for all ADRs
  3. Number ADRs sequentially: Makes them easier to reference
  4. Update the status: Keep the status field up to date
  5. Link to related artifacts: Reference issues, PRs, and other ADRs
  6. Include dates: Always include the decision date
  7. Explain context thoroughly: The context is crucial for understanding the decision
  8. Document alternatives: Include alternatives that were considered
  9. Capture consequences: Document both positive and negative consequences

​
Common Mistakes

  1. Too much detail: ADRs should be concise and focused
  2. Missing context: Without context, the decision is hard to understand
  3. No status updates: ADRs should be updated when their status changes
  4. Inconsistent formatting: Makes it harder to parse and understand
  5. No references: Missing links to related artifacts reduces traceability

​
See Also