architecture-decision-records
by affaan-marchitecture-decision-records helps capture architectural decisions during Claude Code sessions as structured ADRs. It detects decision moments, records context, alternatives, and rationale, and keeps an ADR log for future maintainers. Useful for Technical Writing and engineering teams that need durable decision history.
This skill scores 78/100, which means it is a solid listing candidate for directory users who want an agent-friendly way to capture architecture decisions as ADRs. It is clear enough to install with confidence, though users should note that the repo provides the workflow in one SKILL.md file and lacks supporting scripts or references.
- Explicit activation cues for when to use the skill, including decision moments, trade-offs, and "why did we choose X?" questions.
- Concrete ADR template and structured sections for context, decision, and alternatives, which reduces agent guesswork.
- No placeholder markers and a substantial body of guidance, suggesting real workflow content rather than a demo-only stub.
- No support files, scripts, or references, so users must rely on the markdown instructions alone.
- No install command or broader repo guidance, which may make adoption less obvious for first-time users.
Overview of architecture-decision-records skill
What the architecture-decision-records skill does
The architecture-decision-records skill helps an agent turn live architecture choices into lightweight ADRs during a coding session. Instead of asking for a generic summary after the fact, it is designed to notice decision points, capture context and tradeoffs, and write a structured record that can live in the repo.
Best fit for Technical Writing and engineering teams
This is a strong fit for teams doing AI-assisted development, technical leads who want durable decision history, and Technical Writing workflows that need source material for system docs. The real job-to-be-done is not “write markdown”; it is preserving why a team chose one approach over another before that rationale disappears into chat, commits, or memory.
What makes it different from a normal prompt
A normal prompt can produce an ADR template once. The architecture-decision-records skill is more useful when decisions happen repeatedly across sessions: framework selection, API patterns, data storage, deployment design, or deprecation choices. Its differentiator is activation logic plus a consistent ADR structure based on the lightweight Michael Nygard style.
Key adoption cautions
This skill is narrow by design. It does not replace architecture review, governance, or repository-specific standards on its own. It also appears to ship as a single SKILL.md without helper scripts or validation tooling, so output quality depends heavily on your prompt quality and your repo conventions.
How to Use architecture-decision-records skill
Install context and where to read first
For architecture-decision-records install, add the parent skill collection in your Claude Code skills workflow, then open skills/architecture-decision-records/SKILL.md first. There are no visible companion rules/, resources/, or automation files, so nearly all usable guidance is in that one file. Read these sections in order: When to Activate, ADR Format, then any examples in the markdown fences.
What input the skill needs to work well
The architecture-decision-records skill works best when you provide:
- the decision being made
- the alternatives seriously considered
- constraints such as cost, performance, team familiarity, deadlines, compliance, or migration risk
- who decided and the current status (
proposed,accepted,deprecated,superseded) - the target ADR location, naming scheme, and numbering convention
Weak input: “Write an ADR for using Postgres.”
Strong input: “Create ADR-0012 for choosing Postgres over DynamoDB for transactional order processing. Context: multi-row consistency, existing SQL skills, moderate scale, AWS deployment, 3-month delivery window. Status accepted. Deciders: platform lead, backend lead.”
Turn a rough goal into a strong invocation prompt
For practical architecture-decision-records usage, ask for both extraction and formatting. A good prompt pattern is:
“Use the architecture-decision-records skill. From this discussion, identify whether an ADR should be created. If yes, draft it in Michael Nygard style with Context, Decision, and Alternatives Considered, and note any missing facts you need before finalizing.”
That phrasing matters because the skill is best when the decision is still forming. It lets the agent detect a decision point, draft the ADR, and surface gaps instead of inventing rationale.
Suggested workflow inside a real repo
- Detect a meaningful decision during planning or implementation.
- Ask the agent to use the architecture-decision-records skill and draft the ADR.
- Review for factual accuracy, especially rejected alternatives and constraints.
- Save it in a stable folder such as
docs/adr/oradr/. - Link the ADR from PRs, architecture docs, or onboarding docs.
For Technical Writing, pair the ADR with a short “impact” note: what readers should now assume about APIs, infrastructure, or future migrations. That makes the ADR more reusable beyond engineering chat history.
architecture-decision-records skill FAQ
Is architecture-decision-records worth installing if I can already prompt for ADRs?
Yes, if your problem is consistency and timing rather than markdown formatting. The architecture-decision-records skill gives the agent a clearer trigger: capture decisions when they happen, not weeks later. If you only need a one-off ADR template, a normal prompt may be enough.
Is this good for beginners?
Yes, with one caveat. Beginners can get useful ADR drafts, but they may not know which constraints matter or which alternatives were truly viable. The skill helps structure thinking, but a reviewer should still validate technical tradeoffs before acceptance.
When should I not use this skill?
Skip it for trivial implementation details, temporary experiments, or decisions with no lasting architectural impact. Over-recording creates ADR noise. Use architecture-decision-records for choices future maintainers will ask about, such as “why this stack, pattern, boundary, or integration?”
How does it fit Technical Writing work?
The architecture-decision-records skill is useful for Technical Writing because it captures rationale close to the source. Writers can turn accepted ADRs into system overviews, migration notes, FAQ content, and onboarding material without reconstructing decisions from scattered chats or PR comments.
How to Improve architecture-decision-records skill
Give better source material, not just a topic
The biggest quality driver is specificity. Include constraints, rejected options, and the actual forcing function. “We picked Redis for caching” is weak. “We picked Redis over in-process caching because we need shared invalidation across workers and predictable behavior in horizontal scaling” is much better. The architecture-decision-records skill can only preserve reasoning that is present.
Prevent common failure modes
Common problems are vague context, fake alternatives, and overconfident conclusions. If the draft reads like the decision was obvious, ask the agent to expand tradeoffs. If alternatives are shallow, provide the top 2–3 options you truly debated. If the decision is still provisional, keep status as proposed instead of forcing accepted.
Adapt the ADR output to your repo standard
The upstream skill uses a lightweight ADR structure, but many teams need extra fields like consequences, links, owners, or review date. Improve architecture-decision-records usage by telling the agent exactly which headings are mandatory in your repo and where the file should live. Otherwise you may get a clean draft that still needs formatting rework.
Iterate after the first draft
Treat the first output as a decision checkpoint, not final truth. Ask follow-ups such as:
- “What assumptions in this ADR are unstated?”
- “Which alternative deserves a fairer treatment?”
- “What future reversal signals should we document?”
- “What code areas or docs should link to this ADR?”
Those follow-ups make the architecture-decision-records skill more valuable than a template filler, especially when you want ADRs that remain useful months later.