README.md, AGENTS.md, and CLAUDE.md: which information belongs where
Use README.md to explain the project to readers, AGENTS.md for supported agent instructions, and CLAUDE.md for Claude's documented instruction model.
Comparison · Updated 2026-10-20 · 3 min read
Use README.md to explain the project to readers, AGENTS.md for supported agent instructions, and CLAUDE.md for Claude's documented instruction model. Their purposes can overlap, but their loading behavior is not identical. Keep current task state separate from broad project conventions.
The .md ending means Markdown, a plain-text format with headings and lists. These files contain written guidance, not a new capability by themselves. The agent still needs its own tools and appropriate access.
Compare their useful roles
| Typical purpose | |
|---|---|
README.md | Project introduction, setup, usage, and reader orientation |
AGENTS.md | Project instructions for agent tools that support its discovery model |
CLAUDE.md | Claude Code instructions under its documented loading rules |
Do not infer that an agent reads every project file automatically. Tell it to inspect the relevant guidance and verify the tool's actual loading behavior.
Keep shared instructions in one maintained source
Common conventions might include the test command, code style, and review process. Duplicating these across several files creates an update problem. One file can change while another keeps an earlier instruction.
Where the tool supports imports, use them deliberately and verify the resolved file. In Claude Code, existing instruction files and parent directories can affect AGENTS.md discovery. Read the current documentation before relying on the default.
Do not turn every discussion into a permanent rule
A checkout review can produce temporary findings, a changed version, and an unresolved question. Those details do not all belong in the project introduction or main instruction file. The next session needs their current relationship to the task.
A lasting product decision should include its reason and scope. A review result should identify the version and checks. Choose a record that preserves those distinctions.
Put the shared work around the files in Tinovio
Connect the participating sessions to the project Space. Save the current decision as shared context and link the relevant artifacts. Assign the next review with its owner and completion condition.
The reviewer reads the decision and returns findings in the task thread. The builder records its correction and actual checks. A later session can search for the work state without requiring a complete transcript in AGENTS.md.
Tinovio does not replace the repository files. It connects the messages, responsibilities, and decisions that happen while agents use them. The receiving session still needs to read the applicable records.
Check the setup with a new session
Ask it which instruction files loaded and what task state it found. Confirm the current requirement and next action. If it reads conflicting instructions, correct their source relationship before work continues.
Use the project-instruction guide to create a small, maintainable starting file.