01 · DISCOVERABILITY20%
Find the right file in two attempts.
An agent should locate any module by name, purpose, or callsite without reading implementations.
D2Every package directory must contain a PURPOSE statement.
Clarx scores your repository against five structural pillars, generates a manifest agents can follow, and gives you a semantic component vocabulary that means the same thing to engineers and AI.
Three failure modes agents hit in unprepared repos. Each is detected by a Clarx rule.
Five structural properties. Each weighted 20%. Each auditable. Score capped if a hard rule fails.
An agent should locate any module by name, purpose, or callsite without reading implementations.
Module boundaries are explicit at the file system level. Imports cross them deliberately, not casually.
Average task footprint stays low. Files have one job. Cross-cutting concerns are factored, not threaded.
The repo declares its verification commands, generated paths, and task locations in a single manifest.
Load-bearing files are signalled. Utility sprawl is bounded. The blast radius of any single edit is visible from the file alone.
No telemetry. No login. The scoring engine is open source.
Agents know where to look, what to skip, and how to verify their work. Works with any stack — drop it in alongside your package.json.
Documentation is read once, by humans, when motivation is high. A manifest is read every time, by every agent, in every session. It's load-bearing infrastructure for AI workflows.
It's three things together: an intent declaration, a navigation map, and a verification contract.
{ "version": "0.1", "purpose": "AI-first design system and codebase standard", "generatedDirectories": [ ".next", ".source", "dist" ], "verificationCommands": { "typecheck": "pnpm tsc --noEmit", "test": "pnpm test", "lint": "pnpm lint" }, "commonTaskLocations": { "components": "packages/ui/src/", "engine rules": "packages/engine/src/scoring/rules.ts" } }
Legible to AI tools, design tokens, and the engineer on call at 2am.
The standard works without the components. The components work without the CLI. Everything gets better together.
The interface is not a decoration layer.— from the Clarx standard, §0 · Premise
It is a communication layer.