[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7APAP0KKN81DF4MP1X6QTPJ":3,"skill-same:01M7APAP0KKN81DF4MP1X6QTPJ":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7APAP0KKN81DF4MP1X6QTPJ","codebase-design",null,"Vocabulário compartilhado para projetar deep modules. Use quando o usuário quiser projetar ou melhorar a interface de um módulo, encontrar oportunidades de aprofundamento, decidir onde uma costura deve ficar, tornar o código mais testável ou navegável por IA, ou quando outra skill precisar do vocabulário de deep modules.","matheusdmlopes\u002Fskills-ptbr","matheusdmlopes","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F115191427?v=4","01M7APAA2NZDDT90C9Q4SK3QJE","Matheus De Marco Lopes","01M7APAA3GZ0Z81YMV996S8YF1",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: codebase-design\ndescription: Vocabulário compartilhado para projetar deep modules. Use quando o usuário quiser projetar ou melhorar a interface de um módulo, encontrar oportunidades de aprofundamento, decidir onde uma costura deve ficar, tornar o código mais testável ou navegável por IA, ou quando outra skill precisar do vocabulário de deep modules.\n---\n\n# Codebase Design\n\nProjete **deep modules**: muito comportamento atrás de uma interface pequena, posicionada em uma costura limpa, testável por meio dessa interface. Use esta linguagem e estes princípios onde quer que o código esteja sendo projetado ou reestruturado. O objetivo é alavancagem para os chamadores, localidade para os mantenedores e testabilidade para todos.\n\n## Glossário\n\nUse estes termos com exatidão — não substitua por \"componente\", \"serviço\", \"API\" ou \"divisa\". Linguagem consistente é todo o propósito.\n\n**Módulo (Module)** — qualquer coisa com uma interface e uma implementação. Deliberadamente agnóstico de escala: uma função, classe, pacote ou fatia transversal a camadas. _Evitar_: unidade, componente, serviço.\n\n**Interface** — tudo o que um chamador precisa saber para usar o módulo corretamente: a assinatura de tipos, mas também invariantes, restrições de ordenação, modos de erro, configuração necessária e características de desempenho. _Evitar_: API, assinatura (muito estreitas — referem-se apenas à superfície no nível de tipos).\n\n**Implementação (Implementation)** — o que está dentro de um módulo, seu corpo de código. Distinto de **Adaptador**: algo pode ser um adaptador pequeno com uma implementação grande (um repositório Postgres) ou um adaptador grande com uma implementação pequena (um fake em memória). Use \"adaptador\" quando a costura for o assunto; \"implementação\" caso contrário.\n\n**Profundidade (Depth)** — alavancagem na interface: a quantidade de comportamento que um chamador (ou teste) pode exercitar por unidade de interface que precisa aprender. Um módulo é **deep** quando uma grande quantidade de comportamento reside atrás de uma interface pequena, **raso (shallow)** quando a interface é quase tão complexa quanto a implementação.\n\n**Costura (Seam)** _(Michael Feathers)_ — um lugar onde você pode alterar o comportamento sem editar nesse lugar; o *local* no qual a interface de um módulo reside. Onde colocar a costura é uma decisão de design própria, distinta do que fica atrás dela. _Evitar_: divisa (sobrecarregado com bounded context do DDD).\n\n**Adaptador (Adapter)** — uma coisa concreta que satisfaz uma interface em uma costura. Descreve o *papel* (qual slot preenche), não a substância (o que está dentro).\n\n**Alavancagem (Leverage)** — o que os chamadores obtêm da profundidade: mais capacidade por unidade de interface que aprendem. Uma implementação se paga ao longo de N pontos de chamada e M testes.\n\n**Localidade (Locality)** — o que os mantenedores obtêm da profundidade: alterações, bugs, conhecimento e verificação se concentram em um único lugar em vez de se espalharem pelos chamadores. Corrija uma vez, corrigido em todo lugar.\n\n## Deep vs shallow\n\n**Deep module** = interface pequena + muita implementação:\n\n```\n┌─────────────────────┐\n│   Small Interface   │  ← Poucos métodos, parâmetros simples\n├─────────────────────┤\n│                     │\n│  Deep Implementation│  ← Lógica complexa oculta\n│                     │\n└─────────────────────┘\n```\n\n**Módulo raso (shallow)** = interface grande + pouca implementação (evite):\n\n```\n┌─────────────────────────────────┐\n│       Large Interface           │  ← Muitos métodos, parâmetros complexos\n├─────────────────────────────────┤\n│  Thin Implementation            │  ← Apenas repassa chamadas\n└─────────────────────────────────┘\n```\n\nAo projetar uma interface, pergunte-se:\n\n- Posso reduzir o número de métodos?\n- Posso simplificar os parâmetros?\n- Posso ocultar mais complexidade no interior?\n\n## Princípios\n\n- **A profundidade é uma propriedade da interface, não da implementação.** Um deep module pode ser composto internamente de partes pequenas, mockáveis e substituíveis — elas apenas não fazem parte da interface. Um módulo pode ter **costuras internas** (privadas à sua implementação, usadas por seus próprios testes), bem como a **costura externa** em sua interface.\n- **O teste de deleção.** Imagine deletar o módulo. Se a complexidade desaparecer, ele era apenas um repassador. Se a complexidade reaparecer espalhada por N chamadores, ele estava justificando sua existência.\n- **A interface é a superfície de teste.** Chamadores e testes cruzam a mesma costura. Se você quiser testar *além* da interface, o módulo provavelmente está com o formato errado.\n- **Um adaptador significa uma costura hipotética. Dois adaptadores significam uma costura real.** Não introduza uma costura a menos que algo realmente varie através dela.\n\n## Projetando para testabilidade\n\nBoas interfaces tornam os testes naturais:\n\n1. **Aceite dependências, não as crie.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function processOrder(order, paymentGateway) {}\n\n   \u002F\u002F Hard to test\n   function processOrder(order) {\n     const gateway = new StripeGateway();\n   }\n   ```\n\n2. **Retorne resultados, não produza efeitos colaterais.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function calculateDiscount(cart): Discount {}\n\n   \u002F\u002F Hard to test\n   function applyDiscount(cart): void {\n     cart.total -= discount;\n   }\n   ```\n\n3. **Superfície pequena.** Menos métodos = menos testes necessários. Menos parâmetros = configuração de teste mais simples.\n\n## Relações\n\n- Um **Módulo** tem exatamente uma **Interface** (a superfície que ele apresenta a chamadores e testes).\n- **Profundidade** é uma propriedade de um **Módulo**, medida em relação à sua **Interface**.\n- Uma **Costura** é onde a **Interface** de um **Módulo** reside.\n- Um **Adaptador** fica em uma **Costura** e satisfaz a **Interface**.\n- **Profundidade** produz **Alavancagem** para chamadores e **Localidade** para mantenedores.\n\n## Enquadramentos rejeitados\n\n- **Profundidade como proporção entre linhas de implementação e linhas de interface** (Ousterhout): recompensa inflar a implementação. Em vez disso, usamos profundidade-como-alavancagem.\n- **\"Interface\" como a palavra-chave `interface` do TypeScript ou os métodos públicos de uma classe**: muito estreito — interface aqui inclui todo fato que um chamador precisa saber.\n- **\"Boundary\"**: sobrecarregado com bounded context do DDD. Diga **costura** ou **interface**.\n\n## Indo mais a fundo\n\n- **Aprofundando um cluster dadas as suas dependências** — veja [DEEPENING.md](DEEPENING.md): categorias de dependência, disciplina de costuras e testes no estilo substituir-não-acumular em camadas (replace-don't-layer).\n- **Explorando interfaces alternativas** — veja [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): inicialize subagentes paralelos para projetar a interface de várias maneiras radicalmente diferentes e, em seguida, compare quanto a profundidade, localidade e posicionamento da costura.\n","# Codebase Design\n\nProjete **deep modules**: muito comportamento atrás de uma interface pequena, posicionada em uma costura limpa, testável por meio dessa interface. Use esta linguagem e estes princípios onde quer que o código esteja sendo projetado ou reestruturado. O objetivo é alavancagem para os chamadores, localidade para os mantenedores e testabilidade para todos.\n\n## Glossário\n\nUse estes termos com exatidão — não substitua por \"componente\", \"serviço\", \"API\" ou \"divisa\". Linguagem consistente é todo o propósito.\n\n**Módulo (Module)** — qualquer coisa com uma interface e uma implementação. Deliberadamente agnóstico de escala: uma função, classe, pacote ou fatia transversal a camadas. _Evitar_: unidade, componente, serviço.\n\n**Interface** — tudo o que um chamador precisa saber para usar o módulo corretamente: a assinatura de tipos, mas também invariantes, restrições de ordenação, modos de erro, configuração necessária e características de desempenho. _Evitar_: API, assinatura (muito estreitas — referem-se apenas à superfície no nível de tipos).\n\n**Implementação (Implementation)** — o que está dentro de um módulo, seu corpo de código. Distinto de **Adaptador**: algo pode ser um adaptador pequeno com uma implementação grande (um repositório Postgres) ou um adaptador grande com uma implementação pequena (um fake em memória). Use \"adaptador\" quando a costura for o assunto; \"implementação\" caso contrário.\n\n**Profundidade (Depth)** — alavancagem na interface: a quantidade de comportamento que um chamador (ou teste) pode exercitar por unidade de interface que precisa aprender. Um módulo é **deep** quando uma grande quantidade de comportamento reside atrás de uma interface pequena, **raso (shallow)** quando a interface é quase tão complexa quanto a implementação.\n\n**Costura (Seam)** _(Michael Feathers)_ — um lugar onde você pode alterar o comportamento sem editar nesse lugar; o *local* no qual a interface de um módulo reside. Onde colocar a costura é uma decisão de design própria, distinta do que fica atrás dela. _Evitar_: divisa (sobrecarregado com bounded context do DDD).\n\n**Adaptador (Adapter)** — uma coisa concreta que satisfaz uma interface em uma costura. Descreve o *papel* (qual slot preenche), não a substância (o que está dentro).\n\n**Alavancagem (Leverage)** — o que os chamadores obtêm da profundidade: mais capacidade por unidade de interface que aprendem. Uma implementação se paga ao longo de N pontos de chamada e M testes.\n\n**Localidade (Locality)** — o que os mantenedores obtêm da profundidade: alterações, bugs, conhecimento e verificação se concentram em um único lugar em vez de se espalharem pelos chamadores. Corrija uma vez, corrigido em todo lugar.\n\n## Deep vs shallow\n\n**Deep module** = interface pequena + muita implementação:\n\n```\n┌─────────────────────┐\n│   Small Interface   │  ← Poucos métodos, parâmetros simples\n├─────────────────────┤\n│                     │\n│  Deep Implementation│  ← Lógica complexa oculta\n│                     │\n└─────────────────────┘\n```\n\n**Módulo raso (shallow)** = interface grande + pouca implementação (evite):\n\n```\n┌─────────────────────────────────┐\n│       Large Interface           │  ← Muitos métodos, parâmetros complexos\n├─────────────────────────────────┤\n│  Thin Implementation            │  ← Apenas repassa chamadas\n└─────────────────────────────────┘\n```\n\nAo projetar uma interface, pergunte-se:\n\n- Posso reduzir o número de métodos?\n- Posso simplificar os parâmetros?\n- Posso ocultar mais complexidade no interior?\n\n## Princípios\n\n- **A profundidade é uma propriedade da interface, não da implementação.** Um deep module pode ser composto internamente de partes pequenas, mockáveis e substituíveis — elas apenas não fazem parte da interface. Um módulo pode ter **costuras internas** (privadas à sua implementação, usadas por seus próprios testes), bem como a **costura externa** em sua interface.\n- **O teste de deleção.** Imagine deletar o módulo. Se a complexidade desaparecer, ele era apenas um repassador. Se a complexidade reaparecer espalhada por N chamadores, ele estava justificando sua existência.\n- **A interface é a superfície de teste.** Chamadores e testes cruzam a mesma costura. Se você quiser testar *além* da interface, o módulo provavelmente está com o formato errado.\n- **Um adaptador significa uma costura hipotética. Dois adaptadores significam uma costura real.** Não introduza uma costura a menos que algo realmente varie através dela.\n\n## Projetando para testabilidade\n\nBoas interfaces tornam os testes naturais:\n\n1. **Aceite dependências, não as crie.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function processOrder(order, paymentGateway) {}\n\n   \u002F\u002F Hard to test\n   function processOrder(order) {\n     const gateway = new StripeGateway();\n   }\n   ```\n\n2. **Retorne resultados, não produza efeitos colaterais.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function calculateDiscount(cart): Discount {}\n\n   \u002F\u002F Hard to test\n   function applyDiscount(cart): void {\n     cart.total -= discount;\n   }\n   ```\n\n3. **Superfície pequena.** Menos métodos = menos testes necessários. Menos parâmetros = configuração de teste mais simples.\n\n## Relações\n\n- Um **Módulo** tem exatamente uma **Interface** (a superfície que ele apresenta a chamadores e testes).\n- **Profundidade** é uma propriedade de um **Módulo**, medida em relação à sua **Interface**.\n- Uma **Costura** é onde a **Interface** de um **Módulo** reside.\n- Um **Adaptador** fica em uma **Costura** e satisfaz a **Interface**.\n- **Profundidade** produz **Alavancagem** para chamadores e **Localidade** para mantenedores.\n\n## Enquadramentos rejeitados\n\n- **Profundidade como proporção entre linhas de implementação e linhas de interface** (Ousterhout): recompensa inflar a implementação. Em vez disso, usamos profundidade-como-alavancagem.\n- **\"Interface\" como a palavra-chave `interface` do TypeScript ou os métodos públicos de uma classe**: muito estreito — interface aqui inclui todo fato que um chamador precisa saber.\n- **\"Boundary\"**: sobrecarregado com bounded context do DDD. Diga **costura** ou **interface**.\n\n## Indo mais a fundo\n\n- **Aprofundando um cluster dadas as suas dependências** — veja [DEEPENING.md](DEEPENING.md): categorias de dependência, disciplina de costuras e testes no estilo substituir-não-acumular em camadas (replace-don't-layer).\n- **Explorando interfaces alternativas** — veja [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): inicialize subagentes paralelos para projetar a interface de várias maneiras radicalmente diferentes e, em seguida, compare quanto a profundidade, localidade e posicionamento da costura.\n",{"name":5,"description":7},"main","856f969876d3661ac06e93e82beda8904677c957","skills\u002Fengineering\u002Fcodebase-design","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes","matheusdemarcolopes.com.br","Developer","2026-08-16 10:59:19",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add matheusdmlopes\u002Fskills-ptbr --skill codebase-design",{"tool":38,"command":39},"bunx","bunx skills add matheusdmlopes\u002Fskills-ptbr --skill codebase-design",{"tool":41,"command":42},"pnpm","pnpm dlx skills add matheusdmlopes\u002Fskills-ptbr --skill codebase-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FSKILL.md",true,[46,52,56],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"agents\u002Fopenai.yaml","REFERENCE","参考文档",109,"https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002Fagents\u002Fopenai.yaml",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"DEEPENING.md",2996,"https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FDEEPENING.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"DESIGN-IT-TWICE.md",3160,"https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FDESIGN-IT-TWICE.md",[61,68,75,82,89,96],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7APGYCEMRP2Z8R926B42PB9","writing-for-agents","Redação de documentos para agentes. Use ao criar ou editar skills, ou ao modificar AGENTS.md ou CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7APGVKK4MRXM4Z61E75VNH2","wait-what","Pare. A última mensagem não ficou clara — reformule a explicação.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwait-what\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7APGR9YYE8YW1ZX7NRACGME","to-questionnaire","Transforme uma decisão que você não consegue responder totalmente em um questionário para outra pessoa preencher.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fto-questionnaire\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7APGMHE0796QV2S13AP98AP","teach","Ensine ao usuário uma nova habilidade ou conceito, dentro deste workspace.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fteach\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7APGJKKE94TRFCEXB8VE8VW","handoff","Compacte a conversa atual em um documento de handoff para outro agente assumir.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fhandoff\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7APGFMVWCEAH0SV5SHZGZE7","grilling","Sabatine o usuário implacavelmente sobre um plano, decisão ou ideia. Use quando o usuário quiser estressar seu raciocínio ou usar qualquer frase de ativação com 'grill'.","https:\u002F\u002Fgithub.com\u002Fmatheusdmlopes\u002Fskills-ptbr\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fgrilling\u002FSKILL.md",[],[]]