Zentrales Management der AGENTS.md

Hast du schon einmal in einem Repository mit Cursor oder Copilot gearbeitet und plötzlich ganz andere Vorschläge bekommen als noch im letzten Repository, obwohl eigentlich dieselben Konventionen gelten sollten?

Genau diese Beobachtung hatten wir im Kunden-Projekt immer häufiger. Die Qualität und Verlässlichkeit der KI-gestützten Entwicklerwerkzeuge hängt maßgeblich davon ab, welche Regeln, Schreibstile und Konventionen sie berücksichtigen sollen. Genau dafür gibt es die AGENTS.md. Sie legt pro Repository fest, wie sich die KI-Tools verhalten sollen. Wenn diese Datei jedoch uneinheitlich gepflegt wird, führt das zwangsläufig zu unterschiedlichen KI-Ergebnissen, selbst wenn Teams eigentlich dieselben Standards verfolgen möchten.

Damit die AGENTS.md ihren Zweck zuverlässig erfüllen kann, muss sie überall aktuell, einheitlich und vollständig vorliegen. In der Realität gab es jedoch zahlreiche Varianten. Manche Repositories hatten ältere Stände, manche nutzten leicht abweichende Beschreibungen und in einigen existierte die Datei noch gar nicht. Das führte zu widersprüchlichen KI-Vorschlägen und insgesamt zu einer weniger konsistenten Entwicklererfahrung.

Um dieses Problem nachhaltig zu lösen, haben wir ein neues zentrales Repository erstellt. Dort wird die AGENTS.md künftig als gemeinsame und verlässliche Quelle gepflegt. Ein automatisierter Prozess synchronisiert diese Datei anschließend in alle konfigurierten Ziel-Repositories. Dadurch greifen Cursor, Copilot und andere Werkzeuge immer auf denselben Regelstand zu, unabhängig davon, in welchem Repository man arbeitet. Falls erforderlich, können weiterhin repositoryspezifische Varianten genutzt werden, wenn unterschiedliche Technologien oder fachliche Anforderungen dies notwendig machen.

name: Sync AGENTS.md to other repos

on:
  push:
    paths:
    - 'java/AGENTS.md'    # only trigger when this file changes
  workflow_dispatch:      # allow manual trigger from Actions tab

jobs:
  sync-java-agents-md:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout AI repo
      uses: actions/checkout@v4

    - name: Sync AGENTS.md to target repos
      uses: actions/github-script@v7
      with:
        github-token: ${{ secrets.REPO_SYNC_TOKEN }}
        script: |
          const fs = require('fs');
          const path = require('path');
          
          // 1) Read the source file
          const filePath = path.join(process.cwd(), 'java/AGENTS.md');
          const content = fs.readFileSync(filePath, 'utf8');
          const encodedContent = Buffer.from(content, 'utf8').toString('base64');
          
          // 2) Define the repos you want to sync to
          const targetRepos = [
            'repo-1',
            'repo-2',
            'repo-3',
            'repo-4',
            'repo-5',
            'repo-6',
            'repo-7',
            'repo-8',
            'repo-9'
          ];
          
          // 3) Function to upsert AGENTS.md in a repo root
          async function upsertAgents(owner, repo) {
            const filePath = 'AGENTS.md';
            let sha = undefined;
          
            // Try to get existing file (to keep history via sha)
            try {
              const { data: file } = await github.rest.repos.getContent({
                owner,
                repo,
                path: filePath,
              });
          
              // Only if it's a file
              if (!Array.isArray(file)) {
                sha = file.sha;
              }
            } catch (err) {
              if (err.status === 404) {
                // File does not exist yet – that's fine, we'll create it
                console.log(`AGENTS.md does not exist in ${owner}/${repo}, will create it.`);
              } else {
                throw err;
              }
            }
          
            // Create or update the file
            await github.rest.repos.createOrUpdateFileContents({
              owner,
              repo,
              path: filePath,
              message: 'Sync AGENTS.md from AI prompt library repo',
              content: encodedContent,
              sha,
              committer: {
                name: 'Agents Bot',
                email: '[email protected]',
              },
              author: {
                name: 'Agents Bot',
                email: '[email protected]',
              },
            });
          
            console.log(`Synced AGENTS.md to ${owner}/${repo}`);
          }
          
          // 4) Iterate over all target repos
          (async () => {
            for (const full of targetRepos) {
              const [owner, repo] = full.split('/');
              console.log(`Syncing to ${owner}/${repo}...`);
              await upsertAgents(owner, repo);
            }
          })();

Der technische Aufbau umfasst eine zentrale AGENTS.md Datei, eine einfache Konfiguration aller Ziel-Repositories und einen Sync-Prozess, der sämtliche Änderungen zuverlässig verteilt. Das Ganze ist als GitHub Actions Pipeline umgesetzt. Parallel entwickeln wir die Struktur der AGENTS.md im CDSE-Projekt weiter, damit die KI-Werkzeuge künftig auf einer klar definierten und für alle nachvollziehbaren Grundlage arbeiten können.

Auf diese Weise erreichen wir konsistentere KI-Ergebnisse, weniger manuellen Pflegeaufwand und eine deutlich einheitlichere Arbeitsweise. Je stärker wir KI-gestützte Entwicklungswerkzeuge einsetzen, desto wichtiger wird eine zentrale Steuerung der Regeln, auf denen sie basieren.

Weitere Verbesserungen wie der Sync spezifischer AGENTS.md Varianten sind bereits geplant.