DEV Community

Peter Ma
Peter Ma

Posted on • Originally published at github.com

Aegis: Stop AI Agents from Turning Your Codebase into Chaos

#ai #agentskill #coding #opensource

AI coding agents are incredibly productive — until they're not.

You've probably seen it: you ask an AI to build a feature, and it delivers something that works but silently breaks three other things. The API contract drifts from the frontend's expectations. Types are duplicated across packages. Error handling is inconsistent. There's no test that catches the drift because nobody defined what "correct" means upfront.

This is the real cost of AI-assisted development at scale. Not the code quality of individual files — AI writes decent code. The problem is coherence across a system.

The Root Cause

Most AI coding workflows are implementation-first: you describe what you want, the agent writes code, you review it. This works for small tasks. But for anything beyond a single file — multi-service APIs, full-stack features, team projects — you're missing the layer that keeps everything consistent:

Contracts.

In traditional engineering, we solve this with API specs, shared type definitions, and design documents. But when AI agents generate code, they often skip straight to implementation, hallucinating interfaces that may or may not match what other parts of the system expect.

What is Aegis?

Aegis is an open-source AgentSkill that adds five layers of defense to AI-assisted development:

Design → Contract → Implementation → Verification → PM
Enter fullscreen mode Exit fullscreen mode

Each phase builds on the previous:

1. Design Phase

Before any code is written, Aegis requires a Design Brief — a structured document that captures:

  • Problem statement and user stories
  • Technical approach and architecture decisions
  • API boundaries and data flow
  • Risk assessment

This isn't a 50-page spec. It's a focused, 1-2 page brief that ensures the AI agent and the developer agree on what they're building before how.

2. Contract Phase

The core of Aegis. Before implementation, you define:

  • OpenAPI specs for every API endpoint
  • Shared types (TypeScript/protobuf/JSON Schema) used across services
  • Error code registry — unified error handling, no ad-hoc HTTP 500s

These contracts become the single source of truth. The AI agent generates code against contracts, not into thin air.

3. Implementation Phase

Now the agent writes code — but constrained by contracts. The generated CLAUDE.md (or equivalent config) includes Aegis rules that enforce:

  • All API handlers must match the OpenAPI spec
  • All shared types must come from the contract package
  • All errors must use registered error codes
  • No magic numbers, no ad-hoc interfaces

4. Verification Phase

Aegis includes scripts and templates for:

  • Contract tests — does the implementation match the spec?
  • Gap reports — what's in the design brief but not in the code?
  • Integration tests — do the services actually talk to each other correctly?

5. PM Phase

Progress tracking and quality gates. Know what's done, what's pending, and what's drifted.

Two Modes

Lite Mode — Just the Design Brief. Perfect for solo devs or small features. Takes 5 minutes to set up, prevents 80% of the chaos.

Full Mode — Complete contract-first workflow. For teams, complex projects, or anything with more than one service boundary.

Quick Start

Claude Code users:

git clone https://github.com/skill-forge-ai/aegis.git /tmp/aegis \
  && cp -r /tmp/aegis/cc-skill ~/.claude/skills/aegis \
  && rm -rf /tmp/aegis
Enter fullscreen mode Exit fullscreen mode

OpenClaw users:

npx clawhub@latest install aegis-quality-guardian
Enter fullscreen mode Exit fullscreen mode

Then initialize in your project:

bash ~/.claude/skills/aegis/scripts/init-project.sh /path/to/your/project
Enter fullscreen mode Exit fullscreen mode

What's Included

Category Count Examples
Templates 8 Design Brief, CLAUDE.md, OpenAPI starter, shared types, error codes, contract tests, integration tests, implementation summary
Scripts 6 Project init, stack detection, contract validation, gap report, type generation, guardrails setup
References 3 Contract-first guide, testing strategy, multi-agent protocol

Why Open Source?

Because quality guardrails shouldn't be proprietary. Every team using AI agents faces the same coherence problem. Aegis is MIT-licensed and designed to be extended:

  • Add templates for your language/framework
  • Customize the Design Brief for your domain
  • Contribute contract validation rules
  • Build on the multi-agent coordination protocol

Compatibility

Aegis works with any agent that supports the AgentSkill spec:

  • ✅ Claude Code
  • ✅ OpenAI Codex CLI
  • ✅ Gemini CLI
  • ✅ Cursor
  • ✅ OpenClaw
  • ✅ Any tool that reads SKILL.md

Get Started

Built by SkillForge AI — open-source AI agent skills for the community.

Star the repo if you find it useful. And if you've built quality guardrails for your own AI workflows, we'd love your contributions.

Top comments (0)