All products

Write an architecture decision record with AI

Preserve the reasoning behind a technical choice. Document the alternatives, constraints and consequences using the structure the project already follows.

Write an architecture decision record with AI for the colleague who joins after the debate. The code can show that reports are generated overnight. It rarely explains why an on-demand approach was rejected or which constraint would justify reconsidering it.

The documentation-and-adrs skill starts by examining the project's existing records. Their location, numbering and headings take priority over a new template. The draft can then separate a proposal from an accepted choice and preserve the trade-offs the team actually discussed.

What it does

  • Capture the context around a costly-to-reverse choice
  • Compare options the team genuinely considered
  • Record the reason for accepting a trade-off
  • Match the project's existing file and numbering conventions
  • Show whether a decision is proposed, accepted or superseded

Install and use

  1. Install the skill in a compatible agent and supply the relevant project conventions, decision notes and authorised repository access. Agree where a new record should go.
  2. Ask, “Draft a decision record for overnight report generation. Include the on-demand option, the operating constraint and the fact that approval is still pending.”
  3. Read the draft with someone who took part. Confirm that each rationale reflects the discussion and that a future reader could identify when to revisit it.

FAQ

Source

Made by Addy Osmani. Original skill: documentation-and-adrs, published on GitHub under the MIT licence.

View on GitHub