Skip to content

_BOOTSTRAP.md

Latest commit

 

History

History
379 lines (299 loc) · 15.2 KB

_BOOTSTRAP.md

File metadata and controls

379 lines (299 loc) · 15.2 KB

🚀 BOOTSTRAP — LLM Project Mapper

Para Claude Code executar com multi-agents.

Wesley criou pasta vazia /Users/wesleysimplicio/Projetos/novos/llm-project-mapper/. Sua missão: popular com starter completo + gerar apresentação PDF/PPT.

🎯 Mission

Criar template de repositório AI-friendly que Wesley possa cp -R em qualquer projeto novo. Tudo neutro/genérico (sem stack específica) com placeholders <STACK>, <PRODUCT_NAME>, etc.

Plus: apresentação visual sobre "Como ser AI Agent Specialist" baseada nos conceitos abaixo.

📁 File tree completo (criar TUDO)

llm-project-mapper/
├── README.md                          # explica o starter pack
├── AGENTS.md                          # instruction file Codex/Claude Code
├── CLAUDE.md                          # symlink ou cópia de AGENTS.md
├── .gitignore
│
├── .github/
│   ├── copilot-instructions.md        # instruction file Copilot
│   ├── copilot/
│   │   ├── tdd.agent.md               # custom agent: TDD specialist
│   │   ├── reviewer.agent.md          # custom agent: code review
│   │   └── architect.agent.md         # custom agent: arquitetura
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── ISSUE_TEMPLATE/
│   │   ├── feature.md
│   │   └── bug.md
│   └── workflows/
│       ├── ci.yml                     # lint + unit + e2e
│       └── dod.yml                    # gate Definition of Done
│
├── .specs/
│   ├── README.md                      # como navegar .specs
│   │
│   ├── product/
│   │   ├── VISION.md                  # 1 página, por que existe
│   │   ├── DOMAIN.md                  # entidades, glossário
│   │   └── PERSONAS.md                # quem usa
│   │
│   ├── architecture/
│   │   ├── DESIGN.md                  # diagrama Mermaid + boundaries
│   │   ├── PATTERNS.md                # como escrever código aqui
│   │   ├── ADR-template.md            # template ADR
│   │   └── ADR-001-example.md         # exemplo preenchido
│   │
│   ├── workflow/
│   │   ├── WORKFLOW.md                # branch, PR, deploy
│   │   ├── CONTRIBUTING.md            # como adicionar feature
│   │   └── RELEASE.md                 # processo de release
│   │
│   └── sprints/
│       ├── BACKLOG.md                 # tudo que falta
│       ├── task-template.md           # template task
│       └── sprint-01/
│           ├── SPRINT.md              # exemplo sprint
│           └── 01-example.task.md     # exemplo task preenchida
│
├── .skills/
│   ├── README.md                      # como criar/usar skills
│   ├── _template/
│   │   └── SKILL.md
│   ├── playwright-e2e/
│   │   └── SKILL.md                   # skill prontinha
│   └── conventional-commits/
│       └── SKILL.md                   # skill prontinha
│
├── .claude/
│   ├── settings.json
│   └── hooks/
│       ├── post-edit.sh               # lint+format auto pós-edit (bash)
│       ├── post-edit.ps1              # idem em PowerShell (Windows nativo)
│       ├── pre-commit.sh              # bloqueia commit vermelho (bash)
│       └── pre-commit.ps1             # idem em PowerShell (Windows nativo)
│
├── .codex/
│   └── config.toml                    # sandbox + approval + history
│
├── playwright.config.ts               # com trace/screenshot/video
│
└── presentation/
    ├── slides.md                      # source Marp
    ├── ai-agent-specialist.pdf        # output PDF
    └── ai-agent-specialist.pptx       # output PPTX

📝 Conteúdo de cada arquivo

README.md (raiz)

Explicar: o que é o starter pack, como usar (cp -R em projeto novo), como customizar <PLACEHOLDERS>, ordem de leitura sugerida pra humano.

AGENTS.md (raiz) — ⭐ ARQUIVO MAIS IMPORTANTE

Instruction file mestre. Sections:

  • Stack (placeholder <STACK>)
  • Comandos importantes (npm run dev, npm test, npm run lint)
  • Workflow loop OBRIGATÓRIO (ler task → planejar → editar → lint → unit → e2e → fix loop → commit)
  • Definition of Done com checklist
  • Padrões de código (pointer pra .specs/architecture/PATTERNS.md)
  • Onde encontrar contexto (.specs/product/, .specs/architecture/)
  • Proibido: pular testes, mockar pra fazer passar, commit com vermelho, ignorar ADR
  • Skills disponíveis: lista skills em .skills/
  • Comandos especiais: como criar nova ADR, como abrir PR

CLAUDE.md

Cópia de AGENTS.md ou nota explicando "ler AGENTS.md".

.github/copilot-instructions.md

Espelho do AGENTS.md adaptado pra Copilot (mesmo conteúdo, ajusta tom). Foco em Agent Mode workflow.

.agents/ralph-loop.agent.md

Custom agent executor autônomo padrão (Ralph Loop). Roda read → plan → execute → lint → unit → e2e (Playwright com evidência) → fix → repeat até DoD verde. Frontmatter:

---
name: Ralph Loop
description: Executor autônomo em loop contínuo até DoD verde, com Playwright + evidência obrigatória em toda task.
tools: [edit, terminal, search]
---

.agents/tdd.agent.md

Custom agent TDD-first com frontmatter:

---
name: TDD Specialist
description: Escreve teste falhando antes do código. Loop red-green-refactor.
tools: [edit, terminal, search]
---

.agents/reviewer.agent.md

Custom agent code review (sem editar, só comenta).

.agents/architect.agent.md

Custom agent que só desenha arquitetura e cria ADRs, não escreve código de produção.

Espelho em .github/copilot/agents/<nome>.agent.md para o GitHub Copilot Workspace. .agents/ é canônico (padrão AGENTS.md ecosystem); o mirror em .github/copilot/agents/ é para Copilot Coding Agent que lê estritamente desse caminho.

.github/workflows/ci.yml

GitHub Actions: matrix de Node versions, npm install, lint, test --coverage, playwright install + test, upload artifacts (playwright-report, coverage).

.github/workflows/dod.yml

Gate de PR: roda DoD checklist do AGENTS.md. Falha se coverage < 80%, se Playwright tem evidence faltando, se commit não é convencional.

.github/PULL_REQUEST_TEMPLATE.md

Checklist DoD + link pra task.md + screenshots/evidências.

.github/ISSUE_TEMPLATE/feature.md

Template feature seguindo formato task.md.

.github/ISSUE_TEMPLATE/bug.md

Template bug com reprodução, ambiente, evidência.

.specs/README.md

Mapa: por onde navegar. Ordem: VISION → DOMAIN → DESIGN → ADRs → SPRINT atual → tasks.

.specs/product/VISION.md

1 página template:

  • Problema que resolve
  • Quem usa (link PERSONAS)
  • Diferencial
  • Métricas de sucesso
  • Não-objetivos

.specs/product/DOMAIN.md

Glossário + entidades de negócio. Tabela de termos. Diagrama de entidades simples em Mermaid.

.specs/product/PERSONAS.md

2-3 personas com objetivos, frustrações, contexto de uso.

.specs/architecture/DESIGN.md

Visão geral. Mermaid graph LR ou C4. Boundaries explicadas. Stack overview. Decisões principais (links pra ADRs).

.specs/architecture/PATTERNS.md

  • Naming (variáveis, files, branches)
  • Estrutura de pastas
  • Como criar endpoint novo
  • Como criar componente novo
  • Como criar teste
  • Tratamento de erro
  • Logging
  • Validação

.specs/architecture/ADR-template.md

Template ADR: Status, Contexto, Decisão, Consequências (+ e -), Alternativas consideradas.

.specs/architecture/ADR-001-example.md

Exemplo preenchido fictício (ex: "ADR-001: Usar TypeScript em vez de JavaScript").

.specs/workflow/WORKFLOW.md

  • Branch strategy (trunk-based / git-flow)
  • PR rules
  • Code review protocol
  • Deploy pipeline
  • Hotfix process

.specs/workflow/CONTRIBUTING.md

Step-by-step pra adicionar feature: criar task.md → branch → implementa → PR → review → merge.

.specs/workflow/RELEASE.md

Como fazer release: changelog, version bump (semver), tag, deploy, rollback.

.specs/sprints/BACKLOG.md

Lista priorizada. Formato: tabela com [#, título, prioridade, sprint alvo, status].

.specs/sprints/task-template.md

Template completo:

  • Contexto
  • Acceptance Criteria (testáveis, checkboxes)
  • Out of scope
  • Test plan (unit + integration + e2e)
  • Definition of Done
  • Pegadinhas conhecidas
  • Links

.specs/sprints/sprint-01/SPRINT.md

Exemplo: objetivo, deliverables, riscos, dependências, dates.

.specs/sprints/sprint-01/01-example.task.md

Exemplo task fictícia preenchida (ex: "Auth login com email+senha").

.skills/README.md

Explicação skills: o que são, quando criar, como triggar (explicit $skill ou implicit via description), boas práticas.

.skills/_template/SKILL.md

Template com frontmatter (name, description) + sections (Trigger, Steps, Padrões, DoD).

.skills/playwright-e2e/SKILL.md

Skill pronta: como escrever teste Playwright nesse projeto (config, fixtures, page objects, evidências).

.skills/conventional-commits/SKILL.md

Skill pronta: regras de commit (feat:, fix:, chore:, etc), exemplos, breaking changes.

.claude/settings.json

Config Claude Code: cleanupPeriodDays alto, hooks habilitados, permissions sensatas.

.claude/hooks/post-edit.sh + .claude/hooks/post-edit.ps1

Bash + PowerShell sibling. Rodam prettier+eslint --fix em files .ts/.tsx/.js/.jsx editados. Mesma lógica, melhor disponibilidade cross-platform (macOS/Linux/Git Bash usam .sh; Windows nativo PowerShell usa .ps1).

.claude/hooks/pre-commit.sh + .claude/hooks/pre-commit.ps1

Bash + PowerShell sibling. Rodam npm test --silent, bloqueiam commit se vermelho.

.codex/config.toml

Sandbox workspace-write, approval on-request, history ilimitado, model gpt-5.3-codex (placeholder).

playwright.config.ts

Config completa com trace='on', screenshot on-failure, video on-failure, reporter html+json+junit, outputDir test-results.

.gitignore

Padrão Node/TS + .env + test-results/ + playwright-report/ + coverage/ + .DS_Store + .codex local + .claude/sessions cache.

🎤 presentation/ — Apresentação visual

Tópico: "Como virar AI Agent Specialist e entregar releases por dia"

Stack sugerida: Marp (markdown → PDF + PPTX, simples).

npm i -g @marp-team/marp-cli
marp slides.md --pdf -o ai-agent-specialist.pdf
marp slides.md --pptx -o ai-agent-specialist.pptx

Estrutura de slides (16-22 slides):

  1. Capa — "AI Agent Specialist — Releases Diárias com Agents"
  2. O problema — Dev solo lento, projetos morrem antes de terminar
  3. A virada — Agents + estrutura = velocidade Anthropic-tier
  4. Mental model — Tu = arquiteto/PM. Agent = executor. Spec = contrato.
  5. O loop universal — diagrama (ler → planejar → editar → testar → corrigir → próximo)
  6. Stack de instruction files — AGENTS.md, CLAUDE.md, copilot-instructions.md
  7. Anatomia do AGENTS.md — sections obrigatórias
  8. Specs como código — VISION, DOMAIN, DESIGN, ADRs
  9. ADRs — memória de longo prazo — exemplo + por que importa
  10. Tasks atômicas — task-template breakdown
  11. DoD com gate automático — CI yml diagram
  12. Skills — capacidades reutilizáveis — exemplo SKILL.md
  13. Hooks — automação no ciclo — post-edit, pre-commit
  14. Custom agents — TDD agent, reviewer agent
  15. Worktrees paralelos — 3-5 agents simultâneos
  16. Playwright + evidências — config + flow
  17. Fluxo diário — manhã/tarde/noite breakdown
  18. Métricas que importam — cycle time, PR size, reverts
  19. Hábitos de elite — top 10
  20. Roadmap pra Specialist — semana 1-2, mês 2, mês 3
  21. Pitfalls comuns — drift composto, falsos verdes, context drift
  22. Próximo passo — clonar starter, primeiro projeto

Design: tema dark profissional (Marp gaia ou custom). Diagramas Mermaid embedados quando fizer sentido. Bullets curtos. Code blocks com sintaxe colorida.

🤖 Squad de execução (multi-agents)

Aloca @gerente (Opus) como orchestrator. Spawn em paralelo onde não tem dependência:

Agent Responsabilidade Files
@docs-writer Produto/humano README.md, .specs/product/*
@architect Arquitetura/decisões DESIGN.md, PATTERNS.md, ADR-template.md, ADR-001-example.md
@workflow-writer Processo WORKFLOW.md, CONTRIBUTING.md, RELEASE.md
@sprints-writer Tasks/sprints BACKLOG.md, task-template.md, sprint-01/*
@skills-author Skills .skills/README.md + 3 SKILL.md
@config-writer AI configs AGENTS.md, CLAUDE.md, copilot-instructions.md, copilot/.agent.md, .claude/, .codex/*
@ci-engineer CI/CD/test .github/workflows/*, playwright.config.ts, hooks .sh, PR/issue templates
@presentation-designer Slides presentation/slides.md + export pdf+pptx

Ordem:

  1. Paralelo: docs-writer, architect, workflow-writer, sprints-writer, skills-author, ci-engineer
  2. Depois (depende dos acima): config-writer (AGENTS.md referencia tudo)
  3. Depois: presentation-designer (consolida em slides)

@gerente valida cada handoff: arquivo existe? conteúdo bate com o brief? placeholders consistentes? Se não → reenfila pro agent.

✅ Definition of Done desse bootstrap

  • Todos files do tree existem
  • Nenhum file vazio (mínimo 30 linhas significativas)
  • Placeholders consistentes: <PRODUCT_NAME>, <STACK>, <TEAM>, <DOMAIN>
  • Mermaid diagrams renderizam (testar com npx @mermaid-js/mermaid-cli ou preview VS Code)
  • Hooks .sh têm chmod +x
  • .gitignore inclui artifacts certos
  • PDF e PPTX gerados em presentation/
  • PDF abre, slides legíveis
  • Wesley consegue cp -R llm-project-mapper/ ../novo-projeto/ e ter base AI-friendly
  • README explica próximos passos pós-clone

🎬 Comando inicial pro Claude Code

Wesley vai abrir Claude Code dentro de /Users/wesleysimplicio/Projetos/novos/llm-project-mapper/ e rodar:

Lê _BOOTSTRAP.md e executa. Use multi-agents (@gerente orquestra, spawn
@docs-writer, @architect, @workflow-writer, @sprints-writer, @skills-author,
@config-writer, @ci-engineer, @presentation-designer em paralelo onde possível).

Stack neutra com placeholders <STACK>/<PRODUCT_NAME>/<TEAM>/<DOMAIN>.

Apresentação Marp em presentation/, gera PDF + PPTX (instala marp-cli se
precisar: npm i -g @marp-team/marp-cli).

Quando terminar, roda check final:
- find . -type f | wc -l (deve ser 35+)
- ls presentation/*.pdf presentation/*.pptx
- cat AGENTS.md | wc -l (deve ser 80+)

Reporta DoD do _BOOTSTRAP.md no fim.

💡 Notas de qualidade

  • Todo .md deve ter cabeçalho com # Título claro
  • Code blocks com linguagem (bash, typescript, yaml, mermaid)
  • Bullets curtos (1-2 linhas)
  • Exemplos concretos, não vago
  • Caveman tone OK em comments, mas docs públicos (README) podem ser polidos
  • Português pt-BR (Wesley é brasileiro)
  • Nada de emoji no código fonte; pode usar em README/slides

FIM DO BOOTSTRAP. Boa execução, time. 🚀