Index of every page on this site: llms.txt
All skills
wshobson avatar

/architecture-decision-records

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

Use this Skill: https://skilld.dev/gh/wshobson/agents/architecture-decision-records

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesdecision-templates.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Templates

Template 1: Standard ADR (MADR Format)

# ADR-0001: Use PostgreSQL as Primary Database

## Status

Accepted

## Context

We need to select a primary database for our new e-commerce platform. The system
will handle:

- ~10,000 concurrent users
- Complex product catalog with hierarchical categories
- Transaction processing for orders and payments
- Full-text search for products
- Geospatial queries for store locator

The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
compliance for financial transactions.

## Decision Drivers

- **Must have ACID compliance** for payment processing
- **Must support complex queries** for reporting
- **Should support full-text search** to reduce infrastructure complexity
- **Should have good JSON support** for flexible product attributes
- **Team familiarity** reduces onboarding time

## Considered Options

### Option 1: PostgreSQL

- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
  search, PostGIS for geospatial, team has experience
- **Cons**: Slightly more complex replication setup than MySQL

### Option 2: MySQL

- **Pros**: Very familiar to team, simple replication, large community
- **Cons**: JSON querying/indexing differs from PostgreSQL JSONB; validate the
  required operators and indexes. Built-in FULLTEXT and spatial support exist,
  but their functions and limitations must be checked against this workload.
  See the [MySQL index reference](https://dev.mysql.com/doc/refman/8.4/en/create-index.html).

### Option 3: MongoDB

- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: [Multi-document transactions](https://www.mongodb.com/docs/manual/core/write-operations-atomicity/)
  are supported on replica sets and sharded clusters but can cost more than
  single-document writes; the team has limited experience and needs schema design discipline.

## Decision

We will use **PostgreSQL 15** as our primary database.

## Rationale

PostgreSQL provides the best balance of:

1. **ACID compliance** essential for e-commerce transactions
2. **Built-in capabilities** (full-text search, JSONB) reduce infrastructure complexity
3. **Added extensions**: PostGIS supplies geospatial capabilities after server
   installation and [database enablement](https://postgis.net/documentation/getting_started/).
4. **Team familiarity** with SQL databases reduces learning curve
5. **Mature ecosystem** with excellent tooling and community support

The slight complexity in replication is outweighed by the reduction in
additional services (no separate Elasticsearch needed).

## Consequences

### Positive

- Single database handles transactions, search, and geospatial queries
- Reduced operational complexity (fewer services to manage)
- Strong consistency guarantees for financial data
- Team can leverage existing SQL expertise

### Negative

- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
- Vertical scaling limits may require read replicas sooner
- Some team members need PostgreSQL-specific training

### Risks

- Full-text search may not scale as well as dedicated search engines
- Mitigation: Design for potential Elasticsearch addition if needed

## Implementation Notes

- Use JSONB for flexible product attributes
- Implement connection pooling with PgBouncer
- Set up streaming replication for read replicas
- Use pg_trgm extension for fuzzy search

## Related Decisions

- ADR-0002: Caching Strategy (Redis) - complements database choice
- ADR-0005: Search Architecture - may supersede if Elasticsearch needed

## References

- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`

Template 2: Lightweight ADR

# ADR-0012: Adopt TypeScript for Frontend Development

**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob, @charlie

## Context

Our React codebase has grown to 50+ components with increasing bug reports
related to prop type mismatches and undefined errors. PropTypes provide
runtime-only checking.

## Decision

Adopt TypeScript for all new frontend code. Migrate existing code incrementally.

## Consequences

**Good**: Catch type errors at compile time, better IDE support, self-documenting
code.

**Bad**: Learning curve for team, initial slowdown, build complexity increase.

**Mitigations**: TypeScript training sessions, allow gradual adoption with
`allowJs: true`.

Template 3: Y-Statement Format

# ADR-0015: API Gateway Selection

In the context of **building a microservices architecture**,
facing **the need for centralized API management, authentication, and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx solution**,
to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
accepting that **we need to manage Kong infrastructure ourselves**.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides comprehensive guidelines and templates for documenting technical decisions through Architecture Decision Records (ADRs). It references official documentation for reputable database technologies and standard developer tools. No security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 4220308. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last month
  • Documentation
  • adr
  • architecture
  • decision-records
  • decision-making
  • technical-decisions
  • design-patterns
  • process

README badge

README badge for wshobson/agents/architecture-decision-records

Captures context, decision, and consequences for significant technical choices using templates like MADR format, lightweight ADR, and Y-statements. Includes patterns for managing ADR lifecycles, deprecations, and review processes with directory structure and automation tools.

Generated from the current SKILL.md.

What format should I use for writing ADRs?
The skill provides five templates: Standard ADR (MADR format with full context and rationale), Lightweight ADR (minimal format for simpler decisions), Y-Statement (concise single-paragraph format), Deprecation ADR (for superseding prior decisions), and RFC-style (for proposals requiring team discussion). Choose based on decision complexity and team needs.
When should I write an ADR versus skip it?
Write ADRs for significant decisions like framework adoption, database choice, API design, and security architecture. Skip them for minor version upgrades, bug fixes, implementation details, and routine maintenance.
How do I manage ADRs as a team?
Organize ADRs in a `docs/adr/` directory with sequential numbering, maintain an index README, use a review checklist, and optionally automate with adr-tools. The skill includes templates for directory structure, an ADR index, and a review process.
How do I handle decisions that change or become obsolete?
Mark the original ADR as Deprecated or Superseded and create a new ADR explaining the context change, why the old decision no longer fits, and the migration plan. Link the two ADRs together for traceability.
Can I use lightweight ADRs or must I follow the full template?
The skill supports multiple formats from lightweight (status, context, decision, consequences in minimal form) to comprehensive. Choose the format that matches your decision's scope and team process.

Generated from the current SKILL.md. These answers refresh after source changes.