agentc-consulting/aed-conventions

1---2license: cc-by-4.03language:4  - en5tags:6  - code7  - code-conventions8  - coding-agents9  - agent-enhanced-development10  - style-guide11  - crystal12pretty_name: "AED Conventions — Agent-Enhanced Development"13size_categories:14  - n<1K15---16 17# AED Conventions — Agent-Enhanced Development18 19**Version `v1.1.0-rc.1` — release candidate.**20 21Code conventions for codebases written, reviewed, and maintained by humans22*and* coding agents together. The guiding rule:23 24> **Prefer the form that reads like a plain statement of intent. Reach for25> shorthand only when it makes the intent _clearer_, never just shorter.**26 27This dataset is a mirror. The **canonical source** is28<https://github.com/AgentC-Consulting/aed-conventions>, and if the two ever29disagree, the repository wins. Maintained by30[AgentC Consulting](https://agentc.consulting).31 32## What's here33 34Chapters 01–04, 07 and `quick_reference.md` are the author's original notes35(written 2024-06-03; `03_process_managers.md` revised 2025-11-24), published36**verbatim** — including his own work-in-progress markers and one section still37marked `TBD`. Chapters 05–06 and the evidence are later work.38 39| File | Contents |40|---|---|41| `dist/aed-v1.1.0-rc.1.md` | **Everything, in one file, in reading order** — start here |42| `01_why_models_need_this.md` | Token windows: why naming carries so much weight for a model |43| `02_naming_conventions.md` | `list_of_` naming, boolean-as-question naming, attributes as short statements |44| `03_process_managers.md` | The "when" grammar for business processes |45| `04_feature_stories.md` | Personas, operations, authorization levels |46| `CONVENTIONS.md` | Chapter 05 — six edit-level style rules with before/after Crystal |47| `06_control_flow.md` | CF-1…CF-11 — `case`, loops, guards, rescues, fibers, macros |48| `07_how_the_workflow_runs.md` | Plan in batches, let the agent run, walk away |49| `quick_reference.md` | The cheat sheet |50| `examples/` | Runnable before/after Crystal files |51| `evidence/` | Small-model comprehension benchmark + raw per-probe data |52| `llms.txt` | Machine-readable map, ordered to match the reading order |53 54## Evidence, with its limits55 56`evidence/haiku_comprehension_report.md` reports AED-style Crystal scoring57**60/60** against **54/60** for conventional compressed style, on 10 snippet58pairs blind-answered by Claude Haiku and blind-graded.59 60Read the stated limits before citing it: n=10 pairs, one small model, a single61run with no variance estimate, a model grader rather than a human one, and the62snippet pairs were authored by the same party that authored the conventions.63It is a **directional signal consistent with the hypothesis, not proof of it**.64 65## Status66 67This is a **release candidate**. Two things are unsettled: the CF-1…CF-1168thresholds (open questions are listed at the end of that chapter), and one69naming example in `CONVENTIONS.md` that conflicts with `02_naming_conventions.md`70— chapter 02 is the authority where they disagree.71 72## Versioning73 74**`v1.x` is this foundation being established.** The v1.1.0 expansion is large,75but size is not what moves the major number: everything in it belongs to the76same frontier foundation `v1.0.0` started — filled in, not replaced. The final77tag on this work will be `v1.1.0`.78 79**`v2.0.0` is reserved for the next generation of improvements** — thinking that80supersedes this foundation rather than completing it. Read a major bump here as81a genuine change of generation, not merely a big release.82 83## Citation84 85See `CITATION.cff`. In short:86 87> Tucker, Seth, and AgentC Consulting. *AED Conventions — Agent-Enhanced88> Development: Code That Reads Like Statements*, v1.1.0-rc.1, 2026.89> https://github.com/AgentC-Consulting/aed-conventions90 91## License92 93Dual-licensed, matching the canonical repository:94 95- **Prose and documentation** — [CC BY 4.0](LICENSE). Reuse and adapt freely,96  with credit to [AgentC Consulting](https://agentc.consulting).97- **Code under `examples/`** — [MIT](LICENSE-EXAMPLES). Take it freely, with or98  without credit.99