How to Fix AI Coding Assistants That Forget Project Instructions

You explain your project’s rules: use the existing package manager, preserve public APIs, and run the relevant tests. The assistant follows them for a while, then installs the wrong dependency, edits generated code, or declares success without checking its work.

To fix an AI coding assistant that forgets project instructions, first confirm that the correct rules are available in the current session. Check the instruction file’s name, location, scope, and activation settings. Then remove conflicting guidance, separate permanent conventions from temporary task details, and verify compliance through observable behavior.

Start by Identifying What Actually Failed

Before rewriting your prompt, identify one specific violation. “The assistant ignores everything” is difficult to diagnose. “It ran npm even though this project requires pnpm” gives you something concrete to investigate.

Use the following symptoms to choose your first check:

These are diagnostic starting points, not proof of a particular cause.

The distinction matters. Shortening a prompt will not repair a misspelled filename. Starting another chat will not remove a contradictory global rule. Upgrading the model will not make a missing instruction file appear in a remote checkout.

1. Confirm the Assistant Is Working in the Right Project

Check the actual repository, directory, and environment attached to the task.

This becomes especially important when you use multiple checkouts, Git worktrees, containers, remote development machines, or cloud agents. The instruction file you edited locally may not exist in the environment doing the work.

Confirm that:

• The active project is the intended repository.

• The instruction file exists in that checkout.

• Your latest edits have been saved.

• Required instruction changes have reached the remote environment.

• The assistant can read the file.

For example, updating rules in your main checkout does not establish that a separate worktree contains the same update. Verify the file in the working location rather than relying on its presence elsewhere.

Next, check the assistant’s supported instruction format.

2. Use the Correct Instruction File and Loading Mechanism

A Markdown file becomes persistent guidance only when the tool recognizes it or receives it through a supported mechanism. Different assistants use different discovery rules.

Codex: Check AGENTS.md and Overrides

Codex uses AGENTS.md for project guidance. Its documented startup discovery combines global instructions with files along the path from the project root to the current working directory.

An AGENTS.override.md file takes priority over AGENTS.md in the same directory. Instructions closer to the working directory override earlier guidance. The default combined project-document limit is 32 KiB.

If guidance is missing or stale, check the starting directory, unexpected overrides, and the size limit. Restart Codex in the intended directory after changing startup instructions, then verify the loaded instruction chain. These behaviors are documented in OpenAI’s AGENTS.md guide.

Do not assume every nested instruction file anywhere in the repository is automatically part of the initial context.

Claude Code: Inspect Persistent Instructions With /memory

Claude Code supports CLAUDE.md for written project guidance and auto memory for accumulated notes. The /memory command provides a way to inspect and edit memory-related files.

Anthropic recommends keeping each CLAUDE.md concise, targeting fewer than 200 lines. That recommendation is not a universal hard loading limit.

Claude Code also documents that the project-root CLAUDE.md is reloaded after compaction. Nested files and scoped rules can reload when the relevant files are read. If a requirement disappears, check whether it existed only in conversation or depended on a scope that has not become active again. See Claude Code’s memory documentation.

Cursor: Check Both the File Format and Rule Type

Cursor project rules use .mdc files inside .cursor/rules/. A plain .md file in that directory is not treated as an equivalent project rule.

Check how each rule activates:

• Always Apply: included in every chat session.

• Apply Intelligently: selected by the agent based on relevance.

• Apply to Specific Files: attached when matching files are in context.

• Apply Manually: requires an explicit mention.

A mandatory project convention should not depend on the assistant deciding that a vague description is relevant. Use an appropriate always-applied or file-scoped rule.

Cursor also supports a root AGENTS.md as a simpler option. Confirm that you are testing Agent behavior: its rules do not automatically govern every other Cursor feature. See the official Cursor rules documentation.

GitHub Copilot: Match Instructions to the Feature You Use

GitHub Copilot supports repository-wide instructions in .github/copilot-instructions.md. Path-specific instructions use files under .github/instructions/ with an applyTo pattern.

Support differs across editors, chat, code review, cloud agents, and CLI. Check GitHub’s instruction support matrix before assuming that a configuration supported in one environment applies everywhere.

In Copilot CLI, /instructions shows discovered instruction files and lets you enable or disable them. Its documentation also says applicable instruction files are combined without a general precedence order between those files, so conflicting instructions should be removed. See Copilot CLI custom instructions.

3. Verify Loading Without Accidentally Supplying the Answer

There is a difference between automatic discovery and successfully reading a file on request.

If you explicitly tell the assistant to open an instruction file, it may follow those rules afterward. That proves the file is readable. It does not prove the tool would have loaded it automatically.

Use this two-stage check:

1. Start a fresh session in the intended project. Inspect any available rule list, references, or session diagnostics.

2. Only if the expected guidance is absent, explicitly reference the file and repeat a small task.

If behavior improves only after the explicit reference, discovery or activation deserves closer investigation.

You can also ask:

Before making changes, identify the project instruction sources available to this session and summarize the rules relevant to this task. Report any uncertainty about whether a file was loaded automatically or read afterward.

Treat the response as supporting evidence. An assistant’s claim that it remembers a rule is less convincing than the application’s loading indicators and the actual result.

4. Replace Vague Rules With Decisions the Assistant Can Apply

A rule such as “follow best practices” leaves the assistant to decide what those practices are.

Compare these examples:

Write rules around project-specific decisions. Explain the reason when it prevents a plausible mistake. Clear instructions should also define editing boundaries; see why an AI coding assistant may change unrelated files and how to keep the final patch focused.

For example:

Do not edit generated API clients directly. Change the schema source and use the repository’s documented generation command.

That instruction tells the assistant both what to avoid and what to do instead.

5. Separate Permanent Rules From Temporary Task State

Project instructions should describe conventions that remain useful across tasks. A temporary bug investigation needs a different home.

Keep three categories distinct:

• Permanent rules: package manager, protected directories, API conventions, verification expectations.

• Task requirements: the current bug, permitted changes, acceptance criteria.

• Progress notes: what has been attempted, what failed, and what remains.

Otherwise, yesterday’s exception can become tomorrow’s default. A one-time instruction to skip an unavailable integration test should not silently turn into a standing policy against integration testing.

Here is an example of concise project guidance. Adapt it to your repository rather than copying assumptions that do not apply:

# Project Working Rules

## Changes
- Read the relevant implementation before editing.
- Preserve public interfaces unless the task authorizes a change.
- Keep unrelated cleanup separate from the requested fix.
- Do not overwrite existing uncommitted work.

## Dependencies
- Use the package manager established by this repository.
- Ask before adding or upgrading production dependencies.

## Generated files
- Update the source definition rather than editing generated output.
- Use the documented generation command when regeneration is needed.

## Verification
- Run checks relevant to the changed behavior.
- Report what ran, what failed, and what could not run.
- Never describe an unexecuted check as passed.

Store this content in the format your assistant supports. Different products may require additional metadata or separate scoped files.

6. Remove Contradictions Instead of Repeating the Same Rule

Search for competing instructions in global preferences, project files, nested rules, reusable prompts, and saved notes.

Typical conflicts include:

• “Use npm” in personal preferences and “use pnpm” in the project.

• “Always refactor duplication” alongside “make only the requested fix.”

• A task-specific test command that disagrees with an outdated instruction file.

• Two copies of a policy maintained independently.

Write down the conflict and decide which policy is correct for the project. Then update the relevant sources.

Do not assume all assistants share the same precedence system. A priority rule documented for one product may not apply to another.

For shared projects, maintain one authoritative version of each convention where practical. If several tools need their own instruction files, review those files together when a convention changes.

7. Repair Long Conversations With a Short Handoff

A long session can contain obsolete plans, failed experiments, and corrections that no longer apply. Carrying all of that forward can make the next decision harder.

Anthropic’s best-practices guidance recommends managing context deliberately and using clear task boundaries. Its practical advice includes starting fresh when accumulated conversation is no longer helping. See Claude Code best practices.

Before switching sessions, create a short handoff containing:

Goal:
Fix the settings panel without changing the save API.

Current state:
The UI change is complete. One existing test still fails.

Important constraints:
Preserve the save function signature.
Do not edit generated files.
Keep existing user changes.

Next step:
Investigate the failing test before making further edits.

Verification:
Report the focused test result and any remaining limitation.

In the new session, provide the handoff and confirm that permanent project rules are available.

A fresh chat without the necessary task state can lose useful progress. The goal is a smaller, accurate working context.

8. Test Compliance With a Small, Observable Task

Once the configuration looks correct, check behavior before assigning another large change.

A useful test should exercise a real project convention without risking important work. For example, ask for a plan to add a settings field and inspect whether it selects the existing validation helper.

For an editing test, use a disposable branch or sample file. Choose a narrow task with two or three relevant constraints, such as:

• Reuse the existing helper.

• Preserve a public function signature.

• Run the focused test.

Evaluate the output and command history against those requirements.

A single successful attempt does not establish permanent reliability. However, repeating the same small task after changing only the rule configuration helps distinguish a configuration improvement from an unrelated change in task difficulty.

If problems persist, record the assistant version, operating environment, active rules, task, and observed violation. That gives a support report or further investigation a reproducible starting point.

9. Enforce Critical Requirements Outside the Conversation

Some requirements deserve checks that do not depend entirely on the assistant remembering them.

Examples include:

• Formatting checks for code style.

• Type checks for supported interfaces.

• Tests for required behavior.

• Dependency policies for unapproved packages.

• Review requirements for sensitive changes.

• Permissions that limit available write or execution actions.

Written instructions explain the intended workflow. Automated checks can detect specific violations, and permissions can restrict actions.

Choose controls that match the consequence. A naming preference may need only a lint rule. A sensitive deployment should not depend solely on a sentence in a Markdown file.

Should You Switch Models?

Consider a model change after checking discovery, scope, conflicts, and verification.

Run the same representative task with the same project instructions and compare concrete outcomes. Count missed requirements, incorrect changes, and unsupported claims about testing—not just how confident or polished the explanation sounds.

For this problem, the first question is whether the model received the right instructions. The next is whether it applied them correctly. Keeping those questions separate prevents unnecessary switching and makes improvements easier to measure.

FAQ

Why does the assistant remember instructions in one chat but forget them in another?

The instruction may exist only in the earlier conversation, or the new session may use a different workspace or rule configuration. Put durable conventions in a supported project instruction file and verify that the new session receives it.

Does an AGENTS.md file work with every coding assistant?

No universal behavior should be assumed. Several tools support it, but discovery, scope, precedence, and feature coverage differ. Check the documentation for the exact product and feature you use.

Does context compaction erase all project rules?

No. Behavior depends on the tool and how the instruction was supplied. Persistent project guidance and conversation-only details can be handled differently. Check the tool’s documented reload behavior before blaming compaction.

Should I paste the full instruction file into every message?

Usually, a short reminder of the task’s critical constraints is more practical. Repeatedly pasting the entire file does not fix automatic discovery and can add unnecessary context.

What if the assistant correctly repeats a rule but still breaks it?

Loading may be working while execution fails. Make the requirement more concrete, test it on a smaller task, and use appropriate checks or permissions. Repeating the same rule more emphatically is not a reliable enforcement mechanism.

Make the Next Task Verifiable

Choose one rule the assistant recently violated. Confirm where that rule lives, whether it applies to the current task, and how the session receives it. Resolve any contradiction, then test it with a small, observable action.

Keep the instruction file useful enough that a developer could follow it too. When a rule has a clear trigger, an expected action, and a way to verify the result, both the assistant and its reviewer have less room to guess.