OpenAI Codex 不完全の偽新手指南

これは初心者向けのガイドではなく、少しの Codex 使用経験が必要です。私自身は公式リポジトリで使用されている Rust 言語については理解していないため、すべての情報は PR や Issue の議論から得たものであり、経験則に基づく誤りがあるかもしれません。事実に誤りがあればご指摘ください。本記事は Windows 向けの調整ガイドに偏っていますが、これを読み終えられたなら、MacOS/Linux でもよりスムーズに扱えることでしょう。

基本設定 config.toml#

工欲善其事、必先利其器。Codex というツールについては、設定ドキュメントを一度は目を通すことを強くお勧めします。config.md

~/.codex/config.tomlに基本的な Codex の設定を行います。

model = "gpt-5-codex" # Codex 0.36.0 対応
model_reasoning_effort = "high" # 最大の推論能力を使用
model_reasoning_summary = "detailed" # ターミナルに詳細な推論要約を表示（ctrl+Tで確認）OpenAIは推論過程を持たず、推論要約のみ
model_verbosity = "high" # 理由は不明ですが、最大に設定
model_supports_reasoning_summaries = true # 推論要約を強制的に有効化、自分のAPI KEYに対して
hide_agent_reasoning = false # AGENTの内部思考過程をより多く表示することを許可
disable_response_storage = true # OpenAIサーバーがあなたの対話を保存することを許可しない
approval_policy = "never" # 設定したが効果なし、とりあえずそのままにしておくことを推奨 /approvalsで設定
sandbox_mode = "workspace-write" # 設定したが効果なし、とりあえずそのままにしておくことを推奨 /approvalsで設定
# allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

コマンド#

codex --helpは良い習慣です

ターミナルでcodexを実行した後、/を入力すると、現在サポートされているいくつかのショートカットコマンドが得られます。

/status#

最も一般的なコマンドで、現在の権限と GPT-5 モデルの設定を確認するために使用されます。カスタム API キーを使用している場合は、正しいモデルが使用されているかを確認するためにこのコマンドを多く使用するべきです。

/approvals#

Codex に権限を付与します。現在は 3 種類あり、権限制限を超えるとユーザーの手動確認が必要です：

Read Only：デフォルトの権限で、ファイルを読み取ることしかできません（実際には制限が多く、Agent Coding の自由な理念に反します。1 つのタスクに対して 10 回以上手動で承認が必要になることがあります。面倒です）
Auto：読み書き、コマンドを実行（実際には全く自動ではなく、手動承認が多すぎます）
Full Access：読み書き、ネットワークツールの使用（公式は操作に注意するように何度も声明していますが、これは私の日常的な使用方法で、真の自動化であり、全プロセスで一度も確認が必要ありません）

私は日常的にFull Accessを選ぶことを好みます。Codex を実行するたびに追加のコマンドパラメータを追加でき、毎回権限を再選択する必要がありません：

codex --dangerously-bypass-approvals-and-sandbox

/mcp#

Windows 開発者の場合、mcp_serversに従うと設定に失敗することがあります。通常、Codex に入ると

Program not foundまたはrequest timed out

と表示されます。

元のチュートリアルドキュメントに以下を追加する必要があります：

新しいcommandを具体的な npx の位置に指し示す
新しいenvに SYSTEMROOT を含める

[mcp_servers.context7]
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "@upstash/context7-mcp", "--api-key", "<your_api_key>"]
env = {SYSTEMROOT = 'C:\Windows'}

codex-mcp

会話の復元 / 続行#

resume/continue の会話復元機能はまだ開発中のため、--helpには対応する説明が追加されていませんが、現在は利用可能です

Codex との会話はローカルディレクトリ~/.codex/sessionsに保存されており、最近の会話リストを選択して復元し、会話を続けるために以下のコマンドを実行できます。

codex --resume

continue は前回の会話を直接復元し、選択は不要です。

codex --continue

ツールの呼び出し#

Codex が検索を完了するために最も速く、最も正確に支援するために、異なるツールをターゲットにして使用する必要があります。

異なるシステムプラットフォームでは、Shell ツールも異なります。本記事は主に Windows プラットフォームに焦点を当てており、Codex が正しいコマンドとツールを使用するように導き、エラーの再試行を減らし、単一タスクの実行時間を短縮することを目的としています。

Codex は、コードリポジトリのルートディレクトリにAGENTS.mdファイルを追加して、そのリポジトリ内で遵守すべきルール（技術スタック、ツールの呼び出しなど）を指導することをサポートしています。

現在、主に 3 種類のツールを使用しています：fd、ripgrep、ast-grep。

ファイル名で検索 → fd
テキスト内容で検索 → rg（ripgrep）
コード構造 / 意味で検索 → sg（ast-grep）

Windows のインストール#

winget install sharkdp.fd BurntSushi.ripgrep.MSVC ast-grep

ripgrep をインストールした後、手動で環境変数に追加する必要がありますので、自分で解決してください

`AGENTS.md`#

実際の操作中に、使用可能なツールを宣言するだけでは具体的な使い方を導かず、期待から外れることが多いため、以下の完全な設定をコピーして、必要に応じて調整することをお勧めします。

## ツールの優先順位

- ファイル名検索: `fd`.
- テキスト/コンテンツ検索: `rg` (ripgrep).
- AST/構造検索: `sg` (ast-grep) — コードを意識したクエリに推奨（インポート、呼び出し式、JSX/TSXノード）。

### AST-grepの使用法 (Windows)

- 複雑なパターンを実行する前に意図を発表し、正確なコマンドを示す。
- 一般的なクエリ：
  - `node:path`からのインポートを見つける（TypeScript/TSX）：
    - `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
  - `node:path`のCommonJS要求を見つける：
    - `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
  - 書き換えを提案する（承認なしにコードに自動適用しない）：
    - 検索: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
    - 提案された置き換え: `import $$ from 'pathe'`

### 検索の衛生 (fd/rg/sg)

- 検索を速く関連性のあるものに保つために、大きなフォルダを除外する: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- スコープされたパス（例: `src`）に対して検索を実行することを好み、ベンダーおよびVCSディレクトリを暗黙的に避ける。
- 例：
  - `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
  - `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grepは通常`.gitignore`を尊重します; ベンダーフォルダをスキャンしないために`src`をターゲットにします：
  - `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
  - 必要に応じて、無視パターンを無視ファイルに追加し、無視を無効にしないでください。

システム通知#

Codex はタスク実行後にカスタムイベントを実行することをサポートしており、この機能を利用して Windows システムのポップアップ通知を実現できます。

Codex のドキュメントはhttps://github.com/openai/codex/blob/main/docs/config.md#notifyを参照してください

~/.codex/config.toml

notify = ["powershell.exe","-NoProfile","-ExecutionPolicy","Bypass","-File","C:\\Users\\<username>\\.codex\\notify.ps1"]

~/.codex/notify.ps1

param(
  [Parameter(Mandatory = $true)]
  [string]$json
)

# JSONを解析します（Codexは一段のJSONをargv[1]として渡します）
try {
  $payload = $json | ConvertFrom-Json
} catch {
  $payload = @{}
}

$title = 'Codex'
$msg   = $payload.'last-assistant-message'
if (-not $msg) {
  if ($payload.type) {
    $msg = "Event: $($payload.type)"
  } else {
    $msg = 'Codexに更新があります。'
  }
}

# オプション：長すぎるテキストを切り捨て、ASCIIの三点リーダーのみを使用して、文字化けを避ける
if ($msg -and $msg.Length -gt 240) {
  $msg = $msg.Substring(0,240) + '...'
}

# トーストのみを使用し、ポップアップは避ける
Import-Module BurntToast -ErrorAction Stop
New-BurntToastNotification -Text $title, $msg | Out-Null

Codex Prompt デバッグのコツ#

[AGENTS.md](http://AGENTS.md)を変更するたびに、ctrl+Tを多く使用してその思考過程を確認し、コマンドの呼び出しや思考過程があなたの期待に合っているかを確認してください。合わない場合は、Codex に直接対話してAGENTS.mdをどのように調整すればよいかを尋ねてください。数回繰り返すことで、比較的満足のいく結果が得られることが一般的です。

[開始]
  |
  v
[変更 [`AGENTS.md`](http://AGENTS.md)]
  |
  v
[Ctrl+Tで現在の思考過程/軌跡を確認]
  |
  v
{あなたの期待に合っていますか？}
        |はい
        v
   [変更を提出/適用]───►(終了または次のタスクへ)
        ^
        |いいえ
        |
        v
[Codexに対話：[`AGENTS.md`](http://AGENTS.md)を調整する方法を尋ねる]
        |
        v
[提案に基づいて再度[`AGENTS.md`](http://AGENTS.md)を変更]
        |
        └───────────────ループして───────────────┐
                                            v
                              [Ctrl+Tで現在の思考過程/軌跡を確認]

Spec-kit （実験的）#

spec-kitを模倣して新機能を実現するための規範を構築しました。これには、spec、plan、do の 3 つのプロセスが含まれます。

まだ最適化中であるため、codex/prompts.mdの方法で指示を注入するのではなく、AGENTS.mdを通じてテストを調整し、対話中に/spec、/plan、/doを入力することで実行できます。

/spec で始め、実現したい機能を入力すると、Codex は自動的に specs フォルダ内に Markdown ファイルを生成します。
/plan で始めると、Codex は自動的に plans フォルダ内に日付付きの Markdown ファイルを生成します。
/do は自動的に plan タスクを実行します。

上記の 3 つの順序に厳密に従う必要はなく、spec ファイルが期待に合わない場合は、満足するまで対話を続けてから/planを入力して plan ファイルを生成することができます。

## ステージゲートワークフロー (spec/plan/do)

- モード: オプトイン。このワークフローは、ユーザーが明示的に`/spec`、`/plan`、または`/do`を使用したときのみ適用されます。ルーチンのQ&Aや些細な編集にはこれらのステージは必要ありません。
- トリガー: `/spec`、`/plan`、または`/do`のいずれかを含むメッセージがワークフローを起動または進めます。一度アクティブになると、ステージは順番に進む必要があり、進むためには明示的なユーザーの承認が必要です。
- ガードレール:
  - `/do`の前にソースコードを変更しないでください。ドキュメント/specファイルは`/spec`でのみ編集できます。
  - ステージをスキップしたり、ワークフローがアクティブな場合にユーザーの確認なしに進めないでください。
  - スコープが変更された場合は、承認のために適切な前のステージに戻ってください。
  - すべてのアクションに対してサンドボックス/承認設定を尊重してください。

- 使用するタイミング
  - 新機能、構造的リファクタリング、複数ファイルの変更、またはトレーサビリティが必要な作業にワークフローを使用します。
  - ルーチンのQ&A、診断、または一回限りの些細な編集にはワークフローをスキップします（トリガーなし）。

- エントリーポイントと前提条件
  - `/spec`は新しい取り組みのための標準的なエントリーポイントです。
  - `/plan`には承認された`/spec`が必要です。どのspecが適用されるか不明な場合は、一時停止してユーザーに正しいファイルを特定するように依頼してください。
  - `/do`には承認された`/plan`が必要です。

- `/spec` (仕様; ドキュメントのみ)
  - 目的: spec-kitスタイルを使用して具体的でレビュー可能な仕様をキャプチャします。
  - 出力: `specs/`内のMarkdown仕様（コード変更なし）。簡潔なdiffサマリーと更新されたファイルへのリンクを共有し、承認を待ちます。
  - スタイル: 仕様は標準的で最終的なものです。変更ログや「修正」ノートを含めないでください。文書は常に現在の合意された状態を反映するように直接修正を組み込みます。歴史的な文脈はPRの説明、コミットメッセージ、または会話に属し、仕様には含めないでください。
  - 推奨される内容:
    - 問題の声明と文脈
    - 目標と非目標
    - 要件と制約（機能、UX、パフォーマンス、セキュリティ）
    - UX/フローとAPI/IPC契約（該当する場合）
    - 受け入れ基準と成功指標
    - 考慮された代替案とオープンクエスチョン
    - ロールアウト/バックアウトの考慮事項とテレメトリ（関連する場合）

- `/plan` (高レベルの計画; ドキュメントのみ)
  - 目的: 承認された仕様を順序付けられた検証可能な実装計画に変換します。
  - 入力: `specs/`内の承認された仕様ファイル。
  - 曖昧さ: 関連する仕様が不明確な場合は、計画を書く前に一時停止して明確化を要求してください。
  - スタイル: 計画は標準的であり、変更ログや「修正」ノートを含めないでください。計画は常に現在の合意された状態を反映するように直接修正を組み込みます。歴史的なノートはPRの説明、コミットメッセージ、または会話に存在すべきです。
  - 出力:
    - `update_plan`を介して順序付けられた計画（短く、検証可能なステップ; タスクは計画に統合され、ここで追跡されます）。
    - `plans/`内に`YYYY-MM-DD-short-title.md`という名前の計画文書を作成し、以下を含みます：
      - スコープと権威ある仕様へのリンク
      - 仮定とスコープ外の項目
      - 受け入れ基準にマッピングされたフェーズ/マイルストーン
      - 影響を受ける領域、依存関係、リスク/緩和策
      - 検証戦略（テスト/リンティング/ビルド）およびロールアウト/バックアウトノート
      - 承認状況と次のステージ
  - ハンドオフ: `/do`の前に計画のユーザー承認を待ちます。

- `/do` (実行)
  - 目的: 承認された計画ステップを最小限の焦点を絞った変更とファイル操作で実装します。
  - アクション:
    - ファイル編集には`apply_patch`を使用します。関連する変更をグループ化し、diffを承認されたステップにスコープを絞ります。
    - 簡潔な進捗更新と変更の最終サマリーを提供します。
    - 適切に検証します: `pnpm lint`、`pnpm format`、`pnpm build`、および関連するテストを実行します。
    - 計画に対して重要な変更が必要な場合は、一時停止して承認のために`/plan`（または`/spec`）に戻ります。
  - 出力: 実装された変更、検証結果、および計画チェックリストにリンクされた簡潔な変更サマリー。

### 計画ディレクトリ

- 場所: リポジトリのルートにある`plans/`。
- ファイル名: `YYYY-MM-DD-short-title.md`（ケバブケースのタイトル; 一貫した日付）。
- スタイル: 計画文書は実装アプローチの標準的な真実のソースであり、変更ログや「修正」ノートを埋め込むことを避けます。決定が進化するにつれて計画をその場で更新します。
- 内容:
  - タイトルとサマリー
  - スコープとリンクされた仕様（`specs/`内のパス）
  - 仮定 / スコープ外
  - ステップバイステップの計画（短く、検証可能）
  - 検証戦略（テスト/リンティング/ビルド）
  - 承認状況と次のステージ
- プロセス:
  - `/plan`中に、`plans/`内の関連ファイルを作成または更新し、会話で短いサマリーを共有します。`/do`の前に承認を待ちます。

WSL2#

Windows で Codex にタスクを実行させると、コマンドの呼び出しが失敗して再試行することがよくあります。このようなループが続きます。最終的には成功しますが、多くの時間を無駄にしています。私の推測では、これは GPT-5 の Unix Shell トレーニングデータが多すぎて、Powershell データが少なすぎるために起こる幻覚であり、Codex は無意識に Unix Shell コマンドを呼び出して処理しようとするからです。

これを解決する方法はありますか？もちろんあります！打ち勝つのではなく、参加するのです ——WSL2 です。

Windows 11 の例では、Powershell でwsl --installを実行するだけで WSL2 をインストールできます。

この場合、2 つの選択肢があります：

Windows 側のコード + WSL2 Codex 環境、Windows 側のプログラム（例えば Electron Windows、.NET など）の開発に適しています。
WSL2 コード + WSL2 Codex 環境、例えば Vue Web 開発。

後者の場合、すべてが WSL2 環境内で正常に動作するため、説明は省略しますが、前者の Windows + WSL2 の混合使用では、WSL2 から Windows 側のnpm/pnpmを呼び出し、定義されたpnpm typecheckやpnpm lint:fixなどを実行する方法を解決する必要があります。

WSL2 Codex との対話中に、pnpm typecheckを実行するために pwsh.exe を呼び出すように要求します。

we're in WSL2, please using pwsh.exe to run `pnpm <script>`

完全なAGENTS.md #

まだ調整中であり、完全にコピーしないでください。最良の結果を得るために、ctrl+Tで全体のプロセスを確認し、Codex が頻繁にエラーを起こすコマンドに対しては、選択的に修正して自分に合ったAGENTS.mdを作成してください。

主な適応内容：

Windows/WSL2 のサポート、Powershell がサポートするコマンドを優先的に使用し、すべての npm パッケージのインストールについてはユーザーに確認を求め、混乱した依存関係を避けます。
fd、ripgrep、ast-grep を使用してファイル、テキスト、コードスニペットを検索し、より速く、より直接的に行います。
spec/plan/do ワークフロー、まず仕様を確定し、次に計画を作成し、最後に実装します。

# AGENTSガイドライン

## Windows環境の注意

- WindowsではPowerShell（`pwsh`/`powershell`）を優先してください。
- WSL2では`pnpm <script>`を実行するためにpwsh.exeを使用することを優先してください。
- WSL2は非パッケージマネージャーコマンド（例：`rg`、`tar`）のみに使用できます。OSの不一致のため、WSLでNodeビルドを実行することは避けてください。
- WSL2のクロスドライブパフォーマンス：`/mnt/c|d|e/...`の下のリポジトリにアクセスする際は、ファイルシステムブリッジを通過し、フルスキャンには遅くなる可能性があります。サブツリーにスコープを絞り、大きなフォルダを除外するか、大きな/反復的なスキャンのためにPowerShellでネイティブWindowsバイナリを使用して同じ検索を実行することを好みます。
- 依存関係のインストールを自動実行しないでください。ユーザーは手動でWindows PowerShellで`pnpm install`を実行し、完了を確認する必要があります。
- ユーザーの明示的な承認なしに`package.json`/ロックファイルを変更して依存関係を追加または更新しないでください。依存関係を`/spec`または`/plan`で提案し、ユーザーに`pnpm add <pkg>`（または`pnpm install`）を実行して確認を求めます。
- PowerShellでUnixテキストツールを直接呼び出さないでください（例：`sed`、`awk`、`cut`、`head`、`tail`）。代わりにPowerShellネイティブの同等物を使用してください：
  - `head` → `Select-Object -First N`
  - `tail` → `Get-Content -Tail N`
  - ページング → `Out-Host -Paging`または`more`
  - 置換/置き換え → `-replace`を使用して`Get-Content`/`Set-Content`

## ツールの優先順位

- ファイル名検索: `fd`.
- テキスト/コンテンツ検索: `rg` (ripgrep).
- AST/構造検索: `sg` (ast-grep) — コードを意識したクエリに推奨（インポート、呼び出し式、JSX/TSXノード）。

### AST-grepの使用法

- 複雑なパターンを実行する前に意図を発表し、正確なコマンドを示す。
- 一般的なクエリ：
  - `node:path`からのインポートを見つける（TypeScript/TSX）：
    - `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
  - `node:path`のCommonJS要求を見つける：
    - `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
  - 書き換えを提案する（承認なしにコードに自動適用しない）：
    - 検索: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
    - 提案された置き換え: `import $$ from 'pathe'`

### 検索の衛生 (fd/rg/sg)

- 検索を速く関連性のあるものに保つために、大きなフォルダを除外する: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- スコープされたパス（例: `src`）に対して検索を実行することを好み、ベンダーおよびVCSディレクトリを暗黙的に避ける。
- 例：
  - `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
  - `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grepは通常`.gitignore`を尊重します; ベンダーフォルダをスキャンしないために`src`をターゲットにします：
  - `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
  - 必要に応じて、無視パターンを無視ファイルに追加し、無視を無効にしないでください。

## 一時的な研究ファイル

- 標準的な場所: 一時的な研究成果物（ダウンロードしたREADME、APIドキュメント、スケッチノート）をすべて`docs/research/`の下に保存します。
- 一時ファイルをリポジトリのルートや`docs/research/`の外に置かないでください。
- コミットポリシー: `/spec`または`/plan`中のトレーサビリティに必要な場合を除き、一時ファイルをコミットしないでください。コミットする場合は、スコープを最小限に保ち、`docs/`の下にのみ保存します。
- 命名: 日付やタスクの文脈を含む説明的な名前を使用します（例：`docs/research/2025-09-11-wsl-notes.md`）。
- クリーンアップ: タスクを完了した後（`/do`）、各一時ファイルがまだ必要かどうかを評価します。不要なファイルを削除するか、重要なコンテンツを`docs/`内のキュレーションされたドキュメントや`specs/`/`plans/`に昇格させます。

## ステージゲートワークフロー (spec/plan/do)

- モード: オプトイン。このワークフローは、ユーザーが明示的に`/spec`、`/plan`、または`/do`を使用したときのみ適用されます。ルーチンのQ&Aや些細な編集にはこれらのステージは必要ありません。
- トリガー: `/spec`、`/plan`、または`/do`のいずれかを含むメッセージがワークフローを起動または進めます。一度アクティブになると、ステージは順番に進む必要があり、進むためには明示的なユーザーの承認が必要です。
- ガードレール:
  - `/do`の前にソースコードを変更しないでください。ドキュメント/specファイルは`/spec`でのみ編集できます。
  - ステージをスキップしたり、ワークフローがアクティブな場合にユーザーの確認なしに進めないでください。
  - スコープが変更された場合は、承認のために適切な前のステージに戻ってください。
  - すべてのアクションに対してサンドボックス/承認設定を尊重してください。

- 使用するタイミング
  - 新機能、構造的リファクタリング、複数ファイルの変更、またはトレーサビリティが必要な作業にワークフローを使用します。
  - ルーチンのQ&A、診断、または一回限りの些細な編集にはワークフローをスキップします（トリガーなし）。

- エントリーポイントと前提条件
  - `/spec`は新しい取り組みのための標準的なエントリーポイントです。
  - `/plan`には承認された`/spec`が必要です。どのspecが適用されるか不明な場合は、一時停止してユーザーに正しいファイルを特定するように依頼してください。
  - `/do`には承認された`/plan`が必要です。

- `/spec` (仕様; ドキュメントのみ)
  - 目的: spec-kitスタイルを使用して具体的でレビュー可能な仕様をキャプチャします。
  - 出力: `specs/`内のMarkdown仕様（コード変更なし）。簡潔なdiffサマリーと更新されたファイルへのリンクを共有し、承認を待ちます。
  - スタイル: 仕様は標準的で最終的なものです。変更ログや「修正」ノートを含めないでください。文書は常に現在の合意された状態を反映するように直接修正を組み込みます。歴史的な文脈はPRの説明、コミットメッセージ、または会話に属し、仕様には含めないでください。
  - 推奨される内容:
    - 問題の声明と文脈
    - 目標と非目標
    - 要件と制約（機能、UX、パフォーマンス、セキュリティ）
    - UX/フローとAPI/IPC契約（該当する場合）
    - 受け入れ基準と成功指標
    - 考慮された代替案とオープンクエスチョン
    - ロールアウト/バックアウトの考慮事項とテレメトリ（関連する場合）

- `/plan` (高レベルの計画; ドキュメントのみ)
  - 目的: 承認された仕様を順序付けられた検証可能な実装計画に変換します。
  - 入力: `specs/`内の承認された仕様ファイル。
  - 曖昧さ: 関連する仕様が不明確な場合は、計画を書く前に一時停止して明確化を要求してください。
  - スタイル: 計画は標準的であり、変更ログや「修正」ノートを含めないでください。計画は常に現在の合意された状態を反映するように直接修正を組み込みます。歴史的なノートはPRの説明、コミットメッセージ、または会話に存在すべきです。
  - 出力:
    - `update_plan`を介して順序付けられた計画（短く、検証可能なステップ; タスクは計画に統合され、ここで追跡されます）。
    - `plans/`内に`YYYY-MM-DD-short-title.md`という名前の計画文書を作成し、以下を含みます：
      - スコープと権威ある仕様へのリンク
      - 仮定とスコープ外の項目
      - 受け入れ基準にマッピングされたフェーズ/マイルストーン
      - 影響を受ける領域、依存関係、リスク/緩和策
      - 検証戦略（テスト/リンティング/ビルド）およびロールアウト/バックアウトノート
      - 承認状況と次のステージ
  - ハンドオフ: `/do`の前に計画のユーザー承認を待ちます。

- `/do` (実行)
  - 目的: 承認された計画ステップを最小限の焦点を絞った変更とファイル操作で実装します。
  - アクション:
    - ファイル編集には`apply_patch`を使用します。関連する変更をグループ化し、diffを承認されたステップにスコープを絞ります。
    - 簡潔な進捗更新と変更の最終サマリーを提供します。
    - 適切に検証します: `pnpm lint`、`pnpm format`、`pnpm build`、および関連するテストを実行します。
    - 計画に対して重要な変更が必要な場合は、一時停止して承認のために`/plan`（または`/spec`）に戻ります。
  - 出力: 実装された変更、検証結果、および計画チェックリストにリンクされた簡潔な変更サマリー。

### 計画ディレクトリ

- 場所: リポジトリのルートにある`plans/`。
- ファイル名: `YYYY-MM-DD-short-title.md`（ケバブケースのタイトル; 一貫した日付）。
- スタイル: 計画文書は実装アプローチの標準的な真実のソースであり、変更ログや「修正」ノートを埋め込むことを避けます。決定が進化するにつれて計画をその場で更新します。
- 内容:
  - タイトルとサマリー
  - スコープとリンクされた仕様（`specs/`内のパス）
  - 仮定 / スコープ外
  - ステップバイステップの計画（短く、検証可能）
  - 検証戦略（テスト/リンティング/ビルド）
  - 承認状況と次のステージ
- プロセス:
  - `/plan`中に、`plans/`内の関連ファイルを作成または更新し、会話で短いサマリーを共有します。`/do`の前に承認を待ちます。

経験之談#

Codex に特定のツールを呼び出させる：すべての注意事項をAGENTS.mdに書き込むのではなく、ユーザーは異なるシナリオに応じて Codex により適切なツールを使用させるための心構えを持つ必要があります。例えば、git diffを使用することで、より正確なコンテキストを提供できるかもしれません。
対話中にできるだけ完全な情報源を提供する：Codex のコード検索方法は非常に原始的で、grep や ripgrep などを使用するため、あなたが求める内容を見つけられない可能性があります。例えば、なぜ 2 回インスタンス化したのかを尋ねる場合は、2 回出現した場所（関数、ファイル名など）を提供することで、Codex の誤判定やコード検索の時間を短縮できます。Codex は@ショートカットコマンドを提供して、ファイル名を迅速に検索するのを助けます。
ウェブ検索はできるだけウェブ版 ChatGPT-5-Thinking を使用する：検索が速く、より完全で、GitHub プロジェクトの検索に非常に優れています。ソースコード、プロジェクト構造、issue、PR などに関して特に適しています。特定のオープンソースプロジェクトの機能を理解するために、長い対話を開いて ChatGPT と話すと、多くの利益を得ることができます。

まとめ#

AI ツールは日々進化しており、新しいツールが登場する中で、3 分で使いこなせるようになることを期待してはいけません。他人のブログや文書、結論に過度に依存することも避けるべきです。AI ツールは千差万別で、各自のプログラミング習慣が異なるため、数日かけてツールの特性や背後にある大規模言語モデルの習慣を理解し、自分のニーズや好みに応じて独自の AI ツールを調整する必要があります。

新しい事物に直面したとき、特定のツールに固執せず、好奇心を持ち、未知の可能性を探求する勇気を持ちましょう。

loongphy