Session-start instructions in CLAUDE.md are not enforced before first task execution

Resolved 💬 4 comments Opened Apr 8, 2026 by terry-webandwow Closed May 24, 2026

Environment

| Field | Value |
|-----------------------|----------------------------------------|
| VS Code | 1.114.0 (system setup) |
| Claude Code Extension | 2.1.92 |
| OS | Windows 11 (Windows_NT x64 10.0.26200) |
| Electron | 39.8.3 |
| Node.js | 22.22.1 |

---

Description

CLAUDE.md supports a session-start workflow where Claude is instructed to proactively load additional context files at the beginning of each conversation. This is a core use case for teams that rely on CLAUDE.md to define agent identity, rules, and working instructions across sessions.

The problem: Claude does not reliably execute these startup instructions. When a user opens a new session and immediately sends a task-related message, Claude starts working on the task directly — skipping the startup workflow entirely. The result is that Claude operates without the defined role, rules, and context, effectively ignoring the configuration the user has invested significant effort in building.

---

Steps to reproduce

  1. Create a CLAUDE.md that contains explicit session-start instructions, e.g.:

```
## Session Start
At the start of every session, load the following files before doing anything else:

  • path/to/role.md
  • path/to/rules.md
  • path/to/action-items.md

```

  1. Open a new Claude Code session in VS Code.
  2. Send a task-related message as the first message (e.g. "Please fix bug X").
  3. Observe: Claude starts working on the task immediately without loading the specified files.

---

Expected behavior

Claude reads and executes the session-start instructions from CLAUDE.md before responding to the first user message — regardless of what that first message contains.

---

Actual behavior

Claude skips the startup workflow when the first message is a direct task request. The session-start instructions are only executed if the user explicitly triggers them (e.g. by sending a neutral opening message like "start" or "hello" first).

---

Impact

For users who rely on CLAUDE.md to configure Claude's behavior per project — role definitions, rules, working instructions, context files — this makes the configuration unreliable. The setup only works if users know to send a neutral first message, which is not documented and not intuitive. Users who send task requests directly (which is the natural usage pattern) get an unconfigured Claude that ignores their project setup entirely.

This effectively breaks the contract implied by CLAUDE.md as a configuration mechanism.

---

Suggested fix / workaround

Workaround (current): Send a neutral first message ("Clark, start." or similar) to trigger the startup workflow before sending actual tasks.

Suggested fix: Execute CLAUDE.md session-start instructions as part of the session initialization, before processing the first user message — not as a response to it.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗