Codex-Projektvorlage

Diese Vorlage ist ein kleiner, sprachneutraler Ausgangspunkt für kontrollierte Codex-Arbeitsabläufe. Sie legt Arbeitsregeln, Planung, Tests, Prüfung und CI fest, ohne eine Programmiersprache, ein Buildsystem oder ein Framework vorzugeben.

Sie enthält:

• AGENTS.md mit dauerhaften Arbeitsregeln für Codex,
• prompts/ mit wiederverwendbaren Auftragsschablonen,
• .codex/skills/ mit Arbeitsabläufen für Fehleranalyse, Testplanung und Änderungsprüfung,
• scripts/check.sh als einheitlichen lokalen und CI-Prüfpunkt,
• eine GitHub-Actions-CI im Vorlagenmodus,
• docs/ für Architektur, Projektplanung, Entscheidungen und Checklisten.

Informationen zur Entstehung der Vorlage stehen unter AUTOR.md.

Ausgefüllte Startaufträge für typische Projektarten stehen in SCHNELLSTART.md, zum Beispiel für C++, Java, Webentwicklung und Videoprojekte.

Kurzfassung

1. Diese Vorlage zuerst an ein konkretes Projekt anpassen.
2. Echte Build-, Test-, Lint- und Formatprüfungen in scripts/project-check.sh hinterlegen.
3. Platzhalter in docs/ARCHITECTURE.md und docs/PROJECT_PLAN.md ersetzen.
4. CI vom Vorlagenmodus auf den Projektmodus umstellen.
5. .template-state erst danach entfernen und ./scripts/check.sh ausführen.

Im frisch kopierten Zustand ist die Vorlage absichtlich noch kein grünes Projekt. Für die Pflege der unveränderten Vorlage dient ./scripts/check.sh --template; für ein fertig initialisiertes Projekt dient ./scripts/check.sh.

Für wen diese Vorlage gedacht ist

Geeignet ist die Vorlage für kleine bis mittlere Softwareprojekte, bei denen Codex kontrolliert im Repository arbeiten soll: mit klaren Regeln, nachvollziehbaren Aufträgen, echten Prüfungen und kleinen Änderungssätzen. Sie passt besonders gut, wenn Laufzeit, Framework und Buildsystem noch bewusst vom konkreten Projekt abhängen sollen.

Die Vorlage ist bewusst deutschsprachig. Für internationale Teams kann eine englische Kurzfassung oder eine übersetzte Kopie der Projektregeln sinnvoll sein.

Grenzen

Nicht geeignet ist sie als fertiger Framework-Starter. Sie enthält absichtlich keine Beispielanwendung, keine Paketmanager-Konfiguration und keine vorgetäuschten Standardtests. Wer sofort eine lauffähige Webapp, CLI oder Bibliothek erwartet, sollte diese Vorlage zuerst initialisieren oder einen sprachspezifischen Starter verwenden.

Vorlage verwenden

Begriffe

• Vorlagenmodus: prüft, ob diese noch nicht initialisierte Vorlage vollständig und konsistent ist. Befehl: ./scripts/check.sh --template.
• Projektmodus: prüft ein fertig initialisiertes Projekt mit dessen echten projektbezogenen Prüfungen. Befehl: ./scripts/check.sh.
• .template-state: Markerdatei für den noch nicht initialisierten Zustand. Sie wird erst entfernt, wenn alle Projektangaben, Prüfungen und CI-Schritte eingerichtet sind.
• scripts/project-check.sh: projektspezifischer Prüfpunkt für Build, Tests, Lint und Format. Die mitgelieferte .example-Datei ist nur ein sicherer Ausgangspunkt und schlägt ohne Anpassung absichtlich fehl.

1. Repository kopieren und projektspezifischen Namen sowie Zweck eintragen.
2. Laufzeit, Buildsystem und Abhängigkeiten des Projekts festlegen.
3. Anwendungscode unter src/, Verhaltenstests unter tests/ und kleine nachvollziehbare Beispiele unter examples/ ablegen. Abweichende, in der gewählten Sprache übliche Verzeichnisse sind möglich und werden dann in AGENTS.md dokumentiert.
4. Die projektspezifischen Prüfungen in scripts/project-check.sh anlegen. scripts/project-check.sh.example zeigt einen sicheren Ausgangspunkt, der ohne projektspezifische Befehle absichtlich fehlschlägt.
5. Laufzeit und Werkzeuge in .github/workflows/ci.yml ergänzen und dort ./scripts/check.sh --template durch ./scripts/check.sh ersetzen.
6. Architektur, Akzeptanzkriterien und Risiken unter docs/ konkretisieren und alle Platzhalter […] in docs/ARCHITECTURE.md und docs/PROJECT_PLAN.md ersetzen.
7. Die Datei .template-state als letzten Initialisierungsschritt entfernen.
8. ./scripts/check.sh ausführen und erst bei erfolgreichem Ergebnis mit der Implementierung beginnen.

Schnellstart für die Initialisierung

Die folgenden Befehle zeigen den typischen technischen Ablauf. Sie ersetzen nicht das Ausfüllen der fachlichen Inhalte in docs/ und die echten Prüfkommandos im Projektcheck.

# 1. Projektspezifischen Prüfpunkt vorbereiten.
cp scripts/project-check.sh.example scripts/project-check.sh
chmod +x scripts/project-check.sh

# 2. In scripts/project-check.sh die Beispielmeldung durch echte Build-, Test-,
#    Lint- und Formatprüfungen des gewählten Ökosystems ersetzen.

# 3. docs/ARCHITECTURE.md und docs/PROJECT_PLAN.md ausfüllen.
#    Ein mögliches ausgefülltes Muster steht in docs/examples/PROJECT_PLAN.example.md.

# 4. .github/workflows/ci.yml vom Vorlagenmodus auf den Projektmodus umstellen:
#    ./scripts/check.sh --template  ->  ./scripts/check.sh

# 5. Optional prüfen, welche Initialisierungsschritte noch offen sind.
./scripts/doctor.sh

# 6. Erst als letzten Schritt den Vorlagenmarker entfernen und vollständig prüfen.
rm .template-state
./scripts/check.sh

scripts/doctor.sh ist nicht-destruktiv: Das Skript ändert keine Dateien, sondern meldet nur offene Initialisierungsschritte.

Einheitlicher Prüfpunkt

./scripts/check.sh

Im unveränderten Vorlagenzustand schlägt dieser Befehl absichtlich fehl, weil noch kein echtes Projekt konfiguriert ist. Nutze dann ./scripts/check.sh --template. Erst nach der Initialisierung ist ./scripts/check.sh der richtige vollständige Prüfpunkt.

Das Skript prüft immer grundlegende Repository-Eigenschaften. Im normalen Projektmodus stellt es zusätzlich sicher, dass die Initialisierung abgeschlossen ist: .template-state muss entfernt, die Platzhalter in Architektur und Projektplan müssen ersetzt und die CI muss auf den Projektmodus umgestellt sein. Anschließend ruft es über das ausführbare scripts/project-check.sh die projektspezifischen Build-, Test-, Lint- und Formatprüfungen auf. Solange eine dieser Voraussetzungen fehlt, endet die Prüfung mit einer verständlichen Fehlermeldung. So kann eine noch nicht konfigurierte Vorlage nicht versehentlich als fachlich geprüft gelten.

Die Initialisierung gilt erst dann als abgeschlossen, wenn alle folgenden Bedingungen erfüllt sind:

• .template-state wurde entfernt.
• In docs/ARCHITECTURE.md und docs/PROJECT_PLAN.md steht kein Platzhalter […] mehr.
• .github/workflows/ci.yml ruft ./scripts/check.sh statt ./scripts/check.sh --template auf.
• scripts/project-check.sh existiert, ist ausführbar und enthält die echten Build-, Test-, Lint- und Formatprüfungen des Projekts.

Für die Pflege der noch nicht initialisierten Vorlage und für reine Dokumentationsänderungen stehen eingeschränkte Prüfmodi bereit:

./scripts/check.sh --template       # vollständige Prüfung der Vorlage
./scripts/check.sh --structure-only # Struktur-, Diff- und Skript-Syntaxprüfung
./scripts/doctor.sh                 # offene Initialisierungsschritte anzeigen

Der Vorlagenmodus wird durch die mitgelieferte CI verwendet. Nach der Initialisierung muss die CI auf den normalen Projektcheck umgestellt werden.

Die lokale Codex-Konfiguration startet bewusst ohne Netzwerkzugriff. Aktiviere Netzwerk nur projekt- oder auftragsbezogen, wenn Paketmanager, Dokumentation, GitHub-Zugriffe oder andere externe Dienste wirklich benötigt werden. Lesezugriffe auf GitHub über gh sind in AGENTS.md geregelt; schreibende externe Aktionen brauchen weiterhin einen ausdrücklichen Auftrag.

Ein möglicher Hook sieht beispielsweise so aus:

#!/usr/bin/env bash
set -euo pipefail

# Durch die Befehle des gewählten Ökosystems ersetzen:
your-build-command
your-test-command
your-lint-command
your-format-check-command

Mit Codex arbeiten

Kurzes Auftragsbeispiel

Gewünschte Veränderung im Nutzerablauf: CSV-Berichte lassen sich als UTF-8 laden
Heutiger Zustand: Umlaute werden in einigen Tabellenprogrammen beschädigt
Betroffene Rollen: Mitarbeitende im Controlling
Beobachtbarer Erfolgsnachweis: Der Export enthält „München“ unverändert
Unveränderliche Leitplanken: Der PDF-Export bleibt unverändert
Bekannter technischer Kontext: src/export/ und tests/export/
Prüfweg: ./scripts/check.sh

Codex erhält Informationen aus mehreren Quellen, die unterschiedliche Aufgaben haben:

• AGENTS.md enthält die dauerhaften Arbeitsregeln des Projekts. Codex liest diese Datei automatisch, bevor es mit einer Aufgabe beginnt.
• SCHNELLSTART.md enthält ausgefüllte Startaufträge für typische Projektarten. Sie helfen beim ersten Anpassen einer frisch kopierten Vorlage.
• docs/ enthält tatsächliches Projektwissen wie Architektur, Planung und Entscheidungen. Diese Dateien werden bei Bedarf als fachlicher Kontext gelesen.
• .codex/skills/ enthält wiederverwendbare Arbeitsabläufe, beispielsweise für Fehleranalyse, Testplanung oder Änderungsprüfung. Ein Arbeitsablauf ergänzt den konkreten Auftrag, ersetzt ihn aber nicht.
• prompts/ enthält manuelle Auftragsschablonen. Codex liest diese Dateien nicht automatisch. Du wählst eine passende Vorlage aus, füllst sie aus und sendest den ausgefüllten Text als deine Anfrage an Codex.

Einen Auftrag vorbereiten

1. Wähle die Vorlage, die am besten zu deiner Aufgabe passt:
   • prompts/initialisierung.md für die kontrollierte Anpassung dieser Vorlage an ein konkretes Projekt,
   • prompts/funktionsauftrag.md für eine neue Funktion,
   • prompts/fehleranalyse.md für einen reproduzierbaren Fehler,
   • prompts/strukturpflege.md für eine Strukturverbesserung ohne neues Verhalten,
   • prompts/pruefung.md für eine Prüfung ohne Dateiänderungen.
2. Öffne die Datei und kopiere den Inhalt des Textblocks in deine Anfrage an Codex.
3. Ersetze jeden Platzhalter […] durch konkrete Angaben. Unbekannte Angaben dürfen als „noch offen“ markiert werden; wichtige Fehlermeldungen und Reproduktionsschritte sollten vollständig sein.
4. Entferne Punkte, die nachweislich nicht zur Aufgabe gehören, oder führe sie ausdrücklich als Nicht-Ziele auf. So bleibt der Auftrag klein und eindeutig.
5. Sende den ausgefüllten Auftrag. Codex kombiniert ihn mit den Regeln aus AGENTS.md, dem vorhandenen Code, den Tests und gegebenenfalls einem passenden Arbeitsablauf.

Für die erste Anpassung eines frisch kopierten Repositorys ist meist prompts/initialisierung.md der beste Startpunkt. Die Datei enthält mehrere Varianten: vollständige Initialisierung, nur Projektcheck einrichten, Architektur und Projektplan ausfüllen, bestehende Initialisierung prüfen oder bei noch unklarer Werkzeugwahl zunächst nur Entscheidungen sammeln.

Die Platzhalter in prompts/ bleiben bei der Initialisierung dieser Vorlage absichtlich erhalten, damit die Dateien für jeden neuen Auftrag wiederverwendet werden können. Dauerhafte Regeln gehören stattdessen in AGENTS.md und projektspezifisches Wissen in docs/.

Nach einer Änderung führst du den passenden Prüfmodus aus und prüfst den Diff:

• ./scripts/check.sh --template bei der Pflege dieser Vorlage,
• ./scripts/check.sh im initialisierten Projekt,
• ./scripts/check.sh --structure-only bei reinen Dokumentationsänderungen.

Struktur

.
├── .codex/                     # lokale Codex-Konfiguration und Arbeitsabläufe
├── .github/                    # CI sowie automatisch erkannte GitHub-Vorlagen
├── .env.example                # Vorlage für dokumentierte Umgebungsvariablen
├── .template-state             # Marker der noch nicht initialisierten Vorlage
├── AGENTS.md                   # dauerhafte Projektregeln
├── AUTOR.md                    # Herkunft und Autorenschaft der Vorlage
├── docs/                       # Architektur, Planung, Entscheidungen, Checklisten
├── docs/examples/              # ausgefüllte, nicht verbindliche Dokumentationsmuster
├── ERWEITERUNGEN.md            # empfohlene Codex-Erweiterungen
├── examples/                   # Beispiele oder projekttypische Alternative
├── LICENSE                     # Lizenz der übernommenen Vorlagenbestandteile
├── MCP.md                      # Orientierung zu typischen MCP-Integrationen
├── prompts/                    # Auftragsschablonen, inklusive Initialisierung
├── SCHNELLSTART.md             # ausgefüllte Startaufträge für typische Projekte
├── scripts/check.sh            # einheitlicher Prüfpunkt
├── scripts/project-check.sh.example # Beispiel für projektspezifische Prüfungen
├── src/                        # Anwendungscode oder projekttypische Alternative
└── tests/                      # Verhaltenstests oder projekttypische Alternative

Bewusste Grenzen

Die Vorlage liefert weder Beispielanwendung noch vorgetäuschte Standardbefehle. Welche Compiler, Paketmanager, Testwerkzeuge und Qualitätsprüfungen richtig sind, hängt vom konkreten Projekt ab und muss bei dessen Initialisierung festgelegt werden.

„Sprachneutral“ bedeutet hier nicht „plattformneutral“: Der einheitliche Prüfpunkt ist ein Bash-Skript und setzt eine Unix-artige Umgebung oder unter Windows beispielsweise WSL beziehungsweise Git Bash voraus.

Lizenz

Diese Vorlage steht unter der Apache License 2.0.

Die Nutzung der Vorlage legt die Lizenz eines daraus entstehenden Projekts nicht fest. Übernommene Bestandteile der Vorlage unterliegen weiterhin der Apache License 2.0 und den darin genannten Hinweispflichten.

Ein abgeleitetes Projekt kann eine eigene Lizenz wählen. In diesem Fall sollte die Projektlizenz klar von den übernommenen Vorlagenbestandteilen getrennt werden, zum Beispiel durch einen zusätzlichen Hinweis in der eigenen README oder in einer separaten NOTICE-Datei. Herkunftshinweise in AUTOR.md dürfen ergänzt werden; die Herkunft der übernommenen Vorlage sollte dabei nachvollziehbar bleiben.

English short summary

This repository is a German, language-neutral Codex project template. It provides project rules, documentation placeholders, prompt templates, reusable Codex workflows, CI guardrails and a single verification entry point. It intentionally does not include an example application or fake default build commands. Before using it as a real project, replace the placeholders, add a real scripts/project-check.sh, switch CI from template mode to project mode, remove .template-state, and run ./scripts/check.sh.