Agents Development Guide

Worum geht es?

Dieser Guide erklaert, wie du Agent-Verhalten fuer Codex und OpenAI-basierte Developer-Workflows entwirfst. Der Fokus liegt auf der praktischen Entscheidung: wann du AGENTS.md schreibst, wann eine Skill sinnvoll ist, wann du einen Custom Subagent definierst, wann MCP oder Plugins die richtige Erweiterung sind und wann du mit der OpenAI Agents SDK eine echte Anwendung baust.

1. Starte mit der richtigen Bedeutung von "Agent"

"Agent" kann mehrere Dinge meinen. Waehle immer die kleinste Oberflaeche, die zur Aufgabe passt.

Begriff	Was es ist	Am besten fuer
Main Codex agent	Die aktive Codex-Session in App, CLI oder IDE	Normale Repo-Arbeit, Implementierung, Review, Debugging
AGENTS.md	Dauerhafte Anweisungen, die Codex vor der Arbeit laedt	Repo-Konventionen, Commands, Safety-Regeln, Sprachpolicy
Skill	Wiederverwendbarer Workflow mit Anweisungen, Referenzen und optionalen Scripts	Wiederkehrende Aufgaben wie Docs-Review, Release-Checks, Migrationen
Custom subagent	Benannter Codex-Worker mit eigenen Anweisungen und optionalen Model-/Config-Defaults	Parallele Exploration, Review-Spezialisten, fokussierte Analyse
MCP server	Live-Tools und Kontext fuer Codex	Externe Systeme, private Daten, Docs-Lookup, Browser/Figma/GitHub/Sentry-Tools
Plugin	Installierbares Paket fuer Skills, MCP-Konfiguration, Hooks und Assets	Teilen wiederverwendbarer Faehigkeiten ueber Maschinen, Repos oder Teams hinweg
OpenAI Agents SDK	Developer-Framework fuer agentische Anwendungen	Produktive Agents mit Tools, Handoffs, Tracing, Guardrails und eigener Produktlogik

Faustregel: Nutze AGENTS.md fuer Regeln, Skills fuer Workflows, Custom Subagents fuer parallele Spezialisten, MCP fuer Live-Tools, Plugins fuer Distribution und die Agents SDK fuer Produkte.

2. Entscheidungshilfe

Nutze diese Tabelle, bevor du etwas erstellst.

Bedarf	Erstelle	Warum
Codex soll immer Repository-Regeln befolgen	AGENTS.md	Wird automatisch entdeckt und gilt fuer jede Aufgabe im Scope
Eine wiederkehrende Aufgabe braucht einen konsistenten Ablauf	Skill	Gibt Codex eine wiederverwendbare Prozedur, ohne jeden Prompt aufzublaehen
Eine Aufgabe soll in parallele Spezialisten aufgeteilt werden	Custom subagent	Haelt laute Exploration aus dem Hauptthread heraus
Codex braucht private oder aktuelle externe Daten	MCP server oder Connector	Gibt Codex Tool-Zugriff statt Modellgedaechtnis oder Websuche
Ein Workflow soll fuer andere installierbar sein	Plugin	Paketiert Skills und zugehoerige Integrationsmetadaten
Du baust ein agentisches Produkt	OpenAI Agents SDK	Gibt dir programmatische Kontrolle, Tracing, Handoffs und Guardrails
Du brauchst nur ein einmaliges Verhalten	Prompt instructions	Dauerhafte Dateien waeren unnoetiger Aufwand

Mache nicht aus jeder Vorliebe einen Agent. Dauerhaftes Agent-Verhalten sollte sich lohnen: Es sollte wiederholtes Prompting reduzieren, Fehler verhindern oder einen Workflow leichter pruefbar machen.

3. Agent-Design-Checkliste

Beantworte diese Fragen, bevor du eine Datei schreibst:

Frage	Gute Antwort
Welche Aufgabe soll dieser Agent erledigen?	Ein Satz mit klarem Verb und Objekt
Wann soll er laufen?	Explizite Trigger, Scope und Ausschluesse
Welche Inputs braucht er?	Dateien, Branches, URLs, Issue-Nummern, Docs, Environment-Werte
Welche Outputs soll er liefern?	Patch, Report, Checkliste, Summary, Testergebnis, Entscheidung
Welche Tools darf er nutzen?	Shell, Datei-Edits, MCP-Tools, Web, Browser, externe APIs
Was muss er vermeiden?	Destruktive Commands, Secret-Leaks, breite Refactors, nicht unterstuetzte Pfade
Wie wird Erfolg verifiziert?	Build, Tests, Lint, manueller Check, Quellenangabe, Diff-Review
Was passiert bei Unsicherheit?	Fragen, Annahmen markieren, vor riskanten Aktionen stoppen oder Fallback nutzen

Starke Agents sind eng geschnitten. Ein "reviewer for correctness, security, regressions, and missing tests" ist nuetzlich. Ein "do everything better" Agent ist es nicht.

4. AGENTS.md: dauerhafte Regeln fuer Codex

Nutze AGENTS.md, wenn Codex Projektregeln automatisch befolgen soll.

Guter Inhalt:

• Repository-Struktur,
• Build-, Test-, Lint- und Validierungscommands,
• Code-Style und Naming-Regeln,
• Dokumentations-Sprachpolicy,
• Security- und Secret-Regeln,
• Review-Erwartungen,
• lokale Workflow-Hinweise wie WSL, Docker, Package Manager oder CI-Annahmen.

Vermeide:

• lange Tutorials,
• veraltete Produktdokumentation,
• persoenliche Vorlieben, die nicht ins Repo gehoeren,
• riesige eingefuegte READMEs,
• Regeln, die mit bestehendem Tooling kollidieren.

Beispiel:

# Repository Guidelines

## Documentation

- Write all source docs under `docs/` in English.
- Put German translations under `i18n/de/`.
- Keep code examples, comments, variable names, and command labels in English.

## Validation

- Run `yarn build` after documentation changes.
- Mention existing unrelated warnings in the final summary.

Platzierung

Scope	Ort
Persoenliche Defaults	~/.codex/AGENTS.md
Temporaerer persoenlicher Override	~/.codex/AGENTS.override.md
Ganzes Repository	AGENTS.md im Git-Root
Subtree-spezifische Regeln	AGENTS.md oder AGENTS.override.md in diesem Verzeichnis

Dateien naeher am aktuellen Working Directory werden spaeter geladen und koennen breitere Regeln ueberschreiben.

5. Skills: wiederverwendbare Workflows

Erstelle eine Skill, wenn Codex denselben Workflow wieder und wieder ausfuehren soll.

Gute Skill-Beispiele:

• "Review Docusaurus MDX changes for broken links and build risks."
• "Prepare a release note from merged PRs."
• "Migrate one API endpoint to the new auth helper."
• "Audit a Terraform change for IAM risk."
• "Create a plugin scaffold with the required manifest."

Minimale Struktur:

.agents/
  skills/
    docs-review/
      SKILL.md

SKILL.md:

---
name: docs-review
description: Review Docusaurus MDX changes for broken links, sidebar metadata, build risks, and translation drift.
---

1. Inspect changed MDX files and nearby docs conventions.
2. Check links, headings, frontmatter, admonitions, code fences, and i18n counterparts.
3. Run the documented validation command when practical.
4. Report correctness and build issues before style suggestions.

Gute Skill-Descriptions schreiben

Codex kann eine Skill implizit anhand ihrer description waehlen. Schreibe die Description deshalb wie einen Trigger:

• nenne die genaue Aufgabe,
• erwaehne wichtige Tools oder Dateitypen,
• beschreibe Grenzen,
• halte sie kurz genug, damit sie auch bei vielen installierten Skills nicht ihre Aussage verliert.

Gut:

description: Review Docusaurus MDX changes for links, frontmatter, sidebars, i18n, and build failures.

Schwach:

description: Helps with docs.

Wann Scripts oder Referenzen sinnvoll sind

Halte eine Skill instruction-only, bis sie deterministisches Verhalten braucht.

Ergaenze	Wenn
references/	Der Workflow stabile Beispiele, Policies, Templates oder Schemas braucht
scripts/	Der Workflow wiederholbare Parsing-, Generierungs-, Validierungs- oder API-Schritte braucht
assets/	Der Workflow Templates, Bilder, Fixtures oder Starter-Dateien braucht
agents/openai.yaml	Du Codex-App-Metadaten, Tool-Dependencies oder explizite Invocation-Policy willst

Nutze Scripts fuer mechanische Checks und Instructions fuer Urteilskraft. Ein Script kann kaputte Frontmatter schnell finden; Codex sollte trotzdem beurteilen, ob die Seite gut lesbar ist.

6. Custom subagents: parallele Spezialisten

Erstelle einen Custom Subagent, wenn eine Aufgabe von einem benannten Worker mit eigenen Anweisungen profitiert. Das ist nuetzlich fuer parallele Reviews, Exploration oder Analyse.

Gute Subagent-Beispiele:

• reviewer: correctness, regressions, security, and missing tests.
• explorer: read-heavy codebase mapping before implementation.
• docs-auditor: docs structure, i18n drift, broken links, and MDX risks.
• test-triage: failing test logs, likely root cause, and smallest fix path.
• security-checker: secret exposure, auth boundaries, injection, and unsafe commands.

Persoenliche Agents liegen unter:

~/.codex/agents/

Projekt-Agents liegen unter:

.codex/agents/

Beispiel fuer einen Custom Agent:

name = "docs-auditor"
description = "Review documentation changes for structure, broken links, i18n drift, MDX issues, and validation gaps."
developer_instructions = """
Review documentation like a maintainer.
Prioritize broken builds, broken links, incorrect routing, stale translations, and missing validation.
Do not rewrite prose unless the user explicitly asks for edits.
Return findings with file references and a short validation summary.
"""
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

Nutzung per Prompt:

Spawn a docs-auditor subagent to review this branch for Docusaurus and i18n issues. Wait for the result, then summarize only actionable findings with file references.

Wann Subagents nicht sinnvoll sind

Vermeide Subagents, wenn:

• die Aufgabe klein ist,
• Edits sich stark ueberschneiden wuerden,
• du einen eng kontrollierten Implementierungsthread brauchst,
• Tokenkosten wichtiger sind als parallele Geschwindigkeit,
• der Workflow sensible Approvals braucht, die in einem Thread leichter zu ueberwachen sind.

Subagents erben die aktuellen Sandbox- und Approval-Kontrollen. Behandle sie als Worker innerhalb derselben Safety-Grenze, nicht als Weg, diese zu umgehen.

7. MCP: Tools und Live-Kontext

Nutze MCP, wenn ein Agent Faehigkeiten braucht, die er nicht allein aus Dateien bekommt.

Gute MCP-Nutzungen:

• interne Docs durchsuchen,
• GitHub-Issues oder PRs lesen,
• einen Browser inspizieren,
• Sentry abfragen,
• Figma-Designs lesen,
• interne Developer-Tools aufrufen,
• offizielle Dokumentation abrufen.

MCP ist nicht dasselbe wie eine Skill:

Skill	MCP
Sagt Codex, wie es arbeiten soll	Gibt Codex Tools oder Daten
Liegt als Dateien vor	Laeuft als Server oder Connector
Gut fuer wiederholbare Prozeduren	Gut fuer Live-Systeme und privaten Kontext
Kann Scripts aufrufen	Stellt typisierte Tools bereit

Beispiel-Konfiguration:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

Gute MCP-Server-Instructions sollten Workflow-Grenzen, Rate Limits und Tool-Boundaries erklaeren. Halte den Anfang eigenstaendig, weil Codex ihn bereits beim Entscheiden nutzen kann, ob der Server passt.

8. Plugins: Faehigkeiten paketieren und teilen

Erstelle ein Plugin, wenn eine Skill oder Integration installierbar sein soll, statt manuell kopiert zu werden.

Nutze Plugins fuer:

• Skills im Team teilen,
• mehrere Skills buendeln,
• MCP-Konfiguration buendeln,
• App-Mappings oder UI-Metadaten ausliefern,
• Lifecycle Hooks verteilen,
• einen kuratierten internen Marketplace erstellen.

Minimale Plugin-Struktur:

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    docs-review/
      SKILL.md

plugin.json:

{
  "name": "docs-workflows",
  "version": "1.0.0",
  "description": "Reusable documentation review workflows.",
  "skills": "./skills/"
}

Starte mit lokalen Skills, solange du den Workflow noch entwirfst. Paketier ein Plugin, sobald der Workflow stabil genug zum Teilen ist.

9. OpenAI Agents SDK: agentische Produkte bauen

Nutze die OpenAI Agents SDK, wenn du nicht nur Codex konfigurierst, sondern eine eigene agentische Anwendung baust.

Waehle die Agents SDK, wenn du brauchst:

• application-owned tools,
• Handoffs zwischen Agents,
• Guardrails,
• Traces und Observability,
• wiederholbares Produktionsverhalten,
• produktspezifische Auth und Datenzugriffe,
• Tests und Deployment rund um den Agent.

Minimales Pattern:

from agents import Agent, Runner, function_tool

@function_tool
def lookup_order(order_id: str) -> str:
    return "Order data from the application database"

support_agent = Agent(
    name="Support Agent",
    instructions=(
        "Answer using company policy. "
        "Use tools when the user asks about an order. "
        "Escalate when policy is missing."
    ),
    tools=[lookup_order],
)

result = Runner.run_sync(
    support_agent,
    "Summarize order A123 and suggest the next support action.",
)

print(result.final_output)

Der wichtigste Unterschied: Codex Agents helfen dir, Software zu entwickeln. Agents-SDK-Agents sind Software, die du entwickelst.

10. Erstellungsworkflow

Nutze diese Reihenfolge fuer jede neue Agent-Faehigkeit.

1. Formuliere das Job Statement.
2. Waehle die kleinste Oberflaeche aus der Entscheidungshilfe.
3. Schreibe die Instructions in klarer Sprache.
4. Fuege nur die Tools und Dateien hinzu, die der Workflow wirklich braucht.
5. Teste mit zwei einfachen Prompts und einem adversarial oder uneindeutigen Prompt.
6. Pruefe, ob der Agent im richtigen Moment nachfragt.
7. Verifiziere Outputs mit Build, Tests, Quellenangaben oder Review.
8. Verschiebe das Verhalten erst dann von Prompt nach AGENTS.md, Skill, Subagent, MCP, Plugin oder SDK, wenn es sich als nuetzlich erweist.

Beispiel fuer ein Job Statement:

When documentation files change, review the branch for Docusaurus build risks, broken links, stale German translations, and source-language policy violations. Return actionable findings first and mention validation performed.

Dieses Statement wird wahrscheinlich eine Skill. Wenn du sie parallel mit Security- und Implementierungsreview laufen lassen willst, erstelle zusaetzlich einen Custom Subagent, der diese Skill nutzt.

11. Qualitaetscheckliste

Bevor du einen Agent als "fertig" betrachtest, pruefe:

• Der Name ist spezifisch und stabil.
• Die Description sagt, wann er laufen soll und wann nicht.
• Instructions definieren Inputs, Outputs, Tools und Grenzen.
• Codebeispiele und Commands sind Englisch.
• Es gibt einen Verifikationspfad.
• Secrets muessen nicht in Source-Dateien liegen.
• Der Agent faellt sicher aus, wenn Daten fehlen.
• Er vermeidet breite Refactors, ausser sie werden explizit verlangt.
• Er laesst sich mit einem kleinen Prompt testen.
• Team-Scope lebt im Repo, nicht nur im Home-Verzeichnis einer Person.

12. Empfohlenes Setup fuer dieses Repository

Fuer dieses Docusaurus-Repo passt diese Schichtung:

Bedarf	Empfohlener Ort
Source Docs muessen Englisch sein und Uebersetzungen liegen in i18n	Root AGENTS.md
Wiederholbarer Docs-Review-Workflow	.agents/skills/docs-review/SKILL.md
Paralleler Docs-Spezialist fuer groessere Branches	.codex/agents/docs-auditor.toml
Offizieller OpenAI-Docs-Lookup	MCP server oder bestehende OpenAI Docs Skill
Spaeter teamweite Installation	Plugin, sobald der Workflow stabil ist

Starte mit AGENTS.md plus einer Docs-Review-Skill. Fuege Custom Subagents erst hinzu, wenn der Branch gross genug ist, dass paralleles Review wirklich Zeit spart.

13. Nuetzliche Prompts

Skill erstellen:

Create a repo-local skill named docs-review. It should review changed MDX files for Docusaurus build risks, broken links, sidebar metadata, i18n drift, and source-language policy violations. Keep the skill instruction-only for now.

Custom Subagent erstellen:

Create a project custom agent named docs-auditor. It should review documentation changes, use medium reasoning, avoid rewriting prose by default, and return actionable findings with file references.

Subagents fuer Review nutzen:

Review this branch with parallel subagents. Spawn one reviewer for correctness, one docs-auditor for Docusaurus and i18n, and one test-triage agent for validation gaps. Wait for all results and summarize only actionable findings.

Richtige Oberflaeche entscheiden:

I want Codex to do this repeatedly: <workflow>. Should this be a prompt, AGENTS.md rule, skill, custom subagent, MCP server, plugin, or Agents SDK app? Recommend the smallest durable option and explain why.