davidvictor/build-in-public

Build in Public

Visão Geral

Use esta habilidade quando o projeto já funciona e a tarefa é torná-lo apresentável, seguro e utilizável em público. O destino padrão é um repositório sandbox em ~/.codex/workspaces/default/repos/ ou ~/.codex/workspaces/default/labs/, mas o mesmo fluxo de trabalho funciona para qualquer repositório local.

Recursos

• references/public-release-checklist.md
  Use para a etapa de verificação de lançamento público e para a passagem final de conclusão.
• references/readme-template.md
  Use ao escrever ou reestruturar o README.md.
• scripts/create_release_zip.sh
  Use para criar um zip limpo a partir do HEAD atual após o repositório estar pronto.

Capacidades Nativas do Codex

Quando o host fornece capacidades nativas do aplicativo ou CLI do Codex, use-as como aceleradores sem torná-las dependências rígidas:

• Use a pesquisa na web para fatos atuais da plataforma de publicação, comportamento do gerenciador de pacotes, avisos de segurança ou documentação que possa ter mudado. Prefira fontes primárias e cite-as no relatório final.
• Use a geração de imagens integrada para visuais do README vinculados ao projeto quando um mapa do repositório, diagrama de arquitetura, banner ou ativo ilustrativo tornar o projeto mais fácil de entender. Gere a imagem, inspecione-a, copie o arquivo final selecionado para o repositório em assets/, insira-o no README no local narrativo correto, use texto alternativo descritivo e mantenha rótulos técnicos críticos em Markdown, Mermaid, SVG ou prosa próxima se o texto gerado for imperfeito.
• Use o navegador no aplicativo para visualizações locais da web, visualizações baseadas em arquivos e revisão visual em páginas públicas que não exigem login.
• Use o uso do computador apenas para verificação restrita de GUI quando o projeto for um aplicativo de desktop, fluxo de simulador, planilha, documento, apresentação ou outra superfície que não possa ser verificada por meio de ferramentas normais de shell/navegador.
• Use as worktrees do aplicativo Codex para trabalho de preparação de lançamento paralelo ou exploratório isolado, promovendo apenas os arquivos pretendidos para o fluxo de publicação.
• Use o suporte nativo do Git para revisão, staging, commit, push e PR quando disponível, mas ainda inspecione o diff e mantenha a árvore de trabalho livre de estado local não relacionado.
• Use automações apenas para verificações recorrentes de saúde de lançamento, relatórios de manutenção agendados ou monitoramento de acompanhamento; não transforme decisões de publicação únicas em trabalho de fundo recorrente.
• Use subagentes nativos apenas quando a política do usuário ou host permitir delegação paralela, e divida linhas independentes como auditoria de risco, revisão de documentação e verificação sem sobreposição de propriedade de arquivos.

Resultado Padrão

Ao final desta habilidade, o repositório deve ter:

• um README que explique claramente o problema, por que foi construído, o que faz e como usá-lo
• um diagrama ou ativo visual opcional vinculado ao projeto quando melhorar materialmente a orientação de um novo leitor
• uma descrição pública limpa e tópicos sugeridos do GitHub
• endurecimento básico para configuração, erros, arquivos ignorados e padrões voltados ao usuário
• testes ou verificações rápidas que comprovem o caminho principal e pelo menos um caso de borda ou falha
• uma licença e configuração de exemplo, quando necessário
• um artefato zip limpo criado a partir do código commitado
• ou um repositório público do GitHub no perfil pessoal do usuário ou um bloqueador exato explicando por que a publicação deve esperar

Estratégia de Lançamento

Escolha a via mais segura antes de editar:

1. Reutilize o repositório existente quando seu histórico do git, conjunto de arquivos e nomenclatura já forem seguros para expor.
2. Crie um repositório de exportação público limpo quando o projeto ativo for bom, mas o repositório existente tiver histórico de rascunho, notas privadas, detritos experimentais ou segredos no histórico.

Regras:

• Para projetos sandbox, prefira um repositório público irmão sob ~/.codex/workspaces/default/repos/<slug>-public quando o histórico público for questionável.
• Preserve a proveniência em uma nota curta, mas não vaze caminhos privados, nomes de projetos internos ou detalhes pessoais da máquina.
• Se a reescrita de histórico fosse necessária para tornar o repositório atual seguro, prefira uma exportação pública limpa, a menos que o usuário queira explicitamente que o histórico seja preservado.
• Não publique nada até que o repositório seja compreensível para um estranho a partir de um clone limpo.

Fluxo de Trabalho

1. Pré-verificação

1. Inspecione o repositório alvo, remotos, status do git, sistema de build, comandos de teste e todos os AGENTS.md no escopo.

2. Leia references/public-release-checklist.md.

3. Leia references/readme-template.md se o README precisar ser criado ou reescrito.

4. Determine se deve endurecer no local ou criar um repositório de exportação público limpo.

5. Derive o nome público provável, descrição de uma linha, fluxo de instalação e público-alvo do próprio repositório. Pergunte apenas se esses itens forem verdadeiramente ambíguos.

6. Defina o destino de publicação padrão para o GitHub pessoal do usuário com visibilidade pública quando a solicitação for construir em público.

7. Verifique quais capacidades nativas do Codex estão disponíveis no ambiente atual e, em seguida, escolha o caminho útil mais leve: shell local para trabalho de repositório determinístico, pesquisa na web para fatos externos atuais, navegador/uso do computador para verificação de UI, geração de imagens para visuais úteis e worktrees/subagentes apenas quando melhorarem a produtividade com segurança.

8. Pergunte pela faísca. Antes de escrever qualquer coisa, leia o código profundamente o suficiente para formar três hipóteses plausíveis sobre por que isso foi construído. Em seguida, pergunte ao usuário — apresente seus três melhores palpites como opções, mais um campo de texto livre para algo totalmente diferente:

   Qual foi o momento que fez você construir isso?

   1. [Sua primeira hipótese, extraída do código]
   2. [Sua segunda hipótese]
   3. [Sua terceira hipótese]
   4. Outra coisa — conte-me com suas próprias palavras

   Este padrão se aplica a toda chamada AskUserQuestion nesta habilidade: sempre proponha três opções concretas com base no que você já leu e, em seguida, deixe espaço para o usuário substituir. É mais rápido do que perguntas abertas, e suas hipóteses geralmente revelam enquadramentos que o usuário não considerou.

   Trate a resposta como contexto, não como verdade absoluta. O usuário conhece sua própria motivação, mas pode subestimar o interesse técnico, perder o que é realmente atraente no design ou enquadrá-lo de forma muito restrita. Seu trabalho é ler o código e encontrar o que vale genuinamente a pena ser discutido e, em seguida, usar a resposta deles como uma lente. O código é a fonte primária. A resposta deles é uma dica.

2. Auditar Risco Público

Inspecione o repositório em busca de qualquer coisa que não deva se tornar pública:

• segredos, arquivos .env, tokens, chaves de API, credenciais privadas ou histórico de shell copiado
• URLs internos, e-mails pessoais, caminhos absolutos locais, instruções específicas da máquina ou capturas de tela privadas
• conjuntos de dados privados, ativos de fornecedores ou arquivos de amostra que não podem ser redistribuídos
• caches, logs, bancos de dados gerados, saída de depuração e artefatos locais
• histórico de commit de rascunho que conta a história errada ou expõe contexto privado

Orientação:

• Use inspeção local rápida primeiro: rg, git status, git log, git ls-files e leituras de arquivo direcionadas.
• Se o risco estiver na árvore de trabalho, limpe-o.
• Se o risco estiver apenas no histórico, prefira um repositório de exportação limpo em vez de cirurgia de histórico arriscada.

3. Endurecer o Repositório

Faça a menor passagem crível que torne o projeto utilizável por outras pessoas:

• torne as etapas de instalação e execução determinísticas
• adicione ou aperte env.example, configuração de amostra e regras de ignorar, onde necessário
• melhore o ponto de entrada principal para que os erros sejam legíveis e os padrões sejam sensatos
• remova a desordem experimental morta que confunde os usuários de primeira viagem
• adicione ou melhore os testes para que o caminho principal seja coberto, mais pelo menos um caso de falha ou borda
• combine a prova com a forma do produto:
  • CLIs: ajuda de comando mais um teste de fumaça de comando real
  • bibliotecas: testes de unidade em torno da API pública
  • aplicativos web: fumaça em nível de navegador ou solicitação no fluxo principal
  • APIs/serviços: prova de requisição-resposta mais verificações de tratamento de erros
• adicione CI leve apenas quando o repositório já tiver um comando direto que vale a pena automatizar
• defina a licença padrão como MIT, a menos que o repositório ou o usuário aponte claramente para outro lugar

Não transforme isso em uma grande reescrita. "Pronto para o público" significa polido o suficiente para ser compartilhado honestamente, não reconstruído do zero.

4. Escrever Documentação Pública

Crie ou reescreva a documentação voltada ao público para que um estranho possa se orientar rapidamente:

• use references/readme-template.md para a estrutura do README
• explique o problema primeiro, depois por que este repositório existe, depois como executá-lo
• inclua um caminho de início rápido concreto que funcione a partir de um clone limpo
• documente o comando de teste e quaisquer dependências locais necessárias
• seja explícito sobre limitações atuais, suposições de plataforma ou arestas
• inclua uma nota curta de construção em público que explique a origem do projeto sem compartilhar demais o contexto interno
• inclua um mapa visual do repositório ou diagrama de arquitetura quando ajudar um novo leitor a entender o layout do arquivo, fluxo de dados ou fluxo de trabalho do usuário. Prefira Mermaid ou diagramas nativos do repositório para rótulos exatos; use geração de imagens nativa para ilustrações polidas em modo escuro, banners ou visuais de suporte.
• prepare:
  • uma descrição de uma linha do GitHub
  • uma lista curta de tópicos
  • notas de lançamento opcionais se o usuário quiser um lançamento inicial

Gere o banner ASCII. Todo README recebe um banner figlet no topo, acima de tudo. Use a fonte rectangles — sem caracteres inclinados. Execute:

figlet -f rectangles -w 200 "<texto do banner>"

Regras do texto do banner:

• Use o nome de exibição do projeto, não o slug do repositório
• Substitua quaisquer hífens por espaços (build-in-public → build in public)
• Mantenha tudo em minúsculas (Mock Pop → mock pop)
• Se o nome de exibição diferir do slug do repositório (por exemplo, repositório superwhisperer-lab, nome de exibição superwhisper lab), use o nome de exibição

Envolva a saída em um bloco de código com cerca. Se o figlet não estiver instalado: brew install figlet. Esta é a primeira coisa que alguém vê — sinaliza que o projeto tem uma identidade real.

Gere e posicione visuais do README. Quando uma imagem gerada pertencer ao README, trate-a como um artefato de projeto commitado, não como uma visualização temporária:

1. Decida o trabalho e o posicionamento da imagem antes de gerá-la:

   • visão geral do repositório, mapa de arquitetura ou visual herói: coloque-o perto do topo do README.md, imediatamente após o título e resumo de uma linha ou após o parágrafo de abertura curto, se isso soar melhor
   • captura de tela de recurso ou imagem de fluxo de trabalho: coloque-o na seção que explica, antes da prosa detalhada ou exemplo que suporta
   • imagem suplementar: coloque-a mais abaixo no README ou omita-a se não esclarecer nada

2. Gere a imagem com a geração de imagem nativa do Codex quando disponível, ou use saída Mermaid/SVG/nativa do repositório quando texto exato ou estrutura determinística for mais importante.

3. Inspecione o resultado quanto à legibilidade, rótulos distorcidos, informações privadas e se realmente esclarece o projeto.

4. Copie a imagem final selecionada para o repositório, geralmente em assets/<nome-descritivo>.<ext> ou docs/assets/<nome-descritivo>.<ext>. Não deixe um ativo referenciado no README apenas em um diretório de imagens geradas, downloads, temp ou cache local.

5. Insira a imagem no README.md com um caminho relativo e texto alternativo significativo:

   ![Diagrama de estrutura do repositório em modo escuro](assets/repo-structure-dark.png)
   

6. Faça commit da imagem e da atualização do README juntos para que o caminho seja válido para clones, forks, renderização do GitHub e zips de lançamento.

7. Se o visual for regenerado, use um nome de arquivo estável quando o README deve sempre mostrar a imagem mais recente, ou nomes de arquivo versionados quando preservar saídas anteriores for importante. Mantenha o prompt de geração, diagrama de origem ou script no repositório quando a repetibilidade for importante.

Construa a narrativa a partir do código, informada pelo usuário. A resposta da faísca do usuário é contexto — use-a para entender a intenção, não para escrever a história deles literalmente. A narrativa real vem da leitura atenta do código: qual problema o design realmente resolve, qual é a decisão não óbvia, o que um desenvolvedor colega acharia interessante ou digno de roubar?

Seu trabalho como narrador:

• encontre a coisa no código que é realmente interessante — a restrição que moldou o design, a abordagem que é diferente da solução óbvia, o trade-off que foi feito deliberadamente
• enquadre o problema no nível certo de especificidade: concreto o suficiente para que alguém que teve a mesma frustração o reconheça, geral o suficiente para que não seja apenas sobre a máquina exata do usuário
• dê a ele uma voz — não hype, não texto de marketing, mas o tom claro e ligeiramente animado de um desenvolvedor que realmente resolveu algo irritante e quer lhe contar como

Se a explicação do usuário for superficial ("Eu só precisava que funcionasse"), mergulhe no código e encontre a história real você mesmo. Se a explicação deles for tecnicamente mais rica do que o código justifica, recue-a. O README deve ser honesto sobre o que o projeto é — uma ferramenta pequena, útil e bem feita — não superdimensionado.

O tom é: "Aqui está um problema real, aqui está o que eu construí, aqui está o que é interessante sobre como funciona." Ferramentas pequenas podem ter boas histórias. Não as achate, mas também não as infle.

Evite proliferação de documentação. Um README forte, uma licença e os arquivos mínimos de suporte são melhores do que uma pilha de documentos cerimoniais.

5. Verificar e Empacotar

Execute a verificação mais forte que o repositório pode suportar razoavelmente:

1. Execute os comandos relevantes de instalação, build, lint, teste e fumaça.
2. Verifique as instruções de início rápido em relação ao código real.
3. Se prático, simule um caminho de clone limpo em vez de confiar no estado atual da máquina.
4. Para superfícies web ou visuais, use o navegador no aplicativo quando disponível e capture o resultado da verificação no relatório.
5. Para superfícies apenas de GUI, use o uso do computador restritamente e registre o que foi verificado.
6. Crie o artefato zip público a partir do código commitado:

bash "$(dirname "$0")/scripts/create_release_zip.sh" <caminho-do-repositorio>
# Ou a partir de uma habilidade instalada:
#   bash ~/.claude/skills/build-in-public/scripts/create_release_zip.sh <caminho-do-repositorio>   # Claude Code
#   bash ~/.codex/skills/build-in-public/scripts/create_release_zip.sh <caminho-do-repositorio>    # Codex

O auxiliar escreve o zip em ~/.codex/workspaces/default/repos/ com um nome baseado no slug e carimbo de data/hora. Se o script não existir, crie um que:

• crie um diretório temporário
• clone o repositório com git clone --depth 1
• remova quaisquer referências .git
• crie um zip limpo
• limpe o diretório temporário

Reporte ao usuário o caminho do zip criado.

6. Publicar no GitHub

Crie um repositório público do GitHub e envie o código:

1. Crie um novo repositório no GitHub usando o perfil pessoal do usuário.
2. Use um slug limpo (sem hífens extras, sem prefixo -public no nome real) a menos que o repositório de exportação exista.
3. Use a descrição de uma linha preparada na etapa de documentação.
4. Não adicione gitignore, licença ou README — eles vêm do repositório.
5. Defina a visibilidade como pública.
6. Envie o repositório existente:

git remote add origin <url>
git push -u origin main

7. Atualize os tópicos do GitHub com a lista preparada.
8. Se o usuário quiser um lançamento inicial, crie um lançamento do GitHub a partir do zip criado.

Se o push falhar por erro de autenticação, permissão ou rede, pare e informe o usuário exatamente o que precisa ser corrigido. Não tente contornar problemas de autenticação.

7. Relatório de Conclusão

Forneça um relatório final curto ao usuário:

• URL do repositório (se publicado) ou bloqueador exato
• o que foi auditado e limpo
• estrutura do README e quaisquer visuais adicionados
• cobertura de teste
• caminho do artefato zip
• tópicos do GitHub definidos
• etapa de acompanhamento sugerida, se houver

Perguntas ao Usuário

Toda pergunta deve oferecer três opções concretas extraídas do trabalho de análise que você já fez, mais um campo de texto livre. Sem perguntas abertas sem opções.

• Corrija: "Que licença devo usar?" (mau)
• Melhor: "A licença MIT funciona para este projeto, ou você prefere Apache 2.0, GPL-3.0 ou outra?" (bom)

Tratamento de Erros

Quando uma etapa falhar, pare e relate exatamente o que falhou e por quê. Não continue para a próxima etapa. Não tente contornar silenciosamente falhas de push, autenticação, ferramentas ausentes ou erros de rede.

Se um script ou comando de referência não existir, crie uma versão funcional mínima ou relate a lacuna. Não a ignore.

Se o usuário interromper ou alterar o comando no meio do fluxo de trabalho, respeite a nova direção e atualize o plano de acordo.