Starter Harness Designer — Coding v1
"O que o agente não conseguiu fazer não foi por falta de capacidade, mas por falta de ambiente."
Para quem é esta skill
- Pessoas criando um harness de codificação pela primeira vez
- Não desenvolvedores / juniores que querem montar uma equipe de desenvolvimento
- Pessoas que desejam começar rapidamente com templates validados de full-stack, API ou ML
Mantém a mesma filosofia de três fases Planejador → Gerador → Avaliador do harness-designer-coding para especialistas,
mas redistribui a complexidade de entrada e a precisão de saída de cada fase para o nível iniciante.
| Fase | Para Especialistas | Starter (esta skill) |
|---|---|---|
| Planejador | Descoberta em 4 etapas, perguntas abertas | 3 perguntas de múltipla escolha → numeração do exemplar |
| Gerador | Projeto → geração de arquivos/estrutura | Replicação de exemplar + substituição |
| Avaliador | Verificação independente dos 8 pilares | Checklist leve — apenas substituições ausentes e referências quebradas |
Matriz de Skills
│ Especialista (design livre) │ Iniciante (replicação de exemplar)
──────────────┼─────────────────────────────────────┼────────────────────────────────────
Workspace │ harness-designer-workspace │ harness-starter-workspace
──────────────┼─────────────────────────────────────┼────────────────────────────────────
Codificação │ harness-designer-coding │ harness-starter-coding ★ (esta skill)
Quando NÃO usar esta skill
- Documentação, análise, criação de conteúdo →
harness-starter-workspace - Usuários avançados que precisam de liberdade arquitetural →
harness-designer-coding - Microsserviços empresariais → skill
enterprise
Fluxo de Execução (total de 5 a 10 minutos)
1. [Planejador] 3 perguntas de múltipla escolha (tipo de app, natureza dos dados, escala)
2. [Planejador] Correspondência do número do exemplar + recomendação de Modo de Escala + recomendação de predefinição
3. [Gerador] Replicação do exemplar do harness-100
4. [Gerador] Substituição do nome do projeto, pilha de tecnologia e termos de domínio
5. [Avaliador] Checklist leve (10 segundos)
6. Instruções de conclusão ("Agora, desenvolva assim")
Fase 0: Correspondência de Padrões (Planejador)
Pergunta 1 — O que você quer criar? (Múltipla escolha)
| Nº | Tipo de App | Exemplar Representativo |
|---|---|---|
| 1 | 🌐 Aplicação Web Full-Stack (front+back+BD) | #16-fullstack-webapp |
| 2 | 🔌 Apenas Servidor API | #18-api-designer |
| 3 | 📱 App Mobile (iOS/Android) | #17-mobile-app-builder |
| 4 | 🗃️ Pipeline de Dados / ETL | #27-data-pipeline |
| 5 | 🤖 App AI/LLM / RAG | #41-llm-app-builder |
| 6 | 🧪 Experimento ML / Treinamento de Modelo | #31-ml-experiment |
| 7 | 🎨 Sistema de Design (baseado em shadcn) | #36-design-system |
| 8 | 🔐 Auditoria de Segurança / Teste de Penetração | #28-security-audit |
| 9 | 🚀 Apenas CI/CD / Infraestrutura | #20-cicd-pipeline |
| 10 | ♻️ Modernização / Refatoração de Legado | #22-legacy-modernizer |
Pergunta 2 — Qual é a escala? (Múltipla escolha → Modo de Escala automático)
| Escala | Modo de Escala | Agentes alocados |
|---|---|---|
| MVP / Protótipo para 1 pessoa | Single | Apenas o 1 mais essencial |
| Equipe pequena / Dentro de 1 mês | Reduced | 3 pessoas (arquiteto + desenvolvedor principal + qa) |
| Médio porte ou mais / Produção | Full | 5 pessoas (arquiteto + frontend + backend + qa + devops) |
Pergunta 3 — Qual é o nome do projeto?
Baseado no nome da pasta. A pilha de tecnologia não é perguntada — a pilha padrão do exemplar é usada (o usuário pode substituir depois, se necessário).
Pilhas Padrão (seguir sem substituição):
- Full-stack: Next.js + Prisma + SQLite
- API: FastAPI ou Express
- Mobile: React Native (Expo)
- Dados/ML: Python + pandas + scikit-learn
- RAG: Next.js + Vercel AI SDK + pgvector
Pergunta 4 — Quer deixar um histórico de alterações? (Opcional, sim/não)
"Quando você melhorar este harness mais tarde, quer criar um espaço para registrar o que mudou e por quê?"
- sim → Cria automaticamente o wiki
05-flow-history/+ o arquivo00-system/protocols/flow-change-protocol.md(a construção inicial é registrada como change 0001). Referência:~/.claude/skills/harness-designer-workspace/references/flow-history-template.md - não → Não cria (pode ser adicionado manualmente depois)
Finalidade: retrospectiva de melhoria de fluxo, justificativa para rollback, referência ao criar harnesses semelhantes. Para protótipos de 1 a 2 semanas, recomenda-se não.
Princípio de gerenciamento: Este histórico registra apenas alterações no sistema de fluxo de trabalho (prompts, protocolos, templates, comandos, CLAUDE.md).
Os artefatos produzidos pelo sistema (código, resultados de build, registros de implantação) não são objeto de registro.
Critério de distinção: "Se esta alteração não tivesse ocorrido, o resultado da próxima execução seria diferente?"
→ Seria diferente = alteração no sistema = registrar / Não seria diferente = artefato = não precisa registrar
Detalhes: 00-system/protocols/flow-change-protocol.md
Fase 1: Seleção de Predefinição (Pesos de Avaliação)
| Predefinição | Descrição | Recomendação Automática |
|---|---|---|
| [Equilibrado] (padrão) | Todos os critérios de qualidade equilibrados | Valor padrão |
| [Qualidade primeiro] | OWASP, Testes, Revisor com peso 2x | Auditoria de segurança, pagamentos, saúde, finanças |
| [Velocidade primeiro] | Escala=Single, testes minimizados | Hackathons, protótipo individual |
A seleção é registrada em _workspace/00_input.md.
Fase 2: Gerador — Replicação e Substituição de Exemplar
Etapa de Replicação (fallback automático)
Detecta automaticamente a presença de gh e baixa da forma mais adequada. Funciona igualmente bem apenas com git.
EXEMPLAR="{NN}-{exemplar-name}" # Resultado da correspondência do Planejador (ex: 16-fullstack-webapp)
BASE="ko/$EXEMPLAR/.claude"
if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
# ── Método A: GitHub CLI (gh) ──────────────────────────────
echo "📡 Baixando via gh API..."
FILES=$(gh api "repos/revfactory/harness-100/git/trees/main?recursive=1" \
--jq ".tree[] | select(.path | startswith(\"$BASE/\")) | select(.type==\"blob\") | .path")
mkdir -p .claude/agents .claude/skills
while IFS= read -r filepath; do
rel="${filepath#$BASE/}"
dest=".claude/$rel"
mkdir -p "$(dirname \"$dest\")"
gh api "repos/revfactory/harness-100/contents/$filepath" \
--jq '.content' | base64 -d > "$dest"
echo " ✅ $dest"
done <<< "$FILES"
else
# ── Método B: git sparse checkout (quando não há gh) ─────────────
echo "📡 Baixando via git sparse checkout..."
TMP=$(mktemp -d)
git clone --depth 1 --filter=blob:none --sparse \
https://github.com/revfactory/harness-100.git "$TMP"
git -C "$TMP" sparse-checkout set "$BASE"
mkdir -p .claude
cp -r "$TMP/$BASE/." .claude/
rm -rf "$TMP"
echo " ✅ sparse checkout concluído"
fi
| Condição | Método Usado | Ferramentas Necessárias |
|---|---|---|
gh instalado + logado | Método A (gh api) | gh |
Apenas git disponível | Método B (sparse checkout) | git |
| Ambos ausentes ou falham | Método C (Claude gera diretamente após confirmação do usuário) | Nenhum |
Se ambos os Métodos A e B falharem, o Claude orienta o usuário diretamente:
⚠️ Não foi possível obter o template do GitHub.
Motivo:
ghegitestão indisponíveis ou não há conexão com a internet.Neste caso, o Claude pode escrever os arquivos do harness diretamente, consultando a descrição do exemplar. No entanto, como não é um template validado, mas sim uma reprodução da estrutura pelo Claude, pode haver diferenças de qualidade.
Deseja continuar?
- Sim → Claude gera os arquivos
.claude/diretamente (com base em exemplar-index.md)- Não → Interrompe aqui. Tente novamente após conectar-se à internet ou instalar o git.
Se o usuário escolher Sim: lê a descrição do exemplar correspondente em references/exemplar-index.md e escreve diretamente a estrutura de CLAUDE.md, agents/, skills/.
Se o usuário escolher Não: interrompe imediatamente, informa como tentar novamente e encerra.
Após a conclusão, estrutura:
.claude/
├── CLAUDE.md
├── agents/
│ ├── architect.md — Requisitos · Arquitetura · BD · API
│ ├── frontend-dev.md — React/Next.js (removido conforme Escala)
│ ├── backend-dev.md — API · BD · Auth
│ ├── qa-engineer.md — Testes · Revisão de código (Revisor)
│ └── devops-engineer.md — CI/CD · Infraestrutura (removido conforme Escala)
└── skills/
├── {orchestrator}/skill.md
├── component-patterns/skill.md
└── api-security-checklist/skill.md
- Excluir arquivos de agente de acordo com o Modo de Escala:
- Single → apenas 1 arquiteto (ou o mais relevante)
- Reduced → arquiteto + desenvolvedor principal + qa
- Full → todos os 5
- Criar pasta
_workspace/. Convenção de numeração de artefatos:00_input.md— Entrada do usuário organizada01_architecture.md— Projeto de arquitetura02_api_spec.md— Especificação da API03_db_schema.md— Esquema do banco de dados04_test_plan.md— Plano de testes05_deploy_guide.md— Guia de implantação06_review_report.md— Relatório de revisão
Regras de Substituição
| Original | Substituição | Observação |
|---|---|---|
| Nome do harness | Nome do projeto do usuário | 16-fullstack-webapp → my-todo-app |
| Pilha de tecnologia (Next.js/Prisma etc.) | Manter padrão | Substituir apenas se o usuário especificar |
| Palavras-chave de gatilho | Palavras-chave de domínio | "todo app" → palavra-chave do projeto |
_workspace/NN_*.md | Manter | Nunca alterar a convenção de numeração |
| Injeção de OWASP·SOLID·DORA | Manter absolutamente | Essencial para a expertise de domínio |
| Tabela de Modos de Escala | Manter | Preservar definições de Full/Reduced/Single |
Protocolo SendMessage | Manter | Mecanismo de comunicação entre agentes |
Princípios de Comportamento do Agente de Codificação (inspirados em Karpathy, inserção obrigatória)
Após replicar o exemplar, deve-se adicionar a seção abaixo ao final de .claude/CLAUDE.md (não substituir; preservar):
## Princípios de Comportamento do Agente de Codificação (inspirados em Karpathy)
Todos os agentes de codificação devem seguir os 4 princípios abaixo ao trabalhar.
Consulte a skill karpathy-guidelines para detalhes (gatilho automático).
1. Think Before Coding — Explicitar suposições, perguntar em caso de ambiguidade, sugerir alternativas
2. Simplicity First — Somente o que foi solicitado. Proibir abstrações especulativas e funcionalidades extras
3. Surgical Changes — Alterar apenas as linhas solicitadas. Proibir melhorias em código adjacente
4. Goal-Driven Execution — Critérios de sucesso verificáveis → Loop → Verificação
No checklist leve do Avaliador, adicionar o item "Seção dos 4 princípios Karpathy existe no CLAUDE.md".
Lista de Proibições de Substituição
- Nomes de frameworks: OWASP Top 10, SOLID, DDD, Test Pyramid, DORA Metrics, CWE Top 25, Star/Snowflake Schema, SHAP/LIME, Great Expectations
- Protocolos: SendMessage, TaskCreate, TaskUpdate
- Convenção de pastas:
_workspace/,src/, prefixos numéricos - Definições de Modos de Escala
- Estrutura de 3 Cenários de Teste (Normal / Existing / Error)
- Correção automática bkit: Os 4 princípios Karpathy, OWASP Top 10, DORA Metrics, Modos de Escala não podem ser modificados por sugestões de agentes bkit (code-analyzer, pdca-iterator etc.)
- Elementos de loop: Critérios de conclusão (condição de parada), ordem de revisão do Revisor (qa-engineer), formato de julgamento do review_report — proibido substituir ou remover (um loop só é válido com Meta + Verificação + condição de parada)
Simplificação de Termos (para explicação ao usuário)
| Termo Original | Termo Simplificado |
|---|---|
| architect | Projetista |
| frontend-dev | Desenvolvedor frontend |
| backend-dev | Desenvolvedor backend |
| qa-engineer | Revisor de qualidade |
| devops-engineer | Responsável pela implantação |
| Dependency DAG | Sequência de tarefas |
| Modo de Escala | Tamanho da equipe |
Manter os termos originais nos arquivos internos; usar apenas os termos simplificados na conversa com o usuário.
Fase 3: Avaliador — Checklist Leve
Verificação Automática (10 segundos)
-
.claude/CLAUDE.mdexiste - Número de arquivos em
agents/corresponde ao Modo de Escala (Single=1, Reduced=3, Full=5) - Função de Revisor (qa-engineer) incluída
-
skills/<orchestrator>/skill.mdexiste - Pelo menos 1 skill de extensão de agente (component-patterns ou api-security-checklist)
- Pasta
_workspace/+ templates de artefatos numerados criados - Nomes de frameworks como OWASP·SOLID etc. preservados (verificar contagem original com grep)
- Seção Trigger Boundaries
should-NOTexiste - Tabela de Modos de Escala existe
- Seção de 3 Cenários de Teste (Normal / Existing / Error) existe
- Nome do exemplar original (ex:
16-fullstack-webapp) remanescente: 0 ocorrências - (Se pergunta 4 sim) Pasta
05-flow-history/+ arquivo00-system/protocols/flow-change-protocol.mdcriados - Existem critérios de conclusão (condição de parada) verificáveis em orchestrator skill.md
- O artefato do Revisor (review_report) possui formato que inclui julgamento de aprovado / precisa de correção
Em Caso de Falha
- Substituição ausente → Planejador faz nova pergunta
- Perda de framework → Replicar exemplar novamente e substituir
- 3 falhas → Orientar a usar a versão para especialistas
harness-designer-coding
Fase 4: Instruções de Conclusão (relatório em linguagem simples para não desenvolvedores)
✅ Seu harness de codificação está pronto!
📁 Localização: /my-todo-app/.claude/
👥 Equipe de desenvolvimento (Modo Reduced, 3 pessoas):
- Projetista (architect): Projeta a estrutura do BD e da API
- Desenvolvedor backend: Next.js API + Prisma
- Revisor de qualidade (qa): Testes e revisão de código
🛠️ Pilha padrão: Next.js + Prisma + SQLite (substituível)
🚀 Como usar:
1. No Claude Code, faça um pedido como "crie a funcionalidade de login para o app todo"
2. A equipe trabalha na ordem:
Projetista → Desenvolvedor backend → Revisor de qualidade
3. Resultados: _workspace/01_architecture.md ~ 06_review_report.md
4. Código fonte: gerado na pasta src/
🔒 Segurança e qualidade inclusas:
- Checklist OWASP Top 10 aplicado automaticamente
- Revisão de código baseada nos princípios SOLID
- 3 cenários de teste (normal, arquivo existente, erro)
🔄 Como a equipe trabalha (loop):
A equipe opera em um loop de "Meta (Goal) → Implementação → Revisão (Check) → Concluir se aprovado".
O relatório final do revisor de qualidade (06_review_report.md) é o resultado da verificação.
Se não gostar do resultado, peça novamente com mais detalhes —
esse julgamento final é o seu papel (outer loop).
📘 Próximos passos:
- Para aumentar a equipe para 5 pessoas, adicione frontend e responsável pela implantação (modo Full)
- Para personalização avançada, use a skill harness-designer-coding
Materiais de Referência
- exemplar-index.md — 27 exemplares de codificação + Modos de Escala + índice de frameworks
- Original: https://github.com/revfactory/harness-100 (Apache-2.0)
- Variante para especialistas:
harness-designer-coding - Variante de workspace:
harness-starter-workspace