Skip to content

chore: bootstrap do toolkit de agents (.claude/agents + .claude/skills) - #4

Open
naroga wants to merge 1 commit into
buzzmonitor:masterfrom
naroga:chore/bootstrap-agent-toolkit
Open

chore: bootstrap do toolkit de agents (.claude/agents + .claude/skills)#4
naroga wants to merge 1 commit into
buzzmonitor:masterfrom
naroga:chore/bootstrap-agent-toolkit

Conversation

@naroga

@naroga naroga commented May 14, 2026

Copy link
Copy Markdown

Contexto

Este PR introduz o scaffolding mínimo de agents e skills locais (.claude/agents/ + .claude/skills/) para padronizar o fluxo de desenvolvimento assistido nesta gem. É o terceiro de uma trinca de PRs de bootstrap:

Branch ancorada em master (não empilhada sobre as outras três) para permitir review independente.

Mudanças

  • .claude/agents/backend-implementer.md — único agent scaffoldado. Esta gem é backend Ruby puro (sem frontend, sem DB, sem CI no master ainda, sem docs/), então os agents frontend-implementer, database-analyst, infrastructure e docs-guardian foram deliberadamente omitidos.
  • .claude/skills/create-story/ — cria stories locais em .claude/stories/<id>.md via entrevista dinâmica. Não usa GitHub Issues nem nenhum tracker remoto.
  • .claude/skills/implement-feature/ — orquestrador em ondas; sub-tasks vivem em .claude/stories/<parent>/sub-<n>.md com isolamento por arquivo.
  • .claude/skills/open-pull-request/ — abre PR em pt-BR contra master, push para a remote fork (naroga/gmail), sem labels nem reviewers automáticos.
  • .gitignore — adiciona .claude/stories/ (tracking local por desenvolvedor, nunca comitado).

Decisões

  • Idioma: toda prosa dos agents/skills em pt-BR. Identificadores, comandos e nomes de arquivo permanecem como no código.
  • Story tracking: arquivos locais em .claude/stories/ (no .gitignore). Sem dependência de GitHub Issues, Trello, Linear ou MCPs externos.
  • Sub-tasks: arquivos locais em .claude/stories/<parent>/sub-<n>.md.
  • MCPs: os MCPs configurados no ambiente (Apollo, Close, Gmail, Calendar, Drive, Sentry, Slack, Playwright) não são referenciados pelos agents — nenhum deles é relevante para o loop de dev de uma gem Ruby. Os agents usam só gh, git, rspec, rubocop.
  • Commits: formato convencional #<story-id> <type>(<scope>): <descrição>. Stage explícito por arquivo, nunca git add .. Sem assinatura de IA.

Dependências de outros PRs

Depende da PR #2 (chore/bootstrap-claude-config) mergear: o backend-implementer.md referencia CLAUDE.md como fonte de verdade das convenções do projeto. Enquanto a PR #2 não mergeia, esses pontos estão marcados explicitamente como TBD no agent, com fallback para gemspec + .rubocop.yml + README.md.

Não depende da PR #1 (quality-gates) nem da PR #3 (docs/) para funcionar, mas referencia ambas como TBDs onde aplicável (CI futuro, docs/ futuro).

Como testar

  • ls .claude/agents/ lista backend-implementer.md.
  • ls .claude/skills/ lista create-story/, implement-feature/, open-pull-request/.
  • git check-ignore -v .claude/stories/qualquer.md confirma que está ignorado pelo .gitignore.
  • Frontmatter YAML válido em todos os 4 arquivos .md adicionados.
  • bundle exec rspec segue passando (este PR não toca código de aplicação).
  • bundle exec rubocop -D segue limpo dentro da baseline (este PR não toca código de aplicação).

Notas de revisão

  • O agent referencia o caminho absoluto /Users/naroga/Projects/elife/buzzmonitor/gmail/.claude/agent-memory/backend-implementer/ para memória persistente. Esse caminho é específico da máquina do desenvolvedor que rodou o bootstrap — outros contribuidores que clonarem o repo vão ter caminhos diferentes. É aceitável aqui porque .claude/agent-memory/ também é per-developer e não fica comitada (não está no PR; e pode ser adicionada ao .gitignore futuramente se alguém criar essa pasta).
  • Nenhum agent de infraestrutura porque o master não tem GHA ainda (PR chore: bootstrap dos quality gates (CI + precommit + baseline de lint) #1 introduz). Quando a PR chore: bootstrap dos quality gates (CI + precommit + baseline de lint) #1 mergear, podemos rescaffoldar para adicionar um agent infrastructure separadamente.
Adiciona scaffolding mínimo para o fluxo de agents desta gem:

- .claude/agents/backend-implementer.md — agent para mexer em lib/gmail/
  e spec/gmail/, ciente de workers paralelos, com regras de commit
  explícito e proibição de fallbacks silenciosos.
- .claude/skills/create-story/ — cria stories locais em
  .claude/stories/<id>.md via entrevista dinâmica.
- .claude/skills/implement-feature/ — orquestra implementação em ondas,
  com sub-tasks isoladas por arquivo em .claude/stories/<parent>/sub-<n>.md.
- .claude/skills/open-pull-request/ — abre PR em pt-BR contra master,
  push pra remote fork (naroga/gmail), sem reviewers nem labels
  automáticos.
- .gitignore — exclui .claude/stories/ (tracking local por desenvolvedor,
  nunca comitado).

Sem agents de frontend, database, infra ou docs-guardian (a gem é
backend puro, sem DB, sem frontend, sem CI no master ainda, sem docs/).

Os agents referenciam CLAUDE.md como TBD até a PR gmailgem#2
(chore/bootstrap-claude-config) mergear.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant