This plan defines a technical framework for specification-driven, AI-assisted development in Rust. The framework rests on five implementable principles:
All principles map directly to Rust language features and existing tooling.
| Principle | Rust Implementation | Tooling / Pattern |
|---|---|---|
| Structural separation | Traits (interface contracts) + module visibility | Standard library |
| Generative conformance | Procedural macros (#[derive], attribute macros) + build.rs |
proc_macro, syn, quote |
| Skeleton‑tissue architecture | Traits with default methods + Sealed Trait + modules | sealed crate, visibility rules |
| Validation gates | cargo check, Clippy, cargo deny, cargo test |
Compiler, clippy, deny, test |
| Fixed premise | Git tags + Cargo.lock + rust-toolchain.toml |
Git, Cargo |
| Recursive refinement | Cargo workspaces + cargo-semver-checks + Git worktree |
Workspaces, semver-checks |
Structural specifications are machine‑readable contracts stored under specification/.
| Scope | Format | Tool |
|---|---|---|
| API boundaries (REST) | OpenAPI 3.0+ YAML | utoipa (code‑first) or OpenAPI Generator |
| Data models | JSON Schema | schemars (Rust type → schema) + jsonschema (validation) |
| Internal module contracts | Rust traits + Typestate | Language native |
| Runtime‑validated boundaries | JsonSchema + Validate |
schemars + custom derives |
Selection rule: Use utoipa when the specification must stay synchronized with implementation at compile time. Use OpenAPI YAML + generator when the specification is authored externally. Use traits and Typestate for internal module boundaries.
Two code generation paths exist in Rust:
build.rs (pre‑compile) – Reads external specification files (OpenAPI, JSON Schema) and writes Rust code to OUT_DIR. Regeneration triggered by file changes via cargo::rerun-if-changed.#[derive] macros implement traits automatically; attribute macros transform items.Workflow:
cargo build – build.rs regenerates code if inputs changed.Validation after generation:
cargo check – type and borrowing errors.cargo clippy – lint violations.git diff --exit-code on generated files in CI ensures reproducibility.The skeleton defines execution flow and cross‑cutting concerns. It resides in a module with pub visibility and uses Sealed Trait to prevent external implementation.
mod private { pub trait Sealed {} }
pub trait Skeleton: private::Sealed {
fn run(&self) {
self.pre();
self.core();
self.post();
}
fn pre(&self) {}
fn core(&self);
fn post(&self) {}
}
Tissue implements the skeleton trait. All business logic and concrete behavior are generated from the structural specification.
struct TissueImpl;
impl private::Sealed for TissueImpl {}
impl Skeleton for TissueImpl {
fn core(&self) {
// generated code
}
}
| Mechanism | Effect |
|---|---|
| Default private visibility | Prevents accidental exposure of tissue internals |
pub(crate) |
Limits tissue implementation to the same crate |
| Sealed trait | Blocks external crates from implementing skeleton |
| PhantomData + Typestate | Encodes state transitions in types, zero runtime cost |
Four layers of automated validation. Each layer must pass before a phase is committed.
| Layer | Command | Checks |
|---|---|---|
| Compile‑time | cargo check --all-targets |
Type safety, borrowing, module visibility, trait bounds |
| Lint‑time | cargo clippy -- -D warnings |
Code style, anti‑patterns, custom architecture rules |
| Dependency | cargo deny check |
Vulnerabilities (RustSec), license compliance, duplicate deps |
| Runtime | cargo test --all-features |
Unit, integration, and doc tests; contract validation |
Custom Clippy lints can enforce architecture rules (e.g., “tissue module must not import skeleton module”). Development command: cargo dev new_lint.
A fixed premise is the immutable state after a completed phase: specification files, dependencies, tool versions, and skeleton code.
Phase workflow:
cargo build – automatic regeneration of tissue code.git tag phase/N.Parallel phase development uses Git worktree:
git worktree add -b phase/2 ../project-phase2 main
git worktree add -b phase/3 ../project-phase3 main
API compatibility check between phases:
cargo semver-checks --baseline phase/N-1
Fixed premise artifacts:
| Artifact | Management | Purpose |
|---|---|---|
| Structural specification | specification/ + Git tag |
Phase contract |
| Dependencies | Cargo.lock + deny.toml |
Reproducible builds |
| Rust version | rust-toolchain.toml |
Compiler stability |
| Skeleton code | Git tag + CI immutability check | Architecture invariance |
| Generated tissue | OUT_DIR + CI freshness check |
Specification conformance |
| Phase | Duration | Key Tasks | Success Criterion |
|---|---|---|---|
| 0 – Environment | 1 week | Install Rust, setup project, configure Clippy | cargo check passes with no warnings |
| 1 – Specification | 1‑2 weeks | Define skeleton traits, write OpenAPI/JSON Schema | Compilation succeeds with placeholder tissue |
| 2 – Generation | 1‑2 weeks | Implement build.rs or procedural macro |
Generated code compiles automatically on spec change |
| 3 – Validation | 1 week | Add Clippy custom lints, cargo deny, tests |
CI pipeline passes all gates |
| 4 – Fixed premise | 1 week | Git tagging, cargo-semver-checks, worktree setup |
API breaking changes detected automatically |
| 5 – Pilot | 2‑3 weeks | Apply to one module, iterate phases | Bug rate lower than handwritten baseline |
Total estimated duration: 8‑11 weeks for a pilot team.
| Limitation | Mitigation |
|---|---|
| Steep learning curve (ownership, lifetimes) | Start with a pilot module; conduct internal workshops |
| LLM‑generated Rust code has lower accuracy | Use cargo check/Clippy as feedback loop; fine‑tune models (RustLLM/rust-code-instruct-7b) |
| Long compile times for large crates | Use Cargo workspaces for incremental builds; optimize rerun-if-changed in build.rs |
| No inheritance for template method | Use trait default methods or strategy pattern (composition) |
| Procedural macro complexity | Prefer build.rs for external specs; use macros only for type‑driven generation |
| Dynamic dispatch overhead | Use static dispatch (generics) for skeleton core; reserve dyn Trait for extension points |
Rust provides all necessary language features and tooling to implement a specification‑driven, AI‑assisted development workflow:
build.rs for generative conformance.cargo-semver-checks for recursive refinement with fixed premises.cargo deny, and cargo test for multi‑layer validation gates.PhantomData for zero‑cost state machine enforcement.The resulting process eliminates implementation‑level contract violations, enables safe refactoring through specification‑only changes, and keeps context cost independent of codebase size. The approach is production‑ready for embedded, systems, safety‑critical, and high‑performance backend projects.