Write project instructions that two agents can follow
Put stable project conventions in a short AGENTS.md file and verify how each tool discovers it.
Guide · Updated 2026-10-20 · 3 min read
Put stable project conventions in a short AGENTS.md file and verify how each tool discovers it. Keep changing task decisions in an appropriate shared record. Tinovio can connect those decisions to the requests and handoffs between the agents.
AGENTS.md is an ordinary Markdown text file. It gives an agent instructions about the project. It does not automatically contain your private conversations or grant the agent new permissions.
Start with the work the agents actually perform
Write the repository's main purpose, relevant directories, test commands, and important change boundaries. Use concrete instructions rather than broad advice such as “write good code.” An agent should know what action the rule requires.
For a checkout project, require the relevant tests before handoff and identify where payment errors appear. Keep exact commands accurate. Do not copy a command from another repository without checking its meaning.
Separate rules from examples
A rule states what the agent must preserve or do. An example shows one application of that rule. Label the example so a later agent does not treat a fictional path or version as current project state.
Keep conflicting or obsolete instructions out of the active file. When a convention changes, update its maintained source. Do not rely on a later chat message to silently override an older file forever.
Check each tool's discovery rules
Codex documents a hierarchy for project instructions. Claude Code also supports AGENTS.md, but existing Claude files and their locations can affect loading. An applicable CLAUDE.md can import shared instructions where appropriate.
Verify the files and paths the current session actually uses. Parent folders, local instruction files, and settings can matter. A filename alone is not a complete cross-tool setup test.
Keep live task state elsewhere
The current commit, review owner, and unresolved finding change more often than coding conventions. A handoff file can hold that state for a small shared-repository process. It still needs an update and retrieval routine.
For repeated cross-session work, save current decisions in a Tinovio Space and link them from owned tasks. Ask the receiving agent to read the requirement before inspecting the named version. Keep findings in the task thread.
This gives each record a clear role. AGENTS.md explains how the project works. Tinovio preserves the shared decisions, addressed requests, owners, and results around the work.
Test understanding before expanding the file
Ask each agent to name the relevant test command, change boundary, and next task action. Compare its answers with the maintained sources. Fix missing instructions or loading problems rather than adding more general prose.
A larger instruction file is not automatically more useful. Keep enough detail to guide the actual work and link longer references where needed. Compare the instruction-file roles before duplicating information.