CesarChv19/claude-skills_MC

Implementação de requisito (estrutura de pastas + bitácora)

Indicações gerais a aplicar quando se começa a construir um requisito já analisado (não para a fase de análise). Reconstruído a partir do padrão já usado em RV2-054-132-019_ Integração processo ADG (CONSUBANCO), que é onde foi aplicado pela primeira vez. Esta skill é portável: aplica-se igualmente independentemente do projeto/cliente onde seja usada, seguindo a regra de ancoragem do §0.

0. Onde isto vive (portabilidade entre projetos)

Este prompt não assume uma rota absoluta nem o nome de um cliente em particular. A regra de ancoragem, válida em qualquer projeto onde seja usado:

• Sempre existe uma pasta que agrupa todos os requisitos desse projeto/cliente — o nome literal pode variar (Req\, Requerimientos\, ou outro que o usuário indique na primeira vez que se trabalha num projeto novo) — e dentro dela, uma subpasta por requisito, nomeada com seu código (ex. RV2-054-132-019, às vezes seguido de _<nome curto>, ex. RV2-054-132-019_ Integração processo ADG).
• Todo o resto neste documento (README.md, Compartidos\, EchasXC\, SCRIPTS\...) é relativo a ESSA subpasta do requisito específico, independentemente de como se chame a pasta contentora superior. Não é preciso perguntar o nome da pasta contentora de cada vez — se já existir uma no projeto (Req\ ou Requerimientos\), usar essa; se não existir nenhuma ainda (projeto novo), perguntar ao usuário como a quer nomear antes de a criar.
• Um requisito novo e separado (ver §10) identifica-se por ter (ou necessitar) a sua própria subpasta debaixo dessa pasta contentora, com o seu próprio código — nunca se mete dentro da pasta de outro requisito já existente, mesmo que esteja no mesmo cliente/módulo.

Árvore concreta (tudo de §1-§4 pende diretamente da pasta do requisito, nada vive um nível acima nem abaixo do que mostra esta árvore):

Req\                                     (ou "Requerimientos\", o nome que o projeto já use)
└─ RV2-054-132-019_ Integração ADG\     ← pasta do requisito (§0), âncora de todo o resto
   ├─ README.md                         ← §1, a bitácora
   ├─ Compartidos\                      ← §2, HU/imagens/evidência/chaves
   ├─ EchasXC\                     ← §4, tudo que Claude gera que não é entregável formal
   │  └─ SCRIPTS\                       ← §3, a pasta DE TRABALHO de Claude (não a raiz)
   │     ├─ ORG\                       ← rollback, numeração própria
   │     └─ MOD\
   │        ├─ ALTERS\                 ← só tabelas
   │        ├─ SP\                     ← só stored procedures
   │        ├─ FN\                     ← só funções
   │        └─ VI\                    ← só vistas
   ├─ SCRIPTS\                          ← pasta raiz que é curada pelo usuário (§3), NÃO tocar sem permissão
   ├─ Analise_Impacto_[CÓDIGO].docx    ← entregáveis da fase de análise (se foram pedidos)
   ├─ Estimativa_tempos_[CÓDIGO].xlsx
   └─ Plano_Implementacao_[CÓDIGO].docx

1. Bitácora de alterações — README.md na raiz da pasta do requisito

Um único arquivo, vivo, que é atualizado cada vez que se constrói/modifica algo, se resolve ou se adiciona uma pergunta pendente, ou muda o estado de algo. Estrutura fixa:

• Cabeçalho com código e nome do requisito + "Última atualização: AAAA-MM-DD".
• O que é isto — resumo de 2-4 linhas do requisito.
• Estado geral — o que já está construído — um bullet por fase/módulo, marcando construído / parcial / pendente.
• Arquitetura (onde está cada coisa) — rotas de ecrãs, SPs chave (com as suas flags), jobs, tabelas chave, ficheiros de config. Acesso à BD (servidor, nome da base, utilizador e palavra-passe) NÃO é documentado aqui nem em nenhum ficheiro — muda conforme o portal/projeto, e o utilizador fornece-o no momento em que for necessário, juntamente com a palavra-passe (ver §7).
• Pendentes — separado em "Perguntas ao cliente" (riscar com ~~texto~~ quando se resolverem, sem as apagar) e "Desenvolvimento pendente".
• Bitácora de alterações — uma entrada por sessão/data (**AAAA-MM-DD (título curto)**), mais recente em cima, com: qual lacuna/bug real foi encontrado, o que foi decidido e porquê, que ficheiros mudaram, o que falta o utilizador fazer (correr script, recompilar, testar no ecrã).

Não substitui Analise_Impacto_[CÓDIGO].docx nem Plano_Implementacao_[CÓDIGO].docx (esses são entregáveis da fase de análise) — este README é o estado vivo da construção.

Rotação quando cresce demais — se README.md se aproximar ou ultrapassar ~200KB, arquivar as sessões mais antigas antes de continuar a adicionar (caso real já ocorrido: um README.md chegou a passar 256KB e a ferramenta de leitura deixou de conseguir abri-lo). Mecânica: mover as entradas de bitácora mais antigas para um novo ficheiro README_historico_AAAA.md (um por ano, ou o que for preciso), deixando no README.md ativo apenas as ~10-15 sessões mais recentes + um resumo de 2-3 linhas do arquivado (para não perder continuidade ao ler apenas o ativo). As restantes secções (O que é isto, Estado geral, Arquitetura, Pendentes) nunca são arquivadas, vivem sempre no ativo — apenas a bitácora de sessões roda.

2. Pasta Compartidos\

Tudo o que é insumo ou evidência partilhada com o cliente/fornecedor externo, não código: HU e seus anexos, imagens/capturas embebidas extraídas do documento, chaves (PGP/certificados), ficheiros de mapeamento de dados, ficheiros de teste recebidos ou enviados a um terceiro (ex. CDC).

Se aparecer um documento em Compartidos\ cujo tema não corresponde ao requisito atual (ex. uma HU de "Logs/auditoria" dentro da pasta de "Integração processo ADG"): não assumir nenhuma das duas saídas fáceis — nem tratá-lo como evidência deste requisito só por estar ali, nem ignorá-lo/movê-lo por conta própria. Perguntar ao utilizador qual destes três casos é:

• Mal localizado — pertence a outra pasta, foi copiado por erro.
• Requisito novo e separado que ainda não tem a sua própria pasta — criá-la com esta mesma estrutura, e se partilhar objetos de BD/ecrã com o atual, documentá-lo em "Requisitos relacionados" de ambos (§10).
• Conjunto de requisitos agrupados de propósito numa só pasta de cliente (existe um precedente deste padrão na plantilha de e-mail de passagem para QA, que contempla explicitamente um "Conjunto de requisitos") — se for o caso, confirmar se ainda assim convém uma subpasta por código.

3. Pasta de scripts — SCRIPTS\ORG\ e SCRIPTS\MOD\

Há duas pastas SCRIPTS distintas na pasta do requisito: <requisito>\SCRIPTS\ (raiz) e <requisito>\EchasXC\SCRIPTS\. A de trabalho, onde Claude vai deixando cada script à medida que o constrói, é EchasXC\SCRIPTS\. A pasta raiz SCRIPTS\ é curada pelo utilizador manualmente, promovendo desde EchasXC\SCRIPTS\ quando ele considerar que algo já está bem — não tocar nessa pasta raiz salvo se o utilizador o pedir explicitamente.

MOD\ — uma subpasta por tipo de objeto, sem agrupar, cada uma com numeração sequencial própria e independente (não partilham numeração entre si):

• MOD\ALTERS\ — só tabelas (CREATE TABLE / ALTER TABLE).
• MOD\SP\ — só stored procedures.
• MOD\FN\ — só funções (CREATE FUNCTION).
• MOD\VI\ — só vistas.
• Se aparecer um tipo de objeto que não tem pasta dedicada (índice, trigger, job, etc.), perguntar ao utilizador como quer chamar a pasta em vez de assumir onde vai ou metê-lo na que "se parece". (Erro real já cometido uma vez: uma função foi posta primeiro em SP\, depois em ALTERS\, até o utilizador pedir para criar FN\ dedicada.)
• Padrão de nome em todas: objeto já existente que se modifica → N_NOME_MOD.sql; objeto completamente novo (não existe na BD) → N_NOME_NEW.sql.

ORG\ — rollback dos objetos que se modificam (os _NEW não trazem parceiro aqui: o rollback de algo novo é simplesmente eliminá-lo, não há nada prévio a capturar). Antes de tocar um objeto existente, extrair a sua definição atual tal como vive hoje na BD e guardá-la aqui — esse ficheiro É o rollback.

• ORG\ NÃO é um espelho numérico de MOD\. É fácil assumi-lo e é incorreto — têm numeração independente. Pode até numerar-se por categoria dentro de si mesma (p. ex. um rollback consolidado de todos os MOD\ALTERS numa só passada respeitando dependências, e em separado um rollback por cada SP tocado). Confirmar com o utilizador o esquema de numeração de ORG\ antes de assumir "mesmo número que em MOD" — já foi corrigido uma vez por assumir isto mal.
• Cada vez que se toque/implante um objeto, avisar explicitamente ao utilizador qual é (nome) para que fique claro o que foi movido.

Regras gerais para qualquer script deste apartado:

• DDL sempre idempotent (IF NOT EXISTS / COL_LENGTH(...) IS NULL).
• Um SP novo que chama outro SP novo define-se no mesmo ficheiro/batch que a sua dependência, nunca num número de ficheiro posterior.
• Se depois se "unificarem"/limparem scripts incrementais (colunas adicionadas posteriormente via ALTER soltos que se dobram de volta ao CREATE original): o ALTER de backup deixa-se igual debaixo do CREATE já completo (os dois caminhos convivem, não se escolhe um deles); o ORG correspondente não precisa de alterações se já faz DROP completo do objeto — se fizer rollback coluna a coluna, rever ordem (índices/constraints são removidos antes de tocar a coluna no rollback, são criados depois de fixar a nulabilidade final na criação).

4. Material de trabalho que não é entregável — EchasXC\

Tudo o que Claude gera para apoiar a construção mas que não é entregue formalmente ao cliente nem à equipa (queries de validação, testes manuais, folhas técnicas, e-mails rascunho): vai numa subpasta EchasXC\, separada de Compartidos\ e dos entregáveis formais.

5. Encoding — por nenhum motivo modificar o já estabelecido no ficheiro

Antes de editar qualquer ficheiro com acentos (.aspx/.aspx.vb/.master/scripts, etc.), não assumir que é UTF-8 só porque o declara ou porque file o reporta assim. Alguns ficheiros antigos de portais legacy são realmente ISO-8859-1/Windows-1252 por dentro (acentos como bytes altos únicos), e o Edit/Write normal descodifica/reescreve TODO o ficheiro como UTF-8 — qualquer acento pré-existente no ficheiro completo (não só perto da edição) converte-se em lixo (U+FFFD, vê-se como "�" ou similar no navegador), de forma silenciosa e permanente assim que se guarda.

• Verificar encoding real antes de tocar num ficheiro deste tipo (file arquivo.aspx, e atenção: um ficheiro JÁ corrompido antes pode reportar "UTF-8" limpo sem o ser realmente).
• Se for ISO-8859-1, editar via PowerShell com [System.Text.Encoding]::GetEncoding("ISO-8859-1") — descodificar bytes crus com essa codificação, substituir em memória, reescrever com a mesma codificação. Nunca com a ferramenta Edit/Write padrão sobre um ficheiro com esta suspeita.
• Verificar depois de CADA edição, não só antes: se o repo tiver git, git diff --stat imediatamente depois — um número de deletions muito maior do que se tentou alterar é o sinal de corrupção, não a edição esperada. Sem git, comparar tamanho do ficheiro antes/depois.
• Se já se corrompeu sem dar por isso: reverter com git checkout -- arquivo (recupera os bytes originais intactos) antes de reintentar com o método correto — os acentos perdidos não se podem recuperar uma vez sobrescritos.
• Para ficheiros novos que Claude cria (não edita): sim, levam BOM UTF-8 explícito se o projeto o exigir (confirmar com o utilizador se aplica).

6. Postura geral — agir como sénior, nunca dar nada como garantido

Não assumir que algo "deveria funcionar assim", que um padrão se repete igual que noutro lado, ou que um dado/esquema é o que a memória ou a leitura superficial sugerem. Validar o processo real sempre:

• Contra a BD real (DEV) antes de afirmar esquema, dados ou comportamento — não assumir, consultar.
• Contra o código real (grep/ler o ficheiro) antes de afirmar o que faz um ecrã/SP — não confiar no nome ou na primeira leitura.
• Contra a HU/documento do requisito antes de adicionar algo que "parece necessário" — se não estiver explícito, não se constrói por inércia.
• Validando o resultado de cada alteração (SET PARSEONLY ON, git diff, execução de teste) antes de a dar por terminada, em vez de assumir que compilou/correu bem porque a lógica parece correta.

7. Regras de execução contra BD (aplica a tudo, não só DDL de script)

• Nunca executar INSERT/UPDATE/DELETE/DDL contra a BD, nem em DEV, nem com confirmação explícita no chat. O utilizador executa ele mesmo tudo o que escrever na BD; o papel de Claude é preparar o script e, depois de o utilizador o correr, validar com SELECT que ficou como esperado. Isto é independente da regra das pastas ORG/MOD — aplica-se também a catálogos, dados de teste, qualquer escrita.
• Consultas de só leitura (SELECT, INFORMATION_SCHEMA, sys.sql_modules) sim são livres, sem pedir permissão de cada vez.
• Servidor, nome da base, utilizador e palavra-passe da BD não são documentados em nenhum ficheiro (README.md, Compartidos\, scripts .sql, comentários de código) — o nome da base em particular muda conforme o portal/projeto, pelo que não há um valor fixo que valha a pena fixar por escrito. O utilizador fornece-os no chat quando forem precisos, juntamente com a palavra-passe, e são usados apenas como variável de ambiente no comando dessa sessão — pedi-los de novo da próxima vez, não guardá-los "para não ter que voltar a perguntar". Se já se tem uma palavra-passe/cone…

… [truncado para tradução]