Project rules should travel with the project. Hermes can load either its own .hermes.md family or a portable AGENTS.md family, but the selected type and directory scope determine which instructions reach the agent.
.hermes.mdis the highest-priority Hermes-specific project context type.AGENTS.mdis portable across several coding agents.- Only one project-context type wins at startup.
- Hierarchical files apply from broad repository rules toward more specific subdirectories.
1. Choose the file family
Use .hermes.md when the rules are specific to Hermes or need its parent-to-Git-root discovery behavior. Use AGENTS.md when the same instructions should work in Hermes and other coding agents.
A small project file should state concrete build commands, boundaries, and conventions rather than general encouragement.
# Project rules
## Build
- Run `python3 -m unittest discover -s tests -v` before finishing.
## Boundaries
- Do not edit generated files by hand.
- Keep credentials outside the repository.Do not put user identity or cross-project preferences in a project file. Those concerns have different homes.
2. Understand type precedence
Hermes selects one project-context type. The current priority begins with .hermes.md or HERMES.md, then the AGENTS family, followed by compatible alternatives. A higher-priority type prevents a lower one from being loaded as the startup project context.
This is why adding .hermes.md beside an existing AGENTS.md is not a merge operation. The Hermes-specific family wins. Keep shared rules in one place instead of maintaining two files that appear cumulative but are not.
3. Use hierarchical scope deliberately
Within the AGENTS family, Hermes can merge a chain from the Git root through intermediate directories to the working directory. Deeper files appear later, so they can refine broad repository guidance for one package. AGENTS.override.md provides a personal per-directory override and is usually ignored by Git.
A useful split looks like this:
AGENTS.md
packages/
api/
AGENTS.mdThe root file might define repository-wide test and security rules. The package file should contain only API-specific commands or exceptions. Repeating the whole root file makes drift more likely.
4. Know when context is loaded
Startup context is assembled when the session begins. Changes to a context file require a new session before they affect the startup prompt. Hermes can also discover deeper AGENTS-family files as tools navigate into subdirectories, so package rules become relevant when work enters that area.
Use --ignore-rules only as a diagnostic boundary. It also skips other rule and customization inputs, so a successful run with that flag says the problem may be in injected context; it does not prove which file was responsible.
hermes --ignore-rules5. Probe precedence without invoking a model
The standalone fixture models two cases. The first has both file families and selects .hermes.md. The second has root and package AGENTS examples and reports their root-to-leaf order.
python3 examples/chapter-04-project-context/context_probe.py --root examples/chapter-04-project-context/fixtures/priority --cwd examples/chapter-04-project-context/fixtures/priority/service
python3 examples/chapter-04-project-context/context_probe.py --root examples/chapter-04-project-context/fixtures/agents-chain --cwd examples/chapter-04-project-context/fixtures/agents-chain/packages/api{"context_type":"hermes","files":[".hermes.md"]}
{"context_type":"agents","files":["AGENTS.md","packages/api/AGENTS.md"]}The committed sample uses AGENTS.example.md so it cannot inject tutorial text into an agent working in this repository. In a real project, name that file AGENTS.md.
6. Keep rules testable and small
Good context names the exact command and expected boundary: run one test suite, avoid one generated directory, use one package manager. Vague advice consumes context without guiding a decision. Very long files may be truncated, and stale rules are worse than missing rules because they confidently direct the wrong action.
Start at the repository root with a short portable file. Add a nested file only when a subtree truly needs different instructions. Choose .hermes.md instead when the behavior is intentionally Hermes-only.
Leave a Reply