Rules Reference

All 38 rules organized by category, with trigger types and descriptions.

Table of contents

How Rules Work
🕸️ Rule Dependency Graph
🛡️ Security & Integrity
⚡ Reliability & Performance
🏗️ Architecture & Design
🧩 Maintainability & Quality
🔄 DevOps & Operations

How Rules Work

Rules are markdown files in .agent/rules/ that provide guidance to AI agents. Each rule has a trigger type in its YAML frontmatter:

Trigger	Behavior
`always_on`	Loaded in every session — non-negotiable constraints
`model_decision`	Activated contextually when the agent determines the rule is relevant

When rules conflict, Rule Priority determines the winner. Security always wins.

🕸️ Rule Dependency Graph

The rules are highly interconnected. You can explore these relationships using our Interactive Rule Dependency Graph to see how individual mandates, principles, and idioms relate to each other.

🛡️ Security & Integrity

Rules that ensure code is secure by default.

Rugged Software Constitution

always_on

File: rugged-software-constitution.md

The foundational philosophy based on the Rugged Software Manifesto. Establishes three commitments: Responsible, Defensible, and Maintainable. Defines the 7 Rugged Habits including defense-in-depth, instrument for awareness, reduce attack surface, design for failure, clean up after yourself, verify your defenses, and adapt to the ecosystem.

Security Mandate

always_on

File: security-mandate.md

Non-negotiable security requirements:

Never trust user input — validate server-side
Deny by default — require explicit permission
Fail securely — fail closed, never open
Defense in depth — multiple layers of security

Security Principles

model_decision

File: security-principles.md

Detailed security implementation guidance for authentication, authorization, input validation, cryptographic operations, and handling sensitive data.

⚡ Reliability & Performance

Rules that ensure code is robust and efficient.

Error Handling Principles

model_decision

File: error-handling-principles.md

Techniques for robust error management including error types, recovery strategies, validation errors, business rule violations, infrastructure failures, and resource cleanup.

Concurrency & Threading Principles

model_decision

File: concurrency-and-threading-principles.md

Detailed patterns for safe parallel execution: goroutines, async/await, thread pools, deadlock prevention, and race condition avoidance.

Concurrency & Threading Mandate

always_on

File: concurrency-and-threading-mandate.md

When to use concurrency (I/O-bound vs CPU-bound) and when NOT to use it. Prevents premature optimization and overuse of threads.

Performance Optimization Principles

model_decision

File: performance-optimization-principles.md

Writing efficient and scalable code. Profiling, benchmarking, and optimizing performance-critical paths.

Resource & Memory Management

model_decision

File: resources-and-memory-management-principles.md

Handling files, database connections, network sockets, and locks. Implementing resource pools, cleanup, and timeout strategies.

Monitoring & Alerting Principles

model_decision

File: monitoring-and-alerting-principles.md

Health check endpoints (/health and /ready), metrics instrumentation using RED/USE methods, error tracking integration, circuit breakers, and graceful degradation.

Configuration Management Principles

model_decision

File: configuration-management-principles.md

Separating configuration from code, environment variables, secrets management, configuration hierarchy (CLI args → env vars → config files → defaults), and .env file organization.

🏗️ Architecture & Design

Rules that ensure code is well-structured and scalable.

Core Design Principles

always_on

File: core-design-principles.md

Fundamental software design rules:

SOLID — Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
DRY — Don’t Repeat Yourself
YAGNI — You Aren’t Gonna Need It
KISS — Keep It Simple, Stupid
Separation of Concerns, Composition Over Inheritance, Principle of Least Astonishment

Architectural Pattern (Testability-First)

always_on

File: architectural-pattern.md

The core architectural approach:

I/O Isolation — Abstract all I/O behind interfaces
Pure Business Logic — No side effects in calculations
Dependency Direction — Dependencies point inward toward business logic

Includes pattern discovery protocol, language-specific idioms table, and enforcement checklist.

API Design Principles

model_decision

File: api-design-principles.md

Creating clean, intuitive, and versionable REST/HTTP APIs. Covers endpoints, handlers, middleware, and response formatting.

Project Structure

always_on

File: project-structure.md

The single source of truth for project organization. Enforces feature-based organization (not layer-based). Includes complete layout examples for:

Monorepo (backend + frontend + mobile)
Flutter/Mobile apps
Single backend/frontend apps
Microservices

Database Design Principles

model_decision

File: database-design-principles.md

Schema design (3NF), naming conventions, migration safety rules, query performance (parameterized queries, indexing, N+1 prevention), and transaction management.

Data Serialization & Interchange

model_decision

File: data-serialization-and-interchange-principles.md

Safe data handling for JSON, XML, YAML, Protocol Buffers, MessagePack, and other formats.

Command Execution Principles

model_decision

File: command-execution-principles.md

Principles for running external commands and shell scripts securely — preventing injection, handling exit codes, and managing process lifecycles.

Project Structure — Go Backend

model_decision

File: project-structure-go-backend.md

Go-specific directory layout for backend services, including cmd/, internal/, and feature-based organization.

Project Structure — Vue Frontend

model_decision

File: project-structure-vue-frontend.md

Vue/React frontend directory layout with feature-based organization: components, stores, API, and services.

Project Structure — Flutter Mobile

model_decision

File: project-structure-flutter-mobile.md

Flutter and React Native mobile app layout: screens, widgets, state management, and repository pattern.

Project Structure — Rust/Cargo

model_decision

File: project-structure-rust-cargo.md

Rust workspace and crate layout: src/, tests/, benches/, and multi-crate workspace organization.

🧩 Maintainability & Quality

Rules that ensure code is readable, testable, and long-lived.

Code Organization Principles

always_on

File: code-organization-principles.md

Feature-based organization with clear public interfaces. Module boundaries, feature interaction patterns, and wiring examples.

Code Idioms & Conventions

always_on

File: code-idioms-and-conventions.md

Write idiomatic code for the target language. Follow community conventions, use language built-ins, avoid cross-language anti-patterns. Delegates to dedicated language idiom files for ecosystem-specific guidance.

Go Idioms & Patterns

model_decision

File: go-idioms-and-patterns.md

Go-specific patterns: error handling with %w, small interfaces, goroutines and channels, naming conventions, table-driven tests, and gofumpt/staticcheck/gosec tooling.

TypeScript Idioms & Patterns

model_decision

File: typescript-idioms-and-patterns.md

TypeScript type system idioms: strict mode, discriminated unions, unknown over any, readonly, runtime validation with Zod, Promise.all patterns, and Vitest testing.

Vue Idioms & Patterns

model_decision

File: vue-idioms-and-patterns.md

Vue 3 Composition API patterns: <script setup>, ref vs reactive, Pinia Setup Stores, composables, defineProps/defineEmits with TypeScript, and createTestingPinia for tests.

Flutter Idioms & Patterns

model_decision

File: flutter-idioms-and-patterns.md

Flutter/Dart patterns: const constructors, widget decomposition, immutable models with freezed, Riverpod state management (provider types, ref.watch vs ref.read), go_router navigation, and flutter analyze tooling.

Rust Idioms & Patterns

model_decision

File: rust-idioms-and-patterns.md

Rust ownership and borrowing, error handling with thiserror/anyhow, async with tokio, unsafe code policy, idiomatic patterns (builder, newtype, typestate), and cargo clippy configuration.

Testing Strategy

model_decision

File: testing-strategy.md

Comprehensive testing guidance:

Unit tests (mocked I/O, >85% coverage on domain logic)
Integration tests (Testcontainers, real infrastructure)
E2E tests (Playwright, full user journeys)
Test organization and naming conventions

Dependency Management Principles

model_decision

File: dependency-management-principles.md

Managing external libraries safely — version pinning, audit, and minimizing attack surface.

Documentation Principles

model_decision

File: documentation-principles.md

Self-documenting code, when to comment (WHY, not WHAT), and documentation levels from inline comments to architecture docs.

Logging & Observability Principles

model_decision

File: logging-and-observability-principles.md

Complete implementation guide: log levels, structured logging patterns, language-specific implementations (Go, TypeScript, Python), security considerations, and performance best practices.

Logging & Observability Mandate

always_on

File: logging-and-observability-mandate.md

All operation entry points MUST be logged (start, success, failure). Mandatory context: correlationId, operation name, duration, userId, error.

Accessibility Principles

model_decision

File: accessibility-principles.md

WCAG 2.1 Level AA compliance: semantic HTML, keyboard navigation, ARIA attributes, color contrast, images, and forms.

Git Workflow Principles

model_decision

File: git-workflow-principles.md

Conventional commits format, branch naming, commit hygiene, PR size guidelines (<400 lines ideal), and merge strategy.

🔄 DevOps & Operations

Rules that ensure the development pipeline is reliable and automated.

CI/CD Principles

model_decision

File: ci-cd-principles.md

Pipeline design (lint → build → test → deploy), Dockerfile multi-stage builds, Docker Compose patterns, GitHub Actions templates, and environment promotion strategy.

Code Completion Mandate

always_on

File: code-completion-mandate.md

Before marking any code task as complete, you MUST run automated quality checks:

Generate → 2. Validate → 3. Remediate → 4. Verify → 5. Deliver

Delegates language-specific quality commands (linters, formatters, type checkers) to the respective idiom files.

Rule Priority

always_on

File: rule-priority.md

Conflict resolution when rules contradict each other. Priority order:

Security Mandate (always wins)
Rugged Software Constitution
Code Completion Mandate
Testability-First Design
Feature-specific principles
YAGNI / KISS