DEV Community: Sergio Guadarrama

De Scripts CLI a un Orquestador "Agentic": Construyendo un Sistema Inmunológico para nuestro Codebase 🤖🛡️

Sergio Guadarrama — Mon, 06 Apr 2026 16:17:38 +0000

Todos amamos nuestro IDE vitaminado con IA (hola, Cursor / Copilot). Son asistentes geniales cuando estamos haciendo pair-programming, pero son reactivos. Cuando cerramos la laptop, desaparecen. Y es justo ahí cuando la deuda técnica, el código espagueti y los imports huérfanos hacen fiesta.

Hoy quiero compartirles un experimento arquitectónico en el que hemos estado trabajando. Lo que empezó como un montón de herramientas CLI aisladas para mi uso personal, evolucionó a un Orquestador de Agentes Autónomos que llamamos SKRYMIR.

🔥 El problema de la IA Reactiva vs Proactiva Las IAs tradicionales te ayudan a escribir nuevo código. Cerebro está diseñado como un SRE de código puro: monitorea la salud del repositorio, detecta degradación en la complejidad ciclomática, e inyecta curas preventivas en la madrugada (lo que llamamos "Modo Nocturno").

🛠️ La Anatomía de nuestro Pipeline: El "Tribunal Multi-Agente" Actualmente nos encontramos realizando pruebas pesadas, afinando el flujo asíncrono y recolectando aprendizajes sobre cuánto nivel de autonomía puede manejar el sistema.

El flujo que terminamos validando es un ciclo cerrado de CI/CD impulsado por agentes puros. Desde nuestro panel de control dicto un prompt general: "Integra la validación por horarios".

Aquí va nuestro pipeline interno paso a paso:

La Codificación: Se dispara Aider en una rama asolada (git checkout -b skrymir-feature/). Analiza el repo y programa el requerimiento.
**El Validation Gate: El Executor toma el relevo. Antes de cualquier cosa, hace validaciones locales crudas (como npm run build o correr compiladores de Cargo si es Rust). Si la IA rompió la compilación, se rechaza la rama de inmediato.
Smart Merge: Si todo es verde (Exit Code 0), Cerebro toma control, vuelve a main y realiza el auto-merge de la nueva feature de manera procedimental.
**El Tribunal *(Aquí está la magia): Inmediatamente después del merge, se gatilla una validación en cadena donde 3 Agentes auditan exclusivamente el archivo editado:
Sentinel: Escanea código muerto e imports huérfanos estáticamente (vía su Core en Rust).
Architect: Evalúa que no se hayan violado contratos ni patrones de diseño globales.
Warden: Realiza pasadas preventivas de inyección y vulnerabilidades.
💡 Siguientes Pasos y Aprendizajes Nuestras validaciones de los últimos días nos enseñaron algo vital: la seguridad inicial. Para escalar esto y ganar la confianza de un equipo completo, estamos puliendo el "Modo Aprendiz", donde Cerebro simplemente emite Pull Requests con sugerencias de fixes en lugar de empujarlos en crudo a main, ganando la confianza del desarrollador gradualmente.

Construir herramientas para construir herramientas es otro nivel de diversión. ¿Alguno de ustedes ha experimentado anidando flujos entre distintos agentes de IA locales? ¡Dejen sus aportes en los comentarios!

From 80% False Positives to 95% Accurate: How We Fixed Architecture Linting

Sergio Guadarrama — Wed, 04 Mar 2026 15:39:28 +0000

The Starting Point

Two months ago, we built Architect Linter to solve a real problem: teams'
codebases fall apart as they grow.

v5 used simple pattern matching for security analysis:

Any function with "execute" in name → sink
All parameters → potential sources
Result: False positives everywhere

// Real code from a production NestJS app
// v5 would flag as CRITICAL VULNERABILITY

const executeWithErrorHandling = async (callback) => {
  try {
    return await callback();
  } catch (e) {
    logger.error(e);
    return null;
  }
};

const userInput = req.query.name;
const result = executeWithErrorHandling(async () => {
  // Do something safe with userInput
  return db.prepare("SELECT * FROM users WHERE name = ?").run(userInput);
});

// v5: 🚨 CRITICAL: "executeWithErrorHandling is a sink"
//     🚨 CRITICAL: "executeWithErrorHandling receives user input"
// Reality: ✅ Code is 100% safe (parameterized query)

Developers ignored all findings. Security analysis became useless.

The Rewrite: CFG-Based Analysis

For v6, we completely rewrote the security engine using Control Flow Graphs:

Step 1: Parse code into a CFG

req.query.id (SOURCE)
    ↓
const id = ...
    ↓
escape(id)  (SANITIZER)
    ↓
db.query(id)  (SINK)
    ↓
Result: ✅ SAFE (data was sanitized)

Step 2: Track actual data flow

Which variables receive untrusted data?
Where does that data go?
Is it sanitized before reaching a sink?

Step 3: Only report real issues

// ✅ Safe: Data is parameterized
db.execute("SELECT * FROM users WHERE id = ?", [userId]);

// ⚠️ Unsafe: Direct interpolation
db.execute(`SELECT * FROM users WHERE id = ${userId}`);

// ✅ Safe: Data is escaped
db.execute(`SELECT * FROM users WHERE name = '${escape(userName)}'`);

Result: 95%+ Accuracy

Metric	v5.0	v6.0
True Positives	20%	95%
False Positives	80%+	<5%
Developer Trust	❌ None	✅ High
Enterprise Ready	❌ No	✅ Yes

Bonus: Zero-Config Setup

While we were at it, we also fixed the friction of "I have to configure
this for 30 minutes before I can use it":

$ architect init
🔍 Detecting frameworks...
   ✓ NextJS (from package.json)
   ✓ Django (from requirements.txt)

✨ Generating config...
   Created: architect.json (90% auto-complete)

Ready to lint! Run: architect lint .

Now supports many modern frameworks (TypeScript, Python, PHP).

What This Teaches Us

Simple heuristics don't work for security
- "Contains 'execute'" is a bad signal
- Need to understand actual control flow
Zero-config adoption beats "perfect but complex"
- 30-minute setup → Users abandon
- 5-minute setup → Real usage
Focus beats breadth
- Supporting 11 languages poorly > supporting 3 languages well
- Dropped Go/Java, added Vue/Svelte (web-focused)
Tests catch everything
- We rewrote the core logic (risky!)
- 432+ tests meant we could refactor confidently
- Only broke 0 public APIs

Getting Started

cargo install architect-linter-pro
cd your-project
architect init
architect lint .

GitHub: https://github.com/sergiogswv/architect-linter-pro
Crates.io: https://crates.io/crates/architect-linter-pro
Docs: https://github.com/.../docs/MIGRATION_v6.md

What's Next

v6.1: Variable tracking (catches injection in loops)
v7: Pre-commit hooks + CI/CD templates
v8: VS Code extension (if there's interest)

Questions? Hit me in the comments.

The Missing Piece Between SonarQube and Code Review

Sergio Guadarrama — Thu, 26 Feb 2026 00:55:16 +0000

Or: How we prevented architectural debt before it even happened

SonarQube catches bugs & code smells
Code review catches design decisions
Nothing catches architectural violations ← this gap exists
architect-linter fills this gap
Free, open source, multi-language

The Problem: The Architecture Gap

Let me paint a picture you might recognize.

You have a team of developers. Maybe 10, maybe 100. You've planned a beautiful architecture:

┌─────────────────────────────────────┐
│         Presentation Layer          │
│  (Components, Controllers, Pages)   │
└──────────────────┬──────────────────┘
                   │ (through services)
┌──────────────────▼──────────────────┐
│         Service Layer               │
│  (Business Logic, Domain Logic)     │
└──────────────────┬──────────────────┘
                   │ (through repositories)
┌──────────────────▼──────────────────┐
│         Data Access Layer           │
│  (Repositories, Queries, DB)        │
└─────────────────────────────────────┘

Beautiful. Clean. Maintainable.

Then month 2 happens.

A component directly imports from the database layer "just this once."
A service calls another service that hasn't been created yet.
A utility function imports from the presentation layer.

Month 3? You don't have an architecture anymore. You have... spaghetti.

Why This Happens

SonarQube catches:

✅ Code smells (naming, complexity, duplicates)
✅ Bugs (null references, logic errors)
✅ Security issues (SQL injection, XSS)
❌ Architectural violations (layers crossed, bad imports)

Code Review catches:

✅ Design decisions
✅ Algorithm choice
✅ Function complexity
❌ Systematic architectural patterns (too slow to enforce manually)

The Gap:

100 imports per PR
You check... maybe 5?
95 could violate architecture
Human reviewer can't check them all

The Solution: architect-linter

Enter architect-linter. A linter specifically for architecture.

Think ESLint (which catches code style), but for your system design.

$ architect-linter-pro --check

❌ src/components/Button.tsx imports from src/api/user.ts
   Rule violation: Presentation layer cannot import from API layer
   Suggestion: Use src/services/UserService instead

❌ src/services/Auth.ts imports from src/components/LoginForm.tsx
   Rule violation: Service layer cannot import from Presentation layer

✅ Rest of architecture is clean

How It Works

Define rules in architect.json:

{
  "architecture_pattern": "Hexagonal",
  "forbidden_imports": [
    {
      "from": "src/presentation/**",
      "to": "src/infrastructure/**",
      "reason": "Presentation shouldn't depend on infrastructure details"
    },
    {
      "from": "src/application/**",
      "to": "src/infrastructure/**",
      "reason": "Application layer is infrastructure-agnostic"
    }
  ]
}

Run in CI/CD:

# .github/workflows/architecture.yml
- name: Check Architecture
  run: architect --check

Get violations before merge:

❌ PR blocked: Architecture violations detected
   - 2 violations found
   - Fix before merging

Multi-Language Magic

Unlike ESLint (JS only) or Pylint (Python only), architect-linter works across 4 languages:

TypeScript/JavaScript (ES6 imports)
Python (import/from syntax)
PHP (use statements)
All in the same codebase

Perfect for monorepos with mixed stacks:

frontend/          (TypeScript + React)
backend/           (Python + FastAPI)
services/          (PHP + Laravel)
                   ↓
architect-linter enforces SAME rules across all 3

Real Results

Before architect-linter:

⚠️ 40% of PRs rejected for architecture
⚠️ Code review took 30 minutes per PR
⚠️ Junior devs didn't understand implicit rules
⚠️ Architecture debt accumulated slowly

After architect-linter (2 months):

✅ 5% of PRs rejected (mostly legitimate design changes)
✅ Code review takes 5 minutes (humans focus on logic)
✅ New devs self-correct with CI feedback
✅ Zero new architectural violations

When to Use Each Tool

Need	Tool	Why
Catch bugs	SonarQube	Finds logic errors, security issues
Review logic	Code Review	Humans are best here
Enforce architecture	architect-linter	Automatic, systematic, consistent
All together	All 3	SonarQube + architect-linter in CI, code review for design

Getting Started

Install

cargo install architect-linter-pro

Initialize

architect-linter-pro --init
# Interactive wizard creates architect.json

Run

architect-linter-pro --check

CI/CD Integration

# GitHub Actions
- run: architect-linter-pro --check

# GitLab CI
script:
  - architect-linter-pro --check

# Pre-commit hook
# .pre-commit-config.yaml
- repo: https://github.com/sergiogswv/architect-linter-pro
  rev: v5.0.0
  hooks:
    - id: architect-linter-pro

Comparison: architect-linter vs Alternatives

Feature	architect-linter	ESLint	SonarQube	Manual Review
Multi-language	✅ Yes	❌ JS only	✅ Yes	✅ Yes
Architecture rules	✅ Yes	❌ No	⚠️ Limited	✅ Yes
Fast	✅ Rust, parallel	✅ JS	❌ Slow	❌ Very slow
Free	✅ Open source	✅ Open source	❌ $10k+/year	✅ Yes
Easy setup	✅ 5 min	✅ 5 min	❌ 2 hours	N/A
Automation level	✅ 100%	✅ 100%	✅ 90%	❌ 0%

Try It Now

cargo install architect-linter-pro
architect-linter-pro --init
architect-linter-pro --check

Takes 5 minutes. Your architecture will thank you.

Questions?

🐙 GitHub: https://github.com/sergiogswv/architect-linter-pro
📖 Docs: https://architect-linter-pro.dev
🎯 Crates.io: https://crates.io/crates/architect-linter-pro

Let me know what you think!