Skip to content
Get packs

Architecture Decision Records

Records architecture decisions as structured ADR documents during coding sessions, with context and rejected alternatives.

Source Download skill
Repository
affaan-m/ECC
Stars
295,127
Licence
MIT
Files
1 file

What it does

When you make a significant technical choice (a framework, database, API style or auth approach) while working with the agent, this skill makes it notice the decision and propose writing it up as a short Architecture Decision Record. Each record captures the context, the decision, the alternatives considered and why they were rejected, and the consequences. It keeps an index of records in docs/adr/ so future team members can understand why the codebase looks the way it does. It asks for your approval before creating files or writing anything.

Great for

  • Development teams that want a lasting written trail of why technical choices were made
  • Solo developers who often forget the reasons behind past decisions
  • Projects where decisions currently live only in chat threads, PR comments or memory

Skip it if

  • Trivial choices such as variable naming or formatting, which the skill itself says do not need a record (the record would add noise)
  • Projects that already use a different decision-log system, since it would create a parallel record set

Try asking

  • “Let's record this decision: we are using PostgreSQL instead of MongoDB for the primary datastore.”
  • “Create an ADR for choosing REST over GraphQL for our public API.”
  • “Why did we choose Next.js? Check the existing ADRs.”
  • “We're comparing two auth libraries; help me document the trade-offs once we decide.”
Step-by-step guide: how to use Architecture Decision RecordsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    architecture-decision-records.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip architecture-decision-records.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip architecture-decision-records.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • State the alternatives and the reason you rejected them in the conversation; the skill works best when that information is given explicitly.
  • Review the draft ADR carefully before approving, since the agent will write it into docs/adr/ in your repository once you confirm.
  • The SKILL.md is written in Japanese; if your team works in another language, ask the agent to produce ADRs in that language.

What's inside

  • SKILL.md

Redistributed unmodified from affaan-m/ECC under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.