Last reviewed: 2026-06-14

How to Review Agent Memory and Instruction Files Before a Long-Running Task

A five-minute pre-task review of your agent’s memory and instruction files prevents hours of drift on long sessions. Each coding agent platform loads a different set of files at startup; a stale or incorrect entry in any one of them can send a long-running task in the wrong direction before the first step completes.

Direct answer

Before launching a long-running agent session, check three things:

1. Which instruction files the agent will read. Claude Code reads CLAUDE.md files resolved from the working directory and from a user-level location. OpenAI Codex reads AGENTS.md. GitHub Copilot reads a repository-level custom instructions file. Confirm each expected file exists at the right path and is not empty. Exact paths and resolution hierarchy must be verified in current platform documentation; see ## Contract details to verify.

2. Whether the content is current. Open each file and check that project conventions, banned commands, and task scope rules reflect the current state of the repository. Remove or update entries that reference deleted branches, old file paths, or superseded conventions.

3. Whether the agent loads the file on startup. Run the ## Smoke-test workflow below before the main task begins. A single prompt asking the agent to summarize its project constraints is enough to confirm the file was loaded correctly.

For a broader approach to keeping instruction files accurate over time, see Memory Hygiene for Long-Running Coding Agents.

For broader release checks, see Agent Run Evidence Ledgers for Human Review .

Who this is for

This guide is for engineers and technical leads who:

• Run coding agents on tasks that take many steps or run unattended for extended periods
• Work in repositories with existing instruction files and want to confirm those files are read correctly before a new task starts
• Operate in teams where multiple contributors update the same instruction files, creating a risk of stale or conflicting entries

If you are setting up instruction files for the first time, start with How to Write Repository Instructions for Coding Agents and return here once your files are in place.

Key takeaways

• Each major coding agent platform reads memory and context from a platform-specific instruction file. Verify the correct file exists at the correct path before starting a long session.
• Instruction files are typically loaded at session startup. Changes made after the session starts may not take effect until the next session; verify this against current platform documentation before relying on mid-session edits.
• Stale entries — references to deleted files, renamed functions, or superseded conventions — are the most common source of agent drift on long tasks.
• A smoke-test prompt asking the agent to describe project constraints is the fastest confirmation that the instruction file was loaded.
• If you route agent calls through a model gateway, confirm the gateway endpoint path and authentication variable names are correct before the task starts. Exact endpoint details must be verified against current gateway documentation.

Smoke-test workflow

Run this workflow immediately before launching a long task. It is intentionally short — the goal is to confirm startup state only, not to validate the full task.

Setup assumptions

• The agent CLI is installed and authenticated.
• At least one instruction file (CLAUDE.md, AGENTS.md, or the Copilot custom instructions file) exists in the repository at the expected location.
• You are starting the agent session from the intended working directory.
• If you use a model gateway, the base URL and authentication variable name are set in your environment before the session starts.

Happy-path request

Start a new agent session and ask:

Describe the key project conventions and constraints you have loaded for this repository.

Pass condition: The agent’s response references at least one project-specific constraint or convention that appears in your instruction file. The response should reflect your repository’s actual rules, not a generic description of the agent’s default behavior.

Error-path check

If the agent gives a generic response that does not reflect your instruction file content:

1. Confirm the file is in the expected location (ls CLAUDE.md, ls AGENTS.md, or check the Copilot instructions path).
2. Confirm you started the session from the correct working directory.
3. For Claude Code: verify that the memory file hierarchy includes the project-level file. Exact loading order must be confirmed in current Claude Code memory documentation.
4. For OpenAI Codex: confirm AGENTS.md is at the repository root or the intended subdirectory, and is not excluded from the agent’s file scope.
5. Restart the session and repeat the smoke-test prompt.

Minimum assertions

The smoke test passes when:

• The agent references at least one project-specific convention from the instruction file.
• The agent does not reference conventions from a different project.

What the smoke test must not assert

• Do not assert that the agent uses a specific model variant or produces a response of a specific length.
• Do not assert specific response latency.
• Do not assert that the agent recites every line of the instruction file verbatim.

Sanitized log record template

After each pre-task smoke test, record the following fields with placeholder values. Do not log real credentials, full prompts, or complete agent responses.

task_id: TASK-PLACEHOLDER
agent_tool: AGENT-NAME-PLACEHOLDER
session_start: YYYY-MM-DDTHH:MM:SSZ
working_directory: /path/to/repo-placeholder
instruction_files_reviewed:
  - path: INSTRUCTION-FILE-PATH-PLACEHOLDER
    last_modified: YYYY-MM-DD
    entries_reviewed: 0
    review_outcome: pass
smoke_test_result: pass
smoke_test_response_summary: one-sentence-summary-placeholder
reviewer: OPERATOR-HANDLE-PLACEHOLDER
notes: ""

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

• Claude Code memory documentation - accessed 2026-06-14; purpose: verify project memory and instruction-file context for agent workflows.

• OpenAI Codex AGENTS.md guidance - accessed 2026-06-14; purpose: verify repository instruction-file context for coding agents.

• OpenAI Codex cloud documentation - accessed 2026-06-14; purpose: verify hosted coding-agent workflow context.

• GitHub Copilot repository instructions documentation - accessed 2026-06-14; purpose: verify repository instruction guidance.

• CometAPI chat completions endpoint reference - accessed 2026-05-26; purpose: verify gateway endpoint contract areas for operators who route agent calls through CometAPI.

• CometAPI model overview - accessed 2026-05-26; purpose: verify model routing context for gateway setup; exact model identifiers must be confirmed in current documentation before use.

Contract details to verify

Reader next step

Compare the workflow against Start with CometAPI .

Use Agent Run Evidence Ledgers for Human Review as the next comparison point. Keep When to Stop, Retry, or Escalate: A Practical Guide to Coding Agent Task Control nearby for setup and permission checks.

FAQ

What happens if I start a long task without reviewing memory files? The agent uses whatever instruction files it finds, including stale or conflicting entries. On short tasks this often does not matter. On long multi-step sessions, a single incorrect convention — a banned command that is now required, or a file path that no longer exists — can cause the agent to make incorrect decisions many steps in, requiring a costly restart.

Do I need to review memory files before every session? For short tasks, a quick visual scan is usually enough. For long tasks, multi-file changes, or sessions that will run unattended, a full review and the smoke test above are recommended. The review adds five minutes and can prevent hours of rework.

Can I include gateway configuration in the instruction file? Many operators include the gateway base URL and environment variable names in CLAUDE.md or AGENTS.md so the agent uses the correct endpoint from the start. Use placeholder variable names rather than real credentials, and verify exact endpoint paths and authentication field names against current documentation before adding them. For gateway routing setup, see Route Coding Agent Model Calls Without Endpoint Drift.

What if my repository has instruction files at multiple directory levels? Both Claude Code and OpenAI Codex support instruction files at multiple directory levels. The exact precedence and merge behavior must be verified in current platform documentation. Before a long task, review all instruction files in the hierarchy that apply to your working directory, not only the root-level file.

My agent acknowledged the instruction file but still drifted mid-task. What should I check? Mid-task drift is usually caused by instruction file entries that are ambiguous under edge conditions encountered later in the task, not by the file being absent at startup. After the task, identify which entry the agent was following when it drifted and rewrite it to be more specific. See Memory Hygiene for Long-Running Coding Agents for guidance on keeping entries precise and maintainable.

Can I route the smoke-test prompt through a model gateway? Yes. Routing the smoke-test prompt through your gateway confirms both the agent’s instruction file state and the gateway connection in a single step. Verify the current endpoint path and authentication contract against CometAPI documentation before building this into your workflow. Start with CometAPI to explore gateway routing options.