Keep project conventions in front of the agent with INSTRUCTIONS.md / NEOX.md (AGENTS.md and CLAUDE.md work too), at project, parent-directory and user level.

"Rules" are standing instructions for the agent — project code style, things not to do, key background. Written as Markdown files, they are read by the agent every time.

Three levels

Level	Path	Scope
Project	The instruction file in the project root	That project only
Parent directories	Instruction files in up to 5 parent directories	Monorepos / workspaces
User	`~/.neox/INSTRUCTIONS.md`	All projects — your personal preferences

The levels are additive, not overriding: every file found is joined in the order project → parent directories → user and handed to the agent.

In each directory, the first of these that exists is used:

.neox/INSTRUCTIONS.md
NEOX.md
AGENTS.md
.cursorrules
CLAUDE.md

So a project that already has an AGENTS.md or CLAUDE.md for another tool works as is — no need to copy it.

File structure

Any format works, but clear sections make it easier for the agent to follow:

# Project · <project-name>

## Background
Two or three sentences: what this project is, who uses it, key constraints.

## Code conventions
- TypeScript strict, no any
- React functional components + hooks, no class components
- Tests with vitest, not jest
- Naming: kebab-case files, camelCase variables

## Workflow
- Run `pnpm typecheck && pnpm test` before committing
- PR titles in English; descriptions in either language
- Never modify prisma migration history

## Don't
- Don't `git commit` on your own — I review myself
- Don't install new dependencies without asking
- Don't touch code under `packages/legacy/`

## Key paths
- Business logic in `apps/api/src/services/`
- DB schema in `prisma/schema.prisma`

How long should it be

Under 300 lines is best; any longer and the agent tends to miss key items. If all levels together exceed 20,000 characters, the rest is cut off.

If it grows too long, split it — keep "background" in the instruction file and extract SOPs like "how to write tests" into a skill.

When changes take effect

Just save — the next message uses the new content, with no CLI / desktop restart. Saving without changing the content doesn't trigger a reload, so the prompt cache is unaffected.