software-tradeoffs
Skill0 starsChanged 9 months agoMITView on GitHub
Software tradeoff analysis, decision frameworks, and common tradeoff patterns. Use when evaluating design alternatives, choosing between competing approaches, analyzing costs vs. benefits of technical decisions, or when a decision involves tension between two desirable properties. Covers duplication vs. coupling, flexibility vs. complexity, performance optimization, API design, dependency management, error handling strategies, and distributed system tradeoffs.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- code-antipatternsSkill
- code-namingSkill
- code-plan-auditSkill
- code-pruningSkill
- code-quality-foundationsSkill
- code-readabilitySkill
- code-reviewSkill
- code-scope-boundariesSkill
- code-testing-qualitySkill
- code-yagniSkill
- error-handling-patternsSkill
- refactoring-patternsSkill
The file
Files
Software Tradeoffs
The Tradeoff Analysis Framework
- Identify the tension — What two (or more) desirable properties are in conflict?
- List alternatives — At least two concrete approaches
- Evaluate in context — Pros and cons depend on your specific situation (team size, SLAs, traffic, timeline)
- Choose and accept — Pick one, accepting its cons alongside its pros
- Document the decision — Future you (and teammates) need to know why
The cardinal rule: Context changes everything. A pattern that's optimal in one situation may be harmful in another. Validate assumptions with measurement, not intuition.
The Tradeoff Decision Matrix
| Tradeoff | Option A | Option B | Choose A When | Choose B When |
| DRY vs. Coupling | Extract shared code | Duplicate code | Logic is truly identical and owned by one team | Services evolve independently or teams need autonomy |
| Flexibility vs. Complexity | Add extension points | Keep it simple | Multiple consumers with different needs | One consumer or needs are well-known |
| Optimize vs. Ship | Optimize hot path | Ship and measure | Profiling shows a bottleneck on a hot path | No measured performance problem exists |
| Abstract vs. Direct | Wrap dependencies | Use directly | Dependency may change or needs testing isolation | Dependency is stable and abstraction adds no value |
| Checked vs. Unchecked errors | Force caller to handle | Let errors propagate | Caller can meaningfully recover | Error is unrecoverable or caller can't act on it |
| Library vs. Custom | Use third-party library | Build your own | Problem is well-solved and library is maintained | Core differentiator or library is a poor fit |
| Monolith vs. Services | Single deployable | Distributed services | Small team, early product, simple scaling needs | Independent team scaling, polyglot requirements |
| Consistency vs. Availability | Strong consistency | Eventual consistency | Financial transactions, inventory counts | Social feeds, analytics, caching layers |
Tradeoff Analysis Checklist
- Named the tension: What two desirable properties are in conflict?
- Listed alternatives: At least two concrete approaches identified
- Considered context: Team size, traffic, SLAs, timeline factored in
- Evaluated reversibility: How hard is it to change this decision later?
- Identified the hot path: If performance-related, measured with data
- Checked assumptions: Are you optimizing based on intuition or measurement?
- Considered second-order effects: Does the choice affect other teams, APIs, or systems?
- Documented the decision: Written down why, not just what
"Which tradeoff am I actually making?"
| You're tempted to... | The real tradeoff is... | Ask yourself... |
| Remove duplicated code | Coupling vs. independence | Will these paths diverge? Do different teams own them? |
| Add an extension point | Flexibility vs. complexity | Do you have >1 consumer? Is the use case concrete? |
| Optimize a code path | Performance vs. readability | Is this on the hot path? Do you have profiling data? |
| Add a third-party library | Development speed vs. long-term maintenance | Is this a core differentiator? Is the library well-maintained? |
| Extract a microservice | Team autonomy vs. operational complexity | Is the monolith actually blocking you? |
| Use strong consistency | Correctness vs. availability and latency | What's the business cost of stale or incorrect data? |
| Wrap a dependency | Future flexibility vs. current complexity | How likely is replacement? How deep is the integration? |
"How do I know if I chose wrong?"
| Symptom | Likely Wrong Choice | Course Correction |
| Changing one service breaks another | Over-extracted shared code (too DRY) | Duplicate and decouple |
| Simple features take weeks | Over-engineered flexibility | Remove unused extension points |
| Performance issues in production | Didn't optimize the hot path | Profile, identify bottleneck, targeted fix |
| Library upgrade breaks everything | Too-deep dependency without wrapping | Extract interface, wrap the dependency |
| Teams blocked waiting on each other | Monolith coordination overhead | Extract contested components into services |
| Debugging takes days | Too many microservices for the team size | Consolidate related services |
Common Mistakes
- Applying rules without context — DRY doesn't apply when duplication is coincidental. "Premature optimization is evil" doesn't apply when you have SLA data and profiling.
- Optimizing what you haven't measured — A synchronized singleton is 120x slower than double-checked locking in multithreaded benchmarks, but if accessed once at startup, the difference is meaningless.
- Ignoring coordination cost — Amdahl's law applies to teams. Shared libraries, databases, and APIs introduce synchronization points. Sometimes duplication is the price of parallel progress.
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.