convez.ai
AgenteAutomaçãoIntermediário
m9751

Agent Operating Framework

m9751/agent-operating-framework

Sistema operacional comportamental para agentes Claude com enforcement de regras e circuit breakers

Ver no GitHub
BomPluginScore · de 0 a 100

Framework operacional para agentes de IA (Claude Code) que implementa governança comportamental através de regras, circuit breakers e hooks. Refinado em 12 meses de workflows empresariais, resolve inconsistências de output e garante cumprimento de constraints mesmo sob pressão.

Instalação

$npx convez-ai m9751/agent-operating-framework

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
2
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 4 meses
Versão
v1.8
Issues abertas
0
Contribuidores
1

Casos de uso

  • Garantir consistência de outputs em agentes de código de longa duração
  • Implementar governance e circuit breakers para evitar falhas em cascata
  • Estabelecer protocolo de entrega e verificação para qualidade de artefatos
  • Estruturar project memory e rules com enforcement arquitetônico (memory → rules → hooks)

Veredito

Framework maduro e bem documentado para quem já trabalha com Claude Code e hit o teto de CLAUDE.md simples. Excelente captura de lições operacionais (INCIDENTS.md), com enforcement arquitetônico concreto via hooks. Requer compreensão de ciclo de vida do agente para máximo valor.

README

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

Agent Operating Framework

License: MIT

An operating framework for AI coding agents, refined through ~12 months of private enterprise-sales workflow and ~6 weeks of public iteration.

Quick Start

Copy AGENT_FRAMEWORK.md to your project root as CLAUDE.md. Fill in Section 0 with your project specifics. Start a session.

cp AGENT_FRAMEWORK.md /path/to/your/project/CLAUDE.md

See guides/getting-started.md for the full adoption path.

Who This Is For

You've set up CLAUDE.md. You've built a few skills. You're using Projects Memory. But outputs are still inconsistent, the agent ignores rules under pressure, and you're manually reviewing everything.

This framework is the next step. It adds rules with documented enforcement contracts (some advisory by design), circuit breakers (stop after 3 failures), and an escalation model (advice → law → barriers) that makes your CLAUDE.md actually stick. See the rule-to-hook coverage matrix for what is system-enforced versus advisory in v1.7 — five of six rules ship with hooks; one (no-local-infrastructure) is a decision framework that is advisory by design.

If you're just getting started with Claude Code, read the beginner guides first. If you've hit the wall where your CLAUDE.md "stops working," start here.

I am…Start here
New to Claude Codeguides/getting-started.md
CLAUDE.md "stopped working"guides/from-beginner-to-framework.md
Want copy-paste rulesexamples/claude-code-rules/
Want hooksexamples/hooks/
Want the full framework fileAGENT_FRAMEWORK.md
Curious what failures produced thisINCIDENTS.md

What This Is

A behavioral operating system for Claude Code that combines:

  • Project identity — role, output contracts, quality criteria, session lifecycle
  • Evidence-first culture — four gates: read before touching, first-time check, evidence card, no guessing
  • Circuit breakers — three-failure stop, scope discipline, delivery protocol
  • Quality gates — verification before done, post-delivery checklist, HTML token hygiene
  • Enforcement architecture — memory (advice) → rules (law) → hooks (barriers)
  • Self-improvement — capture lessons, escalate failures, consolidate when rules accumulate

Claude Code note: The hook implementations in examples/hooks/ use Claude Code's PreToolUse/PostToolUse lifecycle. Rule prose is portable to any agent platform.

Every rule exists because its absence caused a specific, documented failure. See INCIDENTS.md for the log.

Library Contents

The Framework

Guides

  • From Beginner to Framework — You've built CLAUDE.md and skills but outputs are inconsistent. Here's why and what to do next.
  • Getting Started — How to adopt the framework, where files go, recommended path
  • Enforcement Architecture — Memory → Rules → Hooks escalation model with examples
  • Rule Consolidation — When rules accumulate past ~20, how to cluster by root cause and compress without losing lessons
  • Why Post-Failure Frameworks Win — Why rules born from incidents beat rules born from best-practice lists
  • Auto-Optimizing Skills — Eval-driven skill improvement: triage, iteration loop, 7 guardrails, data model
  • Hook Operations — The three operational questions: what happens when a hook fails, how to tell if hooks are working, and how to escape when one goes rogue
  • Hook Audit Methodology — 4-track audit pattern (registration, annotations, live fire, telemetry) with triage table and Codex batch audit pattern
  • Silent Failure Discipline — Every fail-open hook path must write to the errors log. Pattern, self-test, and the watchdog that reads it.
  • AGENTS.md Standard — Three-level repo governance contract (identity → routing → procedures + ADR register)

Copy-Paste Rules

Individual rule files for ~/.claude/rules/ or .claude/rules/. Each absorbs multiple earlier rules into a single file with sub-gates:

RuleWhat It Prevents
read-before-acting.mdGuessing instead of reading — 5 gates + three-failure stop
scope-discipline.mdOver-engineering, unapproved dependencies, building what already exists, remediating dormant code
session-lifecycle.mdCold starts, plan-mode violations, sessions that end without auditing delivery
delivery-protocol.mdScattered deliverables, skipped checklists, token-wasteful HTML iterations
no-local-infrastructure.mdPersistent agents on the user's laptop instead of cloud-hosted solutions
secure-configuration.mdConfig file overwrites, secrets in chat, wrong credentials on wrong system

Hook Examples

Shell scripts that enforce rules at the tool-call level — the third tier of the enforcement ladder. Copy to your hooks directory and configure in settings.json:

HookTypeWhat It Enforces
read-gate.shPreToolUse hard blockBlocks writes unless the target resource was read first
search-gate.shPreToolUse hard blockBlocks code creation unless a search was done first
secure-config-gate.shPreToolUse hard blockBlocks secret patterns in any tool call + Write to protected config paths
dormant-code-gate.shCI lint hard blockRejects PRs that modify files whose every extracted symbol has zero callers elsewhere (scope-discipline Gate 5)
delivery-gate.shPreToolUse advisoryReminds agent to log deliverables (fail-open)
focus-breadcrumb.shUserPromptSubmitWrites a session breadcrumb when an explicit task is detected (companion to focus-confirmation-gate)
focus-confirmation-gate.shPreToolUse advisoryWarns when first Edit/Write/Bash fires with no focus breadcrumb (session-lifecycle Phase 1)
deprecated-field-gate.shPreToolUse hard blockTemplate for blocking writes that reference deprecated DB columns or API fields
empty-rule-body-gate.shCI meta-hook hard blockPre-merge gate rejecting rule files < 200 bytes or missing ## Why (closes the empty-stub loophole)
breadcrumb-lib.shLibrary (source only)Shared session-scoped breadcrumb API — source into any hook that needs to log or check session state
startup-gate.shSessionStart advisoryChecks repo, AGENTS.md, active plan, and hook registration gap at session start; writes drift report
hook-telemetry-stop.shStop advisoryReads fire/block breadcrumbs at session end; bulk-INSERTs telemetry rows
lib/normalize-hook-input.shLibrary (source only)Normalizes hook payload field names and tool-name literals across Claude Code and Grok runtimes

See §5.3 Rule-to-Hook Coverage for which rule each hook backs and the full enforced-vs-advisory accounting.

See examples/hooks/README.md for setup instructions and the breadcrumb pattern.

Incident Log

  • INCIDENTS.md — 38 sanitized incidents linking real failures to the rules they produced. Month-precision dates.

The Key Insight

Most agent failures come from the same root cause: acting without reading. The agent guesses a column name instead of checking the schema. It deploys with assumed config instead of reading the setup guide. It tries a fourth variation of a broken approach instead of stopping to research.

Prompt instructions are not enforcement. They are guidance. The only durable approach is an escalation ladder:

Memory (advice) → Rules (law) → Hooks (barriers)

Prose tells the model what it should do. Gates determine what it is allowed to do.

This framework's core principle: one read is worth ten guesses.

Self-Applied Measurement

This framework grades itself. An eval harness in examples/evals/ walks session handoffs from the author's own workflow and scores each one on four deterministic metrics — rule adherence, plan-delivery gap, cost, and dispatch quality — then publishes the trend to a live dashboard:

Dashboard: aof-eval.vercel.app

The harness is the framework's own credibility test: if the rules work, the scores hold. If a regression slips into v1.6, the trend line moves before anyone writes a postmortem. Numbers come from 47 real sessions backfilled at v1.5 ship (mean composite 9.20/10). Re-run manually with python -m examples.evals.run_harness whenever a new batch of sessions lands.

Author

Built and maintained by Michael Busacca — 13+ years enterprise SaaS, running AI-assisted workflows in a high-volume sales context.

Changes

See CHANGELOG.md for version history.

Ver o original no GitHub

Bom para

Relacionados