convez.ai
MCP ServerDevOps & InfraestruturaAvançado
verlyn13

Agentic Architecture Audit

verlyn13/agentic-architecture-audit

Auditoria arquitetural baseada em evidências com citações rastreáveis

Ver no GitHub
BomPluginScore · de 0 a 100

Um MCP server que executa auditoria arquitetural em duas fases para codebases assistidas por IA. A primeira fase (profile-directive) captura o que o repositório *afirma ser*, e a segunda fase (audit-spec) testa essas afirmações em onze etapas, com citações exatas de arquivos e linhas. Todas as descobertas são classificadas por severidade, confiança e reversibilidade.

Instalação

$npx convez-ai verlyn13/agentic-architecture-audit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Validar que a arquitetura de um projeto corresponde à documentação declarada
  • Detectar desvios entre intenção e implementação em codebases complexas
  • Gerar regras de fitness automatizadas para CI/CD a partir de descobertas
  • Auditar contextos limitados, contratos, autoridade e observabilidade

Veredito

Ferramenta sofisticada para times que precisam validar integridade arquitetural com rigor e rastreabilidade. A separação entre discovery e julgamento evita confirmação de viés, e o output estruturado com citações é excelente para auditoria formal e CI/CD. Requer disciplina na documentação inicial (profile-directive) para ser efetiva.

README

A tradução para o português deste README ainda está na fila.

Agentic Architecture Audit

A two-stage, evidence-first audit for AI-assisted codebases. You hand it to a coding agent. It reads your project carefully and reports what is actually there, with file paths and line numbers, versus what you think is there. It changes nothing.

There are two authority texts.

  1. profile-directive.md runs first. It produces a dated snapshot of what the repo claims to be. Stack, bounded contexts, conventions, agent surfaces, authority baselines.
  2. audit-spec.md runs second. It tests those claims in eleven phases, from domain vocabulary and bounded contexts through contracts, state and memory, authority boundaries, observability, prompts, and evals.

The split is deliberate. An agent asked to discover and judge at once will confirm its own expectations. So one pass states the claims and a separate pass tests them.

Every finding must cite a file, a line range, an excerpt, and the command that produced it. Findings are ranked by severity, confidence, strategic weight, and reversibility. The output includes fitness functions: automated rules for CI so the same problem can't come back.

Run order

  1. Copy this package into or near the target project.
  2. Run profile-directive.md against the project. Review the snapshot it produces.
  3. Start the audit agent with companions/kickoff-prompt.md.
  4. Read audit/<date>/SUMMARY.md first. The detail is there when you want it.

New to this? Start with companions/explainer.md. It's the plain-language version.

Repository layout

FileRole
profile-directive.mdAuthority — Project Profile Discovery Directive v1.6. Run first.
audit-spec.mdAuthority — Agentic Architecture Audit Specification v3.5. Run second.
AGENTS.mdCanonical, cross-agent instructions for working in this repo (CLAUDE.md imports it).
CONTRIBUTING.mdHow to contribute: the quality gate, change workflow, and release/provenance discipline.
SECURITY.mdSecurity scope and private vulnerability reporting.
companions/explainer.mdPlain-language explanation of what the audit does.
companions/kickoff-prompt.mdCopy/paste prompt for the audit agent.
MANIFEST.mdDrift control: authority versions and companion targets.
CHANGELOG.mdPackage history and authority-text lineage.
DECISIONS.mdStanding decision ledger (durable D-NNN ids): queued proposals, rejections, open questions. ADRs in adr/ carry the full rationale.
CITATION.cffHow to cite this methodology.
LICENSEApache-2.0.
examples/A real, public run of this audit.
scripts/check_drift.pyDrift linter (self-audit 2026-06-07/FF-004; self-test 2026-06-08/FF-001): companion/version consistency + link resolution, enforced in CI.
.agents/skills/Portable cross-agent skill: run the audit (a thin wrapper that defers to the kickoff prompt).

The root holds exactly what has authority. companions/ makes the authority/derived distinction physical — a core idea of the package itself.

Versions

Authority versions are declared inside each text and tracked in MANIFEST.md. Releases are tagged. If a companion document conflicts with an authority text, the authority text wins.

I developed this by auditing my own agent-built projects. It gets revised when a real run exposes a weakness. The changelog records those lessons.

Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados