Communitygithub.com

CharbelElBateh/personal-website

Como escrever Swift moderno corretamente — modelagem com tipos de valor, segurança contra data races no Swift 6, concorrência acessível (@concurrent, MainActor como padrão, actors, grupos de tarefas), protocolos e genéricos (some vs any), design de API, performance e ARC, Swift Testing, macros e os recursos modernos da linguagem que os agentes ainda não conhecem. Use ao escrever, revisar ou migrar Swift, ou ao corrigir erros de concorrência, travamentos, data races, ciclos de retenção ou problemas de performance.

O que é personal-website?

Esta skill capacita agentes de IA a escrever Swift moderno seguindo as melhores práticas da linguagem, com foco em Swift 6.4 e na linha de base da toolchain Swift 6.3. Ela é essencial para desenvolvedores que desejam modelar dados com tipos de valor, garantir segurança contra data races com o modelo de concorrência do Swift 6.2, e usar recursos como `@concurrent`, `MainActor` como padrão, `actor` e grupos de tarefas. A skill oferece orientação prática sobre progressão de complexidade: começar com código single-threaded no actor principal, adicionar concorrência apenas quando o perfil de desempenho mostrar gargalos, e usar `Sendable` e `@unchecked Sendable` com responsabilidade. Também abrange design de API, performance com ARC, Swift Testing, e macros, garantindo que o agente produza código eficiente, seguro e idiomático. A habilidade é particularmente útil para revisar código legado, migrar para Swift 6 ou resolver problemas complexos como data races e ciclos de retenção.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/write-swift

Perguntar na sua IA favorita

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

Documentação

Escreva Swift

Resposta Inicial

Quando esta skill for invocada pela primeira vez sem uma pergunta específica, responda apenas com:

Estou pronto para ajudar você a escrever Swift moderno, do jeito que a linguagem quer ser escrita.

Não forneça nenhuma outra informação até que o usuário faça uma pergunta.

Como escrever Swift do jeito que a linguagem quer ser escrita, atualizado até Swift 6.4.

Linha de base da toolchain: Swift 6.3 (versão atual em agosto de 2026). Tudo aqui compila no 6.3, a menos que marcado com ⚠, que sinaliza funcionalidades não lançadas do Swift 6.4. As orientações de concorrência assumem o modelo do Swift 6.2 — se o projeto estiver no 6.1 ou anterior, as regras da seção §3 sobre async e @concurrent não se aplicam.

A linha condutora: Swift é uma linguagem de divulgação progressiva. Comece com a coisa mais simples, mais estática e mais single-threaded que funciona, e compre dinamismo — concorrência, semântica de referência, existenciais, ponteiros inseguros — apenas onde você puder apontar o motivo. Cada regra abaixo é uma aplicação disso.

Modele esta hierarquia de padrões. Desça um nível apenas com um motivo que você possa declarar:

NecessidadeUseDesça apenas quando
Dadosstruct/enumprecisar de identidade, compartilhamento ou herança
Abstraçãotipo concretotiver código repetido entre tipos
Polimorfismosome P (genérico)precisar de armazenamento heterogêneo → any P
Execuçãoactor principal, síncronoo perfil mostrar um travamento → async → @concurrent → actor
MemóriaArray, Stringo perfil mostrar o custo → InlineArray, Span
SegurançaAPI segurainteroperabilidade com C ou um caminho crítico medido → Unsafe*

1. Modele dados com tipos de valor

Tipos de valor são o padrão em Swift, não um caso especial.

  • Use struct e enum como padrão. Use class apenas para identidade, estado mutável compartilhado, herança ou ciclo de vida de recurso. Uma janela, uma conexão de banco de dados, uma entidade armazenada em um motor de renderização — esses têm identidade. Um Ponto, uma Bebida, um Material não têm.
  • let por padrão; var apenas quando você altera. É a mesma disciplina de some antes de any e valor antes de referência: comece estreito, amplie com motivo.
  • Um struct com uma propriedade mutável de tipo referência não é nem valor nem referência. Cópias compartilham o objeto; mutações vazam entre cópias. Mantenha o tipo referenciado imutável, exponha apenas propriedades computadas que o delegam ou torne-o uma propriedade armazenada private por trás de copy-on-write.
  • Copy-on-write é como você obtém armazenamento fora da linha e semântica de valor. Encapsule uma classe final em um struct e verifique isKnownUniquelyReferenced(&storage) antes de alterar; copie primeiro se não for. É exatamente assim que Array, String e Dictionary funcionam.
  • Enums são a ferramenta para "um conjunto fixo de coisas" e para estado mutuamente exclusivo. Substituir uma pilha de propriedades armazenadas opcionais (isSharing, selectedRows, shareTarget) por uma enum State torna combinações inválidas irrepresentáveis e torna a mudança de estado atômica em vez de uma sequência de escritas de propriedade que você pode esquecer de concluir.
  • Compor valores produz um valor. Um struct cujas propriedades armazenadas são todas tipos de valor tem semântica de valor gratuitamente — o que torna desfazer, diff e restauração de estado um único caminho de código em vez de um por propriedade.
struct Material {                       // semântica de valor preservada
  var roughness: Double
  private var _texture: Texture         // uma classe

  var color: Color {
    get { _texture.color }
    set {
      if !isKnownUniquelyReferenced(&_texture) { _texture = Texture(copying: _texture) }
      _texture.color = newValue
    }
  }
}

Tipos não copiáveis (~Copyable) expressam propriedade exclusiva: um descritor de arquivo, uma transferência bancária, um recurso aberto. Suprimir a cópia transforma "você não deve executar isso duas vezes" de uma asserção em um erro de compilação e torna deinit em um struct significativo. Marque o método finalizador como consuming para que o compilador prove que é o último uso. A propriedade de parâmetro se torna explícita: borrowing (somente leitura, o padrão), consuming (toma posse), inout/mutating (acesso de escrita temporário).


2. Erros e optionals — torne os caminhos de falha visíveis

O tratamento de erros do Swift se apoia em três pontos: fontes de erro são marcadas para que não possam surpreender; erros carregam contexto suficiente para agir; e erros recuperáveis são diferentes de erros de programador.

  • Recuperável → throw. Erro de programador → precondition/fatalError. Uma chamada de rede falha mantém o programa em execução. Um índice fora dos limites significa que o código está errado e deve parar antes que o bug se torne um problema de segurança.
  • Enums com valores associados são os melhores tipos de erro. case duplicateFriend(String) é melhor que case duplicateFriend — o contexto é o ponto principal.
  • guard para condições de erro, porque força o caminho de saída. if let para o desembrulho comum.
  • throws(MyError) com tipo explícito é para funções internas, código genérico que encaminha erros e ambientes restritos onde encapsular any Error é muito custoso. Para API pública, throws sem tipo preserva sua liberdade de mudar o tipo de erro depois. Observe a unificação: throws é throws(any Error), e sem lançamento é throws(Never) — o que permite que map abstraia sobre ambos.
  • Force-unwrap apenas onde você puder declarar a invariante, e prefira um #require/precondition com falha e uma mensagem em vez de um ! simples.

3. Concorrência: fique single-threaded até que o perfil diga o contrário

Esta é a seção que os agentes mais erram, porque o modelo mudou no Swift 6.2.

Inicie cada aplicativo inteiramente na thread principal. Código single-threaded vai longe, e a maioria dos aplicativos nunca precisa sair dela.

A progressão, em ordem. Não pule etapas.

  1. Single-threaded no actor principal. Nenhuma concorrência. Bom para a maioria dos aplicativos.
  2. async/await para ocultar latência (rede, disco). Ainda sem concorrência própria — APIs do SDK como URLSession.data(from:) descarregam em seu nome.
  3. @concurrent para mover seu trabalho pesado para fora da thread principal — apenas depois que o Instruments mostrar um travamento.
  4. actor para mover estado para fora do actor principal — apenas quando muito estado do actor principal está forçando tarefas a voltar constantemente.

Ative as configurações de compilação corretas primeiro. Ative Concorrência Acessível em todos os projetos. Para módulos de aplicativo e módulos voltados para UI, defina também Isolamento de Actor Padrão como MainActor — é o padrão para novos projetos de aplicativo no Xcode 26, e elimina a maioria das suas anotações @MainActor. Em um pacote: swiftSettings: [.defaultIsolation(MainActor.self)]. Não defina MainActor como padrão para uma biblioteca de uso geral — bibliotecas devem fornecer APIs nonisolated e deixar os clientes decidirem onde o trabalho é executado.

A regra que mudou

No Swift 6.2, marcar uma função como async não a move para fora do actor atual. Ela é executada onde foi chamada. Isso é o que torna "o código mais natural de escrever" livre de data races por padrão.

  • @concurrent — sempre alterna para o pool de threads concorrentes. Use em seu trabalho pesado de CPU.
  • nonisolated — executa onde é chamada. Este é o padrão correto para APIs de biblioteca, porque o chamador decide. nonisolated em um tipo torna todos os seus membros nonisolated (Swift 6.1+).
  • Nem um nem outro — permanece no actor do chamador.
nonisolated struct PhotoProcessor {          // desacoplado do actor principal
  @concurrent                                // garantido para executar em segundo plano
  func process(_ data: Data) async -> ProcessedPhoto {
    async let sticker = extractSticker(data)  // dois trabalhos independentes, em paralelo
    async let colors  = extractColors(data)
    return await ProcessedPhoto(sticker: sticker, colors: colors)
  }
}
  • Crie perfil antes de descarregar. Use Instruments (Time Profiler, travamentos). Se o código puder ser acelerado sem concorrência, faça isso primeiro. Concorrência tem custo real — alocação de tarefas, escalonamento e raciocínio.
  • Não crie uma tarefa para trabalho trivial. Uma tarefa filha para ler um valor de UserDefaults custa mais do que economiza.
  • Uma tarefa por operação de ponta a ponta. Trabalho que deve acontecer em ordem vai em uma tarefa; operações independentes recebem tarefas separadas para que o runtime possa intercalá-las.
  • await é um ponto de suspensão e quebra a atomicidade. O estado pode mudar enquanto você está suspenso, e você pode retomar em uma thread diferente. Reavalie as suposições após cada await. Nunca segure um lock através de um. Nunca confie em armazenamento local de thread através de um.

Reentrância de Actor

Actors garantem exclusão mútua, não transações. Entre dois awaits no mesmo actor, outro trabalho é executado.

  • Altere o estado do actor em métodos síncronos. Código síncrono em um actor é executado até o fim sem interrupção — essa é sua fronteira de transação.
  • Mantenha métodos async do actor enxutos, compostos de operações transacionais síncronas, e deixe o actor em um estado consistente em cada await.
  • O bug clássico: verificar cache → await download → escrever cache. Duas tarefas erram, ambas baixam, a segunda sobrescreve a primeira. Reavalie após o await ou desduplique o trabalho em andamento.
  • Actors não são FIFO. Eles executam o trabalho de maior prioridade primeiro, precisamente para evitar inversão de prioridade. Se você precisar de ordenação, use uma tarefa (que executa do início ao fim) ou um AsyncStream, não um actor.

4. Sendable e compartilhamento de dados

Sendable marca um tipo como seguro para compartilhar entre domínios de isolamento. O compilador verifica em cada fronteira de tarefa e actor.

  • Tipos de valor são Sendable quando seu armazenamento é — inferido automaticamente para tipos não públicos. Tipos públicos nunca têm sendability inferida: marcar um tipo público como Sendable é uma promessa para seus clientes, então Swift obriga você a escrevê-lo.
  • Actors e classes @MainActor são implicitamente Sendable, porque seu estado é isolado.
  • A maioria das classes de modelo não deve ser nem @MainActor nem Sendable. Mantenha-as intencionalmente não Sendable — isso impede que metade do modelo seja alterada na thread principal enquanto a outra metade é alterada em segundo plano. Se precisarem sair do actor principal, torne-as nonisolated, não Sendable.
  • Você ainda pode enviar um objeto não Sendable entre domínios desde que o remetente pare de usá-lo. Faça todas as suas alterações antes de entregá-lo; tocar nele depois é o erro.
  • Closures também capturam estado. Marque um tipo de função como @Sendable apenas se ele genuinamente cruzar domínios.
  • @unchecked Sendable é uma promessa que o compilador não pode verificar. Reserve para tipos com sincronização interna real (um Mutex, um lock). O mesmo vale para nonisolated(unsafe) em um global — último recurso, não um silenciador de avisos.

Quando você encontrar um erro de data race, percorra esta lista:

  1. Não compartilhe. Mova o objeto compartilhado para um local para que cada trabalho concorrente tenha sua própria instância. (Esta é a correção para a grande maioria dos erros reais.)
  2. Transforme-o em um tipo de valor Sendable, para que "compartilhar" seja realmente copiar.
  3. Isole-o em um actor — o actor principal ou o seu próprio.
  4. Só então recorra a Mutex/Atomic do módulo Synchronization (armazene-os em propriedades let) ou @unchecked Sendable.

Variáveis globais e estáticas são a fonte mais comum de erros. Em ordem de preferência: transforme em let; coloque em @MainActor; encapsule em um Mutex; nonisolated(unsafe). Observe que globais em Swift são inicializados lentamente e atomicamente — diferente de C.

Ligando APIs de callback antigas: anote protocolos delegados com @MainActor se você os possui. Se não possui, marque o método como nonisolated e use MainActor.assumeIsolated { } — ele afirma em vez de saltar, então trava alto em vez de correr silenciosamente. @preconcurrency na conformidade é a abreviação para a mesma coisa. Use @preconcurrency import para silenciar temporariamente avisos de sendability de um módulo que não migrou; os avisos voltam — corretamente — quando ele migra.


5. Concorrência estruturada

Sempre prefira tarefas estruturadas.

Tarefas estruturadas (async let, grupos de tarefas) têm escopo como variáveis locais: não podem sobreviver ao bloco, são aguardadas automaticamente e herdam cancelamento, prioridade e valores locais de tarefa através da árvore de tarefas. Tarefas não estruturadas (Task { }, Task.detached) não oferecem nada disso automaticamente.

  • async let para um número fixo e estaticamente conhecido de filhos concorrentes.
  • withTaskGroup quando o número é dinâmico. Grupos de tarefas conformam a AsyncSequence — itere os resultados conforme chegam. Use withDiscardingTaskGroup quando os filhos não retornam nada: libera os recursos de cada filho imediatamente e cancela irmãos no primeiro erro.
  • Task { } apenas quando o tempo de vida do trabalho não se encaixa em um escopo — reagir a um callback de delegate, um toque de botão, uma view aparecendo. Ele herda isolamento de actor e prioridade; você deve gerenciar o cancelamento manualmente.
  • Task.detached quase nunca. Não herda nada — nem isolamento, nem prioridade, nem valores locais de tarefa. Se você precisar de uma raiz destacada, coloque um grupo de tarefas dentro dela em vez de destacar repetidamente.

Cancelamento é cooperativo. Cancelar define uma flag; não para nada. Verifique Task.isCancelled ou try Task.checkCancellation() antes de iniciar trabalho caro, e também em auxiliares síncronos. Para trabalho que está suspenso em vez de em execução (o next() de uma AsyncSequence), use withTaskCancellationHandler — e lembre-se de que o handler executa imediatamente e concorrentemente com o corpo, então o estado que ele toca precisa de sincronização real (um atômico ou um lock, não um actor — você não pode garantir ordenação em um actor).

Limite sua concorrência. Não distribua um filho por item em uma lista sem limites. Inicie N filhos e depois adicione um novo apenas quando um filho terminar.


[Nota: O conteúdo original foi truncado; a tradução continua até onde o texto original foi fornecido.]

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

Habilidades Relacionadas