architecture-fitness-functions

Converte uma regra de arquitetura documentada em prosa (arquivo raiz do agente, ADR, code review recorrente) num teste automatizado e determinístico — uma fitness function. Stack-agnóstico: exemplos p

SKILL.md

GitHub

Skill — Architecture Fitness Functions

Uma fitness function (Ford/Parsons/Kua, Building Evolutionary Architectures) é um teste automatizado que verifica uma propriedade arquitetural — não comportamento de negócio. É o sensor computacional que substitui "confiar que o agente/dev leu a regra e lembrou dela".

Quando promover uma regra para fitness function

Use o sinal do dev-harness-architect: se uma regra documentada em prosa (arquivo raiz do agente) é violada duas vezes por revisão manual ou review de agente, ela deveria ter virado teste desde a primeira vez. Regra prática: se a violação pode ser detectada por um grep, um parse de AST, ou uma checagem de grafo de dependências — é candidata imediata, não espere a segunda violação.

As 5 famílias de regras mais comuns

  1. Direção de dependência entre camadas — ex. "domínio não importa camada de apresentação". Detector: parse de imports/imports do arquivo, comparar contra uma lista de camadas proibidas.
  2. Gateway único para uma operação perigosa — ex. "toda escrita em disco passa por um módulo único", "toda chamada de rede passa por um client único". Detector: grep pela API nativa (open(...), FileManager, URLSession, File(...)) fora do módulo permitido.
  3. Padrão proibido — ex. "sem print() fora da camada de CLI", "sem try!/força-desembrulho fora de testes", "sem captura ampla de exceção". Detector: grep/regex linha a linha, com allowlist de diretórios.
  4. Sem segredo literal — ex. token = "...". Detector: regex sobre atribuições que parecem credencial.
  5. Contrato de saída obrigatório — ex. "todo agente novo tem um teste de schema". Detector: verificar que para cada arquivo novo em agents/ existe um arquivo correspondente em tests/ que importa o schema.

Estrutura comum (independente de stack)

Toda fitness function segue a mesma forma:

Regra → Detector (varre arquivos, coleta violações) → Assert (lista vazia) → Mensagem (arquivo:linha + trecho)

A mensagem de falha deve apontar exatamente onde e sugerir a correção — o agente que vai ler essa falha não tem contexto da conversa que gerou a regra.

Exemplo — Python / pytest (ast + regex)

"""Architecture fitness sensors — enforce root-guide rules at test time."""
import ast
import re
from pathlib import Path

SRC = Path(__file__).parent.parent.parent / "src" / "mypkg"
OUTER_LAYERS = {"cli", "api"}


def _imports(filepath: Path) -> list[str]:
    tree = ast.parse(filepath.read_text(encoding="utf-8"))
    names: list[str] = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            names.extend(a.name for a in node.names)
        elif isinstance(node, ast.ImportFrom) and node.module:
            names.append(node.module)
    return names


def test_domain_does_not_import_outer_layers() -> None:
    violations = []
    for py_file in (SRC / "domain").rglob("*.py"):
        for imp in _imports(py_file):
            if any(f"mypkg.{layer}" in imp for layer in OUTER_LAYERS):
                violations.append(f"{py_file}: imports {imp}")
    assert not violations, "domain/ must not depend on outer layers:\n" + "\n".join(violations)


_SECRET = re.compile(r'(api_key|token|password|secret)\s*=\s*"[^"]{6,}"', re.IGNORECASE)


def test_no_hardcoded_secrets() -> None:
    violations = []
    for py_file in SRC.parent.parent.rglob("*.py"):
        if ".venv" in py_file.parts:
            continue
        for i, line in enumerate(py_file.read_text(encoding="utf-8").splitlines(), 1):
            if _SECRET.search(line):
                violations.append(f"{py_file}:{i}: [REDACTED]")
    assert not violations, "Hardcoded secrets detected:\n" + "\n".join(violations)

Rode em CI como um tier próprio (pytest tests/structural/ -x -q), separado dos testes de comportamento — falha rápida e não depende de fixtures pesadas.

Exemplo — Swift/iOS (regra de gateway único, sem dependências)

Swift não tem um ast acessível em stdlib de forma trivial para scripts soltos; a abordagem mais barata é regex linha a linha, rodando como um script Python (independente do projeto ser Swift — o script só lê arquivos .swift) ou como custom rule do SwiftLint.

Opção A — script Python que varre .swift (funciona sem SwiftLint):

import re
import sys
from pathlib import Path

SRC = Path("Sources")
FORBIDDEN = re.compile(r"\bURLSession\.shared\b")
ALLOWLIST_DIR = "Networking"

violations = []
for swift_file in SRC.rglob("*.swift"):
    if ALLOWLIST_DIR in swift_file.parts:
        continue
    for i, line in enumerate(swift_file.read_text(encoding="utf-8").splitlines(), 1):
        if FORBIDDEN.search(line):
            violations.append(f"{swift_file}:{i}: {line.strip()[:80]}")

if violations:
    print("URLSession.shared usado fora de Networking/:")
    print("\n".join(violations))
    sys.exit(1)

Opção B — SwiftLint custom rule (.swiftlint.yml), se o projeto já usa SwiftLint:

custom_rules:
  no_direct_urlsession:
    included: ".*\\.swift"
    excluded: ".*/Networking/.*"
    regex: "URLSession\\.shared"
    message: "Use o client de rede único em Networking/, não URLSession.shared direto."
    severity: error

Para regra de direção de dependência (ex. "Domain não importa UIKit/SwiftUI"), o mesmo script Python funciona: procure import UIKit/import SwiftUI dentro de Sources/Domain/.

Exemplo — Kotlin/Android (Konsist)

Konsist é uma lib de teste de arquitetura nativa em Kotlin, roda junto do JUnit:

class ArchitectureTest {
    @Test
    fun `domain does not depend on outer layers`() {
        Konsist.scopeFromProject()
            .packages("..domain..")
            .assertFalse {
                it.imports.any { imp ->
                    imp.name.contains("..ui..") || imp.name.contains("..data..")
                }
            }
    }

    @Test
    fun `no direct File access outside storage package`() {
        Konsist.scopeFromProject()
            .files
            .filterNot { it.packagee?.name?.contains("..storage..") == true }
            .assertFalse { file -> file.text.contains("java.io.File(") }
    }
}

Sem Konsist, a mesma ideia funciona com uma regra custom do Detekt (arquivo detekt-rules/ + config em detekt.yml), mais verboso mas sem dependência extra de teste.

Exemplo — Node/TypeScript (dependency-cruiser)

Para direção de dependência entre camadas, dependency-cruiser já resolve sem escrever regex:

{
  "forbidden": [
    {
      "name": "domain-no-outer-layers",
      "severity": "error",
      "from": { "path": "^src/domain" },
      "to": { "path": "^src/(cli|api)" }
    }
  ]
}
npx depcruise src --config .dependency-cruiser.json

Para padrões proibidos (sem console.log fora de cli/, sem segredo literal), eslint com uma regra custom ou um script de regex — mesma forma dos exemplos acima.

Checklist ao escrever uma fitness function nova

  • A regra já existe em prosa no arquivo raiz do agente? Se não, adicione lá também — o teste sozinho não ensina o agente a evitar a violação antes de tentar; ele só pega depois.
  • O detector tem um teste negativo (fixture que viola a regra de propósito) para provar que o sensor de fato dispara?
  • A mensagem de falha diz o arquivo, a linha e a correção esperada?
  • O teste roda em segundos, não minutos — senão vai para o tier de CI certo (não pre-commit) em vez de ficar esquecido/desabilitado.
  • Existe um allowlist explícito de exceções (diretório onde a regra não se aplica), em vez de exceções implícitas via # noqa/// nolint espalhadas pelo código?