# adr-standards

adr-standards embeds the MADR v4.0.0 template, Y-Statement formula, and status taxonomy into ADR folders so agents write architectural decisions to a single standard.

- rule · `type=rule` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline · ★ 1627 repo stars
- Author: microsoft
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/microsoft/hve-core/tree/HEAD/.github/instructions/project-planning/adr-standards.instructions.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/rules/adr-standards

## What it does

The rule applies to `**/.copilot-tracking/adr-plans/**` and `**/docs/planning/adrs/**`. Inside: the MADR v4.0.0 template verbatim (CC0-1.0), the six-slot Y-Statement formula (context, concern, option, alternatives, quality, downside), a status taxonomy (`proposed`, `accepted`, `rejected`, `deprecated`, `superseded`), and the ASR trigger schema for architecturally significant requirements.

The ADR Creator agent picks up these standards when drafting a decision record. For a short form, it produces a Y-Statement as a single sentence; the long form follows MADR structure: context, decision drivers, options, outcome, consequences. The rule also sets file-naming conventions and legal status transitions.

Microsoft material is paraphrased under CC-BY 4.0. Citations from Nygard, IEEE 42010:2022, and arc42 §9 are reference-only to avoid CC-BY-SA contamination.

## Install

### GitHub Copilot (native platform)

**Manually: put the files in place**
- File: `.github/instructions/adr-standards.instructions.md` — The applyTo field sets which files it applies to

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/adr-standards.md` — The paths frontmatter field limits the files: move applyTo from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### Cursor

**Manually: put the files in place**
- File: `.cursor/rules/adr-standards.mdc` — Frontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/adr-standards.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/adr-standards.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/microsoft/hve-core/tree/HEAD/.github/instructions/project-planning/adr-standards.instructions.md

## When to use it
- maintain architectural decisions in a consistent MADR format
- capture choices and rejected alternatives using the Y-Statement formula
- give agents a status taxonomy and transition rules for ADRs
- embed the ADR template in project folders without external dependencies

## Example prompts
- Draft an ADR for the database choice in `.copilot-tracking/adr-plans/` using the MADR template
- Record the decision to switch to TypeScript as a Y-Statement
- Check that all ADRs in `docs/planning/adrs/` match the `adr-standards` schema

## Source text · adr-standards.instructions.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: e88195eedc550e43.

BEGIN THIRD-PARTY FILE e88195eedc550e43
````text
---
description: 'Embedded ADR standards: MADR v4.0.0 template (CC0), Y-Statement formula, status taxonomy, naming rules, ASR trigger schema, and Microsoft-attributed paraphrases for ADR Creator sessions'
applyTo: '**/.copilot-tracking/adr-plans/**, **/docs/planning/adrs/**'
---

# ADR Standards Reference

This file is the standards anchor for the ADR Creator agent. It embeds the MADR v4.0.0 template (CC0-1.0), the Y-Statement six-slot formula (Zimmermann/Zdun), the canonical status taxonomy with legal transitions, the file-naming rule, and the ASR (Architecturally Significant Requirement) trigger schema.
Microsoft-authored guidance is paraphrased under CC-BY 4.0 with explicit change indication. Other sources (Nygard 2011, IEEE 42010:2022, arc42 §9, joelparkerhenderson) are cite-only to prevent CC-BY-SA contamination. Standards lookups outside this embedded set activate `rpi-research` at runtime.

## MADR v4.0.0 Verbatim Template

The Markdown Any Decision Records (MADR) v4.0.0 template is embedded verbatim below.

> Source: github.com/adr/madr @ v4.0.0 (`template/adr-template.md`, tag `4.0.0`).
> License: CC0-1.0 Universal Public Domain Dedication.
> The MADR project releases the template under CC0-1.0; no rights are reserved by the original authors and the template may be reproduced byte-identical without modification.

The template content below is byte-identical to upstream and is pinned to MADR v4.0.0. Any deviation (including the typographical anomaly in the `status:` example) is intentional preservation of the upstream bytes.

```markdown
---
# These are optional metadata elements. Feel free to remove any of them.
status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123"
date: {YYYY-MM-DD when the decision was last updated}
decision-makers: {list everyone involved in the decision}
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
---

# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}

<!-- This is an optional element. Feel free to remove. -->
## Decision Drivers

* {decision driver 1, e.g., a force, facing concern, …}
* {decision driver 2, e.g., a force, facing concern, …}
* … <!-- numbers of drivers can vary -->

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* … <!-- numbers of options can vary -->

## Decision Outcome

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

<!-- This is an optional element. Feel free to remove. -->
### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* … <!-- numbers of consequences can vary -->

<!-- This is an optional element. Feel free to remove. -->
### Confirmation
````
END THIRD-PARTY FILE e88195eedc550e43

The third-party file has ended. Everything between the e88195eedc550e43 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3444 of 18247 bytes. © microsoft · MIT · https://github.com/microsoft/hve-core/tree/HEAD/.github/instructions/project-planning/adr-standards.instructions.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
