Uma correção na origem
chega a todo projeto.

Um defeito num template, numa norma ou num hook aparece primeiro num projeto gerado. Corrigir lá conserta um projeto; corrigir o dono no Nerviz conserta todo projeto gerado dali em diante. Por isso o relato mais útil é aquele que o mantenedor consegue verificar.

O /report-issue abre a issue por você

Digite no projeto gerado, com uma descrição ou um arquivo de lições aprendidas. Ele escolhe o formulário de issue do próprio repositório, pede uma vez a evidência que falta, remove tudo que identifica o seu projeto, procura duplicatas abertas e só publica depois do seu sim.

# dentro do projeto gerado
› /report-issue <descrição do problema>
› /report-issue docs/lessons-learned/sonar-001.md

• Só você abreNada encadeia o /report-issue. Ele é só manual, então o modelo não publica por conta própria.
• Sem evidência, sem issueCada afirmação é conferida contra o código no HEAD antes de qualquer mudança. Uma afirmação sem arquivo, sem saída e sem como reproduzir só poderia ser fechada como needs evidence, então nem é escrita.
• O rastro, nunca o projetoO repositório é público e o seu projeto pode não ser. A issue cita chaves de regra do Sonar, contagens, caminhos dentro de .claude/, comandos e saída de hook. Nunca um caminho em src/, um pacote, uma classe, um trecho de código, a chave do projeto ou a URL do servidor.

Estar atrás da última release gera um aviso, não uma parada: a release nova pode já trazer a correção, e o /arch-adopt a traz para o projeto.

Quatro formulários, um por tipo de relato

Issues em branco estão desativadas. O /report-issue lê os mesmos arquivos de formulário que a web usa, então os dois produzem a mesma issue.

• bug_report.yml

  Bug report

  Título bug: Label bug

  Algo em .claude/ se comporta diferente do que o próprio arquivo diz.

  O que pede
  • Onde aconteceu: no Nerviz, num projeto gerado, ou nos dois
  • O componente e o ponto de entrada exato
  • O arquivo e a linha que prometem o comportamento, citados
  • A saída literal, os passos para reproduzir e a saída do /arch-doctor
  • Versões de java, git e claude, e o sistema operacional

  Aberto por /report-issue ou o formulário web

• feature_request.yml

  Feature request

  Título feat: Label enhancement

  Algo hoje é difícil, repetitivo ou errado em silêncio, e nenhum arquivo promete o contrário.

  O que pede
  • O problema, não a solução
  • Que tipo de arquivo deve carregar: norma, skill, agente, hook, seção do CLAUDE.md, servidor MCP ou docs
  • Como seria verificado
  • Os invariantes que respeita, e se os projetos gerados também precisam
  • Alternativas consideradas

  Aberto por /report-issue ou o formulário web

• new_blueprint.yml

  New blueprint

  Título blueprint: Label blueprint

  Uma arquitetura declarada como dado em .claude/blueprints/, sem mudar nenhuma skill, agente ou comando.

  O que pede
  • Id, nome legível e uma descrição de uma frase
  • when_to_choose e trade_offs honestos
  • build.layout, módulos e direção das dependências
  • packages.map e architecture_paths
  • O checklist de 6 regras do _schema.md

  Aberto por O formulário web

• sonar-lessons.yml

  Sonar lessons

  Título sonar-lessons: Label sonar-lessons

  Achados do SonarQube num projeto gerado, rastreados até a peça de .claude/ que os produziu.

  O que pede
  • A versão de origem, de .arch-provenance.json
  • Um retrato: o quality gate e só contagens
  • Achados por dono: chave da regra, contagem, dono em .claude/, origem
  • As mudanças propostas e a lição estrutural
  • Uma checagem de privacidade: nada que identifique o projeto analisado

  Aberto por /sonar-lessons, depois /report-issue

Abrir os formulários no GitHub →

Não é issue

• Uma vulnerabilidadeRelate em privado, como security advisory. Nunca como issue e nunca com /report-issue: os dois publicam.
• Uma dúvidaPergunte nas Discussions como algo funciona antes de abrir uma issue.
• Um design de que você discordaLeia .claude/decisions/ primeiro. O formulário de bug pede que você confirme que é um defeito, não uma decisão.

Código gerado não deve virar débito técnico

Tudo que o harness gera mira em código que funciona e tem qualidade, não em código que alguém paga depois. Quando o SonarQube acha uma issue, quase nunca é caso isolado: o código veio de um template, uma norma permitiu, ou nada em .claude/ dizia nada e o modelo decidiu sozinho. O /sonar-lessons acha esse dono, para a correção cair onde todo próximo projeto a recebe.

1. /sonarqube-setupColoca o scanner no build file da raiz, e um container local do SonarQube quando ainda não há servidor. Roda uma vez.
2. /sonar-lessonsRoda a análise e lê quality gate, bugs, vulnerabilidades, code smells, duplicação e cobertura pela Web API. Precisa de um servidor respondendo e de SONAR_TOKEN; nunca os configura.
3. sonar-NNN.mdA lição completa em docs/lessons-learned/, guardada no seu projeto: caminhos, linhas e trechos, e a correção no dono de cada grupo.
4. /report-issueVocê digita. Ele abre a lição no formulário Sonar lessons, sem nada do projeto.

# uma vez: scanner no build, um servidor, um token
› /sonarqube-setup

# depois de uma feature: analisar, rastrear, escrever a lição
› /sonar-lessons

# depois abrir onde a correção pertence
› /report-issue docs/lessons-learned/sonar-001.md

Todo grupo de achados ganha um dono

Cada execução se compara com a anterior: o retrato ganha as colunas Previous e Δ, e cada grupo é marcado como novo, recorrente ou sumido. O objetivo é ter menos issues a cada rodada, e é aqui que se vê se isso está acontecendo.

Cada afirmação é conferida antes de qualquer mudança

O mantenedor roda /triage-issue na sua issue. Um agente sem ferramentas de escrita confere cada afirmação contra o código no HEAD e julga a correção proposta à parte. O veredito volta como comentário e label.

O fluxo inteiro, na documentação →

Mudando o próprio harness

Blueprints e normas são as contribuições mais úteis. O repositório não é uma aplicação Java: o que se edita são arquivos de instrução, dados e um hook. Leia o CLAUDE.md antes do primeiro PR; os Invariants dele são o que o review confere.

# JDK 21+, git e curl. Nada mais
git clone https://github.com/nerviz-ai/nerviz.git
cd nerviz
java .claude/hooks/ArchHook.java doctor

# antes de abrir um PR
java .claude/hooks/ArchHook.java schema
claude plugin validate .claude/skills

Na dúvida se é norma, skill, agente ou hook? Escolher o tipo errado é o apontamento mais comum de review, e o /claude-code-architect-designer existe para essa pergunta.

CONTRIBUTING.md, com as regras por tipo de arquivo →