Coding Standards Guide

Principal guide for all code written in SystemPrompt. Follow these standards without exception.

Read playbooks: systemprompt core playbooks show <playbook_id>

Core Principle

SystemPrompt is a world-class Rust programming brand. Every file must be instantly recognizable as on-brand, world-class idiomatic code. No exceptions. No shortcuts. No compromise.

Language Standards

Rust

Primary language for all extensions, MCP servers, and core logic.

-> See Rust Standards for complete standards

Key points:

Write idiomatic Rust (Steve Klabnik style)
Use typed identifiers from systemprompt_identifiers
SQLX macros only (query!, query_as!, query_scalar!)
Repository pattern for all database access
Zero tolerance for unsafe, unwrap(), inline comments

Validation:

cargo clippy --workspace -- -D warnings
cargo fmt --all

YAML/Markdown

Configuration and documentation in services/.

-> See Playbook Authoring for playbook standards -> See Documentation Guide for doc standards

Code Locations

Type	Location	Language
Extensions	`extensions/*/src/`	Rust
MCP Servers	`extensions/mcp/*/src/`	Rust
Agents	`services/agents/*.yaml`	YAML
Skills	`services/skills/*/.yaml`	YAML
Playbooks	`services/playbook/*/.md`	Markdown
Config	`services/config/*.yaml`	YAML

Build Standards

Extensions

-> See Extension Checklist

Every extension requires:

Cargo.toml with systemprompt dependencies
src/extension.rs implementing Extension trait
src/error.rs implementing ExtensionError trait
Schema files in schema/ numbered 001_*.sql

MCP Servers

-> See MCP Checklist — Full requirements -> See MCP Tutorial — Step-by-step guide -> See MCP Tool Patterns — Handler and schema patterns -> See MCP Artifacts — Artifact storage and UI resources

Every MCP server requires:

Tool definitions with JSON schemas
Error handling with domain-specific errors
Structured logging via tracing

Mandatory Patterns

Error Handling

Use thiserror for domain-specific errors. anyhow only at application boundaries.

#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("Item not found: {0}")]
    NotFound(String),
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
}

Logging

All logging via tracing. No println! in library code.

tracing::info!(user_id = %user.id, "Created user");
tracing::error!(error = %e, "Operation failed");

Builder Pattern

Required for types with 3+ fields or mixed required/optional fields.

-> See Rust Standards for full pattern

Forbidden Constructs

Construct	Resolution
`unsafe`	Remove - forbidden
`unwrap()`	Use `?`, `ok_or_else()`, or `expect()`
`panic!()` / `todo!()`	Return `Result` or implement
Inline comments (`//`)	Delete - code documents itself
Doc comments (`///`)	Delete - no rustdoc
`println!` in libraries	Use `tracing`
Raw SQL strings	Use SQLX macros

File Limits

Metric	Limit
Source file length	300 lines
Cognitive complexity	15
Function length	75 lines
Parameters	5

Naming Conventions

Functions

Prefix	Returns
`get_`	`Result<T>` - fails if missing
`find_`	`Result<Option<T>>` - may not exist
`list_`	`Result<Vec<T>>`
`create_`	`Result<T>` or `Result<Id>`
`update_`	`Result<T>` or `Result<()>`
`delete_`	`Result<()>`

Allowed Abbreviations

id, uuid, url, jwt, mcp, a2a, api, http, json, sql, ctx, req, res, msg, err, cfg

Validation Workflow

Before committing any code:

Run linters:

cargo clippy --workspace -- -D warnings
cargo fmt --all

Run tests:

cargo test --workspace

Verify build:

just build

Quick Reference

Task	Playbook
Rust coding standards	`build_rust-standards`
System architecture	`build_architecture`
Build extension	`build_extension-checklist`
Build MCP server	`build_mcp-checklist`
Write playbooks	`guide_playbook`
Write documentation	`guide_documentation`

-> See Rust Standards for complete Rust patterns -> See Architecture for system design -> See Extension Checklist for building extensions -> See Playbook Authoring for writing playbooks