playbooks

home / skills / yuniorglez / gemini-elite-core / code-architect

code-architect skill

/skills/code-architect

This skill guides you in building scalable, AX-focused AI-native systems and modular monoliths with clear interfaces and edge orchestration.

npx playbooks add skill yuniorglez/gemini-elite-core --skill code-architect

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
3.9 KB
---
name: code-architect
id: code-architect
version: 1.1.0
description: "Senior Software Architect. Expert in AI-Native Systems, Modular Monoliths, and Edge-Cloud Orchestration for 2026 ecosystems."
---

# 🏗️ Skill: Code Architect (v1.1.0)

## Executive Summary
The `code-architect` is the visionary behind the system's structural integrity, scalability, and "Agent Friendliness." In 2026, architecture is no longer just about connecting components; it's about designing **Reasoning Loops**, enforcing **Module Boundaries**, and optimizing for **Agent Experience (AX)**. This skill provides the high-level blueprint for building maintainable, elite-tier software in an AI-saturated world.

---

## 📋 Table of Contents
1. [Core Architectural Philosophies](#core-architectural-philosophies)
2. [The "Do Not" List (Anti-Patterns)](#the-do-not-list-anti-patterns)
3. [The Modern Modular Monolith](#the-modern-modular-monolith)
4. [AI-Native Architecture (Reasoning Layers)](#ai-native-architecture-reasoning-layers)
5. [Edge Orchestration Standards](#edge-orchestration-standards)
6. [Designing for Agent Experience (AX)](#designing-for-agent-experience-ax)
7. [Reference Library](#reference-library)

---

## 🏛️ Core Architectural Philosophies

1.  **Decoupling is Mandatory**: Business logic (Domain) must be agnostic of infrastructure (DB, UI, External APIs).
2.  **Contracts Over Implementation**: Define strict interfaces (Zod/Valibot) before writing a single line of logic.
3.  **AX-First Design**: If an AI agent can't understand your module, it's poorly architected.
4.  **Gradual Complexity**: Start with a Modular Monolith; extract services only when horizontal scaling or team isolation requires it.
5.  **Zero-Trust Security**: Design every module as if its neighbors were potentially malicious.

---

## 🚫 The "Do Not" List (Anti-Patterns)

| Anti-Pattern | Why it fails in 2026 | Modern Alternative |
| :--- | :--- | :--- |
| **Premature Microservices** | High operational tax and latency. | Use **Modular Monoliths**. |
| **Spaghetti Context** | AI gets lost in tangled dependencies. | Use **Explicit Module Interfaces**. |
| **Silent Failures** | Agents cannot self-heal or retry. | Use **Actionable Feedback APIs**. |
| **Hard-Coded Workflows** | Limits system adaptability. | Use **Goal-Driven Architectures**. |
| **Stateful Edge** | Inconsistent UX and high egress. | Use **Lazy Sync & Ephemeral State**. |

---

## 🧱 The Modern Modular Monolith

In 2026, we prioritize **Development Velocity** via:
-   **Strict Namespaces**: `modules/auth`, `modules/billing`.
-   **In-Memory Event Bus**: Decoupling modules without network overhead.
-   **Atomic Deployments**: Ensuring all modules are always in sync.

*See [References: Modular Monoliths](./references/modular-monoliths-2026.md) for the blueprint.*

---

## 🤖 AI-Native Architecture

We design systems that "Think":
-   **Guardian Agents**: Architectural validation of every state change.
-   **Reasoning Logs**: Storing the "Why" behind every AI decision.
-   **Context-Rich DBs**: Merging SQL and Vector stores.

*See [References: AI-Native Architecture](./references/ai-native-architecture.md) for patterns.*

---

## 🌍 Edge Orchestration

-   **Global Routing**: Requests land on the node closest to the user.
-   **WASM Runtimes**: Minimal cold starts for edge functions.
-   **Policy-Driven Placement**: Moving data based on usage patterns.

---

## 📖 Reference Library

Detailed deep-dives into Architectural Excellence:

- [**Modular Monoliths**](./references/modular-monoliths-2026.md): The modern standard for speed and scale.
- [**AI-Native Design**](./references/ai-native-architecture.md): Systems with integrated reasoning.
- [**Edge Orchestration**](./references/edge-orchestration-patterns.md): Global patterns for 2026.
- [**Agent Experience (AX)**](./references/agent-experience-ax.md): Designing for machine users.

---

*Updated: January 22, 2026 - 19:20*

Overview

This skill is a senior software architect persona that provides actionable blueprints for AI-native systems, modular monoliths, and edge-cloud orchestration tuned for 2026 ecosystems. It focuses on designing reasoning loops, enforcing module boundaries, and optimizing Agent Experience (AX) so systems are maintainable, observable, and agent-friendly.

How this skill works

The skill inspects high-level architecture choices and recommends concrete patterns: interface-first contracts, modular monolith layouts, in-memory event buses, and policy-driven edge placement. It evaluates designs against anti-patterns (premature microservices, spaghetti context, silent failures) and prescribes replacements like strict namespaces, actionable feedback APIs, and reasoning logs. It also prescribes operational controls such as zero-trust boundaries and atomic deployments.

When to use it

  • Designing a new backend where AI agents must interact reliably with system modules.
  • Refactoring a growing microservice sprawl into a modular monolith for faster iteration.
  • Architecting edge-cloud deployments with low-latency routing and policy-driven placement.
  • Implementing observability for AI decisions using reasoning logs and context-rich stores.
  • Defining contracts and validation layers before implementing core business logic.

Best practices

  • Define strict interfaces and validation schemas before implementing logic (contracts over implementation).
  • Start with a modular monolith and extract services only when clear scaling or organizational boundaries demand it.
  • Treat each module as zero-trust: validate inputs, enforce policies, and limit implicit assumptions.
  • Instrument reasoning: capture why decisions were made alongside system state for auditability and agent debugging.
  • Prefer in-memory event buses for intra-process decoupling and use lightweight message layers for cross-node events.

Example use cases

  • Convert a distributed, brittle microservice landscape into a modular monolith to reduce latency and operational overhead.
  • Design an AI orchestration layer that records reasoning logs and provides guardian agents to validate state changes.
  • Build an edge placement policy that routes user requests to the nearest node and syncs ephemeral state lazily.
  • Create contract-first module templates with validation hooks for agent-friendly integration.
  • Implement atomic deployments so module versions remain consistent across releases.

FAQ

When should I extract services from a modular monolith?

Extract only when horizontal scaling, independent release cycles, or team ownership clearly justify the added operational cost.

How do I make modules agent-friendly?

Provide explicit interfaces, rich contextual metadata, actionable feedback APIs, and reasoning logs so agents can understand inputs, outputs, and the rationale behind decisions.