'AI-Optimized Code Architecture: KI-optimierte Codebasis'

Jeder Entwickler, der KI-Programmierassistenten nutzt, kennt diesen Frust: Die KI schreibt Code, der fast funktioniert, verwendet aber die falschen Namenskonventionen, importiert aus dem falschen Pfad oder erfindet eine API, die gar nicht existiert. Die eigentliche Ursache ist fast immer eine schlechte Struktur der Codebasis und nicht etwa eine Einschränkung der KI.

KI-Assistenten sind Kontext-Vorhersage-Engines. Sie generieren die statistisch wahrscheinlichste Fortsetzung basierend auf dem gegebenen Kontextfenster. Eine gut strukturierte Codebasis erzeugt starke, konsistente Signale, welche die Qualität der Code-Generierung dramatisch verbessern.

Der KI-Code-Generierungs-Stack

So verarbeitet ein KI-Assistent eine Anfrage zur Code-Generierung:

In den mittleren Schritten — der Kontextsammlung und dem Musterabgleich (Pattern Matching) — ist die Struktur Ihrer Codebasis am wichtigsten.

Konsistente Namensgebung ist alles

Die wichtigste Verbesserung, die Sie vornehmen können: rückhaltlose Konsistenz bei der Namensgebung. Die KI lernt Ihre Muster anhand von Beispielen im Kontext.

// Schlecht — inkonsistente Muster verwirren die KI
const getUser = () => {...}
const fetchUserProfile = () => {...}
const loadUserSettings = () => {...}
const retrieveUserPosts = () => {...}

// Gut — konsistentes Verb-Nomen-Muster
const fetchUser = () => {...}
const fetchUserProfile = () => {...}
const fetchUserSettings = () => {...}
const fetchUserPosts = () => {...}

Wenn die KI fetchUser und fetchUserProfile sieht, leitet sie fetchUserSettings direkt beim ersten Versuch korrekt ab.

Gruppierung nach Feature, nicht nach Typ

Die meisten KI-Fehler entstehen, weil die KI nicht weiß, welche Komponente, welcher Hook oder welches Utility verwendet werden soll. Bei der Feature-basierten Gruppierung (Colocation) bleibt zusammengehöriger Code beieinander, sodass die KI den vollen Kontext hat:

src/features/
  auth/
    components/
      LoginForm.tsx
      RegisterForm.tsx
    hooks/
      useAuth.ts
      useAuthRedirect.ts
    api/
      authApi.ts
    types/
      auth.types.ts
    index.ts          ← Barrel-Export
  posts/
    components/...
    hooks/...
    api/
      postsApi.ts
    types/
      post.types.ts
    index.ts

Wenn Sie LoginForm.tsx öffnen, erkennt die KI, dass sich useAuth.ts in der Nähe befindet, und importiert daraus, anstatt eine eigene Auth-Logik zu erfinden.

Explizite Typ-Verträge

Definieren Sie Typen an einem einzigen Ort und importieren Sie diese überall. KI-Tools respektieren explizite Typendefinitionen weitaus besser als abgeleitete Typen, die über verschiedene Dateien verstreut sind:

// features/posts/types/post.types.ts
export interface Post {
  id: string
  title: string
  content: string
  authorId: string
  status: 'draft' | 'published' | 'archived'
  createdAt: Date
  updatedAt: Date
}

export interface CreatePostInput {
  title: string
  content: string
  status?: Post['status']
}

export interface PostFilters {
  status?: Post['status']
  authorId?: string
  page?: number
  limit?: number
}

Wenn die KI einen neuen Hook oder eine neue Komponente generiert, die mit Posts arbeitet, importiert sie diese Typen korrekt, da sie klar benannt und exportiert wurden.

Barrel-Exporte signalisieren Grenzen

index.ts-Dateien fungieren als öffentliche API-Deklarationen für Ihre Module. KI-Tools respektieren diese Grenzen:

// features/posts/index.ts
export { PostList } from './components/PostList'
export { PostDetail } from './components/PostDetail'
export { usePost, usePosts } from './hooks/usePosts'
export type { Post, CreatePostInput } from './types/post.types'
// Keine internen Implementierungsdetails exportieren

Die KI wird aus features/posts importieren, anstatt auf interne Pfade zuzugreifen.

Konsistente Muster zur Fehlerbehandlung

Definieren Sie Ihre Fehlerbehandlung einmal und nutzen Sie diese überall:

// lib/errors.ts
export class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500
  ) {
    super(message)
    this.name = 'AppError'
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} with id "${id}" not found`, 'NOT_FOUND', 404)
  }
}

export class ValidationError extends AppError {
  constructor(message: string, public field?: string) {
    super(message, 'VALIDATION_ERROR', 400)
  }
}

Sobald die KI dieses Muster in Ihrer Codebasis sieht, generiert sie auch ohne explizite Aufforderung die korrekte Fehlerbehandlung für alle neuen Features.

Dokumentieren Sie Ihre Invarianten

Kurze Kommentare zu nicht offensichtlichen Architekturentscheidungen verbessern die Qualität der KI-Ausgabe dramatisch:

// hooks/useOptimisticUpdate.ts

// INVARIANTE: onSettled immer aufrufen, unabhängig von Erfolg/Fehlschlag.
// Dies stellt sicher, dass wir Daten vom Server neu abrufen und nicht auf
// einem veralteten optimistischen State sitzen bleiben. Niemals vorzeitig aus onMutate zurückkehren.
export function useOptimisticUpdate<T>(...) {
  return useMutation({
    onMutate: async (variables) => {
      // ...
    },
    onSettled: () => {
      queryClient.invalidateQueries(...)  // Wird immer ausgeführt
    },
  })
}

Alles zusammenführen

Eine gut strukturierte Codebasis für KI-Unterstützung bietet:

1. Konsistente Namensgebung — Die KI sagt Namen anhand von Mustern korrekt voraus
2. Feature-Colocation — zusammengehöriger Code steht im selben Kontext
3. Explizite Typ-Verträge — Die KI importiert reale Typen und erfindet keine eigenen
4. Barrel-Exporte — klare Modulgrenzen, welche die KI respektiert
5. Dokumentierte Invarianten — Die KI lernt Ihre Architekturregeln

Die Templates in diesem Repo befolgen all diese Prinzipien. Das ist der Grund, warum Entwickler berichten, dass sie komplette Features mit nur einem einzigen Prompt generieren — die Codebasis gibt der KI alles an die Hand, was sie für ein erfolgreiches Ergebnis benötigt.