RUNE is a specification pattern for defining function behavior before AI-assisted implementation.
RUNE provides a structured contract between human intent and AI implementation, ensuring consistent code generation, comprehensive tests, and explicit edge case handling.
RUNE is format-agnostic. The same pattern works as:
.rune files (parseable, validatable)Every RUNE spec must include these required fields:
| Field | Required | Description |
|---|---|---|
| SIGNATURE | Yes | Function declaration in target language syntax |
| INTENT | Yes | What it does (1-3 sentences, docstring-ready) |
| BEHAVIOR | Yes | Logic rules in WHEN/THEN/OTHERWISE format |
| TESTS | Yes | Minimum 3 test cases (happy path, boundary, error) |
| CONSTRAINTS | No | Input validation rules and preconditions |
| EDGE_CASES | No | Boundary conditions and expected behavior |
| DEPENDENCIES | No | External libraries required |
| EXAMPLES | No | Usage examples |
| COMPLEXITY | No | Big-O time/space notation |
Standalone files for formal, parseable specifications. Includes a meta header for tooling.
---
meta:
name: function_name # Required: identifier
language: python # Required: target language
version: 1.0 # Optional: spec version
tags: [category, tags] # Optional: labels
---
RUNE: function_name
SIGNATURE: |
def function_name(param: type) -> return_type
INTENT: |
Clear 1-3 sentence description of purpose.
BEHAVIOR:
- WHEN condition THEN action
- WHEN another_condition THEN another_action
- OTHERWISE default_action
TESTS:
- "function_name(input) == expected"
- "function_name(boundary) == expected"
- "function_name(invalid) raises ValueError"
CONSTRAINTS:
- "param: must be >= 0"
EDGE_CASES:
- "empty input: returns empty result"
DEPENDENCIES:
- "library>=1.0.0"
EXAMPLES:
- |
result = function_name(input)
# Returns: expected
COMPLEXITY:
time: O(n)
space: O(1)
Configure editors to treat .rune as YAML:
VS Code — settings.json:
{ "files.associations": { "*.rune": "yaml" } }
Neovim/Vim:
autocmd BufNewFile,BufRead *.rune set filetype=yaml
Sections inside any .md file. No special tooling needed.
### function_name
**SIGNATURE:** `def function_name(param: type) -> return_type`
**INTENT:** Clear 1-3 sentence description of purpose.
**BEHAVIOR:**
- WHEN condition THEN action
- WHEN another_condition THEN another_action
- OTHERWISE default_action
**TESTS:**
- `function_name(input) == expected`
- `function_name(boundary) == expected`
- `function_name(invalid) raises ValueError`
**CONSTRAINTS:**
- param: must be >= 0
**EDGE_CASES:**
- empty input: returns empty result
Add a ## Function Specifications section to your AGENTS.md:
# AGENTS.md
## Project Context
Python 3.11, pytest, hexagonal architecture.
## Function Specifications
### calculate_order_total
**SIGNATURE:** `def calculate_order_total(items: list[dict], tax_rate: float) -> float`
**INTENT:** Calculates order total including tax.
**BEHAVIOR:**
- WHEN items is empty THEN return 0.00
- WHEN any item has price <= 0 THEN raise ValueError
- CALCULATE subtotal + tax, round to 2 decimals
**TESTS:**
- `calculate_order_total([{'price': 15.99, 'quantity': 2}], 8.5) == 34.70`
- `calculate_order_total([], 8.5) == 0.00`
- `calculate_order_total([{'price': -5, 'quantity': 1}], 8.5) raises ValueError`
The exact function declaration in the target language’s syntax. Not pseudocode.
Python: def calculate_discount(price: float, percentage: int) -> float
TypeScript: function calculateDiscount(price: number, percentage: number): number
Go: func CalculateDiscount(price float64, percentage int) float64
Rust: fn calculate_discount(price: f64, percentage: i32) -> f64
For language-agnostic specs, use a neutral format:
function calculate_discount(price: float, percentage: int) -> float
1-3 sentences describing the function’s purpose — the “what”, not the “how”. Write it as a technical summary that works as a docstring but is understandable by non-developers reviewing the spec. Avoid implementation details (algorithms, regex patterns, library calls).
Each business rule as a WHEN/THEN clause. Use OTHERWISE for the default case.
- WHEN input is invalid THEN raise error with specific message
- WHEN condition A THEN action A
- WHEN condition B THEN action B
- OTHERWISE default action
Order matters — rules are evaluated top to bottom. Put validations first, business logic second, default last.
Minimum 3 test cases covering:
Format: function(input) == expected or function(invalid) raises ErrorType
Tests are written as pseudo-assertions, not executable code. They define the expected behavior concisely:
TESTS:
# Inline values for simple inputs:
- "calculate_discount(100.0, 20) == 80.0"
# [...] means "a representative list matching the spec's CONSTRAINTS":
- "validate_coupon('SAVE10', [...], '2025-01-15')[0] == True"
# Here [...] is shorthand for a valid coupons list. The developer
# expands it into real test data when writing pytest/Jest tests.
# "raises" means the function should throw that exception:
- "calculate_discount(-10.0, 20) raises ValueError"
When converting to real tests, expand [...] into concrete test fixtures that satisfy the CONSTRAINTS section.
Input preconditions — what must be true about the inputs before the function runs. Each constraint maps to a validation check in the implementation.
CONSTRAINTS and BEHAVIOR are complementary: CONSTRAINTS declare what is valid, BEHAVIOR defines what to do when inputs violate those constraints.
# CONSTRAINTS declare the precondition:
CONSTRAINTS:
- "price: must be non-negative float"
# BEHAVIOR defines the action when violated:
BEHAVIOR:
- WHEN price < 0 THEN raise ValueError("Price cannot be negative")
If a constraint has no corresponding BEHAVIOR rule, it is assumed to be a precondition that callers must satisfy (no runtime validation).
Boundary conditions with expected behavior. Each should have a corresponding test.
Supporting information for implementation.
A valid RUNE spec must:
See docs/best-practices.md for writing guidelines.
RUNE is an open standard. Contributions welcome:
.rune files or Markdown specs for common use casesAll contributions should follow the spec fields and validation rules defined above.
MIT License. RUNE is an open standard — use, extend, and build on it freely.