Skip to content

jonhnaka19-tech/akita-method

BranchesTags

Repository files navigation

Akita Method v2.1 — Engineering-First AI Development

32 princípios de engenharia destilados da metodologia de Fábio Akita.

7 hooks de auto-enforcement. 9 slash commands. 6 rules modulares. 1 skill carregável. Funciona em AIOX, BMAD, ou standalone. Auto-fusão em qualquer framework de desenvolvimento.

Version License Compatible Akita

⚠️ Disclaimer e crédito

Este projeto NÃO é oficial do Fábio Akita. É uma destilação independente da metodologia que ele documentou publicamente em:

Todo crédito intelectual vai ao Akita. Este pacote apenas operacionaliza os princípios em forma de:

  • Rules carregáveis pelo Claude Code
  • Hooks de enforcement automático
  • Slash commands para operações pontuais
  • Templates de outputs versionáveis

Se algo aqui ajudar você, siga o Akita (@akitaonrails) e veja o conteúdo original — é onde mora a sabedoria.

O que é

Disciplina de engenharia destilada para uso com agentes de IA (Claude Code, Cursor, Codex, etc.).

Premissa fundadora (Akita):

"A IA reflete quem você é. Bom engenheiro + IA = aceleração 10x. Engenheiro ruim + IA = 10x mais débito técnico produzido 10x mais rápido."

Princípios são carregados automaticamente (rules) e enforced automaticamente (hooks). Você nunca precisa lembrar de invocar nada.

Como este projeto foi criado

Esta é uma destilação de ~3 fontes, em pipeline metodológico documentado:

Fase 1 — Coleta de fontes

  • v1 baseline: 22 artigos do blog akitaonrails.com + 37 dias de imersão (650+ commits, ~144k linhas, ~10 projetos open source)
  • v2: transcrição completa do podcast Flow com Akita (~4h, 10.586 linhas)
  • v2.1: repositório edno2819/Criptografia-Resumo-Fabio-Akita — síntese de 2 vídeos do Akita sobre criptografia/segurança

Fase 2 — Extração e filtragem

  • 75 conceitos identificados na transcrição do podcast (v2)
  • Filtragem por critério "acionável vs informativo" → 29 princípios v2
  • +3 princípios + 1 expansão vindos do material crypto/segurança → 32 princípios v2.1
  • Princípios filtrados (vocabulário descritivo, info temporal, hardware specifics) ficaram fora para manter foco operacional

Fase 3 — Operacionalização

  • 6 rules modulares (carregadas automaticamente pelo Claude)
  • 7 hooks (disparam em git/edit/prompt automaticamente)
  • 9 slash commands (uso ocasional)
  • Templates para outputs versionáveis
  • Adapters para AIOX, BMAD, standalone, custom

Fase 4 — Validação

  • Cross-referenciado com transcrição original (citações literais em source-quotes.md)
  • Coexistência testada com AIOX (não modifica .aiox-core/)
  • Princípios mapeados a hooks universais (git, edit, prompt) → funciona em qualquer framework

Quick Start

Instalação

# Bash (Linux/Mac/Git Bash Windows)
git clone https://github.com/<seu-user>/akita-method.git
cd akita-method
bash install/install.sh

# PowerShell (Windows)
.\install\install.ps1

Verificar

# Em qualquer projeto
/akita:doctor

Usar

Você não usa explicitamente. Akita roda no background:

  • Rules sempre carregadas no contexto do agente
  • Hooks disparam em git/edit/prompt
  • Slash commands disponíveis para casos pontuais

Os 32 princípios

🔴 CORE (19) — bloqueia execução quando violado
  Testes (T1-T7)
    T1 ─ suíte completa antes de declarar terminado [MUST]
    T2 ─ feature + teste como unidade atômica [MUST]
    T3 ─ bug fix → regression test referenciando incidente [MUST]
    T4 ─ smoke + spider/fuzz testing [SHOULD]
    T5 ─ bug sintaxe vs lógica (boundaries) [MUST]
    T6 ─ auditoria diagnóstica brownfield [MUST]
    T7 ─ suíte = persistente + automatizada + bloqueante [MUST]
  Segurança (S1-S8)
    S1 ─ todo input é perigoso [MUST]
    S2 ─ defesa em 6 vetores: SQL+HTML+Prompt+CSRF+Session+Replay [MUST]
    S3 ─ rate limiting + Cloudflare [SHOULD]
    S4 ─ LGPD desde o início [MUST]
    S5 ─ segurança em camadas [SHOULD]
    S6 ─ password storage discipline (memory-hard hashing) [MUST] ← NEW v2.1
    S7 ─ crypto primitive selection (decision matrix) [MUST] ← NEW v2.1
    S8 ─ TLS/HTTPS obrigatório em produção [MUST] ← NEW v2.1
  Escalabilidade (E1-E2)
    E1 ─ você não é a Netflix [MUST]
    E2 ─ teste com volume real [MUST]
  Débito (D1-D2)
    D1 ─ débito em 3 dimensões: TEST+SEC+PERF [MUST]
    D2 ─ pagar incremental (2→testa→3→testa) [SHOULD]

🟡 SUPORTE (9) — guia operacional
    SU1 ─ cross-LLM review [MUST]
    SU2 ─ AI Jail (YOLO em container) [MUST]
    SU3 ─ skills como reuso [SHOULD]
    SU4 ─ Jack o estripador (atomic commits) [MUST]
    SU5 ─ Akita Quick Path (ideia.md) [SHOULD]
    SU6 ─ CLAUDE.md persistente [MUST]
    SU7 ─ documentação como subproduto [SHOULD]
    SU8 ─ cross-LLM continuity (travamento) [SHOULD]
    SU9 ─ responsabilidade do output é de quem usa [MUST]

🟢 FILOSOFIA (4) — operacionalizada
    F1 ─ software é argila, não Lego [SHOULD]
    F2 ─ "será que não tem jeito melhor?" [SHOULD]
    F3 ─ aprendizado deliberado vs decoreba [SHOULD]
    F4 ─ comunicação meta (melhore seu texto) [MUST]

Estrutura do pacote

akita-method/
├── README.md                          (você está aqui)
├── AKITA-INTEGRATION-GUIDE-v2.md      (master guide — fonte de verdade, 100KB+)
├── CHANGELOG.md
├── VERSION (2.1.0)
│
├── content/
│   ├── global/                        → vai para ~/.claude/
│   │   ├── rules/                     (6 rules modulares)
│   │   ├── commands/akita/            (9 slash commands)
│   │   ├── skills/akita-method/       (skill + 4 references + 5 templates)
│   │   └── akita-method/
│   │       ├── hooks/                 (7 hooks bash)
│   │       └── settings.akita.json    (template para settings.json merge)
│   └── project/                       → vai para ./.claude/akita/ (sob demanda)
│       └── workflows/                 (workflows YAML opcionais)
│
├── install/
│   ├── install.sh                     (Bash — Linux/Mac/Git Bash)
│   └── install.ps1                    (PowerShell — Windows)
│
└── adapters/
    ├── standalone.adapter.md          (sem framework hospedeiro)
    ├── aiox.adapter.md                (Synkra AIOX)
    ├── bmad.adapter.md                (BMAD)
    └── extending.adapter.md           (criar adapter para framework custom)

Compatibilidade

Framework Status Adapter
Standalone (sem framework) ✅ Suportado standalone.adapter.md
AIOX (Synkra) ✅ Suportado aiox.adapter.md
BMAD ✅ Suportado bmad.adapter.md
GSD, Specify, custom ✅ Funciona standalone; criar adapter custom extending.adapter.md

Princípio: Akita usa eventos universais (git, edit, prompt). Funciona em qualquer ferramenta de desenvolvimento que respeite esses padrões.

Slash commands

Comando Função Quando usar
/akita:plan <desc> Cria ideia.md (Akita Quick Path) Spike/protótipo pessoal
/akita:audit Brownfield Test Audit (5 etapas) 1ª vez em projeto sem testes
/akita:setup-suite Configura T7 (estrutura+CI+hooks) 1ª vez em projeto sem CI
/akita:check Roda suíte completa manualmente Debug ad-hoc
/akita:pay-debt [n] Paga N items do TEST_BACKLOG Sprint dedicada a débito
/akita:cross-review Revisão com LLM diferente Antes de PR crítico
/akita:extract-skill Destila sessão em skill reusável Após resolver problema difícil
/akita:status Estado do projeto (health score) Visão geral
/akita:doctor Diagnóstico de setup Algo parece quebrado?

Hooks de auto-enforcement

Você não precisa invocar nada. Esses hooks disparam automaticamente:

Hook Trigger Ação Princípio
akita-precommit-gate git commit Roda suíte; bloqueia se vermelha T1, T2
akita-prepush-gate git push Verifica CI; bloqueia push direto em main T7 N2
akita-predeploy-gate deploy commands Bloqueia se suíte não 100% verde T7 N3
akita-coverage-watch Edit em src/ Alerta se sem teste correspondente T2
akita-bug-protocol Prompt com "fix"/"bug" Lembra T3 (regression test) T3
akita-predeploy-checklist Prompt com "deploy" Apresenta checklist obrigatório T7+S5+S8
akita-doctor-quick SessionStart Verificação rápida de setup T6, T7, SU6

Override de hooks (use com parcimônia)

Cada hook respeita variável de ambiente para emergências:

# Skip precommit (T1+T2) — não recomendado
export AKITA_SKIP_PRECOMMIT="motivo"

# Skip prepush (T7 N2)
export AKITA_SKIP_PREPUSH="motivo"

# Skip predeploy (T7 N3) — exige formato "incident-id:descrição"
export AKITA_SKIP_PREDEPLOY="INC-1234:hotfix urgente"

Overrides são logados em ~/.claude/akita-method/logs/ para auditoria posterior.

Documentação completa

Princípio fundador

"A IA reflete quem você é." — Fábio Akita

A IA é uma máquina de escrever. Não te torna escritor. Acelera quem já escreve bem; multiplica os erros de quem escreve mal.

Akita não substitui sua disciplina. Akita garante que sua disciplina seja aplicada consistentemente.

Fontes e contribuições

Origens (todo crédito intelectual)

  • Fábio Akita — autor da metodologia original
  • edno2819 — síntese dos vídeos de criptografia/segurança que alimentou v2.1

Compilação e operacionalização

  • Jonh Wilian — curadoria, filtragem (75 → 32 princípios), arquitetura do pacote
  • Pipeline metodológico via Synthetic Intelligence Factory

Como contribuir

PRs welcome. Critérios:

  • Tested em pelo menos 1 projeto real
  • Princípio acionável (não apenas filosófico)
  • Citação de fonte (Akita material ou outra autoridade)
  • Não duplica nem conflita com princípio existente
  • Anti-patterns documentados

Licença

MIT. Use livremente. Se algo aqui ajudar você profissionalmente, considere:

Origem espiritual: Fábio Akita. Akita não é teoria. É metodologia testada em batalha.

About

Engineering-first AI development discipline — 32 principles distilled from Fábio Akita's methodology. 7 auto-enforcement hooks, 9 slash commands, 6 modular rules. Framework-agnostic (AIOX, BMAD, standalone).

akitaonrails.com

Topics

security tdd developer-tools akita aiox bmad ai-development brazilian-tech claude-code engineering-discipline

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v2.1.0 — Initial public release Latest
Apr 24, 2026

Packages

 
 
 

Contributors

Languages