Inspiration
AI coding assistants can create working software remarkably quickly. However, they may begin implementation before the team has made important architectural decisions explicit: responsibilities, boundaries, quality attributes, risks, and likely future changes.
I wanted to add this missing architecture step directly inside the coding assistant developers already use. The goal was not to replace human architects or create another hosted AI service. It was to help developers think before coding, compare credible alternatives, and preserve the decisions that future coding sessions should follow.
What it does
AI Software Architect is an installable, architecture-first plugin for Codex.
A developer invokes one public skill:
$AI Software Architect
Depending on the request, the architect can:
- clarify architecture-significant requirements;
- review the current project and suggest suitable design patterns;
- compare three to five credible architecture options;
- show transparent fit scores, benefits, liabilities, and assumptions;
- explain architecture styles and design patterns with stored examples;
- ask the user to approve, revise, or request more evidence;
- record an approved Architecture Decision Record;
- create an architecture contract, project context, and coding handoff;
- keep application source code unchanged during architecture planning; and
- review later implementation against the approved architecture.
The decisions are stored with the project instead of remaining trapped inside one chat. This lets a new Codex task understand the intended architecture and identify meaningful architectural drift.
How I built it
I developed the project collaboratively in Codex, using GPT-5.6 Sol extensively for product design, architecture, security analysis, implementation, and exploratory evaluation.
The application combines:
- one public Codex skill with internally routed focused workflows;
- progressive disclosure of architecture knowledge;
- modular references covering architecture styles, GoF patterns, dependency patterns, data patterns, integration patterns, and resilience patterns;
- Pydantic contracts and YAML schemas for structured architecture artifacts;
- short-lived Codex hooks that activate only during an architect workflow;
- deterministic guardrails for repository inspection and artifact persistence;
- a portable shared Python core for future coding-assistant adapters; and
- repeatable automated and exploratory evaluations.
Architecture reasoning remains host-native. The model currently selected by the user in Codex performs the reasoning with the user's Codex allocation. The plugin does not require another AI account, API key, hosted service, or persistent background process.
Challenges I ran into
The largest challenge was making a plugin behave like a coherent architecture workflow without turning it into an unsafe autonomous agent.
Skills were effective for supplying knowledge and instructions, but they could not reliably enforce every transition on their own. I therefore added a plugin-native control plane using lifecycle hooks. These hooks recognize explicit invocation and approval continuations, restrict risky tool behavior during architecture work, and validate architecture artifacts before and after persistence.
Another challenge was balancing usefulness and safety. The architect needs to inspect repositories and save approved decisions, but it must not execute untrusted project code or modify application source. The final design uses fail-closed static-inspection rules, a narrowly bounded .ai-architect/ write surface, complete artifact reconstruction, Pydantic validation, secret scanning, and post-write verification.
Repeated exploratory testing inside Codex revealed workflow and lifecycle problems that conventional unit tests did not expose. Those findings led to architectural changes in invocation routing, continuation handling, plugin provenance checks, persistence, hook failure behavior, and uninstall reliability.
Accomplishments that I'm proud of
The first release provides:
- a complete human-approved architecture workflow inside Codex;
- an installable package that does not require Python,
uv, or project dependencies; - durable ADRs and supporting architecture artifacts;
- project-specific design-pattern recommendations instead of generic lists;
- transparent alternatives rather than silent model decisions;
- safe, static repository inspection;
- a conformance-review workflow that works across Codex tasks;
- 100 automated tests;
- five reproducible end-to-end exploratory evaluations; and
- an adapter-oriented structure prepared for other coding assistants.
The demo shows the complete loop on a deliberately concentrated Python expense application: compare options, approve a lightweight Hexagonal Architecture, record the decision, preserve the source unchanged, and review conformance from a new task.
What I learned
The most important lesson was that model instructions and deterministic controls solve different problems.
The model is best at understanding context, comparing trade-offs, and explaining recommendations. Deterministic schemas and hooks are better at enforcing narrow safety boundaries and verifying persisted artifacts. Combining both produces a stronger workflow than relying on prompts alone.
I also learned that an architecture assistant should not always recommend more architecture. For small or stable applications, "no additional pattern" can be the best answer. The architect must remain proportionate and introduce abstractions only at genuine change seams.
What's next
The first implemented adapter targets Codex. The shared core is designed to support future adapters for GitHub Copilot, Claude Code, Google Antigravity, and other coding assistants without duplicating the architecture knowledge.
Planned work includes:
- coding-assistant-specific adapters;
- broader language-analysis support;
- automated release-level exploratory evaluations;
- additional conformance checks; and
- continued refinement based on real developer feedback.
AI Software Architect is MIT-licensed and is intended to become a community-driven architecture companion for developers working with AI coding agents.
Log in or sign up for Devpost to join the conversation.