guia
Como usar este template
Fluxo de trabalho do cocreate-project-template com Spec-Driven Development (SDD) e camada Harness.
Porta canônica
3001O CoCreate Studio sempre roda em http://localhost:3001. Convenção fixa do template — útil quando você tem vários projetos abertos em paralelo e precisa saber rapidamente qual dashboard pertence a qual projeto.
Como mudar a porta (se conflitar com outro serviço)
Edite harness-ui/package.json, scripts dev e start, trocando -p 3001 pelo número desejado.
Mantenha o padrão 3001 sempre que possível — assim você ou seu time não precisa procurar.
Pré-requisito: leia o ADR-002
O template combina SDD (specs como verdade) com a camada Harness (hooks, traces, loop de correção). Sem essa fundação, várias decisões parecem arbitrárias. Está em docs/adr/adr-002-harness-engineering-complemento-sdd.md.
GATILHO ZERO — /iniciar-projeto
Antes de qualquer código ou spec, rode /iniciar-projeto no Claude Code. A skill conduz 5 fases de perguntas guiadas:
- ›Fase 1 — Perfil do Usuário (quem está conduzindo o projeto)
- ›Fase 2 — Tipo de Projeto (interno/externo, B2B/B2C, estágio, deadline)
- ›Fase 3 — Escopo Inicial (problema, sucesso, fora do escopo)
- ›Fase 4 — Macro Processo do Negócio (Mermaid + descrição)
- ›Fase 5 — Análise Estratégica (riscos + compliance + dependências + top 5 mitigações)
Gera
- · docs/raw/00-perfil-projeto.md
- · docs/macro-processo.md
- · docs/analise-estrategica.md
- · CLAUDE.md preenchido (Perfil + Tipo + Stakeholders)
GATILHO 1 — /processar-contexto
Com o briefing estruturado em docs/raw/, esta skill gera a constitution (spec-000) e a primeira spec de feature (spec-001). Também propõe estrutura de pastas e preenche placeholders restantes.
Gera
- · docs/specs/spec-000-constitution.md
- · docs/specs/spec-001-*.md
- · docs/adr/adr-NNN-*.md (decisões identificadas)
Início de sessão — /preparar-missao
Em toda nova sessão, rode /preparar-missao com uma direção (texto ou voz). Subagent Opus analisa, define a missão, atualiza CLAUDE.md e recomenda Modo Rápido (1-2 skills) ou Modo Orquestrado (3+ skills em paralelo).
Execução — /executar-tarefa ou /orquestrar
Para tarefas simples, /executar-tarefa implementa direto com loop de correção (até 3 tentativas em testes falhados). Para missões complexas multi-área, /orquestrar coordena várias skills em paralelo sem sobreposição de arquivos.
Validação contínua (camada Harness)
Sempre que você editar uma spec/ADR/CLAUDE.md, o hook post-spec-edit registra em .claude/pending-validations.md. Antes de fechar a missão, rode /analisar-coerencia: a skill prioriza as pendências registradas pelo hook.
Fim de sessão — /licoes-aprendidas
Skill consome o trace do dia, identifica TENTATIVAS falhadas no loop de correção, e propõe entradas em docs/licoes-aprendidas.md (Regra de Diamante). Refina o CLAUDE.md com padrões emergentes.
Modos de execução
| Critério | Modo Rápido | Modo Orquestrado |
|---|---|---|
| Áreas tocadas | 1-2 | 3+ |
| Skills necessárias | 1-2 | 3+ |
| Risco de conflito | Baixo | Alto |
| Fluxo | /preparar-missao → execução direta | /preparar-missao → /orquestrar → consolidação |
Onde olhar este dashboard durante o trabalho
- Visão geral: pega o pulso. Quantas skills rodaram hoje, quantas pendências, tem tentativa falhada.
- Runtime: timeline detalhada do que cada skill fez. Útil quando coordena vários chats em paralelo.
- Specs e ADRs: estado das specs (rascunho com placeholder vs ativa).
- Skills: explora o que cada skill faz e quando foi usada pela última vez.
Para o curso SDD
O CoCreate Studio é material pedagógico. Alunos do curso clonam o template e abrem este dashboard ao lado do Claude Code para ver, em tempo real, como skills e subagents interagem. O diagrama Mermaid da home é regenerado a cada refresh com base nas skills cadastradas, então funciona como documentação viva.
Arquitetura completa do ecossistema
referência avançadaO diagrama abaixo mostra todos os fluxos entre você, Claude Code, CoCreate Studio (este painel), as skills agrupadas em 5 categorias, subagents, MCPs, camada Harness (hooks, traces, pendências) e camada compartilhada (specs, ADRs, raw, perguntas). Use a tela cheia para explorar.
Regenerado a cada refresh a partir de .claude/skills/ e .claude/agents/.
Quer usar Codex CLI no lugar do Claude Code?
alternativaO template é otimizado para Claude Code (CLI da Anthropic), que é a recomendação principal. Mas tudo o que está em docs/ é compartilhado e funciona em qualquer cliente — incluindo o Codex CLI (OpenAI), como rota alternativa ou backup.
Passo a passo para adaptar ao Codex
- 1.Leia o AGENTS.md na raiz do projeto — é o equivalente do CLAUDE.md para Codex. Ele aponta as diferenças operacionais e o que está portado vs. ainda não.
- 2.Configure o Codex: copie
.codex/config.toml.examplepara~/.codex/config.tomlou.codex/config.tomllocal e ajuste paths/MCPs. - 3.Invocação por matching natural: no Codex você não digita
/iniciar-projeto— descreve em linguagem natural ("vamos iniciar este projeto") e a skill correspondente em.codex/skills/ativa. - 4.Limitações conhecidas: hooks da camada Harness são exclusivos do Claude Code. No Codex, valide manualmente rodando
/analisar-coerenciaapós editar specs. Detalhes em AGENTS.md. - 5.Roadmap: nem todas as 14 skills do Claude foram portadas para Codex ainda. Hoje, no Codex, você tem
iniciar-projeto,processar-contextoepreparar-missao. Para o restante, opere direto seguindo as regras do CLAUDE.md.
Recomendação: use Claude Code como principal. O Codex serve quando você não tem acesso ao Claude Code ou prefere a stack OpenAI por algum motivo específico (compliance, integração existente). A metodologia SDD + Harness independe do cliente — a casca é só o runner.