Keeping CLAUDE.md and AGENTS.md consistent across a team

AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation. It has no required fields, and its own guidance says explicit chat prompts from the user override everything in the file.

Two files maintained by hand drift. Pick AGENTS.md as the source when the team uses more than one agent, since most of them read it, and make CLAUDE.md a pointer. The Claude Code docs give three ways to do that.

• Import it. A CLAUDE.md that starts with @AGENTS.md loads the shared file first, then any Claude-specific lines below it. This also covers sessions that cannot read AGENTS.md directly.
• Symlink it. ln -s AGENTS.md CLAUDE.md keeps one copy. The docs advise the import instead if anyone clones the repository on Windows, where a committed symlink can check out as a one-line text file.
• Rely on direct reading. Claude Code v2.1.277 and later read AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. Sessions on Amazon Bedrock or with telemetry off need v2.1.281 or later. A personal CLAUDE.local.md counts, so adding one switches that person back to CLAUDE.md only unless they set claude-md-and-agents-md in /config.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The import pattern above is the example from the Claude Code docs.

• Write instructions someone can verify. “Run npm test before committing” works; “Test your changes” does not give the agent anything to check.
• Keep it short. The Claude Code docs suggest under 200 lines per CLAUDE.md because longer files consume context and reduce adherence. Codex stops adding AGENTS.md content once the combined instructions reach 32 KiB by default.
• Scope what applies to part of the code. Use path-scoped rules in .claude/rules/, Cursor rules for specific files, Copilot instruction files with applyTo, or a nested AGENTS.md in the package it covers.
• Keep personal preferences personal. Put them in CLAUDE.local.md or ~/.claude/CLAUDE.md, not in the shared file.
• Review changes like code. Edits to the shared file go through pull requests, with one owner who decides when two rules disagree.
• Remove conflicts. The Claude Code docs warn that Claude may pick one of two contradictory instructions arbitrarily. Claude Code v2.1.283 and later can run /doctor prompt-audit to find outdated and conflicting instructions.
• Enforce in settings, guide in the file. Instruction files are context the agent tries to follow. Hard limits, such as blocked commands, belong in hooks or managed settings.

An instruction file is the right home for facts that hold across features. It reaches its limits when a team asks it to carry more:

• Decisions that change weekly. What the team agreed about a feature last Tuesday does not belong in a file every session loads, and the product and design people who made the decision rarely edit the repository.
• Per-task intent. The file cannot tell an agent what this change is for, what is out of scope, or how the result will be checked.
• Context cost. Every line loads in every session, so each new rule competes with the code the agent needs to read.
• Many repositories. Each repository carries its own copy, so one convention change becomes a pull request per repository. Symlinked shared rules and an organization-managed CLAUDE.md help Claude Code users, but they do not reach every agent.

Keep CLAUDE.md or AGENTS.md for stable repository facts. Hamster holds the context that changes and the context a whole team owns: Skills and Methods for conventions that span repositories, Blueprints for product and architecture context, and Briefs and Plans for the intent and acceptance criteria of each change.

hamster sync writes that context as markdown into .hamster/ in each repository and generates .claude/skills/hamster-project-context/SKILL.md, which tells the agent where every synced file lives. hamster skills sync puts the team's Skills in .agents/skills/, where coding agents load them like any other skill. Agents that prefer a live connection read and update the same content through the Hamster MCP server. The instruction file stays short because it no longer has to carry the plan.