Command: gears adr

Manage Architectural Decision Records (ADRs) that document your working code patterns and technical decisions.

Overview

The adr command helps you create and manage ADRs - documents that explain important technical decisions, design patterns, and architectural choices in your codebase. ADRs answer the "why" behind your working code, making it easier for teammates and AI agents to understand your technical approach.

Syntax

run gears adr new <title>     # Create a new ADR
run gears adr list            # Show all ADRs

Subcommands

`gears adr new <title>`

Creates a new ADR file with a standard template.

Arguments:

<title> - ADR title (will be numbered sequentially)

Creates: .gears/adr/NNN-{slug}.md (where NNN is the next sequential number)

`gears adr list`

Lists all ADRs in the project in chronological order.

Displays:

ADR number
Title
Status (Proposed, Accepted, Deprecated, Superseded)

What Are ADRs?

Architectural Decision Records document:

What: Technical design decisions
Why: Reasoning and context for the decision
When: When the decision was made
Consequences: Trade-offs and implications

ADRs are especially useful for:

Onboarding new team members
Explaining code architecture to AI agents
Remembering why decisions were made months/years later
Avoiding repeated discussions about settled decisions

Working with AI Agents

ADRs are essential for teaching AI agents about your codebase. Always have your agent:

Run gears adr list to see what architectural decisions exist
Run gears adr new "Decision Title" when making technical choices
Read ADR files to understand why the code is structured the way it is

Example:

❌ "Why are we using PostgreSQL?"
✅ "Run gears adr list and open the database decision ADR"

ADRs help agents avoid suggesting changes that contradict established architectural decisions.

Examples

Create Your First ADR

$ run gears adr new "Use PostgreSQL for primary database"
✓ Created ADR: .gears/adr/001-use-postgresql-for-primary-database.md

Document:
  - Context: What problem does this solve?
  - Decision: What did you decide to do?
  - Consequences: What are the trade-offs?
  - Status: Proposed | Accepted | Deprecated | Superseded

The ADR file is created with this template:

# ADR-001: Use PostgreSQL for Primary Database

**Status:** Proposed
**Date:** 2026-03-25
**Deciders:** _[who made this decision]_

## Context

_What is the issue we're facing that motivates this decision?_

## Decision

_What is the change that we're proposing and/or doing?_

## Consequences

### Positive

-

### Negative

-

### Neutral

-

## Alternatives Considered

_What other options were evaluated?_

## References

- _Links, documentation, discussions_

List All ADRs

$ gears adr list

Architectural Decision Records:

001 - Use PostgreSQL for Primary Database (Accepted)
002 - API Authentication with JWT Tokens (Accepted)
003 - Frontend Framework Selection (Accepted)
004 - Caching Strategy with Redis (Proposed)
005 - Microservices vs Monolith (Superseded by 008)

Create and Document a Decision

# 1. Make a technical decision during development
# Decision: We'll use Redis for caching

# 2. Create the ADR
$ gears adr new "Redis Caching Strategy"
✓ Created ADR: .gears/adr/004-redis-caching-strategy.md

# 3. Edit and populate the ADR
# (Fill in Context, Decision, Consequences)

# 4. Set status to Accepted
# (Update Status field to "Accepted")

# 5. Reference in code
# Add comment in code: "See ADR-004 for caching strategy"

# 6. Sync to cloud
$ gears sync push

ADR File Structure

Status Field

ADRs progress through these statuses:

Proposed - Decision is being discussed
Accepted - Decision is approved and implemented
Deprecated - Decision is outdated but still in use
Superseded - Decision replaced by newer ADR (reference it)

Update status by editing the ADR file:

**Status:** Accepted

Full Example ADR

# ADR-002: API Authentication with JWT Tokens

**Status:** Accepted
**Date:** 2026-03-20  
**Deciders:** Sarah (Tech Lead), Mike (Backend Team)

## Context

Our mobile and web applications need to authenticate API requests securely. We need a solution that:

- Works across platforms (web, iOS, Android)
- Scales to millions of users
- Provides stateless authentication
- Allows token refresh without re-authentication
- Is industry standard and well-supported

## Decision

We will use JWT (JSON Web Tokens) for API authentication with Laravel Sanctum.

**Implementation details:**

- Tokens issued upon successful login
- Access tokens expire after 15 minutes
- Refresh tokens expire after 30 days
- Tokens signed with RS256 algorithm
- Public key rotated annually
- Tokens include: user_id, email, issued_at, expires_at

## Consequences

### Positive

- Stateless authentication reduces server load
- Works seamlessly across all client platforms
- Industry standard with excellent library support
- Self-contained tokens (no database lookup per request)
- Enables microservices architecture in future

### Negative

- Cannot revoke individual tokens before expiration (mitigation: short expiration time)
- Slightly larger payload than session IDs
- Requires careful key management and rotation
- More complex than simple session authentication

### Neutral

- Team needs to learn JWT best practices
- Requires infrastructure for key storage/rotation
- Mobile apps must implement token refresh logic

## Alternatives Considered

**Session-based authentication:**

- Pros: Simple, easy to revoke, smaller cookies
- Cons: Requires sticky sessions, harder to scale, doesn't work well for mobile
- Rejected because: Mobile app support and scalability concerns

**OAuth2 with Auth0:**

- Pros: Fully managed, includes social login, scales infinitely
- Cons: External dependency, monthly cost, vendor lock-in
- Rejected because: Want to maintain control and reduce dependencies

**Opaque tokens with database lookup:**

- Pros: Easy to revoke, simple implementation
- Cons: Database hit on every request, doesn't scale well
- Rejected because: Performance concerns at scale

## References

- [JWT.io - Introduction](https://jwt.io/introduction)
- [Laravel Sanctum Documentation](https://laravel.com/docs/sanctum)
- [RFC 7519 - JWT Specification](https://tools.ietf.org/html/rfc7519)
- Team discussion: Slack thread on 2026-03-18
- Story: [story-user-authentication.md](../story/story-user-authentication.md)

Common Workflows

Document as You Decide

# During development: Make a decision
"We should use Redis for session storage instead of database"

# Immediately document it
gears adr new "Redis for Session Storage"

# Fill in the ADR with fresh context
# - Why did we decide this?
# - What alternatives did we consider?
# - What are the trade-offs?

# Set to Accepted and sync
gears sync push

Pre-Implementation Decision

# Before building: Research and decide
# Read about different approaches
# Discuss with team
# Make decision

# Create ADR first
gears adr new "Event Sourcing for Order Management"

# Document everything while it's fresh
# Status: Proposed

# Team reviews and approves
# Status: Accepted

# Now implement based on ADR

Superseding Old Decisions

# Create new ADR that replaces old one
gears adr new "Switch to Event-Driven Architecture"

# In the new ADR:
**Status:** Accepted

This ADR supersedes [ADR-005: Microservices vs Monolith](./005-microservices-vs-monolith.md).

# Update old ADR:
**Status:** Superseded by [ADR-008](./008-switch-to-event-driven-architecture.md)

Best Practices

When to Create an ADR

Create an ADR for:

✅ Technology choices (database, framework, language)
✅ Architecture decisions (monolith, microservices, event-driven)
✅ Design patterns (repository pattern, CQRS, DDD)
✅ Security approaches (auth method, encryption strategy)
✅ Performance decisions (caching, queuing, optimization)
✅ Deployment strategy (containers, serverless, traditional)

Don't create ADRs for:

❌ Minor coding preferences (use linters/formatters)
❌ Temporary workarounds (use code comments)
❌ Feature requirements (use stories)
❌ Routine bug fixes

Writing Good ADRs

Do:

✅ Write ADRs when you make the decision (context is fresh)
✅ Include specific details and examples
✅ List alternatives you considered
✅ Be honest about trade-offs (no silver bullets)
✅ Link to relevant documentation and discussions
✅ Update status as decisions evolve

Don't:

❌ Write novel-length ADRs (concise is better)
❌ Skip the "why" (context is crucial)
❌ Delete superseded ADRs (update status instead)
❌ Make it perfect (done is better than perfect)

ADR Numbering

ADRs are numbered sequentially:

.gears/adr/
├── 001-initial-database-choice.md
├── 002-api-authentication-method.md
├── 003-frontend-framework-selection.md
├── 010-caching-strategy.md
└── 015-deployment-approach.md

Numbers don't need to be consecutive (gaps are fine).

Linking ADRs to Code

Reference ADRs in your code:

// See ADR-002 for authentication approach
class AuthController extends Controller
{
    // Implementation following ADR-002 JWT strategy
}

# This caching strategy is documented in ADR-010
@cache.memoize(timeout=3600)
def get_user_profile(user_id):
    pass

Troubleshooting

Wrong ADR Number

Problem: Created ADR with wrong number

Solution: Rename the file manually:

# Wrong number
mv .gears/adr/005-redis-caching.md .gears/adr/004-redis-caching.md

# Update references in other files if any
grep -r "ADR-005" .gears/

Duplicate Numbers

Problem: Two ADRs with same number

Solution: Renumber the newer one:

ls .gears/adr/  # Find duplicates
mv .gears/adr/003-duplicate.md .gears/adr/006-new-number.md

Finding Specific ADR

Problem: Can't remember which ADR documented something

Solution: Search across all ADRs:

# Search by keyword
grep -r "PostgreSQL" .gears/adr/

# List all ADRs
gears adr list

# Search by date
ls -lt .gears/adr/

# Full-text search
find .gears/adr/ -name "*.md" -exec grep -l "caching" {} \;

ADR Management

Regular Review

# Quarterly: Review all ADRs
gears adr list

# Update outdated ones
# - Deprecated: Still in use but outdated
# - Superseded: Replaced by newer decision

Team Collaboration

# Developer A: Creates ADR as "Proposed"
gears adr new "Use GraphQL for API"
# Status: Proposed
gears sync push

# Developer B: Reviews and comments
gears sync pull
# Read and provide feedback

# Developer A: Updates based on feedback
# Status: Accepted
gears sync push

Related Commands

gears init - Creates the adr/ directory
gears story - Feature stories often reference ADRs
gears session - Document decisions made in sessions
gears sync - Share ADRs with team via cloud

Next Steps

After creating an ADR:

Fill in all sections thoroughly while context is fresh
Discuss with team if status is "Proposed"
Set to Accepted once decision is final
Reference in code with comments linking to ADR number
Update related stories to reference the ADR
Sync to cloud so team has access

← Command: story | Command: sync →