argot CLAUDE.md

argot

A guardrail that flags code foreign to a repo's own patterns — the dependencies, APIs, and constructs an AI coding agent reaches for that the codebase has never used — learned from the repo's git history (north star + metric: benchmarks/catalogs/RUBRIC.md; novel-pattern catch rate @ low false-alarm). A single statically-linked Rust binary (crates/argot-{core,cli}) — no Python, no Node, no runtime dependencies. (Previously a TS/Bun CLI + Python engine; ported to Rust with verified byte-for-byte parity — see docs/rust-port/.)

Guiding principle

In doubt, optimise for code that's easy to change. The Pragmatic Programmer / craftsmanship lens: the right design is the one a future contributor (human or agent) can extend, refactor, or revert without archaeology. When two options look equally correct, pick the one with the smaller blast radius and clearer seams. Don't add abstractions before the second use case shows up; don't keep dead code "just in case"; don't suppress a check when the underlying code is the real fix. Strict tooling (clippy -D warnings, the golden suites) exists to surface change-cost early — work with it, not around it.

Strategy & positioning

Before changing Argot's product, positioning, website, or public claims, read:

• FOUNDER.md — the one-page operating manifesto.
• docs/strategy/ARGOT_STRATEGY.md — canonical strategy (normative decision register D1–D14).
• docs/strategy/ARGOT_CURRENT_REALITY.md — authoritative on what ships today; never market a product requirement as current reality.

This is a founder-level operating layer; it does not change the engineering conventions below.

Task runner

Always use just — it's the canonical interface for all dev commands.

just verify       # fmt --check + clippy -D warnings + test, then verify-features
just verify-features  # the same, per feature: script · arch · integrity
just test         # cargo test --workspace
just extract .    # run extract on this repo → .argot/dataset.jsonl
just dogfood      # run full pipeline against argot itself (or any path) — fast monorepo check
just build        # cargo build --release -p argot → target/release/argot
just bench-quick  # ~1 min bench smoke (one fixture per category + 50 controls)
just arch-verify  # ~25 s architecture-layer fixture-recall regression guard
just integrity-verify  # gaming-fixture recall + control guard for the integrity rules