AGENTS.md
Steer how Hope AI writes code for a given tech stack by shipping an AGENTS.md file inside your dev environment. The guidance travels with the environment — every component that uses it is generated and edited by your rules, with no changes to Hope itself.
How it works
AGENTS.md is the open, cross-tool standard for agent-facing instructions. The same file that guides local agents (Cursor, Copilot, Claude Code) now also guides Hope AI. Hope picks it up automatically in two places:
Generating & changing componentsWhen Hope generates or edits a component, it reads the
AGENTS.md of that component's environment. If the environment ships none, Hope falls back to the parent environment it extends.The interactive agentThe chat-based Hope agent reads the
AGENTS.md of every environment configured for your account (Settings > Hope AI > Environments) and follows it throughout the session.The file is purely additive — if no environment ships an
AGENTS.md, nothing changes. Hope looks for AGENTS.md first, then agents.md.Add an AGENTS.md to your environment
1
Open your environment componentOr create a reusable dev environment if you don't have one yet.
2
Add an AGENTS.md filePlace it in the root of the environment component.
3
Write your guidance in plain MarkdownThe conventions an agent should follow when writing code for your stack.
4
Release the environment to share itEdits in your workspace are picked up right away. Snap and release the env when you want the file to travel with it to your team and other projects.
my-org.envs/my-react-env
├── env.jsonc # packages and versions
├── hope.jsonc # Hope generation rules
├── AGENTS.md # ← agent-facing instructions
└── ...If the env lives in your workspace, Hope reads the workspace copy of
AGENTS.md first — so you can iterate on it without releasing. Once released, Hope falls back to the published version (and to the parent environment's file if the env ships none).What to put in it
AGENTS.md is the place for the conventions an agent should follow when writing code for your stack — the things a new teammate would need to know.
# Agent instructions
## Styling
- Use CSS Modules (*.module.scss); never inline styles.
- Use design tokens from @my-org/design.theme — never hardcode colors.
## State & data
- Fetch data with the hooks in @my-org/data.hooks; don't call fetch directly.
- Co-locate state; lift to context only when shared across routes.
## Testing
- Every component ships a *.spec.tsx using Testing Library and Vitest.
- Test behavior, not implementation details.
## Conventions
- Named exports only; no default exports.Be specific and imperative. "Use CSS Modules" beats "prefer good styling."
Focus on what's non-obvious about your stack — Hope already knows general best practices.
Keep it focused. A long file dilutes the important rules; a tight, scannable one gets followed.
Use
hope.jsonc for structured generation rules (templates, per-file guidance) and AGENTS.md for free-form, agent-facing guidance that any tool can read.