Menü
Write Architecture Decision Records (ADRs) that capture context, options considered, decision rationale, and consequences — creating a searchable decision log for future engineers.
| name | architecture-decision-record |
| description | Write Architecture Decision Records (ADRs) that capture context, options considered, decision rationale, and consequences — creating a searchable decision log for future engineers. |
| metadata | {"displayName":"Architecture Decision Record","categories":["engineering"],"tags":["ADR","architecture","decisions","documentation","technical-decisions"],"worksWellWithAgents":["autonomous-coding-agent","code-generator","code-migrator","cto-advisor","enterprise-architect"],"worksWellWithSkills":["codebase-exploration","monorepo-setup-guide","refactoring-checklist","system-design-document","technical-spec-writing"]} |
Gather the following from the user:
If the user says "we decided to use Kafka," push back: "What problem does Kafka solve that your current approach doesn't? What alternatives did you evaluate? An ADR without alternatives considered is just an announcement."
Every ADR starts with a sequential number, title, and metadata.
# ADR-0017: Use PostgreSQL for Event Storage Instead of DynamoDB
- **Status**: Accepted
- **Date**: 2025-01-15
- **Decision makers**: @alice (tech lead), @bob (architect), @carol (DBA)
- **Consulted**: Platform team, Data engineering team
- **Supersedes**: ADR-0008 (if applicable)
Use a descriptive title that states the decision, not the problem. "Use PostgreSQL for Event Storage" is a decision. "Event Storage" is a topic.
Describe the situation that requires a decision. Include:
Write this for an engineer joining the team 12 months from now. They were not in the room — give them enough context to understand why this decision was even necessary.
List every option evaluated, including "do nothing." For each option, describe how it addresses the problem and its tradeoffs.
For each option, include pros, cons, and an estimated cost or effort. Always include "do nothing" as an option — sometimes the cost of change exceeds the cost of the current pain.
State the chosen option clearly and concisely.
State the chosen option in one sentence. Then explain the rationale — why this option over the alternatives. Connect the reasoning to the constraints stated in the context. Explicitly address why each rejected option was not chosen.
Document what changes as a result of this decision — both positive and negative.
Include three categories: Positive consequences (benefits gained), Negative consequences (costs and limitations accepted), and Risks (what could go wrong, with mitigation strategies).
List concrete next steps. Every action needs an owner and a deadline.
docs/adr/ or decisions/0017-use-postgresql-for-event-storage.mdREADME.md or INDEX.md) linking to all ADRs with title, status, and dateWhen a decision is reversed, don't delete the original ADR. Mark it as Superseded and link to the new ADR that replaces it.
Before finalizing the ADR, verify:
Write structured accessibility audit reports with findings mapped to WCAG criteria, severity levels, affected components, remediation steps, and a prioritized fix timeline.
Write effective prompts for AI coding tools — structure task context, specify constraints, provide examples, and iterate based on output quality. Targets developers using Claude Code, Copilot, Cursor, and similar tools.
Design RESTful and GraphQL APIs with consistent naming conventions, versioning strategy, pagination patterns, error response formats, authentication schemes, and rate limiting — producing a complete API specification.
Create REST and GraphQL integration guides covering authentication flows, pagination strategies, rate limiting, error handling, retry logic, and SDK wrapper patterns. Produces implementation-ready reference documents with code examples.
Design and document automation workflows for n8n, Make, Zapier, and Power Automate. Covers trigger-action chain mapping, conditional branching, error handling, retry logic, and workflow diagrams with platform-specific node references.
Design BI reports and analytics views — with metric definitions, data source mapping, filter logic, drill-down paths, and refresh schedules that enable self-service decision-making.