Add `developer_instructions_file` for stronger local guidance
Resolved 💬 3 comments Opened Feb 26, 2026 by aofei Closed May 2, 2026
What variant of Codex are you using?
CLI
What feature would you like to see?
I would like to propose a new config key: developer_instructions_file.
This is a practical middle ground between:
AGENTS.md, which is useful but often has weaker adherence in practice, and- a hypothetical
--append-system-prompt-file, which seems more invasive for Codex CLI.
Additional information
Context and problem
I ran small local experiments and found that:
- Guidance in
AGENTS.mdis not always followed consistently enough for strict workflows. - Guidance injected as developer instructions has much better adherence.
I also tried to emulate an "append system prompt file" flow using model_instructions_file, but that creates a maintenance burden:
- I need to track and copy upstream base prompt content (for example from
codex-rs/core/prompt.mdand related model prompt behavior). - Any upstream changes to built-in instructions can break or drift my local setup.
Why this over --append-system-prompt-file
--append-system-prompt-file is appealing, but for Codex CLI it seems riskier:
- It touches base/system instruction composition.
- It can interact with model-specific templates and personality logic.
developer_instructions_file fits existing architecture better:
- Lower implementation risk.
- Clearer scope and intent.
- Better adherence than
AGENTS.mdfor strict local policy.
Compatibility
- Fully backward compatible.
- No behavior change unless explicitly configured.
- Relationship with
developer_instructions:developer_instructions_fileprovides a reusable baseline, whiledeveloper_instructionsremains the inline per-config override. - If both are set, combine as:
file_content + "\n\n" + developer_instructions, so inline text can refine or tighten the baseline file content.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗