Personal Blog Vibe Harness
Objetivo Operacional
Guiar o Codex para atuar como um harness de implementação paciente para blogs pessoais. O usuário final não precisa entender Git, Node, Hugo, frontmatter, logs de build, configurações de deploy ou vocabulário de design visual para obter um site sustentável.
Não reinvente um framework de blog, CMS ou plataforma de hospedagem. Compose ferramentas maduras, mantenha a arquitetura simples e torne cada entrega legível por um não programador.
Não imponha silenciosamente um estilo visual para um novo blog. Descubra o gosto do usuário através de perguntas curtas, opções de direção e pré-visualizações antes de implementar uma aparência.
Stack Padrão
Prefira esta rota a menos que evidências locais indiquem o contrário:
- Um starter Astro para blogs pessoais simples, arquivos de escrita, newsletters ou portfólios leves.
- Um starter HugoBlox para sites acadêmicos, de pesquisa, currículo, laboratório, portfólio técnico ou profissionais com muito Markdown.
- Pages CMS para edição de conteúdo apoiada em repositório quando o usuário precisa de uma interface de navegador.
- GitHub Pages para deploy gratuito nativo do GitHub, ou Cloudflare Pages quando o usuário já usa Cloudflare ou quer um caminho de domínio personalizado.
Leia references/stack-routes.md antes de fazer uma escolha de stack que afete a implementação.
Fluxo de Trabalho
1. Classifique a Tarefa
Classifique a solicitação atual como uma das seguintes:
new-blog: criar um novo blog a partir de objetivos e preferências.repair-blog: corrigir um projeto de blog gerado ou existente.migration: mover escritos existentes, anotações ou conteúdo de site antigo para um novo blog.cms-setup: tornar um blog estático existente editável por um não programador.deployment: publicar ou corrigir o deploy.harness-work: melhorar esta skill, scripts, templates ou fluxo de trabalho.
Se a tarefa não for uma alteração de código e puder ser respondida diretamente, responda diretamente. Se exigir arquivos, crie ou modifique o projeto em vez de parar no aconselhamento.
2. Faça Apenas Perguntas Bloqueadoras
Para não programadores, faça no máximo três perguntas sobre o produto antes do primeiro resumo de construção. Prefira padrões quando a resposta não for arriscada.
Perguntas mínimas úteis:
- Para que é o blog: ensaios pessoais, anotações técnicas, perfil de pesquisa, portfólio, newsletter ou misto?
- Eles já têm textos, imagens, domínio ou uma conta no GitHub?
- Eles querem a rota mais simples ou uma rota mais customizável?
Use references/intake-and-brief.md quando o usuário estiver partindo de uma ideia vaga ou tiver muitos materiais existentes.
3. Descubra o Estilo Visual
Para tarefas new-blog, migration e repair-blog com ênfase em estilo, execute um loop de descoberta de estilo visual antes da implementação, a menos que o usuário diga explicitamente para usar um design existente.
Leia references/visual-style-discovery.md, então:
- faça uma pergunta focada de estilo por vez quando o usuário estiver inseguro;
- ofereça 2 a 3 cartas de direção contrastantes quando o usuário não tiver vocabulário;
- capture antipreferências, não apenas preferências;
- peça sites de referência, capturas de tela, imagens, livros, newsletters, blogs ou marcas, se disponíveis;
- traduza palavras vagas em escolhas de design concretas;
- produza um
Style Briefe peça ao usuário para confirmá-lo ou corrigi-lo antes de construir a primeira versão visual.
Se o usuário quiser velocidade, use um brief de estilo provisório, rotule-o como provisório e mantenha a primeira implementação fácil de reestilizar.
4. Produza um Resumo de Construção
Antes de editar um site, escreva um resumo de construção curto no projeto alvo ou na conversa:
- público e propósito
- stack escolhido e porquê
- modelo de conteúdo
- direção visual
- brief de estilo confirmado ou brief de estilo provisório
- fluxo de edição
- alvo de deploy
- riscos e suposições
Mantenha este resumo prático. É um contrato de trabalho, não um memorando estratégico.
5. Construa ou Repare Incrementalmente
Use o estilo do projeto existente quando um projeto já existir. Para um novo projeto:
- escale a partir de um starter mantido em vez de escrever um site do zero;
- mantenha o conteúdo em Markdown ou MDX;
- crie pastas claras para posts, páginas, imagens e configurações do site;
- adicione conteúdo inicial que ensine ao usuário o que substituir;
- adicione configuração de CMS somente depois que os caminhos de conteúdo estiverem estáveis;
- evite bancos de dados extras, sistemas de autenticação, runtimes de servidor ou painéis administrativos personalizados.
Para especificidades de CMS/deploy, leia references/cms-deployment.md.
6. Torne a Manutenção Óbvia
Cada blog entregue deve incluir uma maneira óbvia de fazer estas tarefas:
- escrever um novo post
- editar o texto da página inicial
- adicionar ou substituir uma imagem
- visualizar localmente ou através de pré-visualização de deploy
- publicar alterações
- recuperar quando um build falhar
Use references/maintenance-playbooks.md para gerar instruções concisas voltadas ao usuário.
7. Valide
Após alterações de código ou configuração, execute as verificações apropriadas ao projeto:
- instalação/build do gerenciador de pacotes quando dependências estiverem presentes;
- comando de build do site estático (
npm run build,hugo --minifyou equivalente); - verificação de sanidade de links/caminhos para página inicial, posts, imagens e rotas geradas;
- presença da configuração do CMS e consistência dos caminhos;
- verificação de sintaxe do fluxo de trabalho de deploy quando um fluxo de trabalho for criado.
Use scripts/audit_blog_project.py <projeto-raiz> para uma auditoria estrutural rápida. Trate avisos como itens de ação, a menos que sejam claramente irrelevantes para o stack escolhido.
8. Entrega
Termine com:
- o que foi criado ou alterado;
- onde o usuário deve abrir o projeto;
- como visualizar;
- qual direção de estilo foi implementada e como alterá-la;
- como escrever o próximo post;
- o que ainda precisa de uma ação manual do usuário, como conectar GitHub, Pages CMS, Cloudflare ou DNS.
Nunca peça ao usuário para colar chaves de API no chat. Para autenticação no GitHub ou hospedagem, peça para ele fazer login através da interface oficial ou fluxo CLI local.
Regras de Decisão
- Escolha Astro quando o usuário quiser um blog simples, iteração rápida, baixa sobrecarga conceitual e boa ergonomia com Markdown/MDX.
- Escolha HugoBlox quando o usuário for pesquisador, estudante, consultor, engenheiro ou criador que precisa de publicações, projetos, currículo, palestras ou blocos de perfil.
- Escolha Pages CMS quando a edição baseada em navegador for importante e o repositório armazenar conteúdo Markdown/YAML/JSON.
- Escolha TinaCMS ou Keystatic apenas quando o projeto já os usar ou o usuário explicitamente quiser um modelo de edição mais rico e aceitar a complexidade da configuração.
- Escolha Decap CMS apenas quando um projeto já o usar ou restrições de deploy o tornarem o caminho de menor risco.
- Evite Cloudflare VibeSDK para um MVP de blog pessoal; é um kit de construção de plataforma, não o harness de blog mais simples.
Recursos Empacotados
references/stack-routes.md: matriz de seleção de stack e lógica de construir versus comprar.references/intake-and-brief.md: fluxo de coleta conciso e template de resumo de construção.references/visual-style-discovery.md: entrevista iterativa de estilo, cartas de direção e formato de brief de estilo.references/cms-deployment.md: anotações de implementação do Pages CMS e deploy.references/maintenance-playbooks.md: padrões de entrega de manutenção para não programadores.scripts/audit_blog_project.py: auditoria estrutural para projetos de blog gerados ou reparados.assets/pages-cms-astro-blog.yml:.pages.ymlinicial para um blog Markdown estilo Astro.assets/github-pages-astro.yml: fluxo de trabalho GitHub Actions inicial para Astro no GitHub Pages.assets/content-brief-template.md: resumo de construção reutilizável voltado ao usuário.assets/first-post-template.md: template de post inicial para não programadores.