Updated 17 October 2026 · Software architecture
Abstract. AI coding agents do not make architecture obsolete; they make architecture executable. When Codex, Claude Code or another agent can modify hundreds of files, the decisive design objects are contracts, boundaries, invariants and tests. This article connects object-oriented principles with agentic software engineering and proposes contract-driven agency: agents may change implementations freely only inside machine-verifiable architectural constraints.
OOP after code generation
Encapsulation remains valuable because it limits the blast radius of change. Polymorphism remains valuable because it enables substitution. Dependency inversion becomes even more important because it creates mockable and replaceable tool boundaries. What changes is the consumer: interfaces must now be legible to both humans and models. Ambiguous conventions that experienced maintainers infer tacitly should become explicit schemas, examples and invariant tests.
Repository-scale benchmarks show why. SWE-bench evaluates whether systems can resolve real GitHub issues, exposing the gap between function generation and software maintenance (Jimenez et al., 2024). SWE-agent further shows that the agent-computer interface materially affects results (Yang et al., 2024). Architecture is therefore partly an interface-design problem for machine collaborators.
Agent-readable architecture
| Classic concept | Agentic extension | Executable evidence |
|---|---|---|
| Class invariant | Repository-wide behavioral constraint | Property test or static rule |
| Interface | Typed tool/API contract | Schema validation and contract test |
| Module boundary | Agent permission boundary | Ownership and path policy |
| Design pattern | Reusable playbook | Template plus acceptance suite |
| Code review | Evidence-gated merge | Diff, tests, risk analysis and provenance |
Agentless is instructive because it achieves competitive issue resolution through localization, repair and patch validation without a complex autonomous agent architecture (Xia et al., 2024). The result cautions against agent maximalism: use the smallest control structure that reliably solves the task.
Graph engineering the codebase
An agent should not discover architecture solely by reading files. Build a multi-layer graph: packages depend on packages; services own APIs; data classifications constrain flows; tests cover behaviors; teams own decisions. A change request becomes a subgraph with explicit impact hypotheses. Retrieval over this graph helps the agent locate code, while policies restrict write scope.
Repository context files—such as AGENTS.md, Claude instructions or Cursor rules—are emerging architecture surfaces. Empirical analysis of 401 projects found recurring context categories including conventions, project information and examples (Jiang & Nam, 2025). These files should not become prose dumps. Keep them short, hierarchical, tested and close to the boundary they govern.
Patterns for Codex and Claude workflows
1. Ports, adapters and permissioned tools
Expose databases, queues and external systems through typed adapters. Give agents test doubles by default and production credentials only through approved, narrowly scoped workflows.
2. Characterization before transformation
For legacy code, require an agent to produce behavior-capturing tests before refactoring. Separate the “understand” commit from the “change” commit so reviewers can detect accidental semantic drift.
3. Spec–implement–critic separation
Use distinct contexts—or distinct agents—for specification, implementation and verification. Reflexion research shows the value of feedback and memory, but the verifier must not merely repeat the generator’s assumptions (Shinn et al., 2023).
4. Merge-readiness packs
Require a structured artifact containing changed contracts, test evidence, unresolved risks, dependency effects and rollback instructions. This aligns with the workbench concept in structured agentic software engineering (Hassan et al., 2025).
Anti-patterns
- Generated abstraction inflation: new layers without a demonstrated substitution or isolation need.
- Pattern hallucination: naming a familiar pattern while violating its invariants.
- Test-shaped overfitting: satisfying visible tests while breaking unobserved contracts.
- Autonomous architecture drift: many locally plausible changes that cumulatively erase system boundaries.
Design rule. Let agents optimize implementations; reserve authority over public contracts, data boundaries and irreversible architecture decisions for explicit review. Autonomy should expand only where verification is stronger than the potential blast radius.
References
- Hassan, A. E., Li, H., Lin, D., Adams, B., Chen, T.-H., Kashiwa, Y., & Qiu, D. (2025). Agentic software engineering: Foundational pillars and a research roadmap. arXiv. https://arxiv.org/abs/2509.06216
- Jiang, S., & Nam, D. (2025). An empirical study of developer-provided context for AI coding assistants in open-source projects. arXiv. https://arxiv.org/abs/2512.18925
- Jimenez, C. E., Yang, J., Wettig, A., Yao, S., Pei, K., Press, O., & Narasimhan, K. R. (2024). SWE-bench: Can language models resolve real-world GitHub issues? International Conference on Learning Representations. https://arxiv.org/abs/2310.06770
- Shinn, N., Cassano, F., Gopinath, A., Narasimhan, K., & Yao, S. (2023). Reflexion: Language agents with verbal reinforcement learning. Advances in Neural Information Processing Systems, 36, 8634–8652. https://arxiv.org/abs/2303.11366
- Xia, C. S., Deng, Y., Dunn, S., & Zhang, L. (2024). Agentless: Demystifying LLM-based software engineering agents. arXiv. https://arxiv.org/abs/2407.01489
- Yang, J., Jimenez, C. E., Wettig, A., Lieret, K., Yao, S., Narasimhan, K., & Press, O. (2024). SWE-agent: Agent-computer interfaces enable automated software engineering. arXiv. https://arxiv.org/abs/2405.15793