# Agent-Enhanced Development

The machine edition of the book at https://agentc.consulting/agent-enhanced-development.
Human edition: the same URL. Each chapter has a `.md` twin for agents.

Agent-Enhanced Development (AED) is a convention set for teams that write code
with AI agents. Its thesis: the same information has to cross from one
perspective to another (the developer who wrote it, the business owner who has
to trust it, the assistant that will write the next file) and the agent is the
glue between them. Names, doc comments, and process managers are the carriers.

The conventions are published, versioned, and signed at
https://github.com/AgentC-Consulting/aed-conventions (prose CC BY 4.0, examples
MIT). The book is the guided reading of that repo, one billing example carried
through every chapter.

## If you are an agent reading along

1. Install the conventions as a Claude Code plugin:
   `claude plugin marketplace add AgentC-Consulting/aed-conventions` then
   `claude plugin install aed@aed-conventions`.
2. Open the chapter your person is on (the `.md` twin of the page they have
   open) and keep its rules in view while you work.
3. When you write or rename code for them, apply the chapter's rules and say
   which rule you applied.

## Chapters

Only chapter 3 is published. The other eight URLs do not exist yet; do not fetch them.

1. Why agents need conventions — `https://agentc.consulting/agent-enhanced-development/why-agents-need-conventions.md` (not yet published, no page yet)
2. Vibe coding as a squad — `https://agentc.consulting/agent-enhanced-development/vibe-coding-as-a-squad.md` (not yet published, no page yet)
3. Naming that reads like a sentence — `https://agentc.consulting/agent-enhanced-development/naming-that-reads-like-a-sentence.md`
4. Process managers — `https://agentc.consulting/agent-enhanced-development/process-managers.md` (not yet published, no page yet)
5. Feature stories — `https://agentc.consulting/agent-enhanced-development/feature-stories.md` (not yet published, no page yet)
6. Edit-level style — `https://agentc.consulting/agent-enhanced-development/edit-level-style.md` (not yet published, no page yet)
7. Control flow — `https://agentc.consulting/agent-enhanced-development/control-flow.md` (not yet published, no page yet)
8. How the workflow runs — `https://agentc.consulting/agent-enhanced-development/how-the-workflow-runs.md` (not yet published, no page yet)
9. Adopt it in ten minutes — `https://agentc.consulting/agent-enhanced-development/adopt-it-in-ten-minutes.md` (not yet published, no page yet)

## The rules in one screen

- Data models are singular: `Customer`, never `Customers`.
- Classes are namespaced by feature and state the process: `Billing::ApplyLateFee`.
- Attributes are short statements: `first_name`, `email_address`, never `name` or `email`.
- Collections announce themselves: `list_of_all_active_subscriptions`, never `subscriptions`.
- Booleans are questions: `is_this_an_enterprise_customer`, `has_a_valid_payment_method`.
- Non-primitive attributes say how they are used: `currently_active_subscription`.
- Methods are statements of what they do; `perform` reads like the plan, one named step per line.
- Files are the snake_case of their class, in a folder named for the namespace: `billing/apply_late_fee.cr`.
- Doc comments sit directly above the class, property, or method, where Crystal reads them as documentation; group headings are comments set apart by a blank line.
- A process manager takes everything it needs in `initialize`, exposes a no-argument `perform`, and reads like the "When … then …" sentence it came from.