Project Rules

7.2. Project Rules — A Project’s Own Rules and Context

AGENTS.md — the main project context file

It tells the agent how the project is organized, which conventions to follow, and what special instructions exist. When the working directory is inside a git repository, Hermes loads a merged chain of AGENTS.md files: from the repository root first, then each intermediate directory down to the current working directory — the deeper the file, the more specific its instructions and the higher its priority.

Priority mechanism — only one kind is loaded per session

.hermes.md → AGENTS.override.md → AGENTS.md → CLAUDE.md → .cursorrules

First match wins — multiple kinds are never combined at the same time. Notably: if AGENTS.override.md exists next to AGENTS.md, the override is loaded instead of the committed file — handy for keeping a personal set of instructions (usually gitignored) separate from the team’s shared AGENTS.md, without editing the shared file.

Backward compatibility with Cursor

If the project already has .cursorrules or .cursor/rules/*.mdc and no higher-priority file, Hermes reads and applies them automatically — existing Cursor coding conventions work out of the box without being rewritten.

Security: prompt-injection scan before loading

Every context file is scanned for injection patterns before it is loaded (instructions to “ignore previous guidance”, attempts to read secrets, credential exfiltration…) — but this is only an additional protective layer, not a substitute for reviewing the AGENTS.md content yourself in repositories you did not write.

Notes

• Keep AGENTS.md concise — every character counts against the token budget, because it is included in every message in the session, not just the first one.
• In a monorepo with many packages, take advantage of the per-directory merge mechanism: put general rules at the root and per-package rules in the child AGENTS.md files — the child file overrides exactly the relevant parts.
• AGENTS.md files in subdirectories are not preloaded at session start — they are discovered “lazily” during tool calls and inserted into the tool call result; they are not present in the original system prompt.
• Always review the AGENTS.md content in repositories you did not write before starting a Hermes session there — the injection scanner is a defensive layer, not an absolute guarantee.