Free & open source · MIT licensed
Your AI writes code fast.
AIDD ensures it doesn’t break production.
A lightweight methodology and mechanical CLI that stops Claude Code, Codex, and Gemini CLI from hallucinating requirements and grading their own homework.
$ aidd check specs/001-auth/[!] ERROR: Step 6 bypassed.[!] require_independent_audit.py: Subagent audit missing.[!] The implementer cannot grade its own homework.--> Dispatched QA Subagent (UI & Security)...--> Found 1 missing error handler in CTL-004.$ aidd check-charter .340 violation(s) across 6 rule(s) — relative imports (Art. 3.3)$ aidd search "auth flow"-> AMEND F02-Auth-Shell: reopen its spec — do NOT create a new folder.Never the same agent that wrote it. Never a guessed requirement.
Search first. Ask first. Review independently. Every time.
Sound familiar?
AI coding agents are fast at writing code and bad at knowing what already exists. Left alone, they duplicate specs nobody asked for, ship fixes that fabricate success, and grade their own homework when asked to review it.
“I asked it to fix one button. It rewrote half the screen and I had to figure out what changed.”
Without a plan the AI checks itself against, “fix this” becomes “guess what else might need fixing too.”
“I've reviewed this same screen three times this month for basically the same reason.”
Mistakes found after the code is written cost a redo. AIDD finds them while the plan is still just a plan.
Is this actually for you? If two or more sound like your week, it is:
- ✕Your AI tool creates something new every time, even for a tiny fix, instead of reusing what's already there.
- ✕You've reviewed the same screen or feature more than twice for basically the same reason.
- ✕Nobody on the team is sure which conversation or file has the “real” current requirements anymore.
- ✕You've caught your AI referencing a screen, button, or database table that turned out not to actually exist.
- ✕Your team uses more than one AI coding tool, and each one seems to “know” different things about the project.
- ✕Your architecture rules live in a doc nobody's re-checked against the actual code in months.
How it works
One short routine, every request: check what exists → plan it out loud → build it in small pieces → independent review → compare to the design.
Search first
Every request runs against a compact, auto-built graph of every existing spec before anything new gets created. A match means “amend this,” not “start over.”
Audit the mockup, draw the flow
A mechanical pass inventories every screen, component, and control, then one Mermaid diagram per use case replaces paragraphs of prose — correct the diagram, don't describe the fix.
Align
Every ambiguity becomes an explicit question for you before code is written, not something discovered after a review.
Plan the Screen → Code map
A fresh agent drafts the naming contract and the Screen → Code / Component → Code maps against the real codebase. You approve the draft.
Break into small-PR tasks
One screen, one component, or one behavior per task — never batched — each sized with a classify / estimate / decompose / assign rubric.
Build, one PR at a time
Every PR ships against a four-part Definition of Done: code, a mapping row, a written-back PR reference, and a screenshot diff against the mockup.
Independent review
A separate agent — never the one that built it — audits the result per domain (UI, backend, database, performance). On Claude Code this is a hard technical gate, not just a rule.
Hand off the documentation
A comprehensive handoff doc is assembled from what already exists — reassembled, never re-explained.
Why AIDD, not just “write a spec first”
Plenty of workflows tell an agent to plan before it codes. AIDD’s difference is what happens when the agent is tempted to skip that — and what gets checked mechanically instead of trusted to memory.
Enforced, not just documented
A generic spec-driven process is a set of documents an agent is supposed to follow. AIDD's Step 6 independent-audit rule and its graph-coherence check are actual hooks on Claude Code (require_independent_audit.py, require_graph_coherence_audit.py) that hard-block a write until the rule was actually followed — not a convention trusted to memory.
A charter that's actually checked
Project-wide rules split into judgment calls (prose) and checkable ones (pattern + glob) that check_charter.py runs for real. Run against a real production project, it caught two stale “unused” claims in that project's own hand-written notes — both false — and a third rated low-severity that turned out to be 340 real violations.
Reusable components, not per-screen rebuilds
COMP-nnn codes are built once and referenced by every screen that uses them — like a component-based design tool assembling from a library — closing the “rebuilt three times, slightly differently” gap that pure narrative specs don't catch.
Full-stack traceable, not UI-only
A CTL-nnn control that triggers a network call cites the API-nnn it depends on, and contracts.md cites the control back. A backend change's blast radius on the UI becomes a lookup, not a grep across the whole codebase.
One methodology, every tool
skill/AIDD.md is the tool-agnostic core. Claude Code, OpenCode, and Codex read it natively; generate_adapters.py renders the same steps as native command files for Gemini CLI, Cursor, Windsurf, Cline, and GitHub Copilot — one source, no per-agent copy to keep in sync.
Ships to your actual tracker
An approved tasks.md becomes real, trackable issues in GitHub, Azure DevOps, or Bitbucket via tasks_to_issues.py — dry-run by default, never duplicates on re-run. Not another silo of markdown nobody opens again.
Built for teams, not just solo sessions
Approved tasks become real, trackable issues in the tracker your team already uses — never orphaned markdown nobody re-checks.
GitHub Issues
gh CLI, dry-run by default
Azure DevOps
az CLI + azure-devops extension
Bitbucket Cloud
REST API v2.0, app-password auth
aidd tasks-to-issues specs/001-login/tasks.md --provider azure_devops --org ... --applyFrequently asked
Don’t see yours? Open a GitHub issue or discussion.
Is this a new AI agent I have to learn?+
No. AIDD is not a tool to learn — it's a set of habits your existing AI coding assistant follows for you. You keep using Claude Code, OpenCode, Codex, or Gemini CLI exactly as you do today; AIDD changes what that assistant does before, during, and after it touches code.
Do I need to install anything new?+
For Claude Code: copy skill/ to ~/.claude/skills/aidd and run python scripts/install_hooks.py once. For OpenCode, Codex, or Gemini CLI, a thin adapter points back to the same methodology core — nothing duplicated or relearned per tool.
Does it work in any language?+
The automatic prompt-level nudge covers English, Spanish, Portuguese, and a handful of literal Chinese trigger terms. Outside those, the pipeline still engages — the skill's description is matched semantically regardless of language, and the hard code-edit gate doesn't read the prompt at all.
Is the “independent audit” real, or just a rule in a doc?+
Both, depending on the tool. On Claude Code it's an actual technical gate: writing or updating qa-audit.md is blocked unless a separate subagent was dispatched after the last code edit. On other tools it's the same rule, followed the same way, without that specific lock yet.
Are the token-savings numbers real?+
Yes — measured, not estimated, by comparing a plain read of the relevant spec files against what AIDD's own lookup tools (find_spec.py, check_spec.py) report back, on a real working project. The exact reproduction commands ship in the docs.
Does AIDD replace code review or human judgment?+
No. It replaces the busywork of checking — searching for duplicates, re-reading whole files, grading your own fix — so a person's judgment gets spent on what actually needs it.
Is there a cost?+
AIDD itself is free and open source (MIT license). If your team wants help adopting it — workflow diagnosis, implementation, custom rules, training, ongoing support — every engagement is scoped individually. Open a GitHub issue to talk specifics.
AIDD is 100% free & open source, under MIT
Built by developers dealing with AI hallucinations daily. If AIDD saves you debugging hours, leave a star on GitHub and help us expand the multi-agent adapter ecosystem.
⭐ Star on GitHubGet in touch
Questions, bug reports, or just want to say hi? Send a message and it’ll open your email client, ready to go.