Engineering canon

Agent‑Enhanced Development

AED is how AgentC writes code that humans and coding agents can read, change, and review with the least friction — published as an open, versioned, signed convention set anyone may adopt.

Prefer the form that reads like a plain statement of intent. Reach for shorthand only when it makes the intent clearer, never just shorter.

Code is read and modified far more often than it is written — and in an agent‑driven codebase, “read” now includes every agent that will ever touch the file. Clever, compressed syntax saves the author a few keystrokes and costs every later reader, human or machine, a re‑parse. AED optimizes for the reader.

These conventions are the readability half of the practice. Their correctness companion is edit‑time verification: the compiler’s type check runs on every edited file, so mistakes surface immediately — not minutes later in a full build.

CONVENTIONS · v1.0.0 · SIGNED

The six rules

  1. Branch on type with an explicit if … is_a? — not a clever case. An ordinary if reads like a sentence.
  2. Name the thing — don’t make the reader decode a chain of operations held in their head.
  3. Prefer explicit guard clauses — over nested ternaries and dense one‑liners.
  4. Use full, intention‑revealing names — expressive enough that naming becomes the documentation’s skeleton.
  5. Say why in a comment; let the code say what — comments carry constraints the code can’t show.
  6. One statement per line — let the formatter own the layout.

Shorthand that genuinely clarifies is welcome — the canon lists those cases — and every edit finishes with the end‑of‑edit checklist. The examples are Crystal, because that is what we build with; the rules are about reading, not syntax.

Read the canon

  • Canonical repository — the rules with real before/after examples and the reasoning behind each. CC BY 4.0 prose, MIT examples.
  • Release v1.0.0 — signed and tagged; the adoption record dates every rule.
  • Before/after examples — self-contained files, one per rule cluster, labeled for humans and agents alike.
  • Cite it — CITATION.cff for papers, posts, and tooling docs.
  • Dataset mirror — the examples as a Hugging Face dataset.

These conventions aren’t aspirational — they run in production on every build AgentC ships. See how we build.