Last reviewed: 2026-07-22
Direct answer
Before starting a Codex cloud task, confirm three things: Codex has access to the intended GitHub repository, the cloud environment is configured for the repository, and the instruction file that governs the work is in a place Codex can discover from the working directory.
For Codex-specific guidance, use AGENTS.md or AGENTS.override.md at the repository root or in a relevant subdirectory. Codex documentation says it builds an instruction chain from global guidance, then project guidance from the project root down to the current directory, with closer files appearing later in the combined instructions.
A simple startup workflow:
- Setup assumptions: the repository is connected to Codex cloud, the environment has the dependencies and variables needed for the task, and the repository has committed instruction files for the agent surface you plan to use.
- Happy-path request plan: ask Codex to list the instruction sources it used and summarize the repository rules it will follow before it edits files.
- Error-path check: if the summary omits the expected file, restart from the intended directory or move the instruction file closer to the code being changed.
- Minimum assertions: record the repository name, working directory, discovered instruction filenames, task summary, and whether the planned checks match the repository guidance.
- Pass/fail logging fields:
run_id,agent_surface,repository,working_directory,instruction_files_seen,requested_change,planned_checks,result, andnotes. - What not to assert: do not treat this smoke test as proof that every later code change is correct, that private secrets are available, or that another agent surface reads the same file names.
For a related same-site guide on keeping instruction rules visible to agents, see Place CometAPI Rules in the Files Your Coding Agent Reads .
Sanitized log template:
run_id: "instruction-startup-check-YYYYMMDD-001"
agent_surface: "codex-cloud"
repository: "org/example-repo"
working_directory: "/path/to/work-area"
instruction_files_seen: ["AGENTS.md"]
requested_change: "brief placeholder, no private prompt"
planned_checks: ["unit test placeholder", "lint placeholder"]
result: "pass | fail"
notes: "short operator note with no credentials or private output"
Who this is for
This guide is for maintainers who use Codex cloud on repositories where project rules matter: test commands, branch practices, protected areas, escalation rules, or agent-specific handoff notes. It also helps teams that keep equivalent guidance for Claude Code or GitHub Copilot and want to avoid assuming every tool reads the same file.
Key takeaways
- Codex cloud work should start from the intended repository and environment before any change request is sent.
- Codex-specific repository guidance belongs in
AGENTS.mdorAGENTS.override.md; nested files can narrow the rules for a specific area. - Claude Code uses
CLAUDE.md, but its documentation describes importingAGENTS.mdfromCLAUDE.mdwhen a repository already has shared agent guidance. - GitHub Copilot repository-wide custom instructions use
.github/copilot-instructions.md. - A startup smoke test should confirm what the agent says it loaded; it should not claim code correctness, secret availability, model availability, costs, limits, or production readiness.
Failure modes
- Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
Sources checked
OpenAI Codex cloud documentation - accessed 2026-07-22; purpose: verify hosted coding-agent workflow context.
OpenAI Codex AGENTS.md guidance - accessed 2026-07-22; purpose: verify repository instruction-file context for coding agents.
Claude Code memory documentation - accessed 2026-07-22; purpose: verify project memory and instruction-file context for agent workflows.
GitHub Copilot repository instructions documentation - accessed 2026-07-22; purpose: verify repository instruction guidance.
OpenAI AGENTS.md documentation - accessed 2026-07-22; purpose: verify how Codex discovers and orders
AGENTS.mdguidance.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Codex cloud startup | GitHub is connected, an environment is created, and the task starts from that environment. | https://developers.openai.com/codex/cloud | 2026-07-22 | “Connect the repository, configure the environment, then start the task from that environment.” |
| Codex instruction discovery | Codex reads global guidance and then project guidance from the project root down to the current directory. | https://learn.chatgpt.com/docs/agent-configuration/agents-md | 2026-07-22 | “Place AGENTS.md where Codex can discover it from the work area.” |
| Nested Codex overrides | A closer AGENTS.override.md can replace broader guidance for a specialized directory. | https://learn.chatgpt.com/docs/agent-configuration/agents-md | 2026-07-22 | “Use a nested override only when a subdirectory needs different rules.” |
| Claude Code memory | Claude Code reads CLAUDE.md, and a CLAUDE.md can import AGENTS.md. | https://code.claude.com/docs/en/memory | 2026-07-22 | “Bridge shared instructions into Claude Code with a CLAUDE.md import when appropriate.” |
| Copilot repository instructions | Repository-wide Copilot instructions are stored in .github/copilot-instructions.md. | https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions | 2026-07-22 | “Use the Copilot-specific file for repository-wide Copilot guidance.” |
Reader next step
Compare the workflow against Start with CometAPI .
FAQ
Should one instruction file cover every coding agent?
Not usually. Keep the shared rules consistent, but verify each tool’s documented file name and loading behavior. A repository can keep common rules in one place and bridge them into tool-specific files when the tool supports that pattern.
How do I know Codex cloud actually saw the repository rules?
Start with a small request asking Codex to summarize the active instruction sources before making code changes. Compare the answer with the files you expect from the repository root and current work area.
Should secrets go in instruction files?
No. Instruction files should describe how to use secrets safely, not contain secret values. Keep credentials in the approved secret store or environment configuration for the task.
Can this check replace tests?
No. It only confirms the task starts with the right guidance. You still need the repository’s normal build, test, lint, review, and deployment checks before shipping code.