architecture-decision-records
Capture architectural decisions made during OpenAI Codex sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
npx skills add mturac/everything-openai-codex --skill architecture-decision-records --agent codex
Same command for any agent — swap --agent for claude-code, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Architecture Decision Records Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code. ## When to Activate - User explicitly says "let's record this decision" or "ADR this" - User chooses between significant alternatives (framework, library, pattern, database, API design) - User says "we decided to..." or "the reason we're doing X instead of Y is..." - User asks "why did we choose X?" (read existing ADRs) - During planning phases when architectural trade-offs are discussed ## ADR Format Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: ```markdown # ADR-NNNN: [Decision Title] **Date**: YYYY-MM-DD **Status**: proposed | accepted | deprecated | superseded by ADR-NNNN **Deciders**: [who was involved] ## Context What is the issue that we're seeing that is motivating this decision or change? [2-5 sentences describing the situation, constraints, and forces at play] ## Decision What is the change that we're proposing and/or doing? [1-3 sentences stating the decision clea
- When to Activate
- ADR Format
- Workflow
- Capturing a New ADR
- Reading Existing ADRs
- ADR Directory Structure
- ADR Index Format
- Decision Detection Signals
- What Makes a Good ADR
- Do
- Don't
- ADR Lifecycle
- Categories of Decisions Worth Recording
- Integration with Other Skills
What does the architecture-decision-records skill do?
Capture architectural decisions made during OpenAI Codex sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
How do I install it?
Run `npx skills add mturac/everything-openai-codex --skill architecture-decision-records --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From mturac/everything-openai-codex, a repository with 84 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.