RedLectern topic
Repository-aware agents · project instructions · edits · tests · review · execution boundaries.
For: Programmers · maintainers
After this page you can: Supervise a repository task and review the resulting changes.
Page reviewed
Part of: Artificial Intelligence › AI for coding
An AI coding agent can inspect repository context, modify files, and use tools to carry out a coding task. A useful task is a bounded repository change: describe the behavior you want, point to relevant project guidance, and ask for evidence you can review. Repository instruction files can explain architecture, conventions, and how a project builds and tests; AGENTS.md is one convention for giving agents that context.
Supervision continues after the edit. Compare the diff with the requested behavior, check whether tests were changed or skipped, and run the project’s relevant checks. Review generated commands before allowing them to run, especially when they may modify or delete files or access sensitive resources. Agent permissions and isolation differ across products and environments, so inspect the actual file, network, credential, and execution controls before delegating. Use human review when a change needs domain judgment, security scrutiny, or maintainer approval.
See how repository instructions give an agent project context, and how AGENTS.md fits into one documented workflow.
Start with: Adding repository custom instructions for GitHub Copilot in your IDE
Use a review checklist to examine intent, tests, security, and code that may look plausible but be wrong.
Start with: Review AI-generated code
Repository-aware work starts with the project’s own conventions: architecture, file layout, build and test steps, and patterns that should be preserved. Put durable guidance in repository instruction files, then make the task specific enough to connect that guidance to a requested behavior. Keep the request bounded: identify the outcome, relevant area, constraints, and how you will check the change. For unfamiliar or broad work, ask for a brief plan before edits and clarify assumptions that could affect behavior.
AGENTS.md is a repository-file convention for instructions intended for coding agents. Support and precedence can vary by tool, so verify how the agent you are using discovers and applies instruction files. Keep instructions concrete and current; they should describe how the repository works rather than prescribe patterns that are not actually used.
Shows project context and contribution guidance to check before assigning a repository task.
AGENTS.md
A repository-file convention for instructions intended for coding agents.
Write a three-sentence task request for an agent changing a repository feature. Include the desired behavior, one project constraint, and how you would verify the change.
Example: “Add an empty-state message to the saved-items view. Follow the existing component and localization patterns; do not change the saved-items API. Run the view’s tests and show the diff.”
Treat an agent’s changes as a proposal to evaluate against the task and the repository, not as proof that the task is complete. Read the diff for scope, behavior, and consistency with nearby code. Check that relevant tests exercise the requested behavior, and pay attention to tests that were removed, skipped, or weakened. Run the appropriate project checks and inspect failures rather than assuming a clean summary means they passed.
Review feedback from an agent is another input to verify. It can miss problems or misunderstand context, so validate specific claims against the code and tests. Security-sensitive or complex changes may need a teammate or maintainer to review them. The short practice below makes this concrete: compare the request, changed files, tests, and review comments before deciding what is ready.
Describes review of agent pull requests and cautions about running proposed workflow changes.
An agent changes a validation function and removes a failing test. Name two checks you would make before accepting the change.
Check whether the new behavior still meets the task and repository rules, and inspect why the test was removed. Run the relevant tests and review the diff for unintended changes; ask for a fix or explanation if the test was deleted instead of corrected.
A coding agent may do more than suggest text: depending on the environment, it can edit files, run commands, use network access, or reach credentials. Before delegating, understand which paths it can read or change, whether its commands run locally or in a remote environment, and what approval is needed for broader access. Use the narrowest permissions that still let the task proceed, and review commands that could alter or delete files.
Execution controls vary by product and configuration. A sandbox can limit filesystem, network, or credential access, but its actual policy and enforcement matter. Review workflow-file changes before enabling automation, since workflows may have access to sensitive secrets. Make approval a deliberate decision tied to the proposed action, not a habit of clicking through prompts.
Explains why proposed workflow changes need inspection before workflows are run.
A repository agent asks to run a command that writes files and needs network access. What two things should you inspect before approving?
Check what files the command can change and what network destinations it can reach. Confirm that both are needed for the task and that the execution environment’s permissions and sandbox policy match those limits.
No recent updates are available.
Titus Winters, Tom Manshreck, and Hyrum Wright · 2020
Learn how a large engineering organization approaches code, testing, changes, and documentation. Adapt its examples to your own repository.
Michael C. Feathers · 2004
Learn techniques for restructuring code you need to modify so you can add tests. Its examples and tools reflect an older edition, so adapt them to your current environment.
Steve McConnell · 2004
A broad reference for code construction, including low-level design and naming conventions. Its second edition predates AI agents and their tools.