Codex – Erweiterte Nutzungstipps

Nach Abschluss der Basisinstallation und der ersten Konversation liegt der eigentliche Wert von Codex darin, es in Ihren täglichen Entwicklungs-Workflow einzubinden.

Dieser Artikel behandelt fünf fortgeschrittene Bereiche: Projektkonfiguration, Sitzungsverwaltung, Editor-Integration, CI/CD-Automatisierung und Tipps zum Prompting. Damit helfen Sie Codex, Ihr Projekt zu verstehen, sich Ihre Konventionen zu merken und in der Pipeline automatisch zu arbeiten.

1. Schreiben Sie ein „Onboarding-Dokument“ für Codex mit AGENTS.md

AGENTS.md ist ein Projekthandbuch, das für Codex geschrieben wurde. Im Projekt-Wurzelverzeichnis abgelegt, wird es bei jedem Start automatisch geladen und bleibt während der gesamten Sitzung aktiv.

Warum Sie es benötigen

Standardmäßig weiß Codex nichts über Ihr Projekt.

Es weiß nicht, ob Sie App Router oder Pages Router verwenden, nicht, über welche Datei Datenbankoperationen einheitlich abgewickelt werden sollen, und nicht, welche Dateien nicht verändert werden sollten.

Wenn Sie in jeder Konversation den Hintergrund erneut erklären müssen, ist die Effizienz sehr gering und Fehler sind wahrscheinlich.

Mit AGENTS.md können diese Informationen einmal geschrieben werden und bleiben in Kraft, was erspart, sich selbst zu wiederholen.

Was geschrieben werden sollte

Eine effektive AGENTS.md enthält normalerweise vier Arten von Informationen: Projektübersicht, Tech-Stack, wichtige Konventionen und Verbote.

Das Folgende ist ein vollständiges Beispiel:

# AGENTS.md

## 项目概述
这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。
使用 App Router，不使用 Pages Router.

## 技术栈
- 前端：Next.js 14, React 18, TailwindCSS, shadcn/ui
- 后端：Next.js API Routes, Prisma ORM
- 数据库：PostgreSQL 15
- 认证：NextAuth.js

## 重要约定
- 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例
- API 路由错误统一用 lib/api-error.ts 处理
- 环境变量在 .env.local 中，参考 .env.example

## 禁止事项
- 不要修改 prisma/schema.prisma，除非我明确要求
- 不要删除任何现有测试
- 生产环境的 .env 文件不要碰

Der Abschnitt „Verbote“ ist besonders wichtig. Bei der Ausführung von Aufgaben leitet Codex aktiv ab, welche Dateien geändert werden müssen. Ohne klare Grenzen kann es Stellen berühren, die Sie nicht anfassen möchten. Rote Linien klar zu formulieren ist viel einfacher, als Probleme zu beheben, nachdem sie aufgetreten sind.

Hierarchische Struktur der Konfiguration

AGENTS.md unterstützt drei Verschachtelungsebenen, wobei die Priorität von niedrig nach hoch angeordnet ist.

Je näher eine Datei am aktuellen Verzeichnis liegt, desto höher ist ihre Priorität. Im selben Verzeichnis wird AGENTS.md auf derselben Ebene übersprungen, wenn AGENTS.override.md vorhanden ist.

Die globale Ebene eignet sich für Konventionen, die für alle Projekte gelten, zum Beispiel:

# ~/.codex/AGENTS.md

## 全局约定
- 安装依赖时优先使用 pnpm
- 修改 JavaScript 文件后始终运行 npm test
- 新增生产依赖前先请求确认

Nach Abschluss der Konfiguration können Sie den folgenden Befehl verwenden, um zu überprüfen, ob das Laden korrekt ist:

codex --ask-for-approval never "Summarize the current instructions."

2. Sitzungsverwaltung: Große Aufgaben über Tage hinweg fortsetzen

Die Sitzungsverwaltungsfunktion ermöglicht es Ihnen, den aktuellen Gesprächsstatus in eine Datei zu exportieren und ihn beim nächsten Mal direkt wiederherzustellen, ohne den Hintergrund erneut einzurichten.

Hintergrund

Das Kontextfenster von Codex ist begrenzt.

Wenn Sie eine große Aufgabe bearbeiten, die sich über mehrere Dateien erstreckt und schrittweise vorangebracht werden muss, geht der Kontext verloren, wenn Sie das Terminal zwischendurch schließen oder zu etwas anderem wechseln und später zurückkommen – Codex erinnert sich nicht daran, was zuvor besprochen wurde oder welche Entscheidungen getroffen wurden.

Durch den Export der Sitzung kann dieses Problem gelöst werden, sodass Sie den vorherigen Gesprächsstatus zu jedem Zeitpunkt wiederherstellen können.

Grundlegende Verwendung

Die folgenden sind gängige Befehle im Zusammenhang mit der Sitzungsverwaltung:

Wann exportieren

Sie müssen nicht jede Unterhaltung exportieren. Die folgenden Situationen sind es wert, gespeichert zu werden:

3. Integration mit VS Code

Codex bietet offiziell eine VS Code-Erweiterung. Nach der Installation können Sie Gespräche direkt im Editor starten, ohne zum Terminal wechseln zu müssen.

Installation und Anmeldung

Die Installationsschritte sind wie folgt:

• Schritt 1: Öffnen Sie den Erweiterungsmarktplatz (Cmd/Ctrl + Shift + X).

• Schritt 2: Suchen Sie nach "Codex" oder "OpenAI Codex" und installieren Sie das offizielle Plugin.

  

• Schritt 3: Für die erste Verwendung müssen Sie sich bei Ihrem ChatGPT-Konto anmelden.

• Schritt 4: Sobald das Codex-Symbol in der Seitenleiste erscheint, ist es einsatzbereit.

Nach der Installation kannst du die folgenden Tastaturkürzel für schnelle Aktionen verwenden:

BYO-Modus (für Nutzer ohne ChatGPT-Abonnement)

Wenn du bereits deinen eigenen API Key in der CLI konfiguriert hast (Anthropic, OpenAI oder andere kompatible Anbieter), kannst du ein kostenloses ChatGPT-Konto verwenden, um dich beim VS Code-Plugin anzumelden.

Das Plugin verwendet automatisch die Modellkonfiguration der CLI wieder und zwingt dich nicht, ChatGPT Plus zu verwenden.

4. CI/CD-Integration

Codex CLI unterstützt die Ausführung im Headless-Modus, erfordert keine menschliche Interaktion und eignet sich daher für die Integration in automatisierte Workflows.

Was kann Codex in einer Pipeline tun

Die folgenden sind gängige Einsatzbereiche von Codex in CI/CD im Headless-Modus:

GitHub Actions Beispiel

Der folgende Workflow ermöglicht es Codex, CHANGELOG.md basierend auf den neuesten Commits automatisch zu aktualisieren, jedes Mal wenn Code in den main-Branch gepusht wird:

In der Konfiguration gibt es zwei wichtige Punkte, die besondere Aufmerksamkeit erfordern:

Bei der Verwendung in CI wird empfohlen, in der Datei AGENTS.md im Projektstamm explizit den Umfang der Dateien festzulegen, die Codex im automatischen Modus ändern darf, um unerwartete Änderungen aufgrund der Fehlinterpretation von Prompts zu verhindern.

5. Tipps zum Prompting

Die Qualität der Ausgabe von Codex hängt weitgehend davon ab, wie Sie Ihre Fragen stellen.

Die folgenden fünf Tipps behandeln die häufigsten Probleme, auf die neue Benutzer stoßen, jeweils mit konkreten Beispielen.

Tipp 1: Ausreichend Kontext bereitstellen

Codex kann keine Gedanken lesen. Eine Anweisung wie "Behebe den Bug" lässt es blind raten, und das Ergebnis entspricht oft nicht Ihren Vorstellungen.

Hier ist ein Vergleichsbeispiel:

Effektiver Kontext umfasst drei Elemente:

Tipp 2: Komplexe Aufgaben in zwei Schritte aufteilen

Lassen Sie bei Aufgaben mit großem Änderungsumfang zuerst Codex analysieren und einen Plan skizzieren und führen Sie ihn dann aus, nachdem Sie bestätigt haben, dass die Richtung stimmt.

Alles in einem Schritt zu erledigen, mag schneller wirken, aber die Kosten sind höher, wenn die Richtung nicht stimmt.

Tipp 3: Verwenden Sie den Ask-Modus, um zuerst die Codebasis zu verstehen

askDer Ask-Modus ist ein schreibgeschützter Modus, geeignet, um die Struktur und Logik des vorhandenen Codes zu verstehen, bevor Änderungen vorgenommen werden.

Verstehen vor dem Ändern spart Zeit im Vergleich dazu, nach Änderungen zurückzugehen, um zu verstehen.

Beispiel

# ask 模式不会触发任何文件修改
codex -a ask "这个项目是如何处理用户认证的？梳理完整的认证流程"

Sobald Sie ein klares Verständnis haben, beenden Sie die aktuelle Sitzung und starten Sie im editierbaren Modus neu:

# 可编辑模式（需要确认）
codex -a auto

# 全自动执行（谨慎使用）
codex -a full-auto

Empfohlener Workflow:

ask
↓
理解代码结构
↓
确定修改方案
↓
重新启动 Codex
↓
进入可编辑模式
↓
执行修改

Hinweis: Die CLI unterstützt das Umschalten von Berechtigungsmodi zur Laufzeit nicht mehr; dies muss über einen/approvalsParameter beim Start angegeben werden. Der Desktop-Client unterstützt weiterhin das Umschalten innerhalb einer Sitzung.-aParameter. Der Desktop-Client unterstützt weiterhin das Umschalten innerhalb einer Sitzung.

Tipp 4: Verwenden Sie negative Anweisungen, um Grenzen zu setzen

Codex zu sagen, was nicht angefasst werden darf, ist genauso wichtig wie ihm zu sagen, was zu tun ist.

Besonders bei Refactoring-Aufgaben, die mehrere zusammenhängende Dateien betreffen, können unklare Grenzen leicht zu unnötigen Folgeänderungen führen.

Tipp 5: Zuerst nach einem Plan fragen, dann ausführen

Bei Aufgaben, bei denen du unsicher bist, lass Codex zuerst auflisten, wie er sie anzugehen gedenkt.

Dieser Schritt kostet fast keine Zeit, aber er ermöglicht es dir, Richtungsabweichungen früh zu erkennen und zu vermeiden, zu weit auf den falschen Weg zu geraten.

# 先要计划
codex "你打算怎么实现这个功能？先列出步骤，不要执行"

# 确认计划合理后再推进
codex "计划没问题，开始执行第一步"

Zusammenfassung

Diese fünf Richtungen decken den gesamten Pfad von "Projektkonfiguration" über "tägliche Abläufe" bis "Automatisierung" ab.

Du musst nicht alle von Anfang an verwenden. Es wird empfohlen, in dieser Reihenfolge vorzugehen: Schreibe zuerst AGENTS.md, damit Codex dein Projekt versteht, und integriere es dann nach und nach in deinen VS-Code-Workflow und deine CI/CD-Pipeline.

Prompt-Techniken lassen sich besser nach und nach durch tägliche Nutzung ansammeln, als sie sich alle auf einmal einzuprägen.