Codebase Audit Checklist
Quick health audit before acquisition, on-call rotation, or major refactor.
How to Use This Checklist
- Score unchecked items as debt with severity.
- Run quarterly on production services.
- Pair with
cargo audit,clippy, coverage report.
Build and Dependencies
- Toolchain pinned -
rust-toolchain.tomlmatches CI 1.97.0. - Cargo.lock committed for apps.
cargo auditclean or documented exceptions.- No yanked crates in lockfile.
- Duplicate dependency majors tracked (
cargo tree -d).
Code Quality
- clippy -D warnings passes on main.
- fmt --check passes.
- unwrap count trending down (
rg 'unwrap\(' --type rust). - unsafe isolated and documented.
- TODO/FIXME have owners and dates.
Architecture
- Domain crate free of axum/sqlx imports.
- Handlers under ~50 lines or extracted services.
- Errors typed not strings at boundaries.
- Config validated at startup.
- Migrations versioned and applied in deploy pipeline.
Operations
- Health and readiness endpoints exist.
- Graceful shutdown tested.
- Structured logs with trace/request ids.
- Metrics for latency and error rate.
- Runbooks linked from README.
FAQs
passing score?
Zero critical (security/safety); plan for rest within quarter.
automate?
Script rg counts + CI badges in audit doc.
legacy carve-out?
Document crate excluded with sunset date.
open source audit?
Add LICENSE, SECURITY policy checks.
post-audit?
Tickets filed per unchecked item with priority.
compare teams?
Use same checklist for consistent scoring.
include docs?
Broken links lint; missing ADR for major choices.
perf section?
Last profile date documented; SLO stated.
secrets scan?
gitleaks/trufflehog in CI recommended.
onboarding use?
New tech lead runs audit week one.
Related
- Architecture Decision Checklist
- Refactoring Decisions
- Dependency Management
- Linting & Formatting Best Practices
Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.