AI coding agents are getting much better at writing code.

But in real engineering work, the hard problems are often not just about whether the model can generate a patch.

The harder questions are:

• Did it read the right project baseline first?
• Did it understand the actual owner of the behavior?
• Did it verify the fix before claiming completion?
• Did it distinguish facts from assumptions?
• Did it preserve architecture boundaries?
• Did it leave enough evidence for a human or another agent to continue safely?

I built Aegis to work on that layer.

GitHub: https://github.com/GanyuanRan/Aegis

What is Aegis?

Aegis is an open-source method pack for AI coding agents.

Instead, Aegis provides workflow discipline that can be installed into different AI coding hosts.

The current positioning is:

Aegis Method Pack: runtime-ready workflow discipline for AI coding agents.

That means Aegis focuses on the behaviors around the coding agent:

• how it starts a task
• how it reads project context
• how it plans
• how it debugs
• how it applies TDD
• how it verifies completion
• how it reports residual risk
• how it avoids pretending that a method-layer checklist is runtime authority

Why I built it

When working with AI coding agents, I kept seeing the same failure patterns.

The agent would often:

• skip the architecture baseline
• patch the consumer instead of the canonical owner
• add another fallback instead of retiring the old path
• pass one narrow test and claim the whole task was done
• forget to report architecture drift
• lose the user's requested language or output format
• treat logs or tool output as prompt payload instead of evidence
• confuse the target project with the installed method-pack support path

These issues are not solved only by writing better prompts.

They need repeatable workflow pressure.

What Aegis includes

Aegis currently includes workflow guidance for:

• baseline-first project context
• brainstorming and design clarification
• first-principles review
• writing implementation plans
• test-driven development
• systematic debugging
• long-task continuation
• verification before completion
• architecture alignment reporting
• ADR backfill checks
• cross-host method-pack installation guidance

The goal is not to make the agent more verbose.

The goal is to make the agent less likely to skip the boring steps that protect real projects.

Example: verification before completion

Aegis treats completion claims as something that must be backed by evidence.

Instead of saying:

Done, should work now.

Aegis pushes the agent toward a compact evidence shape:

Evidence Card:
- Command / Check:
- Exit Status:
- Covered:
- Not Covered:
- Residual Risk:
- Confidence:

For architecture-sensitive work, it also asks for an explicit architecture alignment result:

Architecture Alignment:
- Trigger:
- Scope:
- Baseline checked:
- Result: aligned | architecture drift | architecture defect
- Evidence:
- Residual architecture risk:

This is still advisory method-pack discipline.

Example: workspace helper boundaries

One recent fix in Aegis was about a subtle but important boundary.

A method-pack helper should belong to the installed Aegis method-pack path.

The target project should be passed separately:

python <aegis-workspace-helper> check --root <target-project-root>

That sounds small, but it prevents agents from assuming that every project repository must contain its own scripts/aegis-workspace.py.

This is the kind of problem Aegis tries to catch: not just whether a command exists, but whether the ownership model is correct.

What Aegis is not

Aegis deliberately does not claim to be a full runtime platform.

It does not own:

• authoritative runtime core decisions
• authoritative GateDecision
• authoritative PolicySnapshot
• final completion authority

That boundary matters.

A method pack can improve behavior, structure evidence, and make workflows more reliable.

But it should not pretend to be the final source of truth for a project.

The target project's rules, architecture baseline, ADRs, and human decisions still matter.

Who might find this useful?

Aegis may be useful if you:

• use AI coding agents on real codebases
• care about architecture drift
• want stronger verification before completion claims
• want repeatable debugging and TDD workflows
• work across multiple agent hosts
• want agents to preserve project-specific rules instead of inventing new owners

It is probably less useful if you only want a lightweight one-shot coding assistant for small isolated snippets.

Try it

The repo is here:

https://github.com/GanyuanRan/Aegis

The README includes host-specific install notes and verification commands.

A typical verification path includes:

python scripts/aegis-doctor.py --write-config --json
bash tests/e2e/layer1-fast-check.sh --host-profile none

The project is still evolving, and feedback is welcome.

I am especially interested in feedback on:

• whether the method-pack boundary is clear
• whether the install flow is understandable
• which AI coding workflows should be hardened next
• what failure modes people see most often in real agent-assisted development

Closing thought

AI coding agents are no longer just code generators.

They are becoming collaborators in planning, debugging, refactoring, verification, and handoff.

That means the surrounding workflow matters.

Aegis is my attempt to make that workflow more explicit, testable, and reusable.

Disclosure: I used AI assistance to draft and edit this post, then reviewed and adapted it before publishing.