# Recording Architecture Decisions

Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR...

- Repository: https://github.com/GanyuanRan/Aegis (1408 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-10-25
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -g -a claude-code -y`
Codex: `npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -g -a codex -y`
Cursor: `npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -g -a cursor -y`
Gemini CLI: `npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add GanyuanRan/Aegis`

## Description

Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync after architecture-changing work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Recording Architecture Decisions

## Purpose

Record durable architecture decisions without losing the current-state baseline
closure. An ADR records why a decision was made; a baseline records what the
architecture is after that decision.

This skill is a lazy, task-specific workflow. It does not replace
`verification-before-completion`, does not grant completion authority, and does
not make authoritative `GateDecision` or `PolicySnapshot` outputs.

## Required Read Set

Before deciding or writing, read the smallest relevant excerpts from:

- `docs/adr/ADR-CREATION-GATE.md`
- `docs/current/AEGIS_ADR_AUTO_BACKFILL.md`
- the target project's current ADR, baseline, or authority docs that own the
  affected architecture surface

For Aegis repository changes, use this repository's `docs/adr/` and
`docs/current/` authority order. For target projects with their own ADR system,
respect that project owner instead of duplicating the same decision into
`docs/aegis/adr/`.

## When To Use

Use this skill when the user asks to:

- create, write, update, amend, supersede, or evaluate an ADR
- decide whether an architecture decision record is needed
- record a durable architecture decision or decision log entry
- close baseline sync after an ADR-relevant architecture change
- verify that an ADR action did not leave the architecture baseline stale

Do not use it for simple wording edits, ordinary README cleanup, tests-only
coverage improvements, low-risk single-file changes, or bug fixes that only
restore the existing baseline.

## Decision Flow

The rest: https://github.com/GanyuanRan/Aegis/blob/HEAD/skills/recording-architecture-decisions/SKILL.md