🌍 Languages: English | Русский
AES Standard: v1.3 Execution Contract: CLAUDE.md Compliance: L1
A standard for building software with AI agents.
AI Engineering Standard (AES) is a structured methodology for human–AI collaboration in software development.
AES transforms AI from a code generator into a predictable engineering partner.
From prompts → to engineering.
AES requires two files:
PROJECT_CONSTITUTION.md— defines WHAT is builtCLAUDE.md— defines HOW AI builds it
Both contracts are required for AES compliance.
Modern AI-assisted development often leads to:
- architectural chaos
- context loss between sessions
- unpredictable regressions
- inconsistent implementations
- continuous rewrites
AES introduces execution contracts, engineering rules, and operational boundaries, making AI development controlled and scalable.
AI executes decisions — it does not invent them.
Clear separation of responsibilities:
| Role | Responsibility |
|---|---|
| Human | Product vision, architecture, priorities |
| AI Agent | Analysis, implementation, validation |
AES consists of two mandatory contracts.
Defines:
- project scope & non-goals
- architecture decisions
- technology stack
- domain model
- security boundaries
- deployment strategy
- definition of done
Answers:
➡️ What are we building?
Defines:
- AI agent role & boundaries
- development workflow (state machine)
- engineering constraints
- forbidden practices
- development priorities
- command system
Answers:
➡️ How must AI build it?
| Command | Behavior |
|---|---|
/constitution |
Create project constitution |
/explore |
Analyze repository |
/spec |
Create feature specification |
/plan |
Generate implementation plan |
/status |
Show project status |
/fix |
Detect & fix errors |
/review |
Perform code review |
/deploy |
Prepare deployment |
AI never starts implementation without an approved plan.
- project analysis
- constitution creation
- context validation
- specification (spec.md)
- step-by-step execution plan (plan.md)
- risk identification
- human approval
- iterative implementation
- architectural compliance
- continuous validation
- stability verification
- debug cleanup
- production readiness
- use typing available in the project's stack
- single responsibility per file
- new files: compact and focused
- meaningful naming
- layered separation
- dependency isolation
- configuration via environment variables
- guarded external calls
- graceful degradation
- structured logging
- failure recovery
- loading state
- empty state
- error state
- confirmation for destructive actions
❌ Suppression of type errors and linter rules ❌ Hardcoded configuration ❌ Secrets in source code (tokens, passwords, API keys) ❌ Debug logs in production ❌ Dead or commented code ❌ Empty catch blocks ❌ Logic duplication ❌ TODO without description ❌ Magic constants
AES defines a hard boundary around resources that agents must never modify without explicit request:
- System config —
.gitconfig,.ssh,.env, shell profiles - Database — schema changes, data modification, migrations by others
- Infrastructure — CI/CD, Docker, lock files, build configs
- Git — branch policies, hooks, remotes, user identity
- Credentials — API keys, tokens, vault configs, certificates
If a task indirectly requires changes to protected resources, the agent stops and asks.
- Works
- Secure
- Typed
- Readable
- Testable
- Optimized
| Level | Description | Required artifacts |
|---|---|---|
| AES-L1 | Constitution defined | PROJECT_CONSTITUTION.md exists and filled |
| AES-L2 | Specification exists | specs/ contains ≥1 approved spec with plan |
| AES-L3 | Architecture enforced | CLAUDE.md configured, 0 violations in last PR |
| AES-L4 | Production Ready | CI checks AES violations automatically |
Projects may declare:
AES: L3 Compliant
cp PROJECT_CONSTITUTION.template.md your-project/PROJECT_CONSTITUTION.md
cp CLAUDE.md your-project/- Define project constitution
- Establish execution context
- Start your AI agent
AI Coding Agents:
- Claude Code
- Cursor
- GitHub Copilot
- Kilo Code
- opencode
- Qwen Code
- Local LLM agents
- Any agent that reads markdown context files
Spec-Driven Development tools:
- GitHub Spec Kit — AES constitution maps to Spec Kit's
/speckit.constitution, plans to/speckit.plan - Any SDD workflow
Suitable for:
- frontend & backend
- mobile
- ML systems
- DevOps
- any language, any stack
Humans design systems. AI executes them.
AES formalizes this boundary.
- Introduced Acceptance Floor (§3.2) as a named invariant — the REVIEW → DEPLOYMENT transition is gated by an explicit act of human acceptance, never removed by maturity, complexity, or passing verification.
- Verification-first: Agent MUST declare its verification approach in PLANNING (and MUST cover any defined acceptance criteria) and execute it in REVIEW. Self-review, verification execution, and acceptance are now three distinct activities in REVIEW.
- Stack-agnostic integrity check: EXECUTION → REVIEW gate now reads "the project's defined integrity check passes" instead of "no compilation/build errors".
- Operational mechanisms (branching, merge, release gating) anchor in §3.2 — they express acceptance but do not substitute for the invariant.
- PLANNING gate is partially compressible (plan/spec formality scales with project maturity); verification declaration is not.
- Explicit compressibility framing across §4 makes the gate hierarchy unambiguous: which transitions can be simplified, which cannot.
- Language-agnostic: removed TypeScript-specific rules, works with any stack
- Removed hard 150 LOC file limit — replaced with "compact and focused" principle
- Added secrets prohibition to Forbidden Practices
- Added Protected Resources section — hard boundaries around system config, database, git, credentials
- Clarified state transitions with artifact gates (spec.md, plan.md)
- Added
/speccommand - Added
/constitution --quickmode - Compliance levels now tied to verifiable artifacts
- UX states upgraded from SHOULD to MUST (loading, empty, error)
- Added Agent Boundaries section (what agent must not do)
- Added Security section to constitution template
- Removed redundant sections: Communication Semantics (self-evident), Project Context (duplicate of constitution)
- Initial RFC-grade specification
- First release
MIT — use, adapt, extend.
⭐ If AES improves your workflow — consider starring the repository.