A compact, technology-agnostic decision framework for building software that remains fit for purpose, no more complex than necessary, understandable, correct, secure, reliable, testable, operable, and economical to change.
Software projects rarely become difficult because developers lack patterns, tools, or frameworks. They become difficult when thousands of individually reasonable decisions accumulate without a shared way to resolve trade-offs.
This repository provides a small, durable set of values for making those decisions consistently. The values are intended to help developers, reviewers, architects, technical leaders, and AI coding agents answer questions such as:
- Is this abstraction justified, or is it speculative?
- Is this the smallest complete solution?
- Will the code be understandable to someone who did not write it?
- Are important domain rules enforced by the design?
- What evidence shows that the change works?
- How will the system behave, fail, recover, and evolve in production?
- Does this change improve or weaken the long-term health of the codebase?
The canonical document is:
It contains ten values and a decision rule for cases in which the values appear to conflict.
The values give a team a common language for discussing architecture, implementation, testing, operations, security, and technical debt. Reviews become less dependent on personal taste because decisions can be evaluated against explicit criteria.
They make the burden of proof fall on additional abstractions, dependencies, services, configuration, and optimization. Complexity is accepted when it addresses a demonstrated requirement or material risk—not merely because it may become useful someday.
A change is not considered complete only because it compiles or passes a happy-path test. The values also require clarity, encoded invariants, credible verification, secure defaults, operability, migration safety, and an appropriate recovery path.
Small contracts, limited coupling, focused increments, explicit assumptions, and reversible decisions reduce the blast radius of mistakes. They also make later changes easier to understand, test, review, deploy, and undo.
The values treat maintenance as part of engineering rather than cleanup left for later. Automation, reproducibility, removal of obsolete code, reliable tests, useful documentation, and sustainable ownership prevent gradual degradation.
Use them as decision criteria, not as ceremonial slogans.
- Before implementation, state the actual requirement, constraints, success criteria, and material risks.
- During design, choose the smallest architecture that fully addresses those facts and keeps plausible change affordable.
- During implementation, make intent and dependencies explicit, encode important invariants, and avoid speculative generalization.
- Before completion, produce risk-proportionate evidence: tests, static checks, review, operational validation, migration checks, or recovery exercises as appropriate.
- During review, evaluate the whole-system effect of the change, including complexity, coupling, security, operability, compatibility, and future maintenance cost.
- After release, use production evidence and incidents to improve the code, tests, tooling, and architecture.
The values are intentionally technology-agnostic. They do not replace product requirements, domain rules, regulatory obligations, service-level objectives, or repository-specific conventions. Those constraints should be made explicit and applied through the values.
AI coding agents are most useful when the repository gives them durable, concrete, and verifiable guidance. These values can serve as the stable policy layer, while repository-specific instruction files define commands, conventions, architecture boundaries, and validation steps.
When an agent follows the values, its work should tend to:
- begin from explicit requirements and risks rather than assumed scope;
- prefer the smallest complete change over a broad redesign;
- avoid unjustified abstractions, dependencies, frameworks, and services;
- preserve existing contracts or provide an explicit migration path;
- make assumptions, ownership, data flow, and failure behavior visible;
- encode important domain invariants instead of relying only on convention;
- add tests and checks proportional to the behavior and risk introduced;
- run the relevant validation before declaring the task complete;
- account for security, production operation, observability, rollback, and recovery;
- report material trade-offs, residual risks, and anything it could not verify.
These instructions improve consistency, but they do not guarantee correctness. Enforce non-negotiable rules with executable tests, type checking, linters, dependency policies, CI checks, hooks, permissions, and human review.
Codex supports durable repository guidance through AGENTS.md. Keep the file concise and translate the values into concrete actions for the repository.
Example:
# AGENTS.md
Before planning, editing, or reviewing code, read
`./software-engineering-values.md` and use it as the decision framework.
For every change:
- Implement only the smallest complete solution to the stated requirement.
- Do not add an abstraction, dependency, service, or optimization without a demonstrated need.
- Preserve existing public behavior, or provide an explicit migration and deprecation path.
- Encode important invariants in types, schemas, APIs, and data constraints where practical.
- Add or update tests according to the behavior and material risks introduced.
- Run the relevant tests, static checks, and build commands before finishing.
- Consider security, failure behavior, observability, deployment, rollback, and recovery.
- Report assumptions, trade-offs, residual risks, and validation that could not be performed.Add repository-specific commands beneath those rules, for example the exact test, lint, type-check, build, and migration commands.
Claude Code supports persistent project guidance through CLAUDE.md. To avoid maintaining two divergent copies of the same instructions, keep the shared rules in AGENTS.md and import them from CLAUDE.md:
# CLAUDE.md
@AGENTS.mdClaude Code also supports more specific rules for particular paths or file types. Use those only when a part of the repository genuinely has different constraints; avoid duplicating general guidance across many files.
.
├── README.md
├── LICENSE
├── software-engineering-values.md
├── AGENTS.md # Optional: shared operational instructions for coding agents
└── CLAUDE.md # Optional: imports AGENTS.md for Claude Code
The values document should remain the stable source of engineering intent. AGENTS.md should convert that intent into concise, testable operating rules for a particular codebase.
Changes should preserve the compactness and independence of the value set.
A proposed addition should identify a meaningful class of engineering failure that is not already covered by the existing values. A proposed rewrite should improve precision or applicability without weakening the original trade-off. Techniques, tools, patterns, and metrics should normally be documented as implementations of a value rather than introduced as new universal values.
By submitting a contribution, you confirm that you have the right to provide it and agree to make it available under the repository's CC0 1.0 Universal dedication.
The original material in this repository is dedicated to the public domain under CC0 1.0 Universal.
You may use, copy, modify, translate, combine, analyze, redistribute, and commercially reuse it for any purpose without asking permission or providing attribution. Attribution and a link back to this repository are appreciated, but not required.
CC0 applies only to material for which the repository's contributors hold the necessary rights. Third-party names, trademarks, linked resources, and material explicitly identified as governed by other terms remain subject to their respective rights.