From 372de6d2c5c70aede778505bd0b3362a339c0a60 Mon Sep 17 00:00:00 2001
From: Robby He <448523760@qq.com>
Date: Mon, 22 Dec 2025 22:37:37 +0800
Subject: [PATCH] docs: add `developer_instructions` config option and update
 descriptions (#8376)

Updates the configuration documentation to clarify and improve the
description of the `developer_instructions` and `instructions` fields.

Documentation updates:

* Added a description for the `developer_instructions` field in
`docs/config.md`, clarifying that it provides additional developer
instructions.
* Updated the comments in `docs/example-config.md` to specify that
`developer_instructions` is injected before `AGENTS.md`, and clarified
that the `instructions` field is ignored and that `AGENTS.md` is
preferred.

___

ref #7973

Thanks to @miraclebakelaser for the message. I have double-confirmed
that developer instructions are always injected before user
instructions. According to the source code
[codex_core::codex::Session::build_initial_context](https://github.com/openai/codex/blob/rust-v0.77.0-alpha.2/codex-rs/core/src/codex.rs#L1279),
we can see the specific order of these instructions.
---
 docs/config.md         | 1 +
 docs/example-config.md | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/config.md b/docs/config.md
index d03b73698..77d4a9adc 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -1000,6 +1000,7 @@ Valid values:
 | `notify`                                         | array<string>                                                     | External program for notifications.                                                                                             |
 | `tui.animations`                                 | boolean                                                           | Enable terminal animations (welcome screen, shimmer, spinner). Defaults to true; set to `false` to disable visual motion.       |
 | `instructions`                                   | string                                                            | Currently ignored; use `experimental_instructions_file` or `AGENTS.md`.                                                         |
+| `developer_instructions`                         | string                                                            | The additional developer instructions.                                                                                          |
 | `features.<feature-flag>`                        | boolean                                                           | See [feature flags](#feature-flags) for details                                                                                 |
 | `ghost_snapshot.disable_warnings`                | boolean                                                           | Disable every warnings around ghost snapshot (large files, directory, ...)                                                      |
 | `ghost_snapshot.ignore_large_untracked_files`    | number                                                            | Exclude untracked files larger than this many bytes from ghost snapshots (default: 10 MiB). Set to `0` to disable.              |
diff --git a/docs/example-config.md b/docs/example-config.md
index ca4809851..b894867fa 100644
--- a/docs/example-config.md
+++ b/docs/example-config.md
@@ -56,10 +56,10 @@ model_reasoning_summary_format = "none"
 # Instruction Overrides
 ################################################################################
 
-# Additional user instructions appended after AGENTS.md. Default: unset.
+# Additional user instructions inject before AGENTS.md. Default: unset.
 # developer_instructions = ""
 
-# Optional legacy base instructions override (prefer AGENTS.md). Default: unset.
+# (Ignored) Optional legacy base instructions override (prefer AGENTS.md). Default: unset.
 # instructions = ""
 
 # Inline override for the history compaction prompt. Default: unset.