Skip to content

Give reviewers base-pinned AGENTS.md and CLAUDE.md for the changed paths #682

Open

Description

@piekstra

Problem

Repository guidance files (AGENTS.md, CLAUDE.md, nested AGENTS.md files, and the docs/ they link) are where many repositories state the rules a change must follow. Today they reach a reviewer only when an agent prompt tells it to open them in the checkout:

  • cr does not read them; the dossier's repo-guidance.md covers only .codereview/agents provenance (internal/dossier/dossier.go, "Separate review-guidance files are not used for this review").
  • With Keep claude_cli and codex_cli reviewer sessions independent of ambient instruction files #681, no adapter loads them implicitly either, which is the right default for isolation.
  • The checkout a reviewer reads is the PR head. When a PR edits a guidance file, a reviewer that follows its prompt reads the edited rule, so a PR can loosen the rule it is judged against. .codereview/agents already avoids this by reading from the base branch.
  • Each prompt has to rediscover which guidance files apply to which changed paths, and prompts differ in how well they do it.

In repositories that pair their AGENTS.md rules with a repo-local reviewer naming those rules, a meaningful share of findings cite the guidance document and section directly, so this input carries real review signal when it is present.

Proposal

Add a reviewer-facing dossier artifact, for example dossier/final/guidance-map.md, built from the pinned base SHA:

  • For each changed path, list the guidance files that apply: root AGENTS.md and CLAUDE.md, and every AGENTS.md or CLAUDE.md in the path's ancestor directories.
  • Store the base-branch content of each listed file under the run artifact directory, so reviewers read the trusted version rather than the PR head's.
  • Mark guidance files the PR modifies, with a pointer to the diff, so a reviewer can judge the edit itself.
  • Keep it a map plus file copies, not prompt text: reviewers read what they need, in line with the checkout-native design that avoids context stuffing.

Out of scope: following links from guidance files into docs/; agent prompts can still do that.

Open question

This changes the context every reviewer sees by default. It should be measured on a fixed PR set before it becomes the default, comparing findings that cite repository rules and false positives with and without the map. An opt-in profile or flag for the trial would make that comparison straightforward.

Acceptance

  • Dossier artifact listing applicable guidance files per changed path, with base-SHA content copies and modified-by-PR markers.
  • Guidance files changed by the PR do not alter the copies the reviewers receive.
  • Measured comparison recorded before enabling by default.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:pipelineEnd-to-end review pipelineenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions