Introduction

Clarx is an AI-first codebase standard — a versioned set of rules that measure how legible a repository is to agents, plus open-source tools to score and improve it.

It starts from a simple belief: as AI becomes part of every implementation workflow, codebase structure is communication. Agents need to find the right files, respect boundaries, avoid loading irrelevant context, and verify their work. A repo that optimizes for those behaviors scores higher — and ships safer changes.

This applies to any stack. The standard is technology-agnostic. Python services, Go CLIs, React monorepos, and mixed polyglot repos all benefit from discoverable roots, clear module boundaries, committed manifests, and explicit verification commands.

What Clarx provides

The standard — 27 rules across five pillars, each with severity, score impact, and remediation guidance.

The CLI — clarx score runs locally or in CI. Exit codes gate merges. clarx explain turns rule IDs into fixes.

The manifest — clarx-manifest.json is the on-ramp: generated directories, verification commands, common task locations, and workspace maps that agents load every session.

AI rules files — portable CLAUDE.md, Cursor rules, and AGENTS.md snippets that keep generated code aligned with your conventions.

Philosophy

Structure is communication before convenience. A repo should tell an agent where things live, what to skip, and how to verify changes — not bury that in tribal knowledge.

Intent should be explicit in the repo. Manifests, guidance files, and clear entry points encode semantics that scattered README fragments cannot.

Boundaries should be enforceable. Import graphs, package indexes, and generated-artifact hygiene prevent agents from taking shortcuts that humans would catch in review.

Standards must serve humans and machines. Rule IDs, deterministic scoring, and machine-readable output make improvement measurable — not subjective.

The system should survive change. Frameworks and languages churn. Discoverability, boundaries, and operational guidance compound over time.