A software architecture framework for codebases that humans and AI agents can understand, change, and verify.
AI coding makes edits cheaper. It does not make truth, review, validation, or repository context cheap. A codebase can be easy for an agent to modify and still be hard for a human to trust.
Agent-Operable Architecture asks whether the next likely semantic change can be made with bounded context, clear ownership, limited blast radius, and explicit proof that important behavior still holds.
This is a working engineering framework, not a standard, benchmark, maturity model, or architecture style. It is meant for architecture health reviews, repository decay diagnosis, and AI-coding readiness work.
Chinese version: README.zh-CN.md.
Start with two calibrations:
- Likely change scenarios: what changes must this repository absorb?
- Risk profile: what real commitments does the repository have?
Then ask four questions:
- Where is the source of truth?
- Can semantic changes be completed locally?
- What proves important behavior has not broken?
- Can repository context mislead humans or agents?
Patterns, layering, duplication, generated code, compatibility, rollout, and rollback are evidence only when they connect to a real change path and risk profile.
Use this rubric to keep architecture findings grounded:
| Criterion | Review question |
|---|---|
| Change relevance | Which likely future change may fail? |
| Evidence quality | Which files, schemas, tests, imports, generated artifacts, or docs prove the claim? |
| Root question | Is the issue about truth, locality, proof, context, or a specific combination? |
| Agent failure mode | How might an AI agent make the wrong edit or copy the wrong pattern? |
| Human review difficulty | Why would a bounded human reviewer miss the problem? |
| Minimal remediation | What is the smallest change that reduces future failure risk? |
| Validation proof | What executable or repeatable check shows the remediation worked? |
| Risk calibration | Does the recommendation match the repository's actual commitments? |
A good finding is not "this violates Clean Architecture" or "this file is too large." A good finding says what future change may fail, why the repository makes that failure likely, and what proof would reduce the risk.
See docs/examples.md for worked examples:
- duplicate business decision across domain, API, and UI;
- stale README reviving an old source of truth;
- generated code treated as a handwritten pattern;
- migration without rollback proof.
- docs/framework.md: overview and review order
- docs/change-scenarios.md: how to reason from likely changes
- docs/risk-profile.md: how to calibrate rigor by commitments
- docs/core-questions.md: the four-question model
- docs/review-protocol.md: read-only review protocol and rubric
- docs/examples.md: concrete architecture findings
- docs/evaluation.md: how to evaluate framework use
- docs/glossary.md: terms
- templates/architecture-finding.md: finding template
- templates/review-report.md: review report template
- templates/repo-profile.yaml: repository profile template
- evals/rubric.yaml: lightweight evaluation rubric
- architecture health review;
- source-of-truth and ownership cleanup;
- validation topology review;
- context hygiene review for agent workflows;
- AI-coding readiness audit.
- enforcing a preferred architecture pattern;
- requiring compatibility where no commitment exists;
- turning every smell into a refactor;
- replacing concrete PR review;
- making claims without file-level evidence.
- Agent Skill Control Theory: a framework for designing, evaluating, and evolving LLM agent skills.
- DBX Skills: applied Claude/Codex skills for planning, review, architecture health, and engineering workflows.
- db.oneir.xyz: notes on AI coding, architecture, programming foundations, and software judgment.
Version: 0.2
The framework is intentionally small. Its value should be judged by whether it improves real architecture reviews: fewer decorative findings, clearer root causes, better validation, and fewer AI-generated changes that drift away from the intended model.