Agentic SaaS B2B: Disciplina de Desarrollo con Claude Code

-- Patrón canónico (survivió 50 sprints de producción)
BEGIN;

SET LOCAL app.current_tenant_id = 'tenant-123';

-- Esta query automáticamente filtrará por tenant_id
SELECT * FROM documents WHERE id = $1;

COMMIT;

docs/
  architecture/
    interfaces.md
templates/
  interfaces-catalog/
    go/
      tenant.go
      document.go
    typescript/
      tenant.ts
      document.ts

❌ ERROR: Anti-type-invention violado

Intentaste definir: `type TenantID string`
Pero ya existe en: `docs/architecture/interfaces.md#L42`
Definición canónica:
  - Go: `type TenantID string` (pkg/domain/tenant/tenant.go:12)
  - TS: `type TenantID = string` (src/types/tenant.ts:8)

Action: Importar y reusar el tipo existente.

// ✅ CORRECTO — Pattern enforced por skill
func (r *DocumentRepository) FindByID(ctx context.Context, id string) (*Document, error) {
    tenantID := tenant.FromContext(ctx)

    var doc Document
    err := r.db.QueryRowContext(ctx, `
        SELECT id, tenant_id, content, created_at
        FROM documents
        WHERE id = $1
    `, id).Scan(&doc.ID, &doc.TenantID, &doc.Content, &doc.CreatedAt)

    return &doc, err
}

// ❌ INCORRECTO — Te bloquea la skill
func (r *DocumentRepository) FindByID(ctx context.Context, id string) (*Document, error) {
    // FALTA: tenant.FromContext(ctx)
    var doc Document
    err := r.db.QueryRowContext(ctx, `
        SELECT id, tenant_id, content, created_at
        FROM documents
        WHERE id = $1
    `, id).Scan(&doc.ID, &doc.TenantID, &doc.Content, &doc.CreatedAt)

    return &doc, err
}

🚨 RLS VIOLATION DETECTADO

File: pkg/db/documents/repository.go:17
Query: SELECT id, tenant_id, content, created_at FROM documents WHERE id = $1

Problema:
  - Falta `tenant.FromContext(ctx)` antes de la query
  - Sin tenant_id en WHERE, esta query podría leak data cross-tenant

Patch sugerido:

```diff
+ tenantID := tenant.FromContext(ctx)

  var doc Document
  err := r.db.QueryRowContext(ctx, `
      SELECT id, tenant_id, content, created_at
      FROM documents
-     WHERE id = $1
+     WHERE id = $1 AND tenant_id = $2
- `, id).Scan(...)
+ `, id, tenantID).Scan(...)

---

## Agents: Architect-Solution Implementado

Actualmente **1 agent implementado**, **12 planeados**. El único disponible es `architect-solution`.

### Cuando usar Architect-Solution

- Nuevos ADRs (Architecture Decision Records)
- Decisiones cross-module que afectan múltiples services
- Enforcing R9 (modularity) y R13 (anti-invention)
- Review de patrones que podrían causar debt técnico

### Prompt de ejemplo

### Output típico

pkg/connectors/drive/
  ├── webhook_handler.go       (max 200 lines)
  ├── ingestion_service.go     (max 250 lines)
  └── storage_adapter.go       (max 150 lines)

<Callout type="tip" title="12 agents planeados">
Backend, DB, Frontend, QA, Security Officer, SRE, Billing, Connector Orchestrator, Migration Owner, API Gateway, Observability, Support Bot. Roadmap: Q3 2026 - Q2 2027.
</Callout>

---

## Lessons Learned: 50 Sprints de Producción

### 1. Reglas no escritas no existen

Teníamos una wiki interna con "Best Practices". Nadie la leía. Escribir 18 reglas en README del repo las hace **disponibles**, pero no **enforceadas**.

La diferencia crítica: **skills que se auto-activan**. `interfaces-extraction` corre antes de que definas un tipo. `multi-tenant-rls` te bloquea si escribes query sin tenant_id. La regla se ejecuta, no se sugiere.

### 2. Anti-type-invention vale más de lo que crees

R13 fue la regla más costosa de aprender. En el sprint 23, inventar `TenantID` cuando ya existía `TenantId` nos costó:
- 2 horas debugging cyclic imports
- 4 horas de refactor que afectó 7 archivos
- 1 hour de code review para reviewers que ya lo habían revisado

Total: 7 horas de billable time + deuda técnica + frustración del equipo.

Hoy `interfaces-extraction` previene esto. La skill escanea antes de escribir. 7 horas ahorradas **por ocurrencia**. Si esto pasa 10 veces en 50 sprints, **70 horas ahorradas**.

### 3. Gotchas como capital organizacional

Después de 50 sprints, `gotchas.md` tiene 45+ gotchas documentadas. Cada gotcha es:
- Una vez que el team perdió time
- Una vez que NO perderá time de nuevo porque está documentado

Esto no es solo documentation. Es **institutional memory** que se transfiere:

- Nuevo dev se une: `gotchas.md` es su primer reading
- Bug que toma 3 horas resolver: se agrega a `gotchas.md`
- Sprint 47 sufre problema X: Sprint 48 no lo repite

Capital acumulado vs repetición de errores.

### 4. Stack-agnostic es key

El plugin funciona con Go, TypeScript y Python. ¿Por qué? Porque las **reglas de negocio** son agnósticas:

- RLS (R1) → Postgres pattern, no importa el lenguaje
- Anti-type-invention (R13) → AST extraction, syntax-agnostic
- TDD (R18) → Test framework convention, no se cierra a pytest/gotest/jest

Si hubiéramos creado este plugin solo para Go, en el sprint 32 cuando adoptamos TypeScript para connectors, habríamos tenido que duplicar disciplina. Stack-agnostic = disciplina portable.

### 5. Claude Code como substrate, no como silver bullet

Este plugin **no hace que el equipo sea disciplinado**. El plugin **asiste al equipo disciplinado**.

Diferencia clave:
- ❌ Equipo indisciplinado + plugin = plugin bloquea, team lo desactiva
- ✅ Equipo disciplinado + plugin = plugin previene errores humanos

El plugin es un guardrail. Guardrails no te hacen mejor conductor, te evitan salirte de la carretera cuando te descuidas.

---

## Cómo Usarlo

### Instalación

```bash
/plugin marketplace add kr0nicas/agentic-saas-b2b-itproject
/plugin install agentic-saas-b2b-itproject

# Inicializar interfaces.md (si no existe)
touch docs/architecture/interfaces.md

# Inicializar gotchas.md (si no existe)
touch .claude/gotchas.md

# Configurar tenant context (ejemplo en Go)
# pkg/tenant/context.go
package tenant

type contextKey string

const TenantKey contextKey = "tenant"

func FromContext(ctx context.Context) string {
    if tenantID, ok := ctx.Value(TenantKey).(string); ok {
        return tenantID
    }
    return "" // O panic si strict
}