Esta parte nao vende AIOX. Examinamos a hipotese do usuario sobre skill vs command contra evidencia empirica do repositorio, mapeamos os gaps do harness cru que AIOX fecha com guardrails computacionais, e apontamos os lugares onde AIOX tropeca -- incidents reais, overhead injustificado, duplicacao semantica entre camadas.
Contagens reais extraidas do worktree em 2026-04-16, nao estimativas.
Comandos: find .claude/commands -name "*.md" = 75. Skills projeto: ls .claude/skills/ = 6 + 1 symlink mega-brain. Skills globais: ls ~/.claude/skills/ = 3 + 9 symlinks. Hooks: .claude/hooks/*.cjs = 24 arquivos .cjs (totalizando 4995 LOC). Squads: 19 diretorios em squads/*. Amendments: 13 arquivos em .aiox/amendments/. Agentes framework: 13 em .aiox-core/development/agents/.
Nota de metodo: o numero real de skills disponiveis ao modelo e muito maior (200+, contando skills namespaced via plugins como MegaBrain:*, AIOX:agents:*, AIOX:workflows:*, Support:agents:*, etc.). O numero 6+3 reflete apenas skills locais nao-namespaced. A realidade concreta: EMPIRICO o espaco de skills explodiu -- ver system-reminder dos available skills no prompt desta conversa.
O usuario afirmou que skill e melhor que command. Nao e universalmente correto. A resposta real e contextual.
"skill e melhor que commands, e quero entender o porque disso tambem, entenda que eu nao estou certo nas minhas inferencias"
Vamos examinar com honestidade. A hipotese esta parcialmente correta. Skills vencem em discovery, empacotamento e autonomia do modelo. Commands vencem em clareza administrativa, invocacao deterministica e simplicidade para workflows dirigidos por operador. Quem vence depende do contexto.
| Dimensao | Command | Skill |
|---|---|---|
| Estrutura fisica | Arquivo MD unico em .claude/commands/<Dominio>/<nome>.md |
Pasta em .claude/skills/<nome>/ com SKILL.md + recursos opcionais (scripts, templates, prompts/, config.yaml) |
| Invocacao | Explicita pelo usuario: /Dominio:nome |
Duas vias: explicita (/nome) ou auto-sugerida pelo modelo via descricao frontmatter |
| Auto-discovery | Nao. Sem descoberta pelo modelo. Operador precisa saber que existe. | Sim. Lista de skills injetada no prompt via system-reminder. Modelo pode sugerir ativar quando relevante. |
| Empacotamento de recursos | Nenhum -- so o MD. Scripts/templates ficam de fora. | Nativo. Ex: tech-research/prompts/, tech-research/templates/, gowa/SKILL.md + config interno. |
| Lazy-load de conteudo | Carrega quando invocado. | Sim. Descricao curta no prompt; corpo completo so carrega quando ativa. |
| Peso contextual no prompt | Zero ate invocar. | Descricao curta permanente no prompt + nome na lista. Inflaciona o prompt mas permite sugestao. |
| Plugabilidade / namespaces | Organizacao por diretorio de dominio (AIOX/, SquadCreator/, MegaBrain/). |
Namespaces por plugin, ex: AIOX:agents:dev, MegaBrain:gsd:plan-phase. |
| Clareza para operador | /AIOX:init nomeia exatamente o que executa. Sem ambiguidade. |
Skills podem sobrepor -- modelo pode escolher errada. |
Commands: find /Users/italo/italo_gustavo/.claude/commands -name "*.md" | wc -l = 75. Estrutura: 12 dominios (AIOX/, SquadCreator/, MegaBrain/, Support/, Kb/, Sop/, etc.). Skills projeto: .claude/skills/ = 6 locais + 1 symlink. Skills globais: ~/.claude/skills/ = 3 locais + 9 symlinks (apontam para ~/.agents/skills/).
Skills de referencia bem desenhadas:
~/.claude/skills/graphify/SKILL.md -- 55.6K, arquivo unico substancial/Users/italo/italo_gustavo/.claude/skills/tech-research/ -- SKILL.md 57.3K + README.md + prompts/ + templates/ + config.yaml (exemplo de empacotamento completo)~/.claude/skills/elx-audit/SKILL.md -- 11K, skill complexa com pipeline wave-based~/.claude/skills/frontend-design/ (via symlink ~/.agents/skills/frontend-design) -- skill usada internamente pela Anthropic no harness de construcao de apps (ref raw-anthropic-harness-design.md:100)A Anthropic publicou essa mesma filosofia. Em raw-anthropic-harness-design.md:100 Sholto Douglas descreve: "I gave the planner access to our frontend design skill, which it read and used to create a visual design language for the app as part of the spec." Inferencia A disponibilizacao de skills como capabilities descobertas pelo modelo, nao injetadas manualmente, parece ser a direcao explicita do time de harness.
Modelo esta fazendo pesquisa e precisa de tech-research. Ou esta limpando codigo e precisa de doc-rot. Ou esta desenhando UI e precisa de frontend-design. O operador nao precisa saber que a skill existe. O modelo ve a descricao, infere relevancia, pede ativacao.
Quando o processo depende de prompts predefinidos, templates, scripts auxiliares, ou config YAML. tech-research empacota prompts/ + templates/ + config.yaml. Um command unico MD nao pode fazer isso -- teria que apontar para arquivos externos quebrando encapsulamento.
Skills globais em ~/.claude/skills/ (ex: graphify, knowledge-dream) funcionam em qualquer projeto. Commands tem que ser copiados ou linkados. Skills resolvem esse problema ja no design.
Quando a skill evolui (mais prompts, templates atualizados), a mudanca acontece dentro da pasta. Command unico MD cresceria para algo monolitico e dificil de manter.
/SquadCreator:create-from-sop e invocado deliberadamente pelo operador quando ele quer transformar SOPs YAML em squad. Nao ha valor em deixar o modelo "descobrir" -- e uma operacao administrativa dirigida. Ver .claude/commands/SquadCreator/create-from-sop.md:1-78.
AIOX/init.md tem 873 bytes. E um wizard de init. Zero valor em virar skill -- adicionaria overhead sem beneficio.
Dominio por diretorio da organizacao legivel: AIOX/agents/dev.md, AIOX/workflows/maestro.md, MegaBrain/gsd/plan-phase.md. Para um engenheiro novo entender o que existe, a estrutura de commands e mais transparente que uma lista plana de skills.
Quando a intencao e "execute este procedimento exato agora", command explicito e melhor. Skill depende da descricao match -- se o modelo escolhe skill errada, voce tem debug extra.
Parcialmente correta A hipotese precisa ser refinada: "skill e melhor quando a capability emerge no trabalho e precisa de recursos empacotados. Command e melhor quando o operador dispara uma rotina conhecida."
A direcao do harness da Anthropic, conforme raw-anthropic-harness-design.md:122, e: "find the simplest solution possible, and only increase complexity when needed (...) every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing."
Inferencia Skills permitem reduzir complexidade do harness central empurrando capabilities para componentes descobriveis. Quanto mais capaz o modelo (Opus 4.6 -> 4.7 -> future), menos scaffolding injetado o harness precisa. Skills sao a superficie onde essa transferencia acontece: o operador para de dirigir (commands) e comeca a confiar na descoberta (skills). E coerente com raw-anthropic-building-effective-agents.md -- "start simple, let the model drive."
Empirico O system-reminder desta propria conversa lista 200+ skills disponiveis (MegaBrain:*, AIOX:*, Support:*, etc.). O numero de commands nao namespaced (75 no projeto) e 2-3 ordens de grandeza menor que a superficie de skills acessiveis. A direcao esta clara.
Cada item aqui e um ponto onde o harness cru e permissivo demais para uso em producao. AIOX cobre com guardrails computacionais.
Harness cru nao tem nocao de "principios invariantes". AIOX publica 7 artigos constitucionais (I CLI First, II Agent Authority, III Story-Driven, IV No Invention, V Quality First, VII Verify Before Report, VIII Agent Lifecycle) com severidade por artigo (NON-NEGOTIABLE, MUST) e gate real por artigo.
Governance nao e so um doc: cada artigo aponta para um gate computacional. Art. II -> agent-authority.md rule. Art. III -> dev-develop-story.md task. Art. VIII -> agent-lifecycle-guard.cjs hook.
Harness cru permite spawn de multiplos subagents no mesmo working tree sem alertar. INC-1 provou que isso corrompe filesystem (10 stories Maestro v2 wiped em 10 minutos). AIOX adiciona parallel-subagent-isolation-guard.cjs -- BLOCK em exit 2 quando detecta worker + tree dirty + sem isolation:"worktree".
Harness cru trata qualquer subagent como capaz de qualquer coisa. AIOX define who-can-do-what em agent-authority.md (always-on rule): apenas @devops pode git push, criar PR, releases, tags. @dev pode commit local mas nao push. @qa tem veto. @architect nao faz DDL (delega @data-engineer).
Harness cru nao bloqueia push mesmo com lint/typecheck/test falhando. AIOX tem pre-commit-verification-gate.cjs, enforce-tests-before-merge.cjs, task pre-push.md. Build + typecheck + lint + test passa ou push e BLOCK.
Harness cru nao tem backoff. Agentes autonomos podem entrar em loop infinito de polling. AIOX define Art. VIII: max 5 checks com backoff exponencial, idle > 2x tempo ativo termina automaticamente, idle max 30min. agent-lifecycle-guard.cjs monitora (PostToolUse hook, 5.8K).
Harness cru deixa task tracking livre (TodoWrite e suficiente, um hook de lembrete talvez). AIOX exige story.md com AC, File List, checkboxes, rastreabilidade completa. story-completeness-guard.cjs (3.1K) verifica estrutura antes de deixar o dev declarar complete.
Harness cru permite o modelo inventar feature scope livremente. AIOX exige cada statement em spec.md derivar de FR-*, NFR-*, CON-*, ou research finding. Gate real em spec-write-spec.md: BLOCK se spec contiver invencoes.
Harness cru deixa o modelo declarar "done" sem evidencia. AIOX exige evidencia no report (test output, typecheck output, lint output). Task independent-verify.md executa verificacao em contexto fresh -- nao confia no proprio modelo que escreveu.
Harness cru nao tem conceito de "esta pasta e imutavel, aquela e mutavel". AIOX classifica: L1 (Core, NEVER mutavel, .aiox-core/core/), L2 (Templates, NEVER, development/{tasks,templates}), L3 (Config, restricted, data/), L4 (Runtime, ALWAYS, docs/stories/, packages/). l1-boundary-guard.cjs (7.6K) bloqueia edits em L1 sem amendment ativo.
Harness cru nao mantem historico estruturado alem de git log. AIOX mantem 4 fontes auditaveis: (a) docs/stories/ para trabalho, (b) .aiox/amendments/ para mudancas constitucionais (ex: AMA-001-reclassify-execution.yaml), (c) .aiox/incidents/ para post-mortems (ex: INC-1 + INC-2), (d) execution-reports por step.
ls .aiox/amendments/ = 13 yamls, ls .aiox/incidents/ = 1 incident + recovery-raw/. Exemplo .aiox/incidents/2026-04-15-parallel-subagent-filesystem-corruption.md documenta INC-1 e INC-2 com timeline, 5-whys, recovery, prevention, verification.Sem venda. Pontos reais onde AIOX adicionou complexidade, deixou bugs escaparem, ou duplicou semantica.
Quando o caller passa isolation:"worktree", o harness cria worktree pinado em commit stale (session-start SHA). Se o branch avancou, o agente isolado nao ve arquivos novos -- e entao cai silenciosamente para caminhos absolutos no main tree, reproduzindo INC-1. Observado 2026-04-15, horas depois de INC-1 ser "resolvido".
AIOX descobriu e adicionou worktree-base-verifier.cjs -- mas: (a) foi fix reativa, nao preventiva, (b) o workaround real ainda e criar worktree manualmente com git worktree add -b <branch> <path> HEAD, (c) o hook e strict (BLOCK em >5 commits atras) e pode quebrar trabalho legitimo.
Dez stories Maestro v2 wiped em 10 minutos (00:30-00:40 BRT, 2026-04-15) porque o @sm dispara 10 subagents em paralelo no mesmo cwd, sem isolation. Racing git checkout -b + git stash + git reset entre agentes corrompeu o tree. Codigo de um @dev commitou no branch de outro @dev.
Recovery foi possivel apenas porque JSONL transcripts em ~/.claude/projects/.../subagents/ preservaram os Write tool calls verbatim. Sem esses JSONLs, data loss teria sido permanente. A regra existia como prose, mas nao tinha hook. 5-why #4: "v4.0 harness cleanup moveu enforcement para hooks -- caso parallel-subagent nao foi coberto."
Numero total de superficies de controle: 25 hooks, 37 rules (3 always-on + 34 on-demand), 13 agentes canonicos, 19 squads, 7 artigos + 13 amendments, ~75 commands no projeto. Para um engenheiro novo no sistema, isso e fricao cognitiva real.
Inferencia Um dev novo provavelmente: (a) invoca o agente errado, (b) hit um hook que bloqueia sem entender porque, (c) procura rule e encontra versao desatualizada em outro caminho (.cursor/rules/, .gemini/rules/). Overhead justificado para producao critica, excessivo para trabalho exploratorio.
ls -la /Users/italo/italo_gustavo/.claude/.cursor/.gemini/ = 3 diretorios duplicando rules em formatos diferentes.Exemplo concreto no repo: squad-creator existe como:
.aiox-core/development/agents/squad-creator.md (framework agent).claude/commands/AIOX/agents/squad-creator.md (command redirect).claude/commands/SquadCreator/agents/squad-chief.md (command).claude/commands/SquadCreator/create-from-sop.md (command)Skill: SquadCreator:create-from-sop (skill no available list)Skill: SquadCreator:agents:squad-chief (skill).agents/workflows/SquadCreator/squad-chief.md (outro formato).cursor/rules/squad-creator.md + .gemini/rules/AIOX/agents/squad-creator.md (cross-IDE)Qual usar? O operador tem que saber. Skills, commands e agents se sobrepoem semanticamente -- e um sinal de overlap nao resolvido. A pergunta natural "como criar uma squad" tem ~5 caminhos validos que produzem resultados diferentes.
find /Users/italo/italo_gustavo -name "squad-chief.md" -o -name "squad-creator.md" | wc -l retorna 10+ arquivos em 6+ diretorios diferentes..aiox-core/core/ e NEVER mutavel. Protege framework, gera necessidade de amendment formal para mudar classificacao. AMA-001 reclassificou .aiox-core/core/execution/ de L1 para L3 -- processo envolveu documento yaml, aprovacao dupla (@aiox-master + @architect), pre-commit hook update.
Inferencia Para mudancas pontuais no execution/, esse overhead esta em descompasso com velocidade. Para governance de equipe grande, esta correto. Para solo dev, e caro.
Lista de skills disponiveis e longa (200+ no MEMORY + system-reminder). Descricoes curtas, e overlap conceitual (ex: tech-research vs graphify vs knowledge-dream para tarefa "pesquisa"). Inferencia Modelo pode invocar skill subotima e usuario nao saber que existe skill melhor.
Tambem: a propria existencia do skill find-skills (available skill: find-skills) admite que descoberta de skills e um problema. Meta-skill pra descobrir skills e sinal de que o espaco de skills ficou grande demais pra inspecao direta.
Hook BLOCKS quando CLAUDE_BASE >5 commits atras de HEAD. Numero arbitrario. Em sessions ativas de varios dias, 5 commits acumulam rapido. Resultado: hook bloqueia worktree que seria perfeitamente funcional. Workaround: git worktree add -b <name> <path> HEAD manual, ou bypass marker # parallel-subagent-isolation:bypass <reason>.
Bypass manual vira comum, o que degrada a seguranca que o hook deveria prover.
const MAX_COMMITS_BEHIND = 5).Cada hook e um processo node que parse stdin, le estado, faz git checks, escreve stdout. Em tool calls, isso multiplica. Particularmente em PreToolUse em Bash/Edit (mais comuns), cada chamada passa por varios hooks em serie.
Inferencia Com 4995 LOC de hooks (varios spawning execSync('git ...') com timeouts de 1-2s), latencia agregada e perceptivel. Nao medi diretamente, mas observavel em sessions longas de edit+test+commit.
wc -l .claude/hooks/*.cjs = 4995 LOC. Hooks que executam execSync no hot path: worktree-base-verifier.cjs:75, parallel-subagent-isolation-guard.cjs, l1-boundary-guard.cjs, pre-commit-verification-gate.cjs.Nao e "sempre use AIOX". E "use quando o overhead paga em governance".
| Use AIOX quando... | Pule AIOX (use harness cru) quando... |
|---|---|
|
|
A propria Anthropic, em raw-anthropic-harness-design.md:122-124, argumenta: "every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing -- both because they may be incorrect, and because they can quickly go stale as models improve." Implicacao: AIOX deveria periodicamente remover hooks/rules quando modelos novos os tornam desnecessarios. Nao ha evidencia no repo de que esse processo de poda acontece sistematicamente -- amendments adicionam, raramente removem.
"AIOX vale se o custo de uma falha e maior que o custo do overhead." Em sistemas de producao com usuarios pagos, governance paga. Em experimento de 1 hora, nao paga.
Dois sinais concretos de quando AIOX esta sobrando:
# parallel-subagent-isolation:bypass regularmente, o hook esta detectando falsos positivos -- ou voce esta fazendo trabalho fora do dominio do AIOX.AIOX e a produtizacao do Claude Code harness para operacao em escala: stories com traceability, agentes com autoridade formal, gates computacionais em vez de prose opcional, amendments para governance incremental, incidents documentados com prevencao. Faz o que o harness cru nao faz: audit trail + enforced quality + multi-agent coordination.
AIOX nao e substituto universal do harness cru. Em sessions curtas, solo dev, exploracao, o overhead (25 hooks + 37 rules + 13 agentes canonicos + 19 squads + 7 artigos + 13 amendments) e desproporcional. O proprio numero alto de superficies de controle e sintoma de entropia incremental -- amendments adicionam, raramente removem.
A hipotese do usuario esta parcialmente correta. Skills vencem em discovery, empacotamento, plugabilidade cross-projeto -- e isso parece ser a direcao explicita da Anthropic (empurrando skills como a nova superficie de capability expansion). Commands vencem em clareza administrativa para workflows dirigidos por operador, invocacao deterministica e baixo peso contextual. A pergunta nao e "skill ou command" -- e "o operador dirige, ou o modelo descobre?".
INC-1 (corruption) e INC-2 (stale worktree base) sao evidencia de que regras-como-prose nao escalam sob pressao de concorrencia -- precisam de hooks computacionais. AIOX aprendeu isso a duras penas em 2026-04-15 e adicionou 2 hooks novos no mesmo dia. O padrao subjacente: fix reativa apos incident. Nao ha evidencia de que o harness/AIOX tenha mecanismo proativo para auditar todas as invariantes de concorrencia em uma varredura unica.
A direcao da Anthropic (harness design blog) e dar mais autonomia ao modelo: skills que ele descobre, memory que ele consulta, agentes que planejam. AIOX segue essa direcao mas adiciona os guardrails tipicamente ausentes em prototipos da Anthropic -- onde um solo engineer roda 1 agente para construir 1 DAW em 4 horas, voce precisa de zero guardrails. Onde 3-5 agentes paralelos trabalham em 10 stories sobre codigo compartilhado, voce precisa de todos os 25 hooks.
Veredicto final: AIOX e uma resposta legitima a um problema real (producao-grade agent coordination) que a Anthropic ainda nao resolveu no harness central. Mas a resposta tem debito tecnico proprio: overhead cognitivo, duplicacao semantica skill/command/agent, fixes reativas para incidents, e ausencia de mecanismo sistematico de poda. Vale pagar o custo quando o custo de falhar excede o overhead. Senao, o harness cru + skills bem escolhidas e suficiente.