菜单
Use este skill quando o usuario precisar definir padroes de APIs REST/HTTP. Exemplos de ativacao: padronizar versionamento via path; definir convencoes de URLs (plural, ingles, kebab-case); definir paginacao padrao; aplicar RFC 9457 (Problem Details) para erros; adotar OpenAPI 3 e design-first; padronizar codigos de status e payload JSON.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Catálogo de Design Patterns (GoF e auxiliares) com guia de decisão e implementação. Use esta skill sempre que o contexto envolver padrões de projeto, refatoração estrutural, ou quando detectar code smells que um padrão resolve — como: cadeias de if/else para instanciar objetos (Factory), comportamentos condicionais que mudam por estado (State), algoritmos intercambiáveis (Strategy), acoplamento a bibliotecas externas (Adapter), funcionalidades empilháveis (Decorator), notificações reativas (Observer), controle de acesso ou cache em objetos (Proxy), eliminação de duplicação em fluxos similares (Template Method), ou instância única global (Singleton). Também dispare quando o usuário mencionar explicitamente nomes de padrões, pedir para "aplicar um design pattern", "refatorar usando padrões", "desacoplar", ou quando perguntar "qual padrão usar aqui?". Esta skill funciona em qualquer linguagem — os princípios são agnósticos de stack.
Create and edit Excalidraw diagrams programmatically. Use when the user asks to create diagrams, flowcharts, architecture diagrams, wireframes, or any visual drawings in Excalidraw format (.excalidraw files).
Use este skill quando o usuário precisar criar mensagens de commit, revisar commits existentes, ou quando uma tarefa for finalizada e for necessário gerar a mensagem de commit padronizada. Exemplos de ativação: o usuário pede para commitar alterações; o usuário finaliza uma tarefa e precisa da mensagem de commit; o usuário pergunta sobre o padrão de commit do projeto; o usuário pede para revisar ou corrigir uma mensagem de commit.
Use este skill quando o usuario precisar padronizar nomenclatura de roles (perfis de acesso) em microservicos. Exemplos de ativacao: definir SCREAMING_SNAKE_CASE para roles; alinhar Keycloak e claims; configurar roles no .NET e Spring Security; manter catalogo oficial de roles e regras de migracao.
Padroes arquiteturais e estrutura de projeto .NET C# / ASP.NET Core: Clean Architecture com camadas numeradas, Repository Pattern com Entity Framework Core, CQRS nativo (sem MediatR) com Commands, Queries, Handlers e Dispatcher, tratamento global de erros (IExceptionHandler, ProblemDetails), Custom Exceptions e Result Pattern, FluentValidation em handlers, estrutura de pastas e dependencias entre projetos. Usar quando: criar novo microservico; criar modulo/feature; implementar endpoints e fluxo CQRS; definir contratos (DTOs/requests/responses); definir ou revisar estrutura de camadas; organizar pastas e projetos; configurar referencias entre projetos.
Padroes transversais de qualidade de codigo .NET C# / ASP.NET Core: convencoes de nomenclatura (PascalCase, camelCase, kebab-case), principios SOLID e Clean Code, estrutura de metodos e classes, async/await e CancellationToken, Dependency Injection, Exception Handling, estilo de codigo. Skill transversal que deve ser aplicada apos geracao de codigo. Usar quando: gerar codigo C#; revisar naming conventions; validar clean code; aplicar regras de qualidade; revisar estilo e formatacao; configurar DI.
| name | restful-api |
| description | Use este skill quando o usuario precisar definir padroes de APIs REST/HTTP. Exemplos de ativacao: padronizar versionamento via path; definir convencoes de URLs (plural, ingles, kebab-case); definir paginacao padrao; aplicar RFC 9457 (Problem Details) para erros; adotar OpenAPI 3 e design-first; padronizar codigos de status e payload JSON. |
A falta de um padrao para o design e documentacao de APIs REST pode resultar em inconsistencias entre os servicos. Cada equipe implementa aspectos criticos como versionamento, paginacao e, principalmente, a estrutura de respostas de erro de maneira distinta, podendo dificultar integracoes.
Estas divergencias podem acarretar consequencias diretas para o ecossistema de desenvolvimento:
Aumento da carga cognitiva: Desenvolvedores que consomem as APIs sao forcados a aprender as particularidades de cada servico, aumentando o tempo de integracao e a probabilidade de erros.
Fragilidade do ecossistema: A falta de previsibilidade nas interacoes entre servicos gera integracoes frageis e de dificil depuracao.
O objetivo e instituir boas praticas baseadas na especificacao OpenAPI 3, aliada a uma filosofia "Design-First", como a fundacao de um "manual de estilo" para as APIs.
Utilize ASP.NET Core MVC (Controllers) ou Minimal APIs para mapear os endpoints, escolhendo a abordagem mais adequada para o contexto do projeto.
/playlists/{playlistId}/videos ou /customers/{customerId}/invoices/scheduled-eventsvExemplo: https://api.example.com/users/v1/profile
https://[dominio]/[api-name]/v[major-version]/[resource]
Para acoes que nao se encaixam claramente no modelo CRUD (Create, Read, Update, Delete), utilize o verbo POST com URLs que descrevam a acao (estilo RPC).
Exemplo: POST /users/{userId}/change-password em vez de PUT /users/{userId} com um payload complexo.
Utilize os códigos de status abaixo para garantir semântica e previsibilidade nas respostas da API:
| Código | Status | Descrição e Uso Recomendado |
|---|---|---|
| 200 | OK | Sucesso na requisição. Retorna o recurso solicitado no corpo. |
| 201 | Created | Recurso criado com sucesso. Obrigatório retornar o header Location. |
| 204 | No Content | Sucesso, mas sem corpo de resposta (comum em DELETE ou PUT). |
| 400 | Bad Request | Erro de sintaxe (ex: JSON malformado ou campos obrigatórios faltando). |
| 401 | Unauthorized | O usuário não está autenticado ou o token é inválido/expirado. |
| 403 | Forbidden | Usuário autenticado, mas sem permissão de acesso ao recurso específico. |
| 404 | Not Found | O recurso solicitado (ID ou rota) não foi encontrado no servidor. |
| 422 | Unprocessable Entity | Erros de regra de negócio (ex: CPF já cadastrado, saldo insuficiente). |
| 429 | Too Many Requests | O cliente excedeu o limite de requisições (Rate Limiting). |
| 500 | Internal Server Error | Erro inesperado no servidor. Não deve expor detalhes sensíveis (Stack Trace). |
As respostas de erro devem obrigatoriamente aderir ao formato definido pela RFC 9457 (Problem Details for HTTP APIs).
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"status": 403,
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc"
}
Microsoft.AspNetCore.Http.Extensions para implementar Problem DetailsRespostas que retornam uma colecao de recursos devem obrigatoriamente suportar paginacao atraves dos query parameters padronizados:
_page: numero da pagina (iniciando em 1)_size: quantidade de itens por pagina[HttpGet]
public async Task<IActionResult> GetUsers(
[FromQuery] int _page = 1,
[FromQuery] int _size = 10)
{
// Implementacao da paginacao
}
{
"data": [...],
"pagination": {
"page": 1,
"size": 10,
"total": 100,
"totalPages": 10
}
}
openapi.yaml) e o padrao recomendado para escrita e manutencao da especificacaoConsidere implementar partial responses para consultas que podem retornar grandes volumes de dados, permitindo que o cliente especifique os campos desejados.
Exemplo: ?fields=id,name,email
Implemente padroes consistentes para:
?status=active&category=tech?sort=name&order=ascpublic class ExternalApiService
{
private readonly HttpClient _httpClient;
public ExternalApiService(HttpClient httpClient)
{
_httpClient = httpClient;
}
// Implementacao dos metodos
}