Recording Architecture Decisions

This one helps you write architecture decision records without leaving your baseline documentation stale. It walks you through a three-question gate (hard to reverse, surprising without context, real trade-off) before you commit to writing anything, then forces you to sync the current-state baseline if the decision actually changed what the system is. The compact output contract is nice if you want structured decision hygiene. It's opinionated about distinguishing executed decisions from unexecuted ideas, and it won't let you treat an ADR as proof the work is done. Useful if your team has burned itself by recording why without updating what, or by writing decision docs for things that didn't need them.

GitHub stars: 492
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add ganyuanran/aegis --skill recording-architecture-decisions --agent claude-code

Installs into .claude/skills of the current project.

Files

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/.