Rust Project ADR Setup Guide

A companion guide to the main ADR-SYSTEM-GUIDE.md, specifically tailored for Rust projects.

Quick Start for Rust Projects

1. Initial Setup

# In your Rust project root (where Cargo.toml lives)
mkdir -p .claude/{templates,branches,merged}

2. Copy Core Files

From an existing ADR system or template:

ADR-SYSTEM-GUIDE.md - The main guide
adr-index.toml - Project index
adr-helper.sh - Automation scripts
templates/ - ADR templates

3. Rust-Specific Configuration

ADR Index Configuration

# .claude/adr-index.toml - Rust project template

[metadata]
version = "1.0"
language = "rust"
project_type = "library" # or "binary", "workspace"
description = "Index of architectural decisions for [PROJECT_NAME]"

[categories.performance]
description = "Performance optimizations, benchmarking, and scaling decisions"
branches = []

[categories.api-design]
description = "Public API evolution, breaking changes, and ergonomics"
branches = []

[categories.safety]
description = "Memory safety, unsafe code, and concurrency patterns"
branches = []

[categories.dependencies]
description = "Crate selection, version pinning, and dependency management"
branches = []

[categories.testing]
description = "Testing strategies, property testing, and fuzzing"
branches = []

[categories.architecture]
description = "Module organization, trait design, and system structure"
branches = []

[categories.tooling]
description = "Build tools, CI/CD, and development environment"
branches = []

[tags]
breaking-change = []
performance = []
unsafe = []
async = []
proc-macro = []
no-std = []

4. Rust Project Structure Integration

Workspace Projects

my-rust-workspace/
├── .claude/              # ADR system at workspace root
│   ├── ADR-SYSTEM-GUIDE.md
│   ├── adr-index.toml
│   └── branches/
├── Cargo.toml           # Workspace manifest
├── crate-a/
│   └── Cargo.toml
└── crate-b/
    └── Cargo.toml

Single-Crate Projects

my-rust-crate/
├── .claude/              # ADR system at crate root
├── Cargo.toml
├── src/
└── tests/

Rust-Specific ADR Categories

Performance ADRs

Track decisions about:

Algorithm choices and complexity analysis
Memory allocation strategies
Zero-copy optimizations
SIMD usage decisions
Benchmark results and performance regressions

Example Tags: performance, optimization, benchmark, memory

API Design ADRs

Document choices about:

Public trait design
Breaking vs non-breaking changes
Ergonomics vs performance trade-offs
Generic parameter design
Error type design

Example Tags: api-design, breaking-change, ergonomics, traits

Safety ADRs

Record decisions about:

Unsafe code usage and justification
Memory safety guarantees
Concurrency patterns (Send/Sync)
FFI boundaries and safety

Example Tags: unsafe, safety, concurrency, ffi

Dependencies ADRs

Track choices about:

Major dependency additions
Version pinning rationale
Feature flag selections
Optional vs required dependencies

Example Tags: dependencies, features, versioning

Rust-Specific ADR Template

# Branch ADR: [branch-name]

## Meta
- **Branch**: [branch-name]
- **Type**: feat/fix/chore/refactor
- **Created**: YYYY-MM-DD
- **Status**: Active/Merged
- **Author**: [name]
- **PR**: #[number]
- **Merged**: YYYY-MM-DD (when merged)

## Rust-Specific Context
- **Crate**: [crate-name] (for workspace projects)
- **MSRV Impact**: [none/minor/major]
- **Breaking Changes**: [none/minor/major]
- **Safety Impact**: [none/unsafe-added/unsafe-removed]
- **Performance Impact**: [measured/estimated/unknown]

## Problem Statement
### Context
[What's the current situation?]

### Goals
[What are we trying to achieve?]

### Non-Goals
[What are we explicitly not solving?]

### Rust-Specific Considerations
- **Memory Safety**: [any safety implications]
- **Performance Requirements**: [latency/throughput/memory]
- **API Stability**: [compatibility requirements]
- **Feature Dependencies**: [required Cargo features]

## Decision Record

### Options Considered
1. **Option 1**: [description]
   - Pros: [benefits]
   - Cons: [drawbacks]
   - Rust considerations: [language-specific factors]

2. **Option 2**: [description]
   - Pros: [benefits]
   - Cons: [drawbacks]
   - Rust considerations: [language-specific factors]

### Decision
[What we decided and why]

### Rust Implementation Details
- **Public API Changes**: [new/modified/removed APIs]
- **Dependencies Added/Removed**: [crate changes]
- **Feature Flags**: [new/modified features]
- **MSRV Changes**: [minimum supported Rust version]
- **Unsafe Code**: [usage justification if any]

### Trade-offs Accepted
[What we're giving up for this solution]

## Implementation

### Code Changes
- [ ] Core implementation
- [ ] Tests (unit/integration/doc)
- [ ] Documentation updates
- [ ] Examples updates
- [ ] Benchmarks (if performance critical)

### Cargo.toml Changes
- [ ] Dependencies
- [ ] Features
- [ ] MSRV
- [ ] Metadata

### Quality Assurance
- [ ] Clippy warnings addressed
- [ ] Rustfmt applied
- [ ] No unsafe code or justified
- [ ] Benchmarks run (if applicable)
- [ ] Miri tests pass (if unsafe code)

## Challenges & Solutions
[Implementation challenges and how we solved them]

## Impact Assessment

### Performance Impact
- **Benchmarks**: [results or N/A]
- **Memory Usage**: [impact or N/A]
- **Compile Time**: [impact or N/A]

### Compatibility Impact
- **Breaking Changes**: [list any breaking changes]
- **MSRV**: [minimum Rust version required]
- **Platform Support**: [any platform-specific considerations]

## Outcome & Lessons
[What we learned and what we'd do differently]

## Tags
`[tag1, tag2, tag3]`

Common Rust ADR Patterns

Performance Decision Template

### Performance Analysis
- **Baseline**: [current performance metrics]
- **Target**: [performance goals]
- **Measurement Method**: [how we're measuring]
- **Results**: [actual improvements achieved]
- **Trade-offs**: [what we sacrificed for performance]

API Design Decision Template

### API Design Rationale
- **Ergonomics**: [ease of use considerations]
- **Safety**: [compile-time vs runtime guarantees]
- **Flexibility**: [extensibility and composability]
- **Consistency**: [alignment with ecosystem patterns]
- **Breaking Changes**: [impact on existing users]

Dependency Decision Template

### Dependency Analysis
- **Alternatives Considered**: [other crates evaluated]
- **Selection Criteria**: [what factors mattered]
- **Maintenance Status**: [activity and reliability]
- **Feature Overlap**: [avoiding duplicate functionality]
- **Build Impact**: [compile time and binary size]

Integration with Rust Tooling

Cargo Integration

Document feature flag strategies
Track MSRV upgrade decisions
Record dependency audit results

CI/CD Integration

Reference ADRs in PR templates
Link performance regression investigations
Document security audit decisions

Documentation Integration

Reference ADRs in rustdoc comments
Link to relevant ADRs in examples
Include ADR context in migration guides

Rust Community Considerations

RFC Alignment

Reference relevant Rust RFCs
Document unstable feature usage
Track edition migration decisions

Ecosystem Compatibility

Document adherence to API guidelines
Track semver compatibility decisions
Reference ecosystem survey results

Getting Started Checklist for Rust Projects

Initial Setup (Day 1)

Create .claude/ directory structure
Copy and customize adr-index.toml
Set up Rust-specific categories and tags
Create first ADR for project architecture

First Month

Document major dependency decisions
Create ADRs for API design choices
Record performance optimization decisions
Establish testing strategy ADRs

Ongoing

Update ADRs before major refactoring
Reference ADRs in code reviews
Link ADRs to GitHub issues/PRs
Regular ADR index maintenance

Examples from Rust Projects

Performance ADR Example

# Branch ADR: feat/zero-copy-parsing

## Rust-Specific Context
- **Performance Impact**: Measured 40% improvement in parsing throughput
- **Memory Impact**: 60% reduction in allocations
- **Unsafe Code**: Added 3 unsafe blocks with careful justification
- **MSRV Impact**: None (uses stable features only)

API Design ADR Example

# Branch ADR: feat/async-api-redesign

## Rust-Specific Context
- **Breaking Changes**: Major - requires 2.0 version bump
- **Async Runtime**: Tokio-agnostic design chosen
- **Trait Design**: Used associated types over generics for better ergonomics

This guide provides Rust-specific patterns and considerations to complement the general ADR system, ensuring decisions are documented with appropriate technical context for Rust development.

joshrotenberg/RUST-PROJECT-SETUP.md