CLAUDE.md for an agent-to-agent review loop

CLAUDE.md is the instruction file Claude Code loads at the start of every session, from the working directory and each directory above it. For a review loop, the root CLAUDE.md holds what Claude needs to land a pull request without a person: wait for the review of the commit it pushed, answer every finding, and know where the review rules live.

What Claude Code loads, and when

From Anthropic's memory docs:

• At launch: CLAUDE.md or .claude/CLAUDE.md in the working directory and every directory above it, CLAUDE.local.md beside each, and your own ~/.claude/CLAUDE.md. They are concatenated, not overridden, and the files nearest the working directory are read last.
• On demand: a CLAUDE.md in a subdirectory loads once Claude reads, writes or edits a file there.
• Imports: a line @path/to/file pulls that file in at launch, relative to the file that imports it, up to four hops deep. It saves no context, since the imported file loads too.
• Path rules: Markdown files in .claude/rules/ with a paths list in their frontmatter load when Claude touches a matching file. paths is the only frontmatter field read.
• After compaction: the root CLAUDE.md is read again. Nested files and path rules come back only when Claude next touches their files.

All of it reaches Claude as context, not as enforced configuration. A step that must never be skipped needs a hook, which runs whether or not Claude remembers the instruction.

Where the review loop goes

In the root CLAUDE.md, committed. It loads in every session and survives compaction, and a pull request that takes several review rounds is a long session that compacts. A loop written in a nested file or a path rule can drop out of context halfway through.

The step that most often goes missing is the wait. CodePanel's own CLAUDE.md spells it out in its landing procedure:

2. Wait for the review of the commit you pushed, blocking in the same turn:
   MCP `wait_for_review` with that `headSha`, or `codepanel review <repo>#<n>
   --wait`. A timeout means call it again. Never end your turn on "waiting
   for the review" or "waiting for CI": nothing wakes a session that has
   ended.

A session that ends its turn to wait has nothing to wake it, so the pull request stalls with its findings unanswered until someone starts a new session. Each step of the loop is in The review loop; installing the plugin is in Claude Code setup.

Keep it short enough to load whole

Anthropic's docs suggest under 200 lines per CLAUDE.md, and Claude Code skips a file over 4 MiB. CodePanel has its own limit when a repository turns on agent files: 16,000 characters for all repository context in a round, with .codepanel/rules.md first and the agent files after the review rules set in the app (Repo context).

On 2026-10-17 this repository's CLAUDE.md was 294 lines and 16,244 characters. That is over Anthropic's suggestion, and more than CodePanel's whole budget, so with agent files on, part of it would be trimmed. The rules reviewers check live in .codepanel/rules.md, 1,370 characters, which is read first and always fits. Put the invariants there and keep CLAUDE.md for how Claude works.

Sharing it with AGENTS.md

By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. The last one catches people out: adding a personal CLAUDE.local.md turns AGENTS.md off for that person. The Project instructions setting can make Claude read both, but it is each person's own setting, not the repository's. A repository that uses Claude beside agents that read AGENTS.md either starts CLAUDE.md with @AGENTS.md or makes one file a symlink to the other; AGENTS.md compares the two.

The import also suits CodePanel's reviewers. With agent files on, they read both files from the repository root, follow no imports, and leave out a CLAUDE.md that only imports AGENTS.md or repeats it, so the shared text is read once and the lines below the import are read as CLAUDE.md's own.

Agents that read CLAUDE.md

• Claude Code reads CLAUDE.md (code.claude.com).
• Cursor reads CLAUDE.md (cursor.com, page 2).
• Copilot in VS Code reads CLAUDE.md, in the Local harness (code.visualstudio.com).
• OpenCode reads CLAUDE.md, only when there is no AGENTS.md (opencode.ai).
• GitHub Copilot CLI reads CLAUDE.md (docs.github.com).