Datasetpublic

agentc-consulting/aed-conventions

AED Conventions — Agent-Enhanced Development Version v1.1.0-rc.1 — release candidate. Code conventions for codebases written, reviewed, and maintained by humans and coding agents together. The guiding rule: Prefer the form that reads like a plain statement of intent. Reach for shorthand only when it makes the intent clearer, never just shorter. This dataset is a mirror. The canonical source is https://github.com/AgentC-Consulting/aed-conventions, and if the two ever disagree… See the full description on the dataset page: https://huggingface.co/datasets/agentc-consulting/aed-conventions.

sourceHugging Facecc-by-4.0updated 2mo agoView on Hugging Face

0likes36downloads

Dataset Card

AED Conventions — Agent-Enhanced Development

Version `v1.1.0-rc.1` — release candidate.

Code conventions for codebases written, reviewed, and maintained by humans and coding agents together. The guiding rule:

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

This dataset is a mirror. The canonical source is <https://github.com/AgentC-Consulting/aed-conventions>, and if the two ever disagree, the repository wins. Maintained by AgentC Consulting.

What's here

Chapters 01–04, 07 and quick_reference.md are the author's original notes (written 2024-06-03; 03_process_managers.md revised 2025-11-24), published verbatim — including his own work-in-progress markers and one section still marked TBD. Chapters 05–06 and the evidence are later work.

File	Contents
`dist/aed-v1.1.0-rc.1.md`	Everything, in one file, in reading order — start here
`01_why_models_need_this.md`	Token windows: why naming carries so much weight for a model
`02_naming_conventions.md`	`list_of_` naming, boolean-as-question naming, attributes as short statements
`03_process_managers.md`	The "when" grammar for business processes
`04_feature_stories.md`	Personas, operations, authorization levels
`CONVENTIONS.md`	Chapter 05 — six edit-level style rules with before/after Crystal
`06_control_flow.md`	CF-1…CF-11 — `case`, loops, guards, rescues, fibers, macros
`07_how_the_workflow_runs.md`	Plan in batches, let the agent run, walk away
`quick_reference.md`	The cheat sheet
`examples/`	Runnable before/after Crystal files
`evidence/`	Small-model comprehension benchmark + raw per-probe data
`llms.txt`	Machine-readable map, ordered to match the reading order

Evidence, with its limits

evidence/haiku_comprehension_report.md reports AED-style Crystal scoring 60/60 against 54/60 for conventional compressed style, on 10 snippet pairs blind-answered by Claude Haiku and blind-graded.

Read the stated limits before citing it: n=10 pairs, one small model, a single run with no variance estimate, a model grader rather than a human one, and the snippet pairs were authored by the same party that authored the conventions. It is a directional signal consistent with the hypothesis, not proof of it.

Status

This is a release candidate. Two things are unsettled: the CF-1…CF-11 thresholds (open questions are listed at the end of that chapter), and one naming example in CONVENTIONS.md that conflicts with 02_naming_conventions.md — chapter 02 is the authority where they disagree.

Versioning

`v1.x` is this foundation being established. The v1.1.0 expansion is large, but size is not what moves the major number: everything in it belongs to the same frontier foundation v1.0.0 started — filled in, not replaced. The final tag on this work will be v1.1.0.

`v2.0.0` is reserved for the next generation of improvements — thinking that supersedes this foundation rather than completing it. Read a major bump here as a genuine change of generation, not merely a big release.

Citation

See CITATION.cff. In short:

Tucker, Seth, and AgentC Consulting. AED Conventions — Agent-Enhanced Development: Code That Reads Like Statements, v1.1.0-rc.1, 2026. https://github.com/AgentC-Consulting/aed-conventions

License

Dual-licensed, matching the canonical repository:

—Prose and documentation — CC BY 4.0. Reuse and adapt freely, with credit to AgentC Consulting.
—Code under `examples/` — MIT. Take it freely, with or without credit.