---
title: "File name conventions"
source: Architecture Decision Records (JPH)
source_url: https://github.com/joelparkerhenderson/architecture-decision-record
licence: CC0-1.0
domain: engineering
subdomain: adr-examples
date_added: 2026-04-25
---

# File name conventions

If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention.

We prefer to use a file name convention that has a specific format.

Examples:

  * choose-database.md

  * format-timestamps.md

  * manage-passwords.md

  * handle-exceptions.md

Our file name convention:

  * The name has a present tense imperative verb phrase. This helps readability and matches our commit message format.

  * The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability.

  * The extension is markdown. This can be useful for easy formatting.
