Replit Agent Ignores CLAUDE.md — It's Too Busy Rewriting replit.md Without Asking (2026)

Replit Agent doesn’t read CLAUDE.md or AGENTS.md by default — it uses its own file, replit.md, and the difference isn’t just the filename. Every other context file on this site — CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules — is something you write once and the agent treats as read-only ground truth. replit.md is the opposite: Replit Agent generates it automatically when you start a project, reads it before every task, and then edits it back as it “learns” about your codebase. That last part is also, per Replit’s own community forum, the thing that breaks most often.

Quick answer

replit.md isn’t a rules file, it’s closer to a shared notebook

The official docs describe replit.md as a file “Agent reads… to understand your project’s architecture, conventions, and coding style,” which sounds exactly like CLAUDE.md. The part that doesn’t carry over from the CLAUDE.md/AGENTS.md world is this line, easy to skim past: “it can also update the file as it learns more about your project.”

That’s a fundamentally different contract. CLAUDE.md is instructions flowing one direction, human to agent. replit.md is bidirectional — the Agent writes discoveries (tech stack, patterns it noticed, decisions it made) back into the same file you wrote your preferences into. There’s no separate scratch file for what the Agent has “learned”; it goes into the one file that’s also supposed to be your source of truth.

Typical sections the docs describe:

• Project overview and current development phase
• Technology stack and package manager choices
• Coding standards and API/error-handling patterns
• Testing approach and security requirements
• Communication preferences (how verbose you want the Agent to be)

If you delete replit.md and start a new Agent conversation, it regenerates from scratch by re-reading your codebase — there’s no way to restore a specific prior version except from your own git history.

The problem Replit’s own users are reporting

This isn’t a hypothetical edge case. On Replit’s community forum, a user laid out what they called a “fundamental issue”: replit.md is meant to be user-controlled instructions, but “the agent itself continually updates it,” sometimes because it decided it had “done something clever” worth recording. Reported failure modes from that thread and a separate bug report:

• Drift. Careful, hand-written instructions get diluted or overwritten by Agent-generated notes over a few sessions, and there’s no diff view surfaced in the UI to catch it.
• Selective amnesia. Multiple users report the Agent claiming it read replit.md (and a companion sysspec.md some teams add) before starting a task, then acting in ways that show it didn’t — “their actions and questions to me expose the lie,” as one user put it.
• Cold start. New projects begin with an empty or auto-generated replit.md, so your first few prompts are spent re-establishing context the Agent will eventually — but not immediately — persist.

There’s no official Replit response confirming or denying the drift behavior in either thread as of this writing. The one workaround multiple users report actually working: put a line at the very top of replit.md itself — something like “You must never edit this file without my permission” — which the Agent generally respects, since it’s reading its own instructions not to self-modify. It’s a workaround, not a setting; there’s no toggle in the UI to make the file read-only.

Three layers, not one file

As of 2026, Replit Agent customization has grown into three separate mechanisms, and replit.md is only the project-level layer:

Replit’s own customization docs are explicit about the intended division of labor: Custom Instructions are for things that are “always true” — security rules, approved libraries, compliance policies — because they load on every single message and cost context budget accordingly. Skills are structured like a mini SKILL.md folder (name, description, instructions) that only fires when the Agent’s own judgment says the current task matches. Neither is a superset of replit.md; they layer on top of it.

What the docs don’t spell out is precedence — there’s no published rule for what happens when a Custom Instruction says “always use pnpm” and replit.md says “this project uses npm because of a legacy lockfile.” In practice, treat replit.md as the more specific, more recently-written source and Custom Instructions as the baseline that should rarely need to override a project’s actual constraints. If you’re on Pro or Enterprise, keep project-specific exceptions out of Custom Instructions entirely — that’s what replit.md is for.

Does AGENTS.md work at all inside Replit?

Not automatically. Nothing in Replit’s documentation lists AGENTS.md as a file Agent checks by default, and it isn’t part of the replit.md auto-detection path. You can create an AGENTS.md file in a Replit project the same way you’d create any file, but Agent won’t discover or load it on its own — you’d need to reference it explicitly from inside replit.md (e.g., “see AGENTS.md for build and test commands”) to get the Agent to read it as part of a task.

That makes Replit an outlier among the tools covered on this site. Cursor, Windsurf, Aider, Zed, Codex, GitHub Copilot, Gemini CLI, Devin, Amp, and Jules all read AGENTS.md natively at this point, either as a primary file or a fallback. Replit predates and sits outside that convergence — replit.md isn’t a rebrand of AGENTS.md, it’s a genuinely separate mechanism with the self-updating behavior above baked in.

Practical setup: what to actually put in replit.md

Given the self-editing behavior, treat replit.md less like CLAUDE.md and more like a living spec you audit periodically:

# replit.md

**Do not rewrite or restructure this file without asking me first.
Append new findings under "Agent notes" instead of editing sections above it.**

## Stack
- Runtime: Node 22, TypeScript strict mode
- Package manager: pnpm (not npm — legacy lockfile constraint, do not change)
- Database: Postgres via Drizzle ORM

## Conventions
- API routes return `{ data, error }`, never throw past the route handler
- No `any`; use `unknown` and narrow

## Do not
- Do not add new npm dependencies without checking package.json first
- Do not modify files under /infra/ — those are managed by Terraform elsewhere

## Agent notes
<!-- Agent: append discoveries here, do not edit sections above -->

The “do not edit above this line” convention isn’t officially documented Replit behavior — it’s a community-sourced pattern, and it works because it’s an instruction the Agent reads and generally follows, not a filesystem permission. Review the “Agent notes” section periodically and promote anything durable up into the real sections yourself, rather than trusting it to stay organized on its own.

Migrating between Replit and CLAUDE.md/AGENTS.md tooling

If you’re moving a project’s context between Replit and a tool that reads CLAUDE.md or AGENTS.md:

• Into Replit: paste your CLAUDE.md/AGENTS.md content into replit.md directly — the sections map cleanly (stack, conventions, testing, restrictions). Add the “don’t rewrite this” guard line at the top immediately, before the Agent has a chance to touch it.
• Out of Replit: copy the human-authored sections of replit.md into AGENTS.md for portability, but leave anything under an “Agent notes”-style section behind — it’s Agent-generated scratch content, not curated instructions, and importing it verbatim tends to bring in project-specific trivia that doesn’t belong in a rules file another tool will treat as authoritative.

FAQ

Does deleting replit.md reset the Agent’s memory of my project? It removes the file’s content, but the Agent will regenerate a new replit.md on the next session by re-reading your codebase, not by recalling the deleted version. If you want to preserve history, commit replit.md to git like any other file and use version control, not the Agent, to roll back.

Is replit.md read by Replit’s other AI features, or only Agent? The documented behavior covers Agent specifically. Replit’s other AI surfaces (like the standalone Assistant) are not documented as reading replit.md the same way; don’t assume parity without checking current docs for the specific feature you’re using.

Can I use replit.md and Custom Instructions together without conflicts? Yes, that’s the intended design — Custom Instructions carry workspace-wide rules and replit.md carries project-specific ones. Conflicts are possible (see the precedence gap above) but not common if you keep Custom Instructions genuinely universal and leave project exceptions in replit.md.

Why doesn’t Replit just adopt AGENTS.md like everyone else? No official statement addresses this directly. The practical reason is likely that replit.md’s self-updating behavior is a deliberate product feature (Agent-as-author, not just Agent-as-reader), and that doesn’t map onto AGENTS.md’s spec, which assumes a human-authored, agent-agnostic file that any of a dozen tools can read identically.

For the full landscape of which coding agents read which config file and how they layer instructions, see our AGENTS.md vs CLAUDE.md tool support map and the CLAUDE.md / .cursorrules / .windsurfrules / AGENTS.md syntax reference. If your context file exists but isn’t loading in whatever tool you’re using, the AGENTS.md not loading debugging guide covers the tool-by-tool checklist. Browse real project rules files, including working AGENTS.md and CLAUDE.md examples, in our gallery.