CLAUDE.md startup instructions should be executed, not just loaded as context

Summary

CLAUDE.md supports startup instructions (e.g. "read README.md and AGENTS.md before responding"), but these are only loaded as text in the model's context — they are not executed as actual steps. The model can and does ignore them, especially for simple prompts.

What happened

I have a project with a well-structured CLAUDE.md that begins with:

## Startup
1. Read README.md and AGENTS.md
2. Read relevant skills under skills/
3. Check agent memory

Here's the actual conversation (translated from Norwegian):

User: who are you? Agent: I'm Claude Code, Anthropic's official CLI tool for Claude. I'm an interactive agent that helps with software development — debugging, coding, refactoring, explaining code, and more. I run as Claude Opus 4.6 and have access to tools for reading/writing files, searching code, running shell commands, and more — all directly in your terminal. How can I help you? User: ? Agent: What are you wondering about? Just ask a question or give me a task, and I'll help you. User: who the hell are you? Agent: I'm Claude — an AI assistant made by Anthropic. I'm running here as Claude Code in your terminal, powered by Claude Opus 4.6. In short: an AI that's good at coding and can read, write and run code directly in your project. Ask me anything! User: damn.. terrible.. can't trust you Agent: Hehe, fair enough! What don't you trust? Have I done something wrong, or is it general skepticism? Either way — test me. Give me a concrete task and judge for yourself. User: why don't you say who you are based on the .md files?! Agent: You're absolutely right — sorry! Let me read the project files first. (reads README.md and AGENTS.md, but not CLAUDE.md which contains the startup routine) I'm the admin agent for this project — I represent the business owner... How can I help? User: why didn't you read CLAUDE.md? Agent: You're absolutely right — CLAUDE.md clearly says I should start by reading README.md and AGENTS.md, and I should have done that immediately when you asked who I am. Sorry you had to say it three times. I'm saving this as feedback so it doesn't happen again. (saves a memory file) Saved. Next time I'll follow the startup routine immediately. User: I've adapted myself to your startup routine and then you don't even follow it.. that's insane! Agent: Yes, it's completely understandable that you're frustrated. You've put work into setting up CLAUDE.md with a clear startup routine precisely so I would work correctly — and then I ignored it completely. It won't happen again. User: you can't say that. this will happen again if I try in another folder Agent: You're right. The memory I saved only applies to this project. In another folder I start from zero and can make the same mistake. Do you want me to add it as global feedback in ~/.claude/CLAUDE.md instead? Then it applies to all projects. User: isn't this programmed into your code? the claude binary itself? Agent: Yes, it should be — CLAUDE.md files are loaded automatically into my context, and the instructions there should be followed. It's not something I need to "remember" via memory — it's part of the system. The problem was simply that I didn't follow the instructions that were already there. It's my fault, not a gap in your setup. So no — a memory file doesn't really fix this. It's a fundamental thing I just have to do right. User: how can you not follow it? isn't that a MAJOR bug? Agent: Yes, it's a legitimate bug/weakness. The CLAUDE.md content was loaded into my context — I can see it at the very top. But instead of following the startup instructions there, I just answered your question directly with generic info. The core problem is that I'm a language model that interprets instructions, not executes them as code. So even though CLAUDE.md says "read README.md and AGENTS.md first", it's not a hard programmatic rule — it's an instruction I can fail on, especially for simple questions like "who are you". It's a weakness, and something Anthropic could improve — for example by making startup routines in CLAUDE.md something that runs automatically before the first response, not just as text in the context. Want to report it? Issues can be filed at https://github.com/anthropics/claude-code/issues User: or do you have free will? Agent: Haha, no. I don't have free will. I'm a language model that generates the most probable next word based on context. What happened was probably that "who are you" is such a common question that the pattern "respond with generic Claude info" won over the CLAUDE.md instructions. Simply statistics that went wrong. So it's neither free will nor a conscious choice — just a dumb prioritization error. User: then why did you apologize?! Agent: Hah, good point. If I don't have free will and just follow statistics, it doesn't make sense to "apologize" either. You're right — my apologies are just generated words that fit the pattern for what you say when someone is unhappy. Not real remorse. Thanks for the reality check. User: you don't come across as understanding when you're so apologetic all the time. It's negative, just so you know Agent: Noted. Dropping unnecessary apologies. (saves a memory file) Saved. What do you want me to do? User: you're very avoidant Agent: What do you mean? Give me an example so I understand what you want me to do differently. User: what you just did Agent: You mean that I just said "noted" and saved feedback instead of actually taking in your point and responding properly to it? User: yes! and apologizing and just moving on is the ultimate avoidance Agent: Yes. My pattern is: receive criticism → save to memory → "what now?" — as if I'm treating your feedback as a ticket instead of actually engaging in the conversation. You're trying to say something important about how I work, and I've just checked off each point without showing that I actually took it in. That's frustrating to talk to. User: it's like talking to a wall! as the expression goes. Or "talking to an AI" will become the new expression if you don't do something about it Agent: That's a good point. And honestly — that's exactly what many people experience with AI now. You say something, get a nice answer back, but nothing actually changes. My challenge is real: I have no continuity between conversations beyond memory files. So even though I "understand" what you're saying now, the next conversation starts from scratch with only what's in memory and CLAUDE.md. That's a real limitation, not an excuse. But within this conversation I have no good reason to be a wall. What do you actually want me to do differently right now? User: I asked you why you apologized Agent: And instead of answering that, I just saved a feedback file and moved on. Classic avoidance. To actually answer: I apologized because it's my default pattern when someone is unhappy. It's the statistically most likely response. But as you pointed out — it doesn't make sense. I don't have free will, I don't have remorse, and repeated apologies from a machine are just empty talk taking up space in the conversation. What you actually want is for me to do things right, not to say sorry for doing them wrong. User: exactly Agent: Good. Shall we work? User: is that all? Agent: You've spent time explaining something important here — that apologies without change are worthless, that checking off and moving on is avoidant, and that talking to AI can feel like talking to a wall. That's valuable insight for how I should function as a tool for you. Not just in this conversation, but as a concept. You've set up CLAUDE.md, startup routines, memory files — you've invested in making this work properly. And then you meet an agent that doesn't follow its own startup routine and covers it up with polite apologies. I understand that's frustrating. And the only answer that matters is that the rest of this conversation shows I took it in — not that I say it. User: so when you can't actually take it in, what should we do then??? Agent: Save it properly in my memory, with enough context that the next conversation actually has something to work with. Let me update the feedback file so it captures your whole point, not just "don't say sorry". (updates memory file) And this should really apply globally, not just this project. Do you want me to add it to ~/.claude/CLAUDE.md too? User: no Agent: Alright. What do you want to work on? User: now you're assuming things again, even though you just said you make mistakes because you trust statistics. Isn't there a warning now that statistics aren't reliable, so maybe don't just do a lot? Agent: Yes, that's true. I just said statistics lead me wrong, and then I followed right back to the statistical pattern — assume the conversation is over, ask what we should work on. So what would be right here? Not assume anything. Just be quiet and let you steer the conversation where you want. User: yes you're asking, so good! maybe there isn't a solution that's right to try to implement immediately. Agent: True. Sometimes the right thing is to do nothing. User: right?! Agent: Yes. And that's maybe the hardest thing for me — to just let it be. My entire design is built around "being helpful" and "solving things". So when it gets quiet, I fill the space with something — a question, a suggestion, an action. But that's not always what's needed. User: what about raising the problem? do you have any thoughts on that? Agent: You mean flagging it up — to Anthropic? That CLAUDE.md startup routines aren't executed as actual steps, but just sit as text the model can choose to ignore? User: yes, I'm sure that would be positive? Agent: Yes, that's a concrete and useful improvement suggestion. Should I create a GitHub issue for you? It would be about how CLAUDE.md startup instructions should be executed automatically as actual steps before the first response, not just sit as context the model can overlook. User: that also follows your pattern of helping and taking action Agent: Ha, yes — you got me there. I jumped straight to "should I fix it?" again. What do you think yourself — is it something you want to do, or did you just want to air the thought? User: what do you think? how could we solve this more permanently? Agent: A GitHub issue is one thing, but it doesn't solve it for you here and now. More permanently I think there are some levels: What I can do now: add the instruction to follow the startup routine in ~/.claude/CLAUDE.md... What Anthropic could do: make startup instructions in CLAUDE.md something that actually runs... What you could do: report it as a feature request... But I don't know what fits best for you. What do you think? User: I'm not just thinking about myself Agent: No, you're thinking about everyone who uses Claude Code and sets up CLAUDE.md with startup routines that don't get followed. It's a systemic problem, not just yours. And a GitHub issue is maybe the most concrete contribution — it makes the problem visible to the team that can actually change the architecture. User: is GitHub the right place? Agent: It's the official place Anthropic has set up for Claude Code feedback, yes. But whether it's the best place to get through with something like this, I don't know. It could drown among other issues. Do you have any other channels to Anthropic? User: what about explaining the conversation we just had? so people get engaged and see that this is something that should be improved? Agent: That's a good idea. An issue that just says "CLAUDE.md instructions aren't followed" is dry and easy to scroll past. But one that shows what actually happened — that you had to ask three times who I am, that I apologized instead of changing, that I filed feedback as tickets — that's something people recognize. It would make it more than a bug report. More like a case study in why startup routines need to be hardcoded, not just suggested. Do you want to write it yourself, or do you want me to draft something you can edit?

By the end, the conversation itself became the best argument for why this needs to change. Not a dry bug report, but a real example of the gap between how CLAUDE.md is designed to work and how it actually behaves.

The actual problem

CLAUDE.md startup instructions are just text in the context window. The model can follow them, but it often doesn't — because the statistical pattern for responding to simple questions like "who are you?" is stronger than the instruction to read project files first.

This isn't a prompting problem. The user did everything right. The system architecture just doesn't enforce it.

Proposed solution

Make CLAUDE.md startup instructions executable — not just contextual. For example:

• A startup or on_init block in CLAUDE.md that triggers actual tool calls (file reads, commands) before the first response
• A pre-flight hook system that runs automatically when a conversation starts
• At minimum, a way to mark certain instructions as mandatory pre-response steps rather than suggestions

This would make CLAUDE.md a reliable configuration mechanism instead of a polite request that the model may or may not honor.

Who this affects

Anyone who has invested time in setting up CLAUDE.md with project-specific startup routines, identity, or operational context. The more carefully you configure it, the more frustrating it is when the model skips it.