ZeroTwo reads one instruction file from your project and one from your global ~/.zerotwo/ folder before Work and Code tasks start, so every task begins with the same ground rules.
How ZeroTwo discovers guidance
Each location is checked for three file names, in this priority order: ZEROTWO.md, AGENTS.md, CLAUDE.md. The first file that exists with non-empty content is used in full, and the others in that location are ignored. Files are never merged within a location. The two locations are the global folder ~/.zerotwo/ and the root of the project folder, and when both have a file, both are shown to the agent, global first. ZeroTwo reads only the project root, so it does not walk down through subfolders collecting nested files.
A line that contains only @path is replaced by that file's contents. Paths can be relative to the including file, start with ~/, or be absolute. Cloud runs apply the same three names to the repository cloned into the sandbox.
Create global guidance
Put personal defaults in ~/.zerotwo/AGENTS.md (or ZEROTWO.md), such as running tests after a code change or asking before adding a dependency. This file is separate from Settings > Personalization > Companion > Custom instructions, which is a profile field that applies to chat in general. Settings > Import can copy global instructions from another agent into ~/.zerotwo/AGENTS.md, but only when that file does not exist yet.
Layer project instructions
Add a root AGENTS.md with repository norms. To write one, run /init in a Code or Work task in the desktop app. It asks the agent to analyze the codebase and create an AGENTS.md at the repository root, or to improve an existing AGENTS.md or CLAUDE.md in place. If a ZEROTWO.md exists at the root, it takes priority over AGENTS.md, so rename or merge the two to avoid hiding one.
This layout shows which files are used. Highlighted files are loaded, and the nested one is not read because only the project root is checked.
~/.zerotwo/
- AGENTS.mdGlobal defaults, shown first
my-project/
- AGENTS.mdProject norms, shown second
services/
- AGENTS.mdNot read (root only)
Verify your setup
Ask the agent to summarize the instructions it was given, and confirm that the global and project files both show up. ZeroTwo watches instruction files and refreshes them while a session is open, so a restart is not needed after an edit.
Troubleshoot discovery issues
- Nothing loads: confirm the file sits at the project root, or in
~/.zerotwo/for global guidance, and that it is not empty. - Wrong guidance: check for a higher-priority file such as
ZEROTWO.md, which hidesAGENTS.mdandCLAUDE.md. - An include does not expand: the
@pathmust be alone on its line and the target must be readable; a missing target is left as written.
Next steps
- The AGENTS.md site has background.
- Prompting ZeroTwo pairs well with persistent guidance.