dotnet-desktop-setup v1.8.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9d1ed45e3fdb8cb6.

---
name: dotnet-desktop-setup
metadata:
  version: 1.8.0
description: C#/.NET desktop scaffolding (WinForms / WPF / Avalonia) — generates CLAUDE.md, scoped rules, .editorconfig, Directory.Build.props, global.json. Audits coupling (UI/logic, God Classes). Triggers — dotnet setup, .NET scaffolding, WPF project, WinForms project, editorconfig.
---

# dotnet-desktop-setup

Skill de setup para projetos C#/.NET desktop no Claude Code. Funciona como um wizard que analisa
o estado atual do ambiente e codebase, depois gera ou atualiza arquivos de configuracao para
maximizar a qualidade do codigo gerado pelo Claude.

Usa **progressive disclosure** — este arquivo contem o workflow e decisoes. Templates e guias
detalhados ficam em `references/` e sao lidos sob demanda.

---

## Quando usar

- Configurar um novo projeto .NET para Claude Code
- Melhorar CLAUDE.md de um projeto C# existente
- Adicionar padroes de codificacao (.editorconfig, regras escopadas)
- Preparar codebase para desacoplamento UI (WinForms -> WPF/Avalonia)
- Configurar convencoes de teste xUnit
- Auditar acoplamento UI/negocio no codebase

---

## Workflow: 8 Passos

Duas ordens importam: a auditoria (Passo 1) vem antes de tudo — os outros passos usam o que ela mede
(SDK instalado, configs existentes, acoplamento); e o CLAUDE.md do projeto (Passo 4) vem antes das
regras escopadas (Passo 5), porque `domain.md` e extraido dele. Os demais passos sao independentes —
pule ou reordene conforme o cenario (secao "Tratamento de Cenarios"). Cada passo verifica o estado
atual antes de agir — nunca sobrescreve arquivos existentes sem apresentar diff ao usuario.

### Passo 1: Auditoria do Ambiente

Tente executar `scripts/audit-environment.sh` (requer Git Bash no Windows).
Se bash nao estiver disponivel, execute os comandos equivalentes inline usando as ferramentas
Bash, Grep e Glob do Claude Code:

- `dotnet --list-sdks` para listar SDKs
- Glob para verificar existencia de arquivos de config
- Grep para escanear acoplamento (MessageBox, System.Windows.Forms, public static)
- Grep para contar [Fact] e [Theory]

O script/auditoria coleta:
- SDKs .NET instalados (`dotnet --list-sdks`)
- Arquivos de config existentes (CLAUDE.md, .editorconfig, Directory.Build.props, global.json, .claude/rules/)
- Estrutura da solution (.sln → projetos e target frameworks)
- Indicadores de acoplamento UI:
  - `MessageBox.Show()` em arquivos que NAO sao Form*.cs
  - `System.Windows.Forms` em classes fora da camada UI
  - Campos `public static` mutaveis (padrao Global.cs)
- Cobertura de testes (contagem de [Fact] e [Theory])

Apresente o relatorio ao usuario antes de prosseguir. Se o usuario pediu apenas auditoria, pare aqui.

### Passo 2: global.json

Gere `global.json` na raiz da solution para fixar a versao do SDK:

```json
{
  "sdk": {
    "version": "<versao-mais-alta-instalada>",
    "rollForward": "latestFeature"
  }
}
```

- Use a versao mais alta detectada no Passo 1
- `rollForward: latestFeature` permite patch updates sem quebrar
- Se `global.json` ja existe, mostre diff e pergunte ao usuario

### Passo 3: CLAUDE.md Global (~/.claude/CLAUDE.md)

Leia `references/global-claude-md-template.md` para o template completo.

Este arquivo contem convencoes que se aplicam a **qualquer** projeto C#/.NET do usuario:
- Naming conventions (PascalCase publico, _camelCase privado)
- Padroes .NET CLI (--filter, --no-restore, -v q)
- Convencoes de teste (Arrange/Act/Assert, nomenclatura)
- Anti-padroes universais (MessageBox em dominio, static mutavel)
- Preferencias de linguagem C# moderna (file-scoped namespaces, pattern matching, collection expressions)

**Regra:** Se `~/.claude/CLAUDE.md` ja existe, nao sobrescreva. Leia o conteudo atual, identifique
lacunas comparando com o template, e proponha apenas as adicoes necessarias.

### Passo 4: CLAUDE.md do Projeto

Leia `references/project-claude-md-template.md` para o template.

O CLAUDE.md do projeto segue o framework **WHAT-WHY-HOW**:
- **WHAT**: Stack exata com versoes, modelos de dados, dominio
- **WHY**: Decisoes arquiteturais e motivacoes
- **HOW**: Comandos exatos de build/test/release

Limite: **300 linhas maximo** — acima disso, mova conteudo para `.claude/rules/` (Passo 5). Se o
existente ja esta bom (como projetos com CLAUDE.md detalhado), proponha apenas melhorias incrementais:
- Adicionar secao de convencoes se ausente
- Adicionar referencia a codigo canonico (ex: "Para novo service, veja `Services/LicenseValidationService.cs`")
- Adicionar anti-padroes especificos do projeto

### Passo 5: Regras Escopadas (.claude/rules/)

Leia `references/scoped-rules-templates.md` para os 4 templates.

Regras escopadas usam YAML frontmatter com `paths:` para ativar apenas em arquivos relevantes:

| Arquivo | Escopo | Conteudo |
|---------|--------|----------|
| `testing.md` | `**/*Tests*/**` | Convencoes xUnit, Arrange/Act/Assert, nomenclatura |
| `ui-decoupling.md` | `**/*.cs` | Onde MessageBox e permitido, separacao de camadas |
| `architecture.md` | `**/*.cs` | Direcao de dependencias, DI, camadas |
| `domain.md` | `**/*.cs` | Glossario de dominio, regras de validacao especificas |

Para `domain.md`, analise o CLAUDE.md existente e extraia terminologia do projeto.

Crie o diretorio `.claude/rules/` se nao existir. Para regras que ja existem, mostre diff.

### Passo 6: .editorconfig

Leia `references/editorconfig-template.md` para o template completo.

Pontos criticos para projetos .NET desktop:
- `charset = utf-8-bom` — necessario para caracteres especiais (portugues, acentos)
- `end_of_line = crlf` — padrao Windows
- Naming rules com severity `warning` (nao `error`) para adocao gradual
- Analyzers CA relevantes habilitados, CA2007 desabilitado (nao relevante para desktop)

Se `.editorconfig` ja existe, mostre diff. Nunca sobrescreva.

### Passo 7: Directory.Build.props

Gere `Directory.Build.props` na raiz da solution com propriedades compartilhadas.

**Cuidado com frameworks mistos!** Se a solution tem projetos em net5.0, net6.0 e net8.0,
use condicoes para nao quebrar builds:

```xml
<Project>
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
  </PropertyGroup>
  <PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net6.0'))">
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>
```

Apos gerar, **sempre** valide: `dotnet build <solution>.sln`

Se `Directory.Build.props` ja existe, mostre diff. Nunca sobrescreva.

### Passo 8: Hooks Claude Code (recomendacao)

Apresente ao usuario como **recomendacao**, nao aplique automaticamente. Build rapido apos cada
edicao de arquivo C#, em `.claude/settings.json` — o comando fica dentro de `hooks[]`, com `type`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "dotnet build --no-restore -v q 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}
```

Claude Code nao tem evento de commit: para rodar `dotnet test --no-build -v q` antes de cada commit,
use um git hook `pre-commit` do proprio repositorio.

Explique: hooks de build a cada edicao podem ser lentos em solutions grandes. O usuario decide.

---

## Tratamento de Cenarios

### Projeto novo (sem configs)
Execute todos os 8 passos na ordem.

### Projeto existente com config parcial
1. Execute Passo 1 (auditoria)
2. Apresente o que existe vs o que falta
3. Pergunte ao usuario quais passos executar
4. Para cada arquivo existente, mostre diff das adicoes propostas

### Apenas auditoria
Execute apenas Passo 1, apresente relatorio.

### Apenas regras escopadas
Execute Passo 1 (rapido) + Passo 5.

---

## Guias de Referencia (progressive disclosure level 3)

Leia estes arquivos **somente quando necessario** no passo correspondente:

| Arquivo | Leia quando... |
|---------|----------------|
| `references/global-claude-md-template.md` | Passo 3 — criando/atualizando CLAUDE.md global |
| `references/project-claude-md-template.md` | Passo 4 — criando/atualizando CLAUDE.md do projeto |
| `references/scoped-rules-templates.md` | Passo 5 — criando regras em .claude/rules/ |
| `references/editorconfig-template.md` | Passo 6 — criando .editorconfig |
| `references/decoupling-guide.md` | Usuario pede ajuda com desacoplamento UI ou arquitetura |
| `references/testing-guide.md` | Usuario pede ajuda com setup/padroes de testes xUnit |

---

## Detalhes Criticos (aprendidos nos testes)

Estes pontos falharam consistentemente quando a skill nao foi usada:

1. **utf-8-bom, nao utf-8** — Projetos em portugues precisam de `charset = utf-8-bom` no .editorconfig: utf-8 sem BOM causa problemas com acentos em builds do Visual Studio.

2. **YAML frontmatter nas regras escopadas** — Toda regra em `.claude/rules/` precisa de frontmatter com `paths:`; sem isso, a regra carrega em todo contexto e polui o prompt.

3. **Condicoes no Directory.Build.props** — Solutions com frameworks mistos (net5.0 + net8.0) quebram se voce aplicar `<ImplicitUsings>enable</ImplicitUsings>` sem condicao de framework. Sempre use `Condition="$([MSBuild]::IsTargetFrameworkCompatible(...))"`.

4. **CLAUDE.md global vs projeto** — Crie ambos, com conteudo distinto: `~/.claude/CLAUDE.md` guarda o que vale para qualquer projeto C#/.NET do usuario (naming, CLI, anti-padroes universais); `./CLAUDE.md` guarda so o que e deste projeto (stack, dominio, comandos). Convencao universal no arquivo do projeto se repete a cada projeto; convencao do projeto no global vaza para os outros.

5. **Nunca sobrescrever CLAUDE.md existente** — Proponha adicoes como diff. O usuario pode ter contexto importante que seria perdido.

6. **Global.cs e estado estatico** — Sempre incluir na auditoria a busca por `public static` mutavel. E o acoplamento mais insidioso e facil de esquecer.

7. **Atualizar docs apos migracao UI** — Quando a skill gera CLAUDE.md para um projeto que depois migra de WinForms para WPF, os nomes de arquivos UI e a descricao do stack ficam desatualizados. Sempre verificar se referencias a Form*.cs ainda existem apos migracao. Veja `references/decoupling-guide.md` secao "Checklist Pos-Migracao".

---

## Anti-padroes desta Skill

Evite estes erros ao executar o workflow:

- **Fixar SDK nao instalado** — global.json deve refletir o que `dotnet --list-sdks` retorna
- **Adicionar pacotes sem consultar** — Nao adicione FluentAssertions, NSubstitute etc. sem perguntar
- **Forcar MVVM em WinForms** — WinForms nao tem data binding nativo. Use Passive View/MVP como intermediario
- **Ignorar convencoes existentes** — Se o projeto usa portugues nos testes, mantenha. Se usa Assert direto, nao force FluentAssertions