CLAUDE.md richtig aufbauen

Stellen Sie sich folgendes Experiment vor: Sie geben Claude Code den Prompt „Implementiere ein Repository für die Product-Entity nach bestehendem Muster.“ Das Projekt nutzt Minimal APIs, EF Core, ein Repository-Pattern und FluentValidation. Beim ersten Durchlauf ist die CLAUDE.md leer. Der Agent erzeugt ein generisches Repository mit statischen Helpern, schreibt die Validierung in den Controller und ignoriert Unit-of-Work. Beim zweiten Durchlauf beschreibt die CLAUDE.md Architektur, Konventionen und Anti-Patterns. Das Ergebnis sieht aus, als hätte ein erfahrenes Teammitglied es geschrieben. Gleicher Prompt, völlig andere Qualität.

Dieser Unterschied ist kein Zufall. Eine CLAUDE.md ist das Interface, über das ein Entwickler Architekturwissen an einen Coding-Agenten übergibt. Dieser Artikel zeigt, wie Sie eine solche Datei in fünf Blöcken aufbauen.

Was ist eine CLAUDE.md?

Die Datei liegt im Root eines Git-Repos und wird bei jeder Sitzung automatisch eingelesen. Sie wird zum System-Prompt des Agenten. Andere Tools haben ähnliche Mechanismen: GitHub Copilot liest .github/copilot-instructions.md, Cursor nutzt .cursorrules. Das Prinzip ist universell.

Wichtig ist, was sie nicht sein sollte: kein Tutorial, keine API-Doku, kein Architektur-Dokument im klassischen Sinne. Sie richtet sich an einen Agenten, der Code lesen kann, aber Kontext braucht, den Code allein nicht transportiert. Warum EF Core statt Dapper? Warum Unit-of-Work? Eine gute CLAUDE.md beantwortet das durch knappe Regeln.

Block 1: Architektur-Überblick

Der erste Block liefert den technologischen Rahmen. Ohne ihn rät der Agent: Controller statt Minimal APIs, AutoMapper statt manuellem Mapping, ein Pattern, das nicht zum ORM passt.

# Architektur
- .NET 8 mit Minimal APIs (keine Controller)
- PostgreSQL mit EF Core 8 (Code-First)
- CQRS: Commands über MediatR,
  Queries direkt über Dapper
- Authentifizierung über Keycloak (OIDC)
- Docker Compose für lokale Entwicklung

Jede Zeile ist eine Entscheidung, die der Agent nicht treffen muss. .NET 8 mit Minimal APIs heißt app.MapGet() statt [HttpGet]. CQRS mit MediatR und Dapper heißt: Lesezugriffe umgehen den ORM, Schreibzugriffe laufen über Handler. Das ist komprimierter Kontext für den Agenten, nicht Dokumentation für Kollegen.

Block 2: Konventionen und Patterns

Der zweite Block definiert, wie Technologien eingesetzt werden. In .NET mit Repository-Pattern ist die Spannbreite enorm: direkte DbContext-Injektion oder Unit-of-Work, Validierung im Service oder per Pipeline. Ohne Regeln würfelt der Agent.

# Konventionen
- Repository-Pattern mit IUnitOfWork
  (siehe src/Infrastructure/UnitOfWork.cs)
- FluentValidation für alle Commands
  (Validator im selben Ordner wie Handler)
- Mapping manuell in Extension Methods
  (kein AutoMapper)
- Fehlerbehandlung über Result<T>-Pattern
  (siehe src/Shared/Result.cs)

Jede Regel enthält eine Referenz auf eine konkrete Datei. Der Agent bekommt Regel und Beispiel. Er kann die Datei lesen und das Pattern replizieren. Eine Regel ohne Vorlage lässt Spielraum. Eine Vorlage ohne Regel gibt kein Kriterium. Beides zusammen ergibt präzise Ergebnisse.

Block 3: Anti-Patterns

Der wirkungsvollste Teil. Positive Regeln sagen, was der Agent tun soll, verhindern aber nicht, dass er zusätzlich Unerwünschtes einbaut. Ein Agent, der Unit-of-Work kennt, kann trotzdem einen Service Locator ergänzen:

# Anti-Patterns (NICHT verwenden)
- KEIN Service Locator
  (IServiceProvider nicht injizieren)
- KEINE statischen Helper-Klassen
  (stattdessen Extension Methods)
- KEINE direkten DB-Zugriffe aus Endpoints
  (immer über Repository/Handler)
- KEIN AutoMapper
- KEINE Async-Void-Methoden

Ohne diesen Block generiert Claude Code in circa 30 Prozent der Fälle einen Service Locator. Mit dem Block fällt das auf null. Die Großbuchstaben KEIN und KEINE sind kein Stilmittel, sondern ein Signal, das die Aufmerksamkeit des Agenten zuverlässig erhöht.

Block 4: Referenzen auf Vorlagen

Dieser Block macht die CLAUDE.md zum Steuerungsinstrument. Statt nur Patterns zu benennen, zeigt er konkrete Referenzimplementierungen:

# Vorlagen
Für neue Features orientiere dich an:
- CQRS-Command:
  src/Features/Orders/CreateOrder/
    CreateOrderCommand.cs
    CreateOrderHandler.cs
    CreateOrderValidator.cs
- Repository:
  src/Infrastructure/Repositories/
    OrderRepository.cs
- Integration-Test:
  tests/Integration/Orders/
    CreateOrderTests.cs

Der Agent liest gezielt die Vorlagen anstelle des gesamten Projekts. Ohne Referenzen variiert die Struktur von Feature zu Feature. Mit Referenzen entsteht Code wie aus einem Guss.

Block 5: Projektspezifische Regeln

Block fünf enthält implizites Teamwissen, das normalerweise nur in den Köpfen der Entwickler existiert:

# Projektregeln
- Features in Ordnern nach Domäne,
  z.B. src/Features/Orders/
- Tests: xUnit + FluentAssertions,
  Schema: MethodName_Scenario_Expected
- Integration-Tests: WebApplicationFactory
  mit Testcontainers für PostgreSQL
- Commits: Conventional Commits
  (feat:, fix:, refactor:, test:)

Ohne diese Regeln erzeugt der Agent Tests mit Assert.Equal statt FluentAssertions, benennt Methoden falsch und legt Features in der falschen Struktur an. Der Code kompiliert, aber jeder Review erfordert Nacharbeit.

ADRs als Kontext-Erweiterung

Die fünf Blöcke decken den stabilen Kern ab. Aber Projekte entwickeln sich. Hier kommen Architecture Decision Records ins Spiel. Die CLAUDE.md enthält die aktuelle Wahrheit, ADRs das Warum. Dokumentiert eine ADR, dass das Team von Dapper zu EF Core migriert ist, baut der Agent keine Dapper-Queries in neue Features ein.

# Architektur-Entscheidungen
Siehe docs/adr/ fuer Details.
Besonders relevant:
- ADR-001: CQRS mit MediatR statt
  klassischem Service-Layer
- ADR-003: EF Core statt Dapper
  für Commands (Testbarkeit)
- ADR-007: Result<T> statt Exceptions

Der Agent liest ADRs bei Bedarf. Das erweitert den Kontext dynamisch, ohne die CLAUDE.md aufzublähen. Faustregel: unter 200 Zeilen. Alles darüber gehört in referenzierte Dokumente.

Praxistest: Mit und ohne CLAUDE.md

Derselbe Prompt zweimal: „Implementiere ein ProductRepository mit CRUD-Operationen.“ Ohne CLAUDE.md zeigt der Code typische Agent-Artefakte:

// Ohne CLAUDE.md generiert
public class ProductRepository
{
  private readonly AppDbContext _ctx;
  public ProductRepository(
    AppDbContext ctx) => _ctx = ctx;
  public static ProductDto ToDto(
    Product p)
    => new() { Id = p.Id,
      Name = p.Name };
  public async Task<Product?> GetById(
    int id)
    => await _ctx.Products
      .FindAsync(id);
}

DbContext direkt statt IUnitOfWork. Statische Mapping-Methode statt Extension. Kein Interface. Kein Compilerfehler, aber jeder Review fällt durch. Und nun mit CLAUDE.md:

// Mit CLAUDE.md generiert
public class ProductRepository
  : IProductRepository
{
  private readonly IUnitOfWork _uow;
  public ProductRepository(
    IUnitOfWork uow) => _uow = uow;
  public async Task<Result<Product>>
    GetByIdAsync(int id)
  {
    var product = await _uow.Context
      .Products.FindAsync(id);
    return product is null
      ? Result<Product>
        .Failure("Product not found")
      : Result<Product>
        .Success(product);
  }
}

IUnitOfWork, Result-Pattern, Interface, Async-Suffix. Dazu Validator, Handler und Unit-Test nach Vorlage. Der Code hätte einen Review bestanden. Der Aufwand für die CLAUDE.md: zwei Stunden. Manuelles Korrigieren eines Features: 30 bis 60 Minuten. Nach dem vierten Feature ist die Investition amortisiert.

Checkliste: Ist Ihre CLAUDE.md produktionsreif?

Fünf Kriterien: Fasst ein Architektur-Block Stack und Patterns in maximal zehn Zeilen zusammen? Definieren Konventionen mit Datei-Referenzen die Spielregeln? Adressieren Anti-Patterns häufige Agent-Fehler? Verweisen ADR-Referenzen auf Architekturentscheidungen? Bleibt die Datei unter 200 Zeilen? Beginnen Sie mit Architektur-Block und Anti-Patterns für den größten Soforteffekt.

Dokumentation als Interface

Die CLAUDE.md ist Symptom eines Wandels: Dokumentation wird von einem Nebenprodukt zur Voraussetzung. Wer gut dokumentiert, bekommt bessere KI-Ergebnisse. Wer besser dokumentiert als das Nachbarteam, liefert schneller. Dokumentation wird zur strategischen Kompetenz, ein Thema, das der Hauptartikel dieser Serie unter [1] vertieft.

Eine gepflegte CLAUDE.md nützt nicht nur dem Agenten. Sie nützt neuen Teammitgliedern, Ihnen selbst nach Monaten Abwesenheit und zwingt Sie, Tribal Knowledge explizit zu machen.

Im nächsten Teil wird es um ADRs gehen: Wie man sie schreibt, pflegt und den Agent-Kontext systematisch erweitert. Die CLAUDE.md ist das Fundament. ADRs sind die Wände. Zusammen entsteht ein Gebäude, in dem Agenten nicht raten, sondern wissen.

[1] Patrick Schnell, Der Stellenwert von Developern in Zeiten von KI, dotnetpro 4/2026, Seite 6 ff.