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, ships a manifest agents can follow, and gives you open-source tools to measure and improve any codebase — any language, any stack.
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 codebase standard and scoring tools", "generatedDirectories": [ ".next", ".source", "dist" ], "verificationCommands": { "typecheck": "pnpm tsc --noEmit", "test": "pnpm test", "lint": "pnpm lint" }, "commonTaskLocations": { "engine rules": "packages/engine/src/scoring/rules.ts", "CLI commands": "packages/cli/src/commands/" } }
Start with the vocabulary, add CI scoring, or go all-in with manifest and AI rules. Each layer stands on its own.
The interface is not a decoration layer.— from the Clarx standard, §0 · Premise
It is a communication layer.