A comprehensive Claude Code skill for architecting production-ready Rust applications with complete documentation, ADRs, guardrails, and handoff materials.
This project is adapted from 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+
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)
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
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
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
- 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
# In Claude Code, run:
/plugin install github.com/nanlong/rust-architectThe skill will be automatically available as rust-architect.
# 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/To verify the skill is installed:
# In Claude Code
/skills listYou should see rust-architect in the list.
# In Claude Code
/skills rust-architectOr 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 gathers requirements through these questions:
- Project Domain: What system are you building? (e.g., web service, CLI tool, data processing)
- Tech Stack: Confirm Rust + tokio + axum + sqlx?
- Project Location: Where to create files? (provide absolute path)
- Structure Style: Single crate, binary + library, or multi-crate workspace?
- Special Requirements: Async runtime? Web framework? Database? CLI interface?
- Scale Targets: Expected load and performance requirements
- AI Collaboration: Using Director/Implementor workflow?
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!
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
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> without justification (prefer message passing)
- And 10 more with detailed rationale
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)
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
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
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
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
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
One of the unique features of this skill is creating documentation that enables a two-AI workflow:
- Creates feature designs
- Makes architectural decisions
- Writes implementation plans (Superpowers format)
- Reviews code against design
- Maintains architectural consistency
- Executes implementation plans
- Writes tests first (TDD)
- Implements features
- Reports progress and blockers
- Maintains code quality (cargo clippy, cargo test, cargo fmt)
- Director: Creates design + plan → commits
- Implementor: Executes plan (TDD) → commits with passing tests
- Director: Reviews implementation → approves or requests changes
- Repeat: Until feature complete
The generated HANDOFF.md provides complete workflow documentation with message templates and communication protocols.
The skill enforces these proven Rust principles:
- Clear ownership transfer at API boundaries
- Borrow when read-only access suffices
- Clone only when justified and documented
- Use Arc for shared ownership across threads
- Lifetime annotations kept minimal
- 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
- Send/Sync traits prevent data races at compile time
- async/await for non-blocking I/O
- Channels for message passing between tasks
- Arc<RwLock> only when truly needed
- Lock-free atomics for counters
- 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
- Write tests first (red → green → refactor)
- Unit tests for pure functions
- Integration tests in tests/ directory
- Property-based tests with proptest
- Benchmarks with criterion
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
// ✅ 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
}// ✅ 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)?)
}// ✅ ALWAYS use tokio::time::sleep in async
async fn delay() {
tokio::time::sleep(Duration::from_secs(1)).await;
}Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-improvement) - Make your changes with tests
- Run cargo fmt, cargo clippy, cargo test
- Commit with clear messages (
git commit -m 'Add: improved ADR template') - Push to your fork (
git push origin feature/amazing-improvement) - Open a Pull Request
- 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
- GraphQL API patterns (async-graphql)
- WebSocket patterns
- gRPC service patterns (tonic)
- Distributed tracing (tracing/opentelemetry)
- Kubernetes deployment templates
- Observability and monitoring setup
- Load testing scripts with examples
- Migration from other languages guides
- Embedded systems patterns (no_std)
- WebAssembly patterns
- Event sourcing templates
- CQRS implementation patterns
This skill works well with:
- test-driven-development - For TDD workflow
- code-review - For reviewing generated code
- git-workflow - For managing commits and branches
A: Yes, just specify "single crate" when asked about structure. The skill adapts, though workspace organization is recommended for larger projects.
A: The skill focuses on std applications but can adapt. Specify your requirements (no_std, target platform) and the skill will adjust recommendations.
A: No, it's optional. If you answer "no" to that question, the skill still creates complete architecture docs without the AI collaboration guardrails.
A: Yes! All documentation is Markdown, fully editable. Treat the generated files as a starting point and adapt to your needs.
A: The skill is optimized for tokio + axum + sqlx but can adapt. Specify your preferences (actix-web, diesel, etc.) when asked.
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
MIT License - See LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
This Rust version is adapted from elixir-architect by @maxim-ist.
Special thanks to the original author for creating the comprehensive architecture skill framework that inspired this Rust adaptation.
This entire skill was generated and refined by 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
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
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.