Semantic Driven Development is an approach where architectural intent — what entities mean and how they relate — is captured as a live, queryable layer alongside the codebase. Development decisions are driven by semantic declarations rather than file structure, naming conventions, or runtime behavior.
Existing approaches to semantics in software fall into a few families:
| Approach | Primary artifact | Relationship to code |
|---|---|---|
| Semantics-driven DSL design | Semantic domain model | Code is derived from the model |
| Model-driven development (MDD) | Ontologies + UML | Code is generated from models |
| Spec-driven development | Schemas, contracts | Code is validated against specs |
| Atlas / SDD | Compound identities in a live registry | Code is annotated with meaning, in the same runtime |
Atlas doesn't replace or generate code. It runs alongside it — a semantic overlay on a living codebase. The registry is an atom. Invariants check actual state. History tracks how meaning shifts across releases.
A compound identity like #{:domain/auth :tier/service :effect/write} is not a type, not a spec, not an ontology class. It is a semantic coordinate — simultaneously queryable, composable, and diffable.
This makes possible things that none of the other approaches support directly:
:domain/payment and :effect/write" — cuts across files, namespaces, modules.Given the registry as ground truth, completeness can be checked at increasing levels of sophistication:
1. Structural completeness — deterministic invariants.
"Every execution-function with :effect/write must have :audit/enabled."
Expressible today with dsl-axiom / fn-axiom. Runs in CI.
2. Vocabulary completeness — asymmetric evolution detection. "We added 5 new endpoints but no data-schemas for them." Detectable from history diffs: vocabulary growth in one entity type without corresponding growth in another signals a gap.
3. Semantic completeness — LLM-assisted gap analysis.
"You have 12 domain/payment entities but none handle refund failure."
No single invariant catches this. It requires reasoning over the full registry with domain understanding — exactly what LLMs are good at when given rich, structured context. Compound identities provide that context.
Most architectural knowledge lives in people's heads or in stale documentation. Atlas makes it live, queryable, and diffable. SDD means:
Can you improve this documentation?Edit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |