The principles that guide how we engineer at ChainSafe.
VISION.md states the mission, vision, and core values that apply company-wide. This document is engineering's manifestation of those — the operating principles that flow from the values when applied to how we build software. Together:
- Values describe who we are. (
VISION.md) - Principles describe how we engineer. (this document)
- Invariants describe the testable rules that operationalize the principles. (
invariants/engineering-invariants.md) - The Operator–Agent Contract describes how human and AI collaborators honor all of the above. (
operating-model/collaborator-statement.md)
These principles provide a solid base for every engineer at ChainSafe — human or AI agent — to act, make decisions, and navigate their autonomy.
-
Open-source everything. Everything we build, code or otherwise, should be open-source. Any exceptions to this should be deeply considered. License restrictions should only be used to ensure the continued freedom of individuals to build on top of or modify our work. Published work should be accessible and welcoming to external contributors.
-
Empower people. It is very easy for processes and structures to disempower individuals, which is why we strive for self-organizing teams with high autonomy. Individuals that feel empowered are far more productive. This empowerment leads to greater satisfaction and engagement, which helps to build better teams and ultimately better software.
-
Standards lead to better code. Use a systematic approach to ensure that code is of high quality. This involves using established practices and tools to create software that is easy to read, test, maintain, and extend. Standards should be encouraged, or enforced where necessary, through established processes such as code reviews. These standards should always be documented, and automated wherever possible.
-
Plan for quality. Quality should be a consideration at every development phase and a shared responsibility. Before building software components or systems a definition of quality must be established. Throughout development, this definition should be periodically re-evaluated and continuously targeted.
-
Every piece of software is a building block. Teams are responsible for creating software in a modular fashion that is designed to be easily understood, maintained, and integrated with other modules in the system. By doing so, we can enable others to build on top of our work, creating new functionality and extending the system in new and interesting ways.
-
Transparency by default. Commitment to transparency fosters trust, collaboration and informed decision-making across the organization. We prioritize open communication channels and comprehensive sharing of information. All work should be visible and easy to find, to enable every team member to contribute effectively.
-
Take initiative in making things better. While not everything should be your job, see how can you help, support your colleagues and assist one another. Proactively approach the problems you notice with a positive and helpful attitude.
-
Autonomous and aligned teams. It's important for teams to have the staff, resources, and independence to deliver value to the organization while aligning their work with company objectives and vision. This requires clear communication and collaboration between teams and leadership. With trusted and aligned teams, we can achieve a culture of ownership, innovation, and continuous improvement.
-
Outcomes over effort. Focus on delivering working software and achieving measurable results rather than just putting in long hours. Set clear goals and expectations, and continuously validate and iterate on your work to ensure that you are making progress towards those goals. Keep in mind that the ultimate goal is to deliver value to users and impact our community, not just to complete tasks or meet deadlines.
-
Document everything. Our teams should prioritize documenting everything, from code and processes to proposals and decisions. This ensures that knowledge is shared and preserved, making it easier for new team members to get up to speed and for existing team members to refer back to previous work. Documentation should be clear, concise, and accessible to all team members. If something isn't documented, it doesn't exist.
Some principles can be made testable; some can't. The principles above are the aspiration — what we believe about good engineering. The engineering invariants page is the enforcement — the subset of these principles that can be checked mechanically (in CI, in review, at gates) and a small set of additional rules that close obvious failure modes.
Principles that are predominantly testable are restated as invariants. Examples:
- Standards lead to better code → invariant: lint, format, type-check, test — never bypass without an explicit operator override.
- Plan for quality → invariant: every non-trivial change ships with a definition of quality that was set before implementation.
- Document everything → invariant: every non-trivial change ships with an ADR or PR description an operator can audit.
- Transparency by default → invariant: decisions live in the repo, not in chat.
Principles that are predominantly cultural stay here, in this document, and don't appear in the invariants page:
- Empower people, Take initiative in making things better, Autonomous and aligned teams — these describe the working culture engineering hiring, peer review, retrospectives, and team-building are oriented around. They resist mechanical enforcement and are no weaker for it.
VISION.md— company-wide mission, vision, and core values.invariants/engineering-invariants.md— the testable subset.invariants/agent-era-invariants.md— invariants specific to AI-assisted engineering work.operating-model/collaborator-statement.md— the operator/agent contract that operationalizes these principles for collaborative work.