Como criar um portfólio com Claude Code e Astro: implementação prática

Comece pela função do portfólio

Um site de portfólio não é apenas uma galeria de imagens. Ele deve ajudar recrutadores, clientes, parceiros e organizadores de eventos a decidir rapidamente se você resolve o problema deles. A primeira versão precisa mostrar quem você é, que tipo de trabalho entrega, quais provas existem e como iniciar uma conversa.

Neste guia, Claude Code é usado como parceiro de desenvolvimento local. A documentação oficial do Claude Code explica que ele pode ler o projeto, editar arquivos, executar comandos e trabalhar com ferramentas de desenvolvimento. Isso permite criar uma versão pequena, revisar o diff e confirmar o build.

Vamos usar Astro com CSS simples. Para um portfólio pessoal, HTML estático costuma ser suficiente: carrega rápido, é barato de hospedar e reduz complexidade. A estrutura de projeto do Astro também é fácil de explicar ao Claude Code.

Se você ainda está começando, leia antes o guia interno Claude Code para iniciantes. Para o fluxo com Astro, veja também desenvolvimento Astro com Claude Code.

Escopo da primeira versão

O site terá uma página com Hero, About, Projects, Services e Contact. Não vamos adicionar CMS, login, animação pesada nem formulário com backend no começo. O objetivo é publicar algo claro e melhorar com base em feedback real.

flowchart TD
  A["Brief do portfólio"] --> B["src/data/profile.ts"]
  B --> C["src/pages/index.astro"]
  C --> D["src/styles/global.css"]
  D --> E["npm run build"]
  E --> F["Revisão antes da publicação"]

Separe dados e apresentação. src/data/profile.ts guarda perfil e projetos; index.astro renderiza a página. Essa divisão facilita pedir ao Claude Code mudanças menores, como “melhore apenas o texto dos projetos” ou “ajuste só o layout dos cards”.

my-portfolio/
  src/
    data/profile.ts
    pages/index.astro
    styles/global.css
  public/
    ogp.png
    projects/booking-site.webp

Imagens em public/ podem ser usadas como /projects/booking-site.webp. A referência de MDN para o elemento img reforça o uso de alt útil. Para imagens abaixo da primeira tela, a página de Lazy loading explica loading="lazy".

Prompt para usar com Claude Code

Um pedido amplo demais gera um site genérico. Defina público, arquivos, limites e critério de conclusão.

Quero criar um site de portfólio pessoal com Astro.
O público são recrutadores e pequenos clientes que precisam entender meu trabalho em menos de três minutos.

Requisitos:
- Uma página com Hero, About, Projects, Services e Contact
- Guardar perfil e projetos em src/data/profile.ts
- Implementar src/pages/index.astro e src/styles/global.css
- Não adicionar React nem biblioteca pesada de UI
- Todas as imagens precisam de alt
- Botões CTA devem ficar legíveis no mobile
- Terminar com npm run build

Antes de editar, resuma o plano de implementação e os arquivos que serão alterados.

Pedir o plano antes de editar impede mudanças grandes sem necessidade. Se Claude Code sugerir CMS, API ou pacote de animação, peça justificativa. Depois da implementação, use SEO com Claude Code para uma revisão separada.

Código inicial copiável

Para um projeto novo, crie a app Astro. Em um repositório existente, peça para Claude Code ler a estrutura antes.

npm create astro@latest my-portfolio
cd my-portfolio
npm run dev

Depois crie os dados. Evite descrições vagas como “sei React”. Fale de problema, papel, implementação e resultado.

// src/data/profile.ts
export const profile = {
  name: "Masa Tanaka",
  role: "Frontend engineer / consultor de adoção de Claude Code",
  location: "Tokyo, Japan",
  summary:
    "Crio sites rápidos e fáceis de manter com Astro, React, TypeScript e operações de conteúdo orientadas a melhoria contínua.",
  skills: ["Astro", "TypeScript", "React", "CSS", "SEO", "Content Ops"],
  links: {
    email: "masa@example.com",
    github: "https://github.com/example",
  },
} as const;

export const projects = [
  {
    title: "Melhoria do fluxo de reservas",
    description:
      "Reorganizei menu mobile, descrição de serviços e CTA de reserva para reduzir atrito antes do contato.",
    image: "/projects/booking-site.webp",
    alt: "Captura de site de reservas com cards de serviço e botão principal",
    tags: ["Astro", "SEO", "Responsive"],
    url: "https://example.com/booking",
  },
  {
    title: "Dashboard SaaS de tarefas",
    description:
      "Redesenhei cards, filtros de status e estados vazios para orientar usuários em teste.",
    image: "/projects/task-dashboard.webp",
    alt: "Captura de dashboard SaaS com cards de tarefas e filtros",
    tags: ["TypeScript", "UI Design", "Dashboard"],
    url: "https://example.com/dashboard",
  },
] as const;

A página Astro mínima fica assim. O contato usa email para manter a primeira versão simples.

---
import { profile, projects } from "../data/profile";
import "../styles/global.css";
---

<html lang="pt">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{profile.name} | Portfolio</title>
    <meta name="description" content={`${profile.role}: projetos, serviços e contato.`} />
    <meta property="og:title" content={`${profile.name} | Portfolio`} />
    <meta property="og:description" content={profile.summary} />
    <meta property="og:image" content="/ogp.png" />
  </head>
  <body>
    <main>
      <section class="hero" aria-labelledby="hero-title">
        <p class="eyebrow">{profile.location}</p>
        <h1 id="hero-title">{profile.name}</h1>
        <p class="lead">{profile.summary}</p>
        <div class="actions">
          <a class="button primary" href="#projects">Ver projetos</a>
          <a class="button secondary" href={`mailto:${profile.links.email}`}>Iniciar conversa</a>
        </div>
      </section>

      <section id="projects" class="section" aria-labelledby="projects-title">
        <h2 id="projects-title">Projects</h2>
        <div class="project-grid">
          {projects.map((project) => (
            <article class="project-card">
              <img src={project.image} alt={project.alt} width="960" height="540" loading="lazy" />
              <div class="project-body">
                <h3>{project.title}</h3>
                <p>{project.description}</p>
                <ul class="tag-list">
                  {project.tags.map((tag) => <li>{tag}</li>)}
                </ul>
                <a href={project.url} target="_blank" rel="noreferrer">Ler mais</a>
              </div>
            </article>
          ))}
        </div>
      </section>
    </main>
  </body>
</html>

CSS de base:

/* src/styles/global.css */
:root {
  --bg: #f7f3ec;
  --panel: #ffffff;
  --text: #1f2933;
  --muted: #5f6c7b;
  --accent: #0f766e;
  --line: #d8dee4;
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Inter, system-ui, sans-serif;
  background: var(--bg);
  color: var(--text);
  line-height: 1.75;
}

.hero,
.section {
  width: min(1120px, calc(100% - 32px));
  margin: 0 auto;
}

.hero {
  min-height: 82vh;
  display: grid;
  align-content: center;
}

.actions,
.tag-list {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  padding: 0;
  list-style: none;
}

.button {
  display: inline-flex;
  min-height: 44px;
  align-items: center;
  justify-content: center;
  padding: 0 18px;
  border: 1px solid var(--accent);
  border-radius: 6px;
  text-decoration: none;
  font-weight: 700;
}

.button.primary {
  background: var(--accent);
  color: white;
}

.project-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 24px;
}

.project-card {
  background: var(--panel);
  border: 1px solid var(--line);
  border-radius: 8px;
  overflow: hidden;
}

.project-card img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

@media (max-width: 640px) {
  .button {
    width: 100%;
  }
}

Casos reais de uso

O conteúdo muda conforme quem lê.

Caso	O que a pessoa quer validar	O que incluir
Emprego	Escopo técnico e responsabilidade	Stack, papel, demo, GitHub
Freelance	Se você resolve o problema dela	Serviços, exemplos, CTA por email
Palestras ou escrita	Autoridade no tema	Temas, artigos, bio curta
Registro de aprendizado	Progresso e reprodutibilidade	Notas, erros, demo, próximos passos

Para emprego, destaque sua responsabilidade real. Para freelance, crie entradas claras: auditoria de landing page, melhoria de performance, revisão de CTA ou revisão de fluxo com Claude Code. Para palestras, conecte tema, artigos e bio logo no começo.

ClaudeCodeLab usa a mesma lógica para monetização: conteúdo gratuito gera confiança, materiais baixáveis reduzem o primeiro passo e consultoria resolve problemas específicos. O CTA deve dizer que tipo de conversa faz sentido. A página de treinamento e consultoria é um bom exemplo.

SEO, acessibilidade e erros comuns

SEO para portfólio é clareza. Use termos que a audiência buscaria: “portfólio frontend”, “desenvolvedor Astro”, “consultoria Claude Code” ou um termo local de serviço. Coloque isso em title, description, h1 e projetos de modo natural.

Revise este portfólio Astro por SEO e acessibilidade.
Verifique title, description, h1/h2/h3, alt das imagens, links internos,
links externos, CTA e leitura no mobile.
Retorne apenas problemas, motivos e a menor correção útil.

Erros frequentes: construir demais antes de explicar quem você é; escrever prova vaga como “sei React”; publicar sem npm run build, sem checar links, OGP e mobile; enviar para IA nomes de clientes, URLs internas ou valores .env. Use dados fictícios e capturas anonimizadas quando necessário.

Resultado testado e próximo passo

A decisão mais útil é separar dados em src/data/profile.ts. Na prática, isso permite pedir mudanças de texto sem misturar layout, e mudanças visuais sem tocar o conteúdo. A revisão do diff pelo Claude Code fica menor e mais confiável.

Antes de publicar, execute npm run build e revise Hero, Projects e Contact em largura mobile. Depois, trate o portfólio como produto pequeno: atualize screenshots, melhore descrições fracas, teste CTA mais específico e conecte artigos internos relevantes.