architecture-decision-records

architecture-decision-records is a skill for Claude Code, Codex from rmyndharis/antigravity-skills. It costs 41 tokens per session (2,993 once invoked), scanned A, a copy of architecture-decision-records, MIT.

A guide for Architecture Decision Records, or ADRs—short documents that record why a significant technical choice was made. It covers the context, alternatives, decision, trade-offs, consequences, and later status.

In plain words
What is it for?
Use it when adopting a framework, choosing database technology, making a major architectural change, reviewing past design choices, or documenting their consequences.
Why use it?
It preserves the reasoning behind important design choices so future developers do not have to reconstruct it. It also helps teams compare options and understand the effects of a decision.

Skill for Claude CodeCodex

Written for no agent in particular: nothing here depends on one.

Good fit Use it when adopting a framework, choosing database technology, making a major architectural change, reviewing past design choices, or documenting their consequences.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/rmyndharis/antigravity-skills/architecture-decision-records
About the project

Antigravity Skill Vault is a collection of reusable Agent Skills for Google Antigravity, covering software development, operations, security, and business work. It is for people who want Antigravity agents to follow specialized expertise, personas, and structured workflows. The catalogue skills are entries from this collection.

rmyndharis/antigravity-skills · 1,529 stars · on GitHub

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add rmyndharis/antigravity-skills --skill architecture-decision-records
Clone the repo
git clone --depth 1 https://github.com/rmyndharis/antigravity-skills

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for architecture-decision-records

README.md
[![agentmods](https://agentmods.dev/badge/skills/rmyndharis/antigravity-skills/architecture-decision-records/github.svg)](https://agentmods.dev/skills/rmyndharis/antigravity-skills/architecture-decision-records)
Your own site
<a href="https://agentmods.dev/skills/rmyndharis/antigravity-skills/architecture-decision-records"><img src="https://agentmods.dev/badge/skills/rmyndharis/antigravity-skills/architecture-decision-records/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for architecture-decision-records

Your own site · 80×15
<a href="https://agentmods.dev/skills/rmyndharis/antigravity-skills/architecture-decision-records"><img src="https://agentmods.dev/badge/skills/rmyndharis/antigravity-skills/architecture-decision-records.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 41 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 2,993 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin 77% copy Near-identical to another mod in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00041 $0.02993
Opus 5 $0.00020 $0.01496
Sonnet 5 $0.00008 $0.00599
Haiku 4.5 $0.00004 $0.00299

Measured 13d ago against content hash 18eea04db3df, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-12, from the pricing page.

Security

Grade A, and why

architecture-decision-records scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 13d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

Origin

This is a copy

77% identical to architecture-decision-records — 18 lines differ, which has more behind it and is treated as the original. This page carries a canonical link to it rather than competing with it.

skills/architecture-decision-records/SKILL.md · 442 lines

How it starts

The opening of the file, as written. The whole thing — 442 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Architecture Decision Records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

Use this skill when

  • Making significant architectural decisions
  • Documenting technology choices
  • Recording design trade-offs
  • Onboarding new team members
  • Reviewing historical decisions
  • Establishing decision-making processes

Do not use this skill when

  • You only need to document small implementation details
  • The change is a minor patch or routine maintenance
  • There is no architectural decision to capture

Instructions

  1. Capture the decision context, constraints, and drivers.
  2. Document considered options with tradeoffs.
  3. Record the decision, rationale, and consequences.
  4. Link related ADRs and update status over time.

Core Concepts

1. What is an ADR?

An Architecture Decision Record captures:

  • Context: Why we needed to make a decision
  • Decision: What we decided
  • Consequences: What happens as a result

2. When to Write an ADR

Write ADR Skip ADR
New framework adoption Minor version upgrades
Database technology choice Bug fixes
API design patterns Implementation details
Security architecture Routine maintenance
Integration patterns Configuration changes

3. ADR Lifecycle

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

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**: Weaker JSON support, no built-in full-text search (need
  Elasticsearch), no geospatial without extensions

### Option 3: MongoDB
- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: No ACID for multi-document transactions (at decision time),
  team has limited experience, requires 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, PostGIS) reduce
   infrastructure complexity
3. **Team familiarity** with SQL databases reduces learning curve
4. **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`

Read the full file on GitHub · 442 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 13d ago First seen · 442 lines · 41 tokens per session scan A 18eea04db3df

Subscribe to this mod's changes

architecture-decision-records is a skill published in the GitHub repository rmyndharis/antigravity-skills (1,529 stars, last pushed 1mo ago), licensed MIT. It adds 41 tokens to every session and 2,993 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. It is 77% identical to architecture-decision-records, differing in 18 lines, and is treated as a copy.

Related

Other skills, from other repositories

code-review

Systematic code review skill covering both requesting a review (pre-commit checklist) and receiving and responding to review feedback. Checks code quality, security, test coverage, architectural alignment, and documentation before any code is committed.

omergocmen/vibe-coder-kit · 47 tokens

writing-plans

TÜRKÇE AÇIKLAMA ─────────────── Bu skill, onaylanmış bir scope veya fikirden somut, uygulanabilir bir implementasyon planı üretir. Hangi dosya değişecek, hangi sırayla, kim yapacak, ne kadar sürecek, hangi riskler var — hepsini netleştirir. Planın çıktısı doğrudan executing-plans veya dispatching-parallel-agents…

omergocmen/vibe-coder-kit · 0 tokens

brainstorming

TÜRKÇE AÇIKLAMA ─────────────── Bu skill, bir fikir veya problemi Sokratik yöntemle rafine eder. Agent sana cevap vermez — sorular sorar. Bu sorular aracılığıyla fikrin netleşir, varsayımlar sorgulanır, kapsam belirlenir ve gerçek ihtiyaç ortaya çıkar. "Ne yapalım?" sorusunu "Tam olarak ne yapmamız gerekiyor ve…

omergocmen/vibe-coder-kit · 0 tokens

project-context-primer

Run this skill at the very start of any new conversation or agent session before writing a single line of code. It loads the project's architectural decisions, conventions, known gotchas, and current task status so the agent operates with full context — not as a blank slate.

omergocmen/vibe-coder-kit · 58 tokens

test-driven-execution

Before writing any implementation code, define the acceptance criteria and test cases that the code must satisfy. Agents then write code to pass these tests — not to match a vague description. Eliminates "it works on my machine" and "I think this is what you wanted" outcomes.

omergocmen/vibe-coder-kit · 61 tokens

idea-validator

Structured validation framework that scores product ideas. Use when evaluating problem severity, willingness-to-pay, or founder-market fit. For market intelligence, see market-research.

tuliosousapro/SaaS-blueprint · 35 tokens