ADRKit

Architecture decision record generator

An architecture decision record (ADR) captures one significant technical decision: the context, the options you weighed, what you chose and what it will cost you. ADRKit gives you a form for each record and turns it into a clean Markdown file as you type.

Decisions

    Files are named like 0001-title.md for a docs/adr folder.

     
     
     
      
    Saved you some time? Leave a tip, entirely optional.
      
     
    Records are numbered for you, can supersede older ones, and export as a zip with a README index ready to drop into a docs/adr folder in your repository. Nothing is uploaded; your decisions stay in this browser.
     
    How the records fit together
     
    Each record gets the next free number and a file name made from that number and its title, such as 0002-use-postgresql-as-the-primary-database.md. Numbers never change, even if you delete a record, because other documents may refer to them. When a new decision replaces an old one, choose the old record under Supersedes: the new file gets a “Supersedes” link, the old one is marked Superseded and gets a “Superseded by” link back, and the index shows the change.
     
    Download all builds a zip with a docs/adr folder containing every record and a README.md index table with number, title, status and date. Unzip it at the root of your repository and commit it, or copy just the index if you keep records elsewhere.
     
    Choosing a template
     
    Use MADR when you want to show the options and trade-offs; it is the most complete format and suits decisions that will be debated. Use Nygard for short, quick records where the decision is clear. Use a Y-statement to capture small decisions in one sentence or to summarise a long one. You can change the template of any record at any time; the fields carry across and the preview updates.
     
    Private by design
     
    ADRKit has no accounts and no server-side storage. Your records are saved in local storage in this browser only, and the zip is built on your device.
     
    Frequently asked questions
     
    When should I write an ADR?
    Whenever a decision is hard to reverse or will puzzle someone later: a database, a framework, an API style, a hosting model, a security approach.
    Which template should I use?
    MADR is the most popular and covers options and trade-offs. Nygard is the shortest. A Y-statement fits the whole decision in one sentence.
    Can I edit an ADR after it is accepted?
    Convention says no: write a new ADR that supersedes the old one. ADRKit links the two and marks the old one as superseded.
    Is ADRKit free?
    Yes. The ADR generator, templates and zip export are free with no account.
    Where are my ADRs stored?
    Only in this browser on this device. Download the zip to keep them in your repository.
     
    More tools