greenspuns-tenth-rule
Skill6 starsChanged 34 days agoMITView on GitHub
Apply Greenspun's Tenth Rule when reviewing complex codebases that have grown their own configuration systems, rule engines, templating languages, scripting layers, or workflow DSLs. Trigger on phrases like "we built our own config language", "we have a custom rules engine", "this template system has gotten really complex", "we're basically reimplementing X ourselves", or any time a team has reinvented a programming language feature or general-purpose tool inside their application. This rule is a useful diagnostic for spotting accidental complexity.
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- aposd-red-flag-reviewSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- ci-preflightSkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- galls-lawSkill
- goodharts-lawSkill
- gsd-core-hooksSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- rubber-duckSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Recognize the pattern early: When you find yourself adding "variables" or "conditionals" to a config file, stop and ask: are we building a …
- Distinctive: line 39
Use the rule as a refactoring trigger: If you discover a Greenspun situation in an existing codebase, that's a signal to extract, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Greenspun's Tenth Rule
"Any sufficiently complicated C or Fortran program contains an ad hoc, informally-specified, bug-ridden, slow implementation of half of Common Lisp." — Philip Greenspun
The core idea
When a program grows complex enough, developers eventually need features that their current language or framework doesn't easily provide: dynamic dispatch, higher-order functions, user-configurable behavior, extensibility hooks. Rather than adopting a language or tool that has these features natively, they build them from scratch — usually badly, incompletely, and without realizing that's what they're doing.
The result is a half-implemented, poorly-documented programming language or runtime lurking inside a codebase that was never meant to host one.
What this looks like in practice
- A configuration file format that has grown conditionals, loops, and variables → you've built a scripting language
- A "template engine" with logic, iteration, and state → you've built a programming language
- A rules engine with complex precedence and side effects → you've built an interpreter
- A workflow system with retries, timeouts, and branching → you've built a runtime
- A plugin system with dynamic loading and lifecycle hooks → you've built a module system
The key tell: these systems are always informal (undocumented), incomplete (missing features that users keep requesting), buggy (edge cases not handled), and slow (performance not considered in the original design).
Why it happens
Engineers solve the immediate problem in front of them. The first version is simple and reasonable: "we just need a config flag." Then "the flag needs to be conditional." Then "we need to reuse this condition elsewhere." Then "we need a way to script this." Nobody decided to build a language — they just kept solving the next problem.
What to do about it
Recognize the pattern early. When you find yourself adding "variables" or "conditionals" to a config file, stop and ask: are we building a language? If yes — do it on purpose, with proper tooling.
Embrace an existing language or tool. Lua, Python, JavaScript, YAML with a real schema validator, Jsonnet, Starlark, HCL — many languages were specifically designed to be embedded as scripting layers. They come with documentation, debuggers, and community knowledge.
If you must build a DSL, build it intentionally. Decide explicitly that you're building a language. Define it formally. Provide documentation and error messages. Think about the user experience of writing in it.
Use the rule as a refactoring trigger. If you discover a Greenspun situation in an existing codebase, that's a signal to extract, formalize, or replace the ad hoc system — not necessarily to add features to it.
Key questions to surface
- Does our configuration/template/rule system have features that feel like programming language features (conditionals, loops, variables)?
- Is this system documented? Can new team members learn it from docs, or only by reading code?
- Would adopting an existing scripting language (Lua, Python embedded, etc.) give us what we need, with less maintenance burden?
- Are we repeatedly adding features to a system that was never designed to be this complex?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

