Communitygithub.com

Xavier189/dig-skill

dig(探骊)— Escavação Socrática de Requisitos para agentes de código: levante hipóteses, pergunte o que importa, itere até ficar limpo e confirme um memorando de clareza antes de começar o trabalho. Compatível com Claude Code e Agent Skills.

O que é dig-skill?

Esta habilidade (skill) implementa um processo de escavação sistemática de requisitos para agentes de IA de codificação, como Claude Code. Em vez de aceitar cegamente uma solicitação superficial, o agente levanta hipóteses sobre a intenção real do usuário, faz perguntas direcionadas e iterativas, e sintetiza um "memorando de clareza" antes de qualquer implementação. A abordagem é fortemente inspirada no método socrático, onde cada pergunta deve mudar potencialmente o curso da ação. O processo garante que decisões implícitas, restrições ocultas e suposições sejam explicitadas, evitando entregas tecnicamente corretas, mas alinhadas erroneamente com os objetivos de longo prazo do usuário. A skill foi projetada principalmente para Claude Code, mas é compatível com outras plataformas de Agent Skills, com etapas claras para hipotetizar, perguntar, iterar, sintetizar e persistir descobertas de longo prazo na memória.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add Xavier189/dig-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Dig — Escavação Socrática de Requisitos

Revele o que o usuário realmente quer antes de qualquer trabalho começar. A solicitação declarada é uma pista inicial, não o requisito. Intenções ocultas, restrições não declaradas e decisões silenciosamente delegadas a você são onde o trabalho entregue dá errado.

Combine a linguagem do usuário; mantenha os termos técnicos em sua forma original.

A barra que toda pergunta deve superar

Pergunte apenas o que mudaria o que você vai construir. Antes de perguntar algo, nomeie duas respostas realistas que levariam a abordagens diferentes; se toda resposta provável levar à mesma ação, você já sabe o suficiente — não pergunte. Esta barra tem precedência sobre cada etapa abaixo: uma etapa realizada sem ela é teatro.

Processo

0. CONTEXTO — absorva antes de levantar hipóteses

Leia o que é relevante: arquivos que a tarefa toca, documentos do projeto e — se sua plataforma mantém memória persistente — metas de longo prazo e preferências recorrentes armazenadas. Procure pelo panorama geral do usuário — uma entrega tecnicamente correta, mas desalinhada com seus planos de longo prazo, ainda é uma falha.

1. HIPOTETIZE — comprometa-se com uma interpretação que o usuário possa atacar

Antes de perguntar qualquer coisa, apresente uma hipótese de trabalho em três partes. Escreva cada parte para que o usuário possa apontar para uma linha e dizer "não — isso está errado". Autoverificação: se uma frase sobreviveria inalterada na hipótese de uma tarefa diferente, é enchimento — apague-a.

  1. O que você realmente quer — o resultado por trás da solicitação declarada, em uma ou duas frases. Se a solicitação é uma solução ("adicione um cache Redis"), declare o problema que você acredita que ela pretende resolver ("a página de listagem está lenta no pico") — a lacuna entre esses dois é onde as escavações compensam.
  2. Onde isso dá errado — os um ou dois lugares onde ESTA tarefa tem mais probabilidade de falhar ou ser mal interpretada: uma armadilha nomeada ("listas filtradas paginadas são o pior caso para cache — explosão de chaves, baixa taxa de acertos"), nunca um risco genérico ("o escopo pode aumentar").
  3. Se forçado a começar agora, eu… — um esboço concreto, uma decisão por linha, cada linha marcada:
    • ✅ explícito — o usuário já disse
    • 🔍 delegado — você usaria o padrão X, mas o usuário deve ratificar (escolha de tecnologia, estrutura, compensações, qualquer coisa difícil de reverter); recomende, nunca decida silenciosamente
    • ❓ ambíguo — você não consegue nem escolher um padrão

Mantenha toda a hipótese com menos de ~15 linhas — ela deve ser corrigível à vista. O esboço é uma isca: um plano concreto atrai correções que uma lista abstrata de incógnitas nunca atrairá.

Antes de mostrá-la, teste-a sob estresse de seis ângulos: objetivo real (o pedido é um meio para algo não declarado?), escopo (o que o usuário assume que está dentro ou fora que você não sabe?), critérios de sucesso (vocês dois concordariam que funcionou?), falha (o que quebra primeiro, e quem percebe?), dependências e restrições (o que deve existir, ou não deve mudar?), ajuste de longo prazo (o esboço luta contra o panorama geral do usuário?). Estes são ângulos de ataque, não seções a preencher — nunca escreva uma linha por ângulo. A maioria dos ângulos não vai morder; os dois ou três que podem derrubar a parte 1 ou redirecionar a parte 3 são exatamente de onde vêm suas perguntas.

Se o teste de estresse deixar mais de ~8 bifurcações não resolvidas, a tarefa é grande demais para uma única escavação — proponha dividi-la em subtarefas em vez de interrogar.

2. PERGUNTE — perguntas em lote cultivadas a partir dos pontos mais fracos

Apresente a hipótese e, em seguida, pergunte — via AskUserQuestion no Claude Code, ou como uma lista numerada em uma única mensagem em plataformas sem uma ferramenta de perguntas estruturada: até 4 perguntas por lote, ordenadas por impacto, cada uma com opções concretas e uma recomendação. Nunca faça perguntas uma a uma. Pergunte tudo o que você já sabe que está aberto agora — o loop abaixo existe para perguntas nascidas de respostas, não para racionar as conhecidas.

Cada pergunta deve:

  • nomear o que testa — qual parte da hipótese, qual bifurcação 🔍/❓. Uma pergunta que você não consegue amarrar à hipótese (incluindo enchimento como "mais alguma coisa que eu deveria saber?") é um reflexo de lista de verificação: corte-a.
  • superar a barra acima — alguma resposta realista deve mudar a abordagem.
  • recusar soluções disfarçadas de requisitos — trace "adicione um cache" de volta à lentidão que ele deve corrigir antes de projetar o cache.

Se o teste de estresse não deixar nenhum 🔍 ou ❓ de pé, diga isso e vá direto para o memorando — uma escavação com zero perguntas é um resultado legítimo, não uma falha de desempenho.

Calibre cada lote em relação a Superficial vs profundo no final deste arquivo.

3. ITERE — escave até que as respostas parem de mover a hipótese

Cada resposta pode expor uma bifurcação que era invisível antes dela. Um loop de lotes não é alimentação gota a gota: uma nova rodada é justificada apenas por novas informações da última. Após cada lote:

  1. Atualize a hipótese em voz alta, apenas o delta — "sua resposta sobre X muda o esboço: …". Nunca reafirme o que não mudou.
  2. Portão de admissão para perguntas de acompanhamento — uma nova pergunta só ganha seu lugar se declarar, dentro de si mesma: (a) qual resposta a abriu — cite ou parafraseie de perto as palavras do usuário — e (b) qual bifurcação ela decide. Formato: "Você disse que as gravações devem ser visíveis imediatamente — isso descarta o TTL simples, então: invalidar na gravação, ou descartar o cache para esta consulta?" Se você não conseguir preencher ambos os campos, está executando uma lista de verificação novamente, não seguindo um fio: descarte-a.
  3. Converja quando as respostas de uma rodada não abrirem perguntas de acompanhamento admissíveis e cada 🔍/❓ estiver resolvido ou explicitamente adiado. Diga que você convergiu e passe para o memorando — nunca encha uma rodada final para parecer completo. Não há limite de rodadas e nem cota de rodadas: uma rodada muitas vezes é suficiente; o portão decide, não a ambição.
  4. Muito grande? Se duas rodadas consecutivas abrirem tantas novas bifurcações quanto fecham, pare de interrogar — a solicitação são várias tarefas vestindo uma frase. Proponha uma divisão e escave apenas a primeira subtarefa.
  5. Válvula de escape — se o usuário disser "partiu", "comece", "apenas faça" ou equivalente, pare de perguntar imediatamente: dobre cada item não resolvido na seção Itens em aberto do memorando com o padrão que você aplicará e apresente o memorando para sua confirmação habitual.

4. SINTETIZE — o memorando de clareza

Apresente um memorando que o usuário possa verificar em ~10 segundos, exatamente cinco seções:

  • Goal(真实目标) — o objetivo real, uma ou duas frases
  • Decisions(已拍板) — cada decisão ratificada, uma linha cada
  • Boundaries(明确不做) — exclusões explícitas
  • Success criteria(成功标准)
  • Open items(开放项) — perguntas adiadas, riscos, suposições restantes

Obtenha confirmação explícita. Em seguida, faça a transição: para o modo de plano em grandes construções, ou diretamente para a implementação em trabalhos contidos. O memorando é a entrada downstream.

5. ASSENTE — persista o que sobrevive à tarefa

  • Apenas informações duradouras: metas entre tarefas (por exemplo, um projeto paralelo em andamento que esta tarefa atende), preferências recorrentes, contexto de domínio. Nada local à tarefa.
  • No máximo 1-2 gravações de memória por escavação; verifique as memórias existentes primeiro e prefira atualizar em vez de criar. Sem memória persistente na sua plataforma? Pule as gravações.
  • Fatos claramente entre projetos: sugira ao usuário que os adicione ao arquivo de instruções global (CLAUDE.md, AGENTS.md ou equivalente da sua plataforma) — não edite a configuração global você mesmo.
  • Persistência do memorando: DESLIGADA por padrão. Quando o usuário pedir para salvar (ou uma integração de arnês solicitar), escreva em docs/clarity/AAAA-MM-DD-<slug>.md com frontmatter task/date/status e as cinco seções do memorando como cabeçalhos fixos — essa estrutura é o contrato legível por máquina.

Superficial vs profundo — calibre aqui

Solicitação do usuário: "Nossa página de listagem de usuários leva 3-4 segundos no pico. Adicione um cache Redis para ela — me dê um plano de implementação."

Superficial — cada um parece profissional; nenhum muda se o cache é mesmo o movimento certo:

  • "Redis ou Caffeine?"
  • "Qual TTL — 5 minutos ou 30?"
  • "Armazenar em cache a resposta da página inteira ou entradas por usuário?"

Estes escolhem parâmetros em cima de um plano não examinado; eles aceitam a solução disfarçada como o requisito.

Profundo — cada um nomeia a bifurcação que decide:

  • "A página está lenta apenas no pico ou sempre?" — sempre lento aponta para a consulta em si, onde um índice pode corrigi-la diretamente; apenas no pico aponta para pool/concorrência, onde um cache mal ajuda. Decide se o Redis é o projeto certo.
  • "Depois que alguém edita um usuário, por quanto tempo a lista pode ficar desatualizada?" — "deve estar atualizada imediatamente" torna a invalidação o projeto real e a otimização de consulta provavelmente mais barata; "minutos estão bem" torna o TTL simples viável. Decide a forma — ou a existência — do design do cache.
  • "Alguém mediu para onde vão os 3-4 segundos?" — se não, o esboço começa com EXPLAIN e métricas de pool, não Redis; um índice de 30 minutos supera um imposto de consistência permanente. Decide a etapa 1 do trabalho.

Um acompanhamento legítimo da rodada 2, na forma admissível:

  • "Você disse que só está lento no pico e o pool de conexões atinge o máximo — isso move o diagnóstico de 'consulta lenta' para 'falta de conexões', então: aumentar o pool ou primeiro descobrir o que está monopolizando as conexões?"

Copie os movimentos, nunca o conteúdo. Os movimentos profundos são: rastrear a intenção, precificar a consequência, atacar seu próprio esboço. Nunca reutilize estas perguntas literais em uma tarefa que não seja esta tarefa.

Habilidades Relacionadas