Give an agent useful repository context

Start with the current checkout

An agent needs to know which repository and branch it is changing. It also needs to know whether the working directory contains unrelated changes. These facts affect what it can safely edit and how the final diff should be interpreted.

Ask the agent to inspect the project instructions and package configuration before implementation. A remembered command from another repository can be wrong here. A familiar framework name does not establish the installed version or project conventions.

For a small change, provide the relevant module, callers, tests, and architecture decision. Add more information when the investigation shows a specific need.

Use repository instructions for stable rules

An instruction file can describe supported commands, module boundaries, review requirements, and actions that require an owner decision. The AGENTS.md convention gives coding tools a recognizable place for this information. Tool support and instruction precedence can differ, so check your tool’s behavior.

Keep stable project rules in the repository. Keep the current task in the task brief. Do not turn the instruction file into a history of every conversation or a list of temporary plans.

A useful instruction says “Run the authorization integration tests when a route changes access behavior.” A vague instruction says “Always be careful with security.” The first identifies a trigger and an action that a reviewer can verify.

Check instructions against the code

Instructions become stale when commands, directories, or architecture change. If a guide names a missing script, inspect the package configuration. If a document says a service is read-only, inspect the permissions before relying on that claim.

Record the conflict. Use direct evidence about the current version to understand implementation behavior. Do not silently discard an intentional policy because old code violates it. Policy and current behavior answer different questions.

For example, the guide may prohibit direct writes to a shared branch while an old script still performs them. The correct response is to preserve the policy and correct the script. Existing code is not permission to repeat a prohibited action.

Keep the context relevant and safe

A whole repository can contain credentials, private fixtures, customer exports, and old support logs. Repository access does not automatically make every file appropriate for a model service.

Use approved tools and data handling rules. Exclude secrets from context. Replace customer examples with invented data where possible. Check connected tools as well as uploaded files: a search connector can retrieve information that was never in the initial prompt.

A repository instruction that says “do not read secrets” is useful guidance. It is not a substitute for limiting access to secret storage and sensitive directories.

Leave a useful record for the next person

At completion, record the changed behavior, verification, and unresolved limits in the pull request. Update durable project documentation when the supported workflow changes. Avoid copying the entire agent transcript into the repository.

The record should help a future maintainer repeat the work without reconstructing a long conversation. Link to canonical documents and keep one authoritative description of each stable rule.

Good context reduces repeated investigation. It also makes mistakes easier to detect because the expected behavior and working commands are explicit.