KI, Swift

KI-Skills für Swift

Schreibe einen Kommentar

Vor zwei Jahren half »Prompt Engineering« zu besseren Ergebnissen bei KI-Tools. Heute ist der Weg ein anderer:

  • Die Datei AGENTS.md (für die meisten KI-Tools) bzw. CLAUDE.md (für Claude Code) im Projektverzeichnis fasst wichtige Projektinformationen und Coding-Anweisungen zusammen. IDEs wie Cursor bzw. CLIs wie Claude Code oder Codex berücksichtigen diese Datei bei jedem Session-Start automatisch. Damit bietet diese Datei eine großartige Möglichkeit, das Default-Verhalten von KI-Tools den eigenen Ansprüchen anzupassen.

  • Skills ermöglichen es, Anweisungen für bestimmte Bearbeitungsschritte im Markdown-Format zu formulieren. Während AGENTS.md immer berücksichtigt wird, werden Skills nur bei Bedarf ausgewertet. Skills können auch Anweisungen für den Aufruf externer Tools beinhalten und ersetzen dann in manchen Fällen die MCP-Server-Konfiguration.

Dieser Beitrag zeigt die Anwendung von AGENTS.md und Skills speziell für die Programmiersprache Swift — aber losgelöst davon, ob Sie in Xcode arbeiten oder eine externe CLI verwenden. Der Artikel hat einen leichten Claude-Fokus, weil ich mich persönlich in der Anthropic-Welt wohler fühle als in der von OpenAI. Qualitativ gibt es keine großen Unterschiede zwischen beiden Systemen, beide funktionieren mittlerweile herausragend gut.

AGENTS.md bzw. CLAUDE.md auf Projekt-Ebene

Wenn Sie in Xcode mit Claude Agent oder Codex arbeiten, sollte Ihr erster Prompt in einem neuen Projekt /init lauten. Der Claude Agent bzw. Codex analysiert dann Ihren Code und erzeugt die Datei CLAUDE.md bzw. AGENTS.md. (AGENTS.md ist ein generischer Name. Die Datei wird von den meisten KI-Tools berücksichtigt, absurderweise aber nicht von Anthropic-Tools, die auf CLAUDE.md bestehen.)

Die Datei wird im Projektverzeichnis gespeichert; sie ist im Projektnavigator unsichtbar, weil dieser eine Verzeichnisebene tiefer ansetzt. Im Regelfall lohnt es sich, diese Datei in einem Editor nachzubearbeiten und dort bei Bedarf eigene Coding-Anweisungen hinzuzufügen.

Beachten Sie, dass die Datei bei jeder Session in den Kontext gelesen wird. Halten Sie sich daher kurz!

Die von Claude Code ohne meine Mithilfe generierte Datei CLAUDE.md für das Cart-Beispielprogramm (Kapitel 25 in meinem Swift-Buch) sieht beispielsweise so aus:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Run

This is an Xcode project (`family-cart.xcodeproj`). Build and run through Xcode or use the `BuildProject` MCP tool. There are no tests, no linter, and no package dependencies.

## Architecture

**Family Cart** is a SwiftUI shopping list app that syncs across family members via a REST API. The codebase follows a strict three-layer structure reflected in the folder naming:

### 1_model
- **ShoppingItem** — Immutable `struct` (Codable, Identifiable). All mutations produce new copies via the `with(...)` helper. Persisted locally as JSON in the Documents directory (`shoppingItems.json`). The `[ShoppingItem].save()` extension handles local persistence.
- **Category** — `@Observable class` with 10 predefined grocery categories. Each has a `shortcut` string (e.g. `"bread"`, `"veg"`, `"dairy"`) used as the foreign key in ShoppingItem. Categories are not persisted — they are recreated from `predefinedCategories()` on every launch. `Color(hex:)` extension lives here.

...
## Key Patterns

- **No Combine**: The app uses `@Observable` (Observation framework) and Swift concurrency (async/await). Avoid introducing Combine.
- **Immutable model pattern**: `ShoppingItem` is a struct. Always use `with(...)` to create modified copies, then `replaceItem(_:with:)` on the view model. Never mutate items in place.
- **Single ViewModel**: All state flows through `ShoppingViewModel`. Views receive it as a parameter (not via `@Environment`).
- **Categories as constants**: The 10 categories and their shortcuts are hardcoded. Category images use custom assets with `-fill` suffix variants for selected state.
- **Localization**: Strings are localized via `Localizable.xcstrings` (English + German). Category names use `LocalizedStringKey`.
- **Soft delete**: Items are never removed from the array — `deleteItem()` sets `isDeleted = true` and title to `"deleted"`.

## REST API

Backend at `cart.kofler.info:443`. Authentication via HMAC-SHA256 tokens that rotate every 5 minutes. Key endpoints:

- `GET /version` — connectivity test
- `GET/PUT /items/{family_id}` — pull/push shopping items
- `PUT /newfamily`, `PUT /newmember` — family setup
- `GET /family/{code}`, `GET /members/{family_id}` — family lookup

AGENTS.md bzw. CLAUDE.md auf Xcode-Ebene

Während AGENTS.md bzw. CLAUDE.md im Projektverzeichnis eben nur für dieses Projekt gilt, können Sie die gleichnamige Datei auch in speziellen Xcode-Verzeichnissen speichern. Die dort formulierten Regeln gelten dann für alle Projekte in Xcode, in denen Sie den jeweiligen Agenten zu Hilfe nehmen.

Die aktuelle KI-Integration sieht die folgenden beiden Verzeichnisse zur Konfiguration von Claude Agent bzw. Codex vor (Quelle):

~/Library/Developer/Xcode/CodingAssistant/codex
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig

Die dort gespeicherten Dateien werden — parallel zu eventuell ebenfalls vorhandenen gleichnamigen Dateien auf Projektebene — automatisch berücksichtigt, sobald Xcode Codex oder Claude Agent startet.

Vorsicht! Das ClaudeAgentConfig-Verzeichnis gilt nicht, wenn Sie in Xcode Claude verwenden. Es wird nur von Claude Agent berücksichtigt. Diese verwirrende Differenzierung zwischen zwei fast gleichnamigen KI-Features hat mir anfangs eine Menge Zeit gekostet.

Systemweite AGENTS.md-Dateien sind also der ideale Ort, um Swift- bzw. Xcode-spezifische Anweisungen zu speichern, die nichts mit einem konkreten Projekt zu tun haben. Es ist empfehlenswert, den Coding-Agenten dort Hinweise zu geben, dass diese ausschließlich moderne Swift-Sprachmerkmale (z.B. Concurrency) und SwiftUI-Features nutzen sollen.

Warum ist das so wichtig? Sprachmodelle werden mit im Internet verfügbaren Informationen trainiert. Dort überwiegen aber veraltete Informationen, die sich auf ältere Swift/SwiftUI-Versionen beziehen. Deswegen ist der von KI-Sprachmodellen generierte Code oft sub-optimal. (Dass Apple den Coding-Agenten via MCP Zugriff auf die aktuelle Dokumentation gibt, hilft nicht viel. Die KI erkennt gar nicht die Notwendigkeit, dort nachzusehen.)

Es gibt im Internet mehrere Vorlagen für AGENTS.md/CLAUDE.md. Die beste stammt meiner Ansicht nach von Paul Hudson (Hacking with Swift):

https://github.com/twostraws/SwiftAgents/blob/main/AGENTS.md

Laden Sie die Datei herunter, und speichern Sie diese unter einem der beiden folgenden Pfade:

~/Library/Developer/Xcode/CodingAssistant/codex/AGENTS.md
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/CLAUDE.md

Lesenswert ist dazu auch Hudsons Blog-Artikel What to fix in AI-generated Swift code!

AGENTS.md bzw. CLAUDE.md auf Systemebene

Die Dateien .claude/CLAUDE.md bzw. .codex/AGENTS.md erfüllen die gleiche Funktion, aber auf Systemebene und losgelöst von Xcode. Dort durchgeführte Einstellungen gelten allerdings für ALLE Programmiersprachen. Insofern ist es keine gute Idee, hier Swift- oder Xcode-spezifische Anweisungen zu speichern.

Wenn die Dateien CLAUDE.md bzw. AGENTS.md auf mehreren Ebenen (System, Xcode, Projekt) existieren, werden alle Dateien berücksichtigt und kombiniert. Umso wichtiger ist es, die Dateien nicht unnötig aufzublähen.

Swift-spezifische Skills

Skills verfolgen die gleiche Idee wie AGENTS-Dateien, formulieren also Regeln im Markdown-Format. Aber während die AGENTS-Dateien immer berücksichtigt werden, werden Skills nur bei Bedarf ausgewertet. Beispielsweise kann ein Skill-Dateiset Refactoring-Regeln enthalten. Erst wenn Sie in einem Prompt explizit Refactoring erwähnen (manchmal müssen Sie ganz explizit auf den Skill hinweisen), werden die dort gespeicherten Zusatzregeln berücksichtigt. Skills können auch Anweisungen für den Aufruf externer Tools beinhalten. Das ist an dieser Stelle aber kein Thema.

In den letzten Monaten haben einige Blogger Skill-Sets für Swift und SwiftUI zusammengestellt (siehe die Links am Ende dieses Beitrags). Ich greife an dieser Stelle den besonders nützlichen Skill SwiftUI Pro heraus:

https://github.com/twostraws/SwiftUI-Agent-Skill

Dieser Skill ist dazu gedacht, um in vorhandenen SwiftUI-Projekten einen Code Review durchzuführen — wahlweise via Claude Code, Codex CLI oder Xcode. Das KI-Sprachmodell durchsucht den Code dann nach veraltetem Code und macht Verbesserungsvorschläge. Das funktioniert großartig!!

Ein konkretes Anwendungsbeispiel im Zusammenspiel mit Claude Code folgt gleich. Vorerst geht es aber um die Installation, bei der es mehrere Varianten gibt, je nachdem ob Sie den Skill in einer CLI (Claude Code, Codex CLI) oder direkt in Xcode nutzen möchten.

Beginnen wir mit der Installation für CLI-Tools: Dazu öffnen Sie ein Terminalfenster und wechseln in das Projektverzeichnis. (Das Installationskommando setzt Node.js voraus. Führen Sie gegebenenfalls vorher brew install node aus.)

cd my-swiftui-project
npx skills add https://github.com/twostraws/swiftui-agent-skill --skill swiftui-pro

Während der Installation werden Sie gefragt, welche KI-Tools/Agenten Sie verwenden (z.B. Antigravity, Claude Code, Codex, Cursor usw.). Das hat Einfluss auf den Installationsort. Viele KI-Tools berücksichtigen das Verzeichnis .agents/skills, aber manche Tools wollen ihr eigenes Verzeichnis (z.B. .agent/skills oder .claude/skills). Dort werden standardmäßig Links auf die Dateien in .agents eingerichtet.

Außerdem müssen Sie sich entscheiden, ob die Skills universell für alle Projekte gelten sollen (Installation relativ zum Home-Verzeichnis) oder nur für ein Projekt (Installation im Projekt-Verzeichnis). Vor allem wenn Sie auf Ihrem Rechner Projekte in verschiedenen Programmiersprachen entwickeln, ist die projektspezifische Installation sicherer.

Die Xcode-Installation ist leider etwas umständlicher. Ich gehe davon aus, dass Sie vorher eine CLI-Installation in ein Projektverzeichnis durchgeführt haben. Von dort kopieren Sie nun das gewünschte Skills-Unterverzeichnis in das passende Xcode-Verzeichnis:

# für Claude Code
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills
cd my-swiftui-project
cp -a .claude/skills/swiftui-pro ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills

# für Codex
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/codex/skills
cd my-swiftui-project
cp -a .agents/skills/swiftui-pro ~/Library/Developer/Xcode/CodingAssistant/codex/skills

Jetzt sollten Sie sich noch vergewissern, dass der neue Skill wirklich im KI-Agenten Ihrer Wahl innerhalb von Xcode verfügbar ist (hier für Claude Code).

Kontrolle der Installation eines Skills in das Xcode-Claude-Agent-Verzeichnis

Der Aufruf des Skills variiert je nach Coding-Agent:

  • Claude Agent: /swiftui-pro funktioniert nicht. (Dieses Claude-Code-Kommando klappt nur in der CLI.) Vielmehr müssen Sie in Xcode einen Prompt formulieren, der so ähnlich wie diese Anweisung aussieht: »Use the SwiftUI Pro skill to look for problems in this project.«

  • Codex: $swiftui-pro

Anwendungsbeispiel mit Claude Code

Im Folgenden gehe ich davon aus, dass Sie mit Claude Code arbeiten. Nach dem Start vergewissern Sie sich mit dem Kommando /skills, dass Claude die Skill-Regeln swiftui-pro kennt. Den Code Audit starten Sie nun mit /swiftui-pro (bzw. in Codex mit $swiftui-pro).

cd my-swiftui-project
claude

> /skills

  ...

> /swiftui-pro 

  ...

  Summary

  1. Accessibility (high): Multiple icon-only buttons throughout
    (PlanTabView:66, SettingsTabView:159, CategoriesView:23/37) are invisible
    to VoiceOver. The CategoryHeader uses onTapGesture instead of Button, also
    problematic for VoiceOver.

  2. Deprecated API (high): foregroundColor() used in 6+ locations should be
    foregroundStyle().  cornerRadius() used in 3 locations should be
    clipShape(.rect(cornerRadius:)). tabItem() should be the modern Tab
    API. .autocapitalization() should be .textInputAutocapitalization(). Style
    struct instances (PlainButtonStyle(), etc.) should use static member
    syntax.

  3. Code organization (medium): Multiple type definitions per file throughout
     the view layer (PlanTabView has 3 types, SettingsTabView has 3,
     EditItemView has 3, CategoriesView has 2). Each should be in its own
     file. The itemsForEach method returning some View should be a dedicated
     View struct.

  4. Data flow (medium): Category class is @Observable but missing
     @MainActor. @State var vm in ShoppingTabView, PlanTabView, and
     CategoriesView is not marked private.

  5. Modern Swift (low): Use Date.now over Date(), URL.documentsDirectory over
     FileManager lookups, !items.isEmpty over items.count > 0, modern ISO 8601
     date parsing, and the Tab enum pattern for tab selection.

  The review is complete above. Would you like me to fix any of these issues?

Alle Probleme auf einmal zu beheben ist keine gute Idee. Besser gehen Sie schrittweise vor und erstellen nach jedem Fix und dem nachfolgenden Test Ihrer App Xcode einen Commit.

> fix foregroundColor()

  Done. Replaced all .foregroundColor() with .foregroundStyle() across 3 files:                            

  - ContentView.swift - 4 occurrences (debug overlay text colors)                                          
  - PlanTabView.swift - 2 occurrences (toggle button labels)              
  - SettingsTabView.swift - 3 occurrences (error text, warning text, sync time indicator) 

> ! git commit -a -m 'fixed foregroundColor -> foregroundStyle'
Start des Code Reviews
Zusammenfassung der gefundenen Probleme
Behebung eines der festgestellten Probleme

Lesetipps

AGENT-Dateien und Skills bestehen aus Markdown-Dateien. Selbst wenn Sie keine KI-Tools verwenden wollen, lohnt sich die Lektüre dieser Regeldateien. Sie werden nirgendwo sonst so kompakte Regeln zur richtigen Swift/SwiftUI-Programmierung finden! Lesen Sie beispielsweise die Anweisungen zur richtigen Verwendung von Actors aus dem Concurrency-Skill von Paul Hudson.

Quellen/Links

Grundlagen zu AGENTS.md/CLAUDE.md/Skills

Agentic Coding mit Xcode

Für Swift optimierten AGENTS.md-Dateien und Skills von Paul Hudson

Ähnliche Dateien/Skills von anderen Entwicklern

Videos

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Wenn Sie hier einen Kommentar absenden, erklären Sie sich mit der folgenden Datenschutzerklärung einverstanden.