kitocode

Framework token-economy para entrega de software guiada pelo Claude Code. PT-BR.

Stacks suportadas:

• csharp-portaria — C# .NET 9 (Clean Arch + CQRS-lite + MediatR + EF Core 9 + Npgsql)
• frontend-react — Next.js 15 + TypeScript + Tailwind + shadcn/ui + TanStack Query + Zod
• python-fastapi — FastAPI + SQLAlchemy 2 + Pydantic 2 + asyncpg

Filosofia

Cada historia e uma capacidade do sistema, nao apenas um cadastro. 8 tipos: crud, business-flow, integration, report, automation, authorization, architecture, refactor.

Tipo nao-crud exige artefato aprovado (mockup ou contrato) antes da implementacao — voce nao escreve logica adivinhando, escreve seguindo um contrato.

Instalacao

npx kitocode meu-projeto
cd meu-projeto

Ou no diretorio atual:

npx kitocode

Pre-requisitos: Node >= 20, Python >= 3.10. O CLI verifica e avisa.

Uso

Abra o diretorio no Claude Code e digite /proximo. O oraculo analisa o estado do projeto e diz o proximo passo.

📘 Tutorial completo end-to-end: veja TUTORIAL.md. Inclui passo-a-passo de um projeto exemplo (API C# + frontend Next.js), referencia de comandos, cenarios comuns e troubleshooting.

Fluxo padrao:

[/ideia]  →  /prd  →  [/ux]  →  /arq  →  /historias  →  [/artefato + /aprovar]  →  /impl HIST-NNN  →  /commit HIST-NNN

/ideia (recomendado): engenheiro de software conversacional. Conduz analise em rodadas, modela OO (heranca/abstracoes/value-objects), gera 7 documentos estilo TCC em documentacao/. Apos rodar, o /prd consome a analise direto sem mais perguntas.

Comandos principais

| Comando | O que faz | |---------|-----------| | /proximo | oraculo: analisa estado e sugere proximo passo (/help e reservado pelo Claude Code) | | /ideia | engenheiro conversacional: levanta requisitos + modelagem OO + 7 docs | | /prd | cria PRD em YAML (usa analise se /ideia rodou) | | /ux | cria UX (telas, fluxos, estados) — so projetos com frontend | | /arq | gera arquitetura.yaml a partir do PRD/UX | | /historias | quebra arquitetura em historias (8 tipos de capacidade) | | /artefato HIST-NNN | gera mockup ou contrato pre-implementacao | | /aprovar HIST-NNN | marca artefato aprovado, libera /impl | | /impl HIST-NNN | implementa uma historia | | /commit HIST-NNN | commita historia concluida (gate de qualidade) | | /agregado Nome | atalho: scaffold direto agregado C# | | /uiux <query> | design system (estilo+paleta+fonte) via ui-ux-pro-max | | /run | sobe API + frontend em background, sincroniza URL automatica | | /seguranca | auditoria + aplicacao de seguranca backend/frontend | | /observabilidade | aplica Serilog + health checks | | /ci | aplica GitHub Actions CI + CodeQL + Dependabot | | /rev | revisa codigo contra blueprint | | /pos | review + seguranca + reindex (gate antes de commit) | | /doc | gera README do projeto |

Lista completa: CLAUDE.md.

Decisoes ja tomadas

• Idioma: PT-BR para dominio
• Validacao: FluentValidation embutida no Comand
• Erro padrao: ComandResult / PagedResult com tratamento central via ExceptionMiddleware
• Auth: JWT (NetDevPack)
• DB: PostgreSQL (Npgsql para C#)
• Sem cascade delete (ClientSetNull)
• NoTracking global em queries
• Zero comentarios em codigo de dominio
• Strings: varchar(200) default
• IDs: Guid / uuid
• DateTime: timestamptz (Brasilia explicito via DataBrasilia.HorarioBrasilia)

Estrutura instalada

meu-projeto/
├── CLAUDE.md                       # instrucoes do framework para Claude
└── .framework/
    ├── nucleo/                     # blueprints e convencoes
    ├── modelos/                    # templates YAML + extras
    ├── skills/                     # 26 skills (PRD, UX, scaffold, review...)
    ├── scripts/                    # 30+ scripts Python
    ├── templates/csharp-core/      # Core/WebApi.Core embutidos (autonomia)
    └── estado/                     # estado vivo do projeto (gerado)

Autonomia

O framework e autonomo: nao precisa do Portaria-master ao lado. Os arquivos do Core/WebApi.Core estao embutidos em .framework/templates/csharp-core/.

Plataforma

Hoje os scripts assumem o launcher Windows py. Em macOS/Linux:

alias py=python3

Ou substitua py por python3 ao executar comandos.

Atribuicao

A skill ui-ux-pro-max (50+ estilos, 161 paletas, 57 font pairings, 99 UX guidelines) e copia direta de github.com/nextlevelbuilder/ui-ux-pro-max-skill (NextLevelBuilder, MIT).

Licenca

MIT — veja LICENSE.