A specification pattern for consistent AI code generation.
Define function behavior once. Any AI tool generates consistent, tested code with the same behavior — every time, every developer, every language.
AI code generation gives different results every time. Ask three developers to build the same function with AI — you get three different implementations. Different error handling, missing tests, forgotten edge cases.
There's no contract between "what I want" and "what AI produces."
RUNE is that contract. A structured pattern that specifies what a function does — its signature, behavior rules, edge cases, and tests. Give it to any AI tool and get the same behavior every time.
Requirements ──▶ RUNE specs ──▶ Code + Tests
(Analyst) (Analyst + AI) (Developer + AI)
RUNE is a pattern, not a file format. The same structure (SIGNATURE, BEHAVIOR, TESTS...) can be written as YAML .rune files for formal specs or as Markdown sections inside AGENTS.md. The container changes, the contract doesn't.
A business requirement says: "Validate coupon codes. Case-insensitive. Check expiration. Return valid/invalid with reason."
RUNE: validate_coupon
SIGNATURE: |
def validate_coupon(code: str, coupons: list[dict], date: str) -> tuple[bool, str]
BEHAVIOR:
- WHEN code is empty THEN return (False, "Coupon code cannot be empty")
- WHEN code not found (case-insensitive) THEN return (False, "Not found")
- WHEN coupon has expired THEN return (False, "Expired")
- OTHERWISE return (True, matching_coupon)
TESTS:
- "validate_coupon('SAVE10', [...], '2025-01-15')[0] == True"
- "validate_coupon('save10', [...], '2025-01-15')[0] == True"
- "validate_coupon('', [], '2025-01-15')[0] == False"
- "validate_coupon('OLD', [...], '2025-01-15')[0] == False"### validate_coupon
**SIGNATURE:** `def validate_coupon(code: str, coupons: list[dict], date: str) -> tuple[bool, str]`
**BEHAVIOR:**
- WHEN code is empty THEN return (False, "Coupon code cannot be empty")
- WHEN code not found (case-insensitive) THEN return (False, "Not found")
- WHEN coupon has expired THEN return (False, "Expired")
- OTHERWISE return (True, matching_coupon)
**TESTS:**
- `validate_coupon('SAVE10', [...], '2025-01-15')[0] == True`
- `validate_coupon('save10', [...], '2025-01-15')[0] == True`
- `validate_coupon('', [], '2025-01-15')[0] == False`Same pattern, different container. The AI generates code with the same behavior from both.
RUNE complements AGENTS.md — it doesn't replace it.
- AGENTS.md defines how the project works (conventions, architecture, tools)
- RUNE specs define how each function behaves (signature, rules, tests, edge cases)
You can embed RUNE specs directly inside 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`
**BEHAVIOR:**
- WHEN items is empty THEN return 0.00
- WHEN any item has price <= 0 THEN raise ValueError
...Or keep them as separate .rune files — whatever fits your workflow.
| Without RUNE | With RUNE |
|---|---|
| Different code every time | Same behavior, any AI tool |
| No tests until after | Tests defined before code |
| Edge cases forgotten | Edge cases in the contract |
| "It works on my prompt" | Reproducible results |
| Requirements lost in chat | Specs live in the repo |
RUNE specs are complete contracts. A colleague can rebuild your entire project from specs alone — without seeing a single line of your code.
Developer A Developer B
writes specs ──▶ shares .rune files ──▶ generates code + tests
(Python) (no code) (Go, Rust, whatever)
This works because the spec captures what the function does, not how:
- The SIGNATURE defines the exact interface
- The BEHAVIOR defines every rule the function must follow
- The TESTS define the expected outputs for given inputs
- The EDGE_CASES define boundary conditions
Two developers implementing the same spec in different languages, with different AI tools, on different machines — will produce code with identical behavior. The internal implementation may differ (variable names, algorithms, idioms), but the contract is the same.
Practical implications:
- Onboarding — New team members get specs, not a codebase tour. They generate working code on day one.
- Cross-team collaboration — Backend and frontend teams share specs, not implementations. Each generates code in their own language.
- Code reviews — Review the spec first. If the spec is right, the implementation follows.
- Rebuilding from scratch — Lost the code? The specs are enough to regenerate it with consistent behavior.
- Multi-vendor projects — Share specs with external teams without exposing proprietary code.
A RUNE spec is portable knowledge. Code is a local artifact.
1. Load the Writer skill into your AI tool.
Upload skills/rune-writer/SKILL.md to Claude Projects, paste it into ChatGPT, add it to .cursorrules, or any other method. This teaches the AI the RUNE pattern.
2. Describe what you need.
"I need a function that checks if an order qualifies for free shipping. Orders over $50 get free shipping. Loyalty members always get free shipping."
3. The AI generates a RUNE spec.
Review it. Does the BEHAVIOR cover all your rules? Are the TESTS complete? Iterate until the contract is right.
4. Implement from the spec.
"Implement check_free_shipping.rune"
The AI generates code + tests that follow the spec exactly.
7 skills for the full lifecycle. Start with the Writer — add others as needed.
| Skill | What it does |
|---|---|
| Writer | Create specs from requirements. Implement code from specs. |
| Validator | Check if a spec is complete and well-formed. |
| Refiner | Suggest missing tests, edge cases, and clarifications. |
| Test Generator | Generate runnable test files from a spec. |
| Diff | Compare spec vs implementation to detect drift. |
| From Code | Reverse-engineer a spec from existing code. |
| Multi-Lang | Generate implementations in multiple languages from one spec. |
Copy AGENTS.md into your project as a reference for your AI tools.
- Full pipeline — Requirements to specs to code (start here)
- Multi-language — Same spec in Python + TypeScript
- RUNE inside AGENTS.md — Specs embedded in markdown
- Basic specs — Simple functions with implementations
- MCP tools — Async tool specifications
- Getting Started — Quick tutorial
- Workflow Guide — Complete guide with all skills
- Before & After — Side-by-side comparison
- SPEC.md — Full pattern reference
- Best Practices — Writing guidelines
- Templates — Starter templates for manual writing
RUNE is an open standard. Contributions welcome:
- Submit example specs (YAML or Markdown)
- Build tooling (linters, validators, extensions)
- Write integration guides
- Create language-specific templates
See SPEC.md for details.
MIT License - see LICENSE for details.
Stop generating chaos. Start carving specs in stone.