Rust Architect

A comprehensive Claude Code skill for architecting production-ready Rust applications with complete documentation, ADRs, guardrails, and handoff materials.

🎯 Origin

This project is adapted from [elixir-architect](https://github.com/maxim-ist/elixir-architect) and generated by Claude Code.

• Original Inspiration: maxim-ist/elixir-architect - Elixir project architecture skill
• Adaptation: Rust ecosystem (tokio, axum, sqlx) with Rust-specific best practices
• Generated by: Claude Code - AI-powered development assistant
• Tech Stack: Rust 1.83+, tokio 1.48+, axum 0.8+, sqlx 0.8+

Overview

Rust Architect is a Claude Code skill that acts as an expert system architect, creating comprehensive project documentation packages that enable Director and Implementor AI agents to successfully build complex Rust systems following industry best practices.

This skill creates:

• ✅ Complete directory structure for multi-crate workspace projects
• ✅ Architecture documentation (8 comprehensive files)
• ✅ Architecture Decision Records (ADRs)
• ✅ AI collaboration guardrails (Director/Implementor roles)
• ✅ Handoff documentation with workflows
• ✅ Domain-specific adaptations (Web Services, CLI Tools, Backend Systems)

Key Features

Expert Consultation

Automatically launches Task agents to research:

• Domain-specific architecture patterns in Rust
• axum/tokio/sqlx best practices
• Rust workspace organization patterns
• Ownership and borrowing strategies
• Superpowers framework for implementation planning

Comprehensive Documentation

Generates 20+ documentation files including:

• Foundation: README.md, CLAUDE.md with AI context
• Architecture: 8 detailed architecture documents (~6,000 lines)
• Guardrails: NEVER_DO, ALWAYS_DO, role definitions, review checklist
• Decisions: ADRs with alternatives and trade-offs
• Handoff: Complete workflow for Director/Implementor collaboration

Domain-Specific Adaptations

Special handling for:

• Web Services: axum/actix patterns, async runtime, connection pooling
• CLI Tools: clap patterns, configuration management, error reporting
• Backend Systems: Background tasks, message queues, event processing

Proven Architectural Patterns

• Ownership and borrowing as architectural boundaries
• Zero-cost abstractions with compile-time guarantees
• Fearless concurrency with async/await
• Error handling with Result<T, E> and proper propagation
• Type-driven development with strong type safety
• Cargo workspaces for modular organization
• Test-driven development with unit/integration/property tests

Installation

Method 1: Claude Code Plugin (Recommended)

# In Claude Code, run:
/plugin install github.com/nanlong/rust-architect

The skill will be automatically available as rust-architect.

Method 2: Manual Installation

# Clone the repository
git clone https://github.com/nanlong/rust-architect.git

# Copy skill to Claude Code skills directory
mkdir -p ~/.claude/skills
cp -r rust-architect/skills/rust-architect ~/.claude/skills/

Verification

To verify the skill is installed:

# In Claude Code
/skills list

You should see rust-architect in the list.

Usage

Basic Invocation

# In Claude Code
/skills rust-architect

Or simply describe your need:

I need to architect a web service using Rust, axum, and sqlx with
complete documentation for Director and Implementor AI collaboration

Claude will automatically invoke the skill if appropriate.

The Skill Will Ask You

The skill gathers requirements through these questions:

1. Project Domain: What system are you building? (e.g., web service, CLI tool, data processing)
2. Tech Stack: Confirm Rust + tokio + axum + sqlx?
3. Project Location: Where to create files? (provide absolute path)
4. Structure Style: Single crate, binary + library, or multi-crate workspace?
5. Special Requirements: Async runtime? Web framework? Database? CLI interface?
6. Scale Targets: Expected load and performance requirements
7. AI Collaboration: Using Director/Implementor workflow?

Example Session

User: Create architecture docs for a REST API service at /Users/me/projects/api_server

Claude: [Invokes rust-architect skill]

Skill: I'll help architect your REST API service. Let me gather some details:

1. Confirm tech stack: Rust 1.75+, tokio 1.35+, axum 0.7+, sqlx 0.7+?
2. Structure: Multi-crate workspace with separate api/core/db crates?
3. Special requirements:
   - Authentication needed? (JWT, sessions)
   - Expected requests per second?
   - Real-time features (WebSockets)?
4. Will you use Director/Implementor AI workflow?

[After answering questions, skill launches expert Task agents]

Skill: Researching REST API patterns in Rust...
      Analyzing axum middleware and state management...
      Studying Rust workspace organization...

[Creates complete documentation package]

Skill: ✅ Project architecture complete!

Created 23 files at /Users/me/projects/api_server:
- Foundation docs (README, CLAUDE.md)
- 5 guardrail documents
- 8 architecture documents
- 4 Architecture Decision Records
- Handoff documentation

Ready for Director AI to create first feature design!

What Gets Created

The skill generates this structure at your specified location:

project_root/
├── README.md                      # Project overview
├── CLAUDE.md                      # Complete AI agent context
├── docs/
│   ├── HANDOFF.md                # Director/Implementor workflow
│   ├── architecture/             # 8 comprehensive architecture docs
│   │   ├── 00_SYSTEM_OVERVIEW.md
│   │   ├── 01_DOMAIN_MODEL.md
│   │   ├── 02_DATA_LAYER.md
│   │   ├── 03_CORE_LOGIC.md
│   │   ├── 04_BOUNDARIES.md
│   │   ├── 05_CONCURRENCY.md
│   │   ├── 06_ASYNC_PATTERNS.md
│   │   └── 07_INTEGRATION_PATTERNS.md
│   ├── design/                   # Empty - Director fills during features
│   ├── plans/                    # Empty - Director creates Superpowers plans
│   ├── api/                      # Empty - Director documents APIs
│   ├── decisions/                # Architecture Decision Records
│   │   ├── ADR-001-framework-choice.md
│   │   ├── ADR-002-error-strategy.md
│   │   ├── ADR-003-ownership-patterns.md
│   │   └── [domain-specific ADRs]
│   └── guardrails/              # AI collaboration rules
│       ├── NEVER_DO.md          # Critical prohibitions (15 items)
│       ├── ALWAYS_DO.md         # Mandatory practices (25 items)
│       ├── DIRECTOR_ROLE.md     # Architect AI role definition
│       ├── IMPLEMENTOR_ROLE.md  # Coder AI role definition
│       └── CODE_REVIEW_CHECKLIST.md

Documentation Highlights

NEVER_DO.md

15 critical prohibitions with code examples:

• Never use f64/f32 for money (use rust_decimal or integer cents)
• Never unwrap in library code (return Result<T, E>)
• Never clone without justification (use references when possible)
• Never block async runtime (use tokio::time::sleep not std::thread::sleep)
• Never use Arc<Mutex<T>> without justification (prefer message passing)
• And 10 more with detailed rationale

ALWAYS_DO.md

25 mandatory practices across:

• Memory safety (ownership, borrowing, lifetimes)
• Testing (TDD, edge cases, property tests with proptest)
• Code quality (clippy, rustfmt, documentation)
• Architecture (separation of concerns, error propagation, async patterns)

Architecture Documents

Each of the 8 architecture files includes:

• Complete explanations with context
• Concrete code examples (valid Rust that compiles)
• Performance considerations
• Testing patterns
• Common mistakes and corrections

ADRs (Architecture Decision Records)

Each ADR documents:

• The decision made
• Context and rationale
• Alternatives considered with pros/cons
• Why alternatives were rejected
• Implementation guidelines with DO/DON'T examples
• Validation criteria
• Review schedule

Use Cases

Web Services (axum/actix-web)

Perfect for:

• REST APIs
• GraphQL services
• Microservices
• API gateways
• Real-time services with WebSockets

Special handling:

• Request/response patterns
• Middleware architecture
• State management with Arc
• Error response formatting
• Connection pooling strategies

CLI Tools (clap)

Perfect for:

• Command-line utilities
• System administration tools
• Data processing pipelines
• Development tools
• Configuration management

Special handling:

• Argument parsing patterns
• Configuration file handling
• Progress indicators
• Error reporting to terminal
• Subcommand organization

Backend Services

Perfect for:

• Background job processing
• Event processing systems
• Data pipelines
• Message queue consumers
• Scheduled tasks

Special handling:

• Async task patterns with tokio
• Channel-based communication
• Graceful shutdown
• Error recovery strategies
• Health monitoring

Director/Implementor Workflow

One of the unique features of this skill is creating documentation that enables a two-AI workflow:

Director AI (Architect)

• Creates feature designs
• Makes architectural decisions
• Writes implementation plans (Superpowers format)
• Reviews code against design
• Maintains architectural consistency

Implementor AI (Coder)

• Executes implementation plans
• Writes tests first (TDD)
• Implements features
• Reports progress and blockers
• Maintains code quality (cargo clippy, cargo test, cargo fmt)

Workflow Cycle

1. Director: Creates design + plan → commits
2. Implementor: Executes plan (TDD) → commits with passing tests
3. Director: Reviews implementation → approves or requests changes
4. Repeat: Until feature complete

The generated HANDOFF.md provides complete workflow documentation with message templates and communication protocols.

Architectural Principles

The skill enforces these proven Rust principles:

1. Ownership as Architectural Boundaries

• Clear ownership transfer at API boundaries
• Borrow when read-only access suffices
• Clone only when justified and documented
• Use Arc<T> for shared ownership across threads
• Lifetime annotations kept minimal

2. Zero-Cost Abstractions

• High-level code compiles to fast machine code
• Iterator chains optimize to tight loops
• Generics specialize at compile time
• Traits enable polymorphism without runtime cost
• Benchmarks validate performance claims

3. Fearless Concurrency

• Send/Sync traits prevent data races at compile time
• async/await for non-blocking I/O
• Channels for message passing between tasks
• Arc<RwLock<T>> only when truly needed
• Lock-free atomics for counters

4. Error Handling with Result

• No exceptions, no panics in library code
• Result<T, E> for recoverable errors
• thiserror for library error types
• anyhow for application error handling
• ? operator for error propagation

5. Test-Driven Development

• Write tests first (red → green → refactor)
• Unit tests for pure functions
• Integration tests in tests/ directory
• Property-based tests with proptest
• Benchmarks with criterion

Performance Targets

The skill includes realistic performance targets in documentation:

• API Latency: <10ms (p50), <50ms (p95), <200ms (p99)
• Throughput: >10,000 requests/second
• Memory: <1KB allocations per request
• Test Coverage: >80% for core logic
• Compile Time: <2 minutes for incremental builds

Best Practices Codified

Ownership Patterns

// ✅ ALWAYS prefer borrowing
fn count_words(text: &str) -> usize {
    text.split_whitespace().count()
}

// ✅ Take ownership when transforming
fn to_uppercase(mut s: String) -> String {
    s.make_ascii_uppercase();
    s
}

Error Handling

// ✅ ALWAYS use Result in libraries
pub fn parse_config(path: &Path) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)?;
    Ok(toml::from_str(&content)?)
}

Async Patterns

// ✅ ALWAYS use tokio::time::sleep in async
async fn delay() {
    tokio::time::sleep(Duration::from_secs(1)).await;
}

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-improvement)
3. Make your changes with tests
4. Run cargo fmt, cargo clippy, cargo test
5. Commit with clear messages (git commit -m 'Add: improved ADR template')
6. Push to your fork (git push origin feature/amazing-improvement)
7. Open a Pull Request

Areas for Improvement

• Additional domain adaptations (Embedded, WebAssembly, etc.)
• More code examples in the skill
• Integration with other Claude Code plugins
• Community-contributed architecture patterns
• Performance optimization guides

Roadmap

v1.1 (Planned)

• [ ] GraphQL API patterns (async-graphql)
• [ ] WebSocket patterns
• [ ] gRPC service patterns (tonic)
• [ ] Distributed tracing (tracing/opentelemetry)

v1.2 (Planned)

• [ ] Kubernetes deployment templates
• [ ] Observability and monitoring setup
• [ ] Load testing scripts with examples
• [ ] Migration from other languages guides

v2.0 (Future)

• [ ] Embedded systems patterns (no_std)
• [ ] WebAssembly patterns
• [ ] Event sourcing templates
• [ ] CQRS implementation patterns

Related Skills

This skill works well with:

• test-driven-development - For TDD workflow
• code-review - For reviewing generated code
• git-workflow - For managing commits and branches

FAQ

Q: Can I use this for single-crate projects?

A: Yes, just specify "single crate" when asked about structure. The skill adapts, though workspace organization is recommended for larger projects.

Q: Does this work for embedded systems?

A: The skill focuses on std applications but can adapt. Specify your requirements (no_std, target platform) and the skill will adjust recommendations.

Q: Do I need Director/Implementor AI workflow?

A: No, it's optional. If you answer "no" to that question, the skill still creates complete architecture docs without the AI collaboration guardrails.

Q: Can I customize the generated documentation?

A: Yes! All documentation is Markdown, fully editable. Treat the generated files as a starting point and adapt to your needs.

Q: What if my project uses different tech stack?

A: The skill is optimized for tokio + axum + sqlx but can adapt. Specify your preferences (actix-web, diesel, etc.) when asked.

Q: How often should ADRs be reviewed?

A: The skill sets review schedules (typically 6 months), but review ADRs whenever:

• Performance becomes a bottleneck
• Scale significantly changes
• New crates or patterns emerge
• Team composition changes

License

MIT License - See LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

Original Inspiration

This Rust version is adapted from [elixir-architect](https://github.com/maxim-ist/elixir-architect) by @maxim-ist.

Special thanks to the original author for creating the comprehensive architecture skill framework that inspired this Rust adaptation.

Generation

This entire skill was generated and refined by [Claude Code](https://claude.ai/claude-code), an AI-powered development assistant, including:

• Complete SKILL.md (3,300+ lines) with 69 Rust code examples
• All architecture documentation templates and patterns
• Guardrails documentation (NEVER_DO, ALWAYS_DO, role definitions)
• Code review checklists and workflow templates
• Health check & graceful shutdown production examples
• Workspace decision matrices and migration guides

Rust Ecosystem Resources

This skill incorporates wisdom and patterns from:

• The Rust Programming Language Book - Ownership and borrowing principles
• Rust API Guidelines - Idiomatic Rust patterns
• tokio Documentation - Async/await best practices
• Jon Gjengset - Rust concurrency and performance patterns
• Superpowers Framework - Implementation planning format

Version

Current Version: 1.0.0

Release Date: 2025-01-13

Compatibility: Claude Code 1.0+

Built with ❤️ by the Rust community

_Adapted from elixir-architect • Generated by Claude Code_

_Creating production-ready architectures, one documentation package at a time._