// The Unix/Linux design philosophy as a lens for system design — mechanism vs policy, composability, small tools, text streams, convention over configuration, and the principle of least surprise. Use when evaluating designs for composability, simplicity, or separation of concerns.
Use when the /systems-design mode is active. 9-phase structured design methodology -- problem framing, system classification, constraints, candidate architectures, tradeoff analysis, risk review, refinement, migration planning, and documentation. Governs conversation flow, delegation patterns, and user validation checkpoints.
Use when the /systems-design-review mode is active. 7-step design review methodology -- understand the design, classify the system, evaluate against codebase, adversarial analysis, tradeoff validation, synthesis, and action items. Governs conversation flow, delegation patterns, and user validation checkpoints.
Adversarial review of a system design from 6 critical perspectives -- SRE, security, staff engineer, finance, operator, and developer advocate. Produces a unified risk assessment. Use for INTERACTIVE on-demand reviews during a design conversation (/adversarial-review). For RECIPE-DRIVEN reviews (where prior step context is needed), use the systems-design-critic agent instead.
Domain patterns for Azure cloud architecture — compute selection, managed services, identity (Entra ID), networking, data platform, messaging, deployment, cost management, and operational patterns. Use when designing or evaluating a system deployed on Microsoft Azure.
Domain patterns for peer-to-peer system architecture — network topologies, NAT traversal, peer discovery, data distribution, consistency without central authority, identity and trust, and incentive mechanisms. Use when designing or evaluating a decentralized, peer-to-peer, or mesh-networked system.
Domain patterns for single-page application architecture — client-side routing, state management, rendering strategies, authentication, performance, and offline support. Use when designing or evaluating a browser-based SPA, progressive web app, or rich client-side application.
| name | design-philosophy-linux |
| description | The Unix/Linux design philosophy as a lens for system design — mechanism vs policy, composability, small tools, text streams, convention over configuration, and the principle of least surprise. Use when evaluating designs for composability, simplicity, or separation of concerns. |
The Unix philosophy as a thinking tool for modern system design.
The deepest principle in Unix. The kernel provides mechanisms (process scheduling, file descriptors, memory mapping). User-space provides policy (which processes run, what files mean, how memory is used). The kernel doesn't have opinions about your workflow. It gives you the tools to build any workflow.
The litmus test: Could two reasonable users want different behavior here? If yes, you're looking at policy — don't hardcode it. Provide a mechanism and let the caller decide.
How this applies broadly:
Design evaluation questions:
The failure mode: Over-separating mechanism from policy creates systems that are infinitely flexible and impossible to use out of the box. X11 separated mechanism from policy so aggressively that every desktop environment had to reinvent window management from scratch. The mechanism layer should be opinionated enough to be useful — just not so opinionated that it precludes valid alternatives.
The most cited and most misunderstood Unix principle. grep searches. sort sorts. uniq deduplicates. Each does one thing, does it thoroughly, and handles edge cases within its domain. The key word is well, not small.
What this actually means:
A component should have a clear responsibility boundary. Everything inside that boundary, it handles completely. Everything outside, it delegates. grep doesn't sort its output because sorting is outside its boundary. But grep handles binary files, compressed input, recursive directories, regex dialects, and colorized output — because those are all within "searching text."
How microservices got this wrong: "Do one thing" was interpreted as "be small." Teams created services so thin they couldn't do anything useful alone. A "user service" that only stores user records but can't validate an email address. A "notification service" that can't template a message. The result: every operation requires orchestrating five services, and the real logic lives in the orchestration layer — which is now doing everything and doing it badly.
The real principle: Draw clear responsibility boundaries. A component owns a coherent piece of functionality, not a minimal piece. The question isn't "Is this small enough?" but "If I need to change how X works, do I change exactly one component?"
Design evaluation questions:
The tension: "Do one thing well" is in tension with "provide a complete solution." Unix resolves this through composition — the pipeline provides the complete solution while each tool provides one step. Your system needs an equivalent composition mechanism. If you don't have one, making components smaller just makes the system harder to use.
Unix programs communicate through text streams. The format is simple enough that any program can produce and consume it. This means any program can connect to any other program, even programs that were written decades apart by people who never met.
The power of a universal interchange format:
The magic isn't text. The magic is universality. When every component speaks the same format, the number of possible integrations is N (one adapter per component), not N² (one adapter per pair). You pay for this with type safety — text streams carry no schema, no types, no validation. That's the trade.
How this maps to modern systems:
| Unix Concept | Modern Equivalent | Tradeoff |
|---|---|---|
| Text streams | JSON payloads | Human-readable, schema-optional, verbose |
| Pipes | HTTP requests | Universal, stateless, high overhead per call |
| Signals | Events/webhooks | Async notification, no return value |
| Files | Object storage / REST resources | Addressable, persistent, no push notification |
| stdin/stdout | Request body / response body | Clear directionality, one-shot |
| Environment vars | Configuration injection | Implicit, global, stringly-typed |
The tradeoff between universal and typed interfaces:
Design evaluation questions:
cat access.log | grep 404 | cut -d' ' -f7 | sort | uniq -c | sort -rn | head -20
Nobody designed a "top 20 not-found URLs" feature. The feature emerged from composition. This is the central insight: composable systems gain features over time without changing existing components.
Stdin/stdout discipline:
What makes Unix tools composable isn't their size — it's their discipline. Each tool reads from stdin, writes to stdout, and reports errors to stderr. This discipline is what enables arbitrary connection. Without it, composition is accidental at best.
The equivalent disciplines for modern systems:
OrderPlaced { orderId, items, total } composes. SendConfirmationEmail { to, template } doesn't — it embeds policy in the event.The composability test: Can someone use this in a way I didn't anticipate? If your component can only be used in the one workflow you designed it for, it's not composable — it's a step in a procedure.
Design evaluation questions:
The failure mode: Composability fetishism. Not everything needs to compose. A user-facing application is a composition — it should present a cohesive experience, not expose its internal pipes. Compose at the infrastructure layer. Integrate at the product layer.
Unix is full of conventions. Config lives in /etc. User config lives in ~/.config (XDG) or ~/.<app>. Executables live in /usr/bin or /usr/local/bin. Logs go to /var/log. Temp files go to /tmp. None of this is enforced by the kernel — it's pure convention. And it works because everyone follows it.
Why conventions reduce cognitive load:
Every decision a user doesn't have to make is cognitive budget freed for the decisions that matter. When you apt install nginx, you know the config is in /etc/nginx/, the logs are in /var/log/nginx/, and the binary is in /usr/sbin/. You didn't read the docs to learn this. You just knew, because convention.
The 80/20 rule of configuration:
How this maps to system design:
GET /users, POST /users, GET /users/:id. REST naming conventions mean you can often guess an API without reading docs.{ "error": { "code": "NOT_FOUND", "message": "..." } }. Don't make callers handle five different error shapes.The failure mode: invisible assumptions.
When conventions become so ingrained that nobody documents them, they become invisible assumptions. New team members violate them without knowing they exist. The convention calcifies into a trap. Conventions must be:
Design evaluation questions:
Run cp file1 file2. If it succeeds, it prints nothing. You only hear from it if something goes wrong. This isn't laziness — it's design. Silent success means the output stream carries only signal. If every command printed "Success!", pipelines would drown in noise.
The principle: Don't produce output unless you have something the user didn't already know. Success is expected — don't announce it. Failure is unexpected — report it clearly.
How this applies to modern systems:
204 No Content is the Unix-philosophy response to a successful DELETE. The status code tells you it worked. An empty body tells you there's nothing more to say. Don't wrap every response in { "status": "success", "message": "Operation completed successfully" } — that's noise masquerading as helpfulness.-v for verbose. Add -vv for debug. Never make the user pipe through grep -v to find the actual output.The principle of least surprise:
Related but distinct: the system should behave the way the user expects. If a function is called delete(), it should delete — not archive, not soft-delete, not mark-for-deletion. If it does something other than delete, call it something other than delete().
Least surprise is evaluated from the user's perspective, not the implementer's. What a user expects depends on their experience and the conventions of the domain. A Unix user expects rm to be permanent. A Google Docs user expects delete to be recoverable. Neither is wrong — but surprising the user is always wrong.
Design evaluation questions:
In Unix, devices are files (/dev/sda), processes are files (/proc/1234), network sockets are files, pipes are files. You interact with all of them using the same system calls: open, read, write, close. Learn the file interface once, and you can interact with anything.
The power of uniform interfaces:
A uniform interface reduces the API surface area a user must learn. Instead of "here are 15 different ways to interact with 15 different things," it's "here's one way to interact with everything." The user pays a fixed learning cost and gets access to the entire system.
How this maps to modern systems:
| Unix | Modern Equivalent | What's Uniform |
|---|---|---|
| Everything is a file | REST: everything is a resource | CRUD operations (GET/POST/PUT/DELETE) |
| Everything is a file | Kubernetes: everything is a manifest | Declare desired state in YAML, kubectl apply |
| Everything is a file | Event systems: everything is an event | Publish, subscribe, replay |
| Everything is a file | Git: everything is an object | Hash-addressable, immutable content |
| Everything is a file | S3: everything is an object | PUT, GET, DELETE with a key |
The power:
kubectl get works on pods, services, deployments, custom resources — anything that speaks the Kubernetes resource interface. One tool, infinite applicability.The limits:
Not everything maps cleanly to one interface. Files have a natural metaphor for "read this data" but a strained metaphor for "subscribe to changes." REST has a natural metaphor for CRUD but a strained metaphor for long-running operations, batch processing, or real-time streams. When the uniform interface doesn't fit, you have two bad options: torture the metaphor (POST /orders/batch-process-and-notify-async) or break the uniformity (add a WebSocket endpoint alongside REST).
Design evaluation questions:
When reviewing any system design, run it through these lenses:
| Principle | Question | Red Flag |
|---|---|---|
| Mechanism vs Policy | Can two users want different behavior here? | Policy hardcoded in the mechanism layer |
| Do One Thing Well | Can you describe this component's job in one sentence? | "It handles X and also Y and sometimes Z" |
| Text Streams | What's the universal interchange format? | Every integration requires a bespoke adapter |
| Composability | Can this be used in a way the designer didn't anticipate? | Component only works in one specific workflow |
| Convention Over Configuration | What's the zero-config experience? | User must configure 12 settings before first use |
| Silence is Golden | What does a healthy system's log look like? | Pages of output with no errors to be found |
| Everything is a File | What's the uniform interface? | Every entity type has a completely different API |
The Unix philosophy is, itself, a mechanism — not a policy. It provides thinking tools for evaluating designs, not rules for making them. The judgment of when to apply each principle, how strongly, and when to deliberately violate one in service of another — that's the policy, and it's yours to make.