AI-Driven Development โ a manifesto, its principles, and the laws behind them
A stand on how AI changes the way we build software: constrain the output, not the reasoning. Humans write the specification and own the contracts and the release; generators build everything deterministic; agents fill the rest inside guardrails; and work is done when it is rolled out, observed and measured.
An argument, not a tool
In Greek myth, Aeos (แผจฯฯ) is one of the four horses that pull Helios' Sun Chariot across the sky โ pure power, held on a fixed course by its driver. That is the stance of this project: the human holds the reins; the agents do the pulling.
AEOS began as an argument, not a tool. Its premise is that AI makes the engineering discipline of the last forty years more valuable, not less. Domain-driven design, explicit contracts, tests, feature flags and continuous delivery are exactly the controls that keep agent output correct โ so the right response to capable agents is to double down on discipline and treat every agent like a capable engineer on their first day, every day: it remembers nothing between runs and sees only what has been written down, so you write everything down.
The Twelve Principles
Each principle links to its enforcement tooling โ a reference architecture, CI gates and tool comparisons for turning it into a control a machine checks.
AI makes the engineering discipline of the last forty years more valuable. Domain-driven design, explicit contracts, tests, feature flags and continuous delivery are the controls that keep agent output correct.
Enforcement tooling โ IIAn agent gets real trust and autonomy inside explicit guardrails. It remembers nothing from yesterday and sees only what has been written down, so the team writes down everything it needs.
Enforcement tooling โ IIIGherkin scenarios, EARS requirements, actors, UML and ERD diagrams, the OpenAPI contract and the domain invariants are the most important engineering artefacts. A human drafts them and an agent reviews the draft, and an agent drafts only from decisions already in the decision log.
Enforcement tooling โ IVEverything derivable from the specification is generated deterministically: types and interfaces from the OpenAPI contract, repository code from a human-owned schema, and the end-to-end suite from Gherkin scenarios. Invariants are enforced by constraints and property tests, and agents fill in the business logic.
Enforcement tooling โ VDecision logs, specifications and the agents' own reasoning are committed next to the code, and every artefact links to the decision behind it. A gap found late amends the decision log or the spec first, and a missing decision stops the work.
Enforcement tooling โ VIEvery reviewer on the panel (engineering, product, invariants, architecture and security) runs deterministic checks before a review agent covers what rules cannot express. When an agent keeps catching the same problem, that finding becomes a rule.
Enforcement tooling โ VIIThe specification, any change to the API contract or database schema, and the release always have a human. Above that floor, engineering leadership decides where humans sign off, and a gate earns autonomy from evaluation data and loses it with an escaped defect.
Enforcement tooling โ VIIIDeployment runs automatically behind feature flags, automated rollback and detailed monitoring. Release is a human decision, and work is done when it is released, observed and measured against its success metric.
Enforcement tooling โ IXThe full pipeline is for changes people would otherwise argue about later, while a wording fix, a behaviour tweak or a bug starts further down. Every track still goes through a pull request with green checks, and contract and schema changes always get an engineer review.
Enforcement tooling โ XThe Product Engineering Architect is an engineer accountable for the specification, the contracts, the invariants and the data model, and agents build to them. The Product Manager owns the strategy, the problem and the priority, and the two meet at the specification.
Enforcement tooling โ XIJuniors write part of their code by hand, start with small specifications and failing tests, and review agent output alongside a senior. Teaching is part of a senior's job, because this model depends on a steady supply of seniors.
Enforcement tooling โ XIIDelivery is judged on the DORA metrics, with lead time measured to deployment and to release, alongside spec amendments, time waiting at human gates, the panel's override rate and model spend per released change. Agents do not learn between runs, so the evaluations tune the system.
Enforcement tooling โThe Documents
The Implementation
aeos-core is the reference implementation of these principles: AEOS, the Agentic Engineering Operating System โ a CLI that drives a ticket from idea to reviewed code through LLM-agent pipelines, where every stage has a worker agent, a reviewer agent with machine-readable rubrics, and a human approval gate, and the orchestrator that decides what runs next is a deterministic function that never merges a PR and never clears the final human gate.