Scoped instructions: memory, rules and path-specific context

Layer CLAUDE.md from user to project to directory, scope rules by path, and understand why editing instructions mid-session changes nothing.

The instruction hierarchy

More specific files are appended after more general ones, so a directory-level instruction can refine or contradict a repository-level one. That ordering matters: put broad conventions at the top and local exceptions close to the code they describe.

# CLAUDE.md

## Commands
- Tests: npm test -- --runInBand
- Types: npx tsc --noEmit
- Lint: npx eslint . --max-warnings 0

## Conventions
- TypeScript strict mode; no implicit any
- Vitest for unit tests, Playwright for end-to-end
- Zod at every network boundary; parse, do not cast

## Never
- Never edit generated files under src/gen/
- Never commit .env or anything matching secrets/*

Path-scoped rules

A rules directory lets you attach guidance to a glob instead of a folder, so a rule can cover migrations everywhere without putting a file in every directory.

---
paths:
  - "src/api/**/*.ts"
  - "src/workers/**/*.ts"
---

# Server-side rules

- Every handler validates input with the schema from src/schemas.
- Never log a full request body; log the request id instead.
- Return the error envelope: { error: { code, message } }.
- Database access goes through the repository module, never raw SQL here.

• Rules load only when a matching file is in play, so unrelated work does not pay for them.
• One concern per rule file - mixing front-end and database guidance makes both harder to change.
• Because rules are files in the repository, a change to them shows up in the diff and can be reviewed.

Why mid-session edits do not apply

# the honest sequence
vim CLAUDE.md          # add: "always run npm test before finishing"
# ... the running session does not know about this

# a new session picks it up
exit
claude

Instruction files are read at session start, not on every turn. Editing one in another window while a session is live has no effect on that session, which is a common source of the belief that the agent is ignoring you. Application memory behaves the same way: it is loaded when the session begins.

• Finish or clear the session before relying on a new rule.
• Keep instruction files under roughly a page; every token is charged on every turn of every session.
• Prefer an imperative sentence over an explanation - 'run npm test before reporting done' beats a paragraph about testing culture.
• Put one-off requests in the chat; put anything that must survive a /clear in a file.

FAQ

Related

Managing the context window and session hygiene Subagents and context isolation

Last refreshed 2026-09-18.