Design Log Methodology
Jay is built using the Design Log methodology — a rigorous, document-first approach to software architecture. Every significant feature is designed in writing before a single line of code is written.
Browse Design Logs
Jay FrameworkWhat is a Design Log?
A Design Log is a structured document that captures the full decision-making process for a feature or architectural change. It's not a spec, not a ticket, and not documentation — it's a living record of why things are built the way they are.
Unlike traditional design documents that become stale, design logs are written before implementation begins and serve as the single source of truth throughout the development process. They capture the context, constraints, trade-offs, and decisions that code alone cannot convey.
The methodology was born out of the need to give AI agents — and human developers — a reliable reference point. When multiple agents collaborate on a complex system, ambiguity is the enemy. The design log eliminates ambiguity by making intent explicit and verifiable.
The Design Log is the Source of Truth
Any plan — whether provided by the user, generated during plan mode, or inferred by an AI agent — must be validated against the design log before implementation. If a plan deviates from the design log, the deviation must be flagged. The design log takes precedence over guesses, assumptions, or blind code searches.
Required for Every Contribution
Every contribution to Jay — whether from a human developer or an AI agent — must follow the Design Log methodology. New features and architectural changes require a design log to be written and approved before implementation begins. No code is merged without it.
Open Design, Not Just Open Source
We believe open source frameworks should be transparent beyond the code. That means publishing not just what we built, but how we designed it — what we tried, what failed, and how the system evolved over time.
Jay's design logs are a public record of every architectural decision, dead end, and trade-off. They show the reasoning behind the code, not just the result. If you want to understand why Jay works the way it does, the answer is always in the design log.