Repository Instructions for AI Coding Agents

Repository instructions give AI coding agents a shared, project-specific guide to how they should inspect, change, and test code. Pair clear instructions with practical guardrails—such as review requirements, limited permissions, and automated checks—to reduce avoidable mistakes while keeping humans in control. Before you begin, identify the agents and development tools your team uses; instruction-file names and supported features vary, so confirm them in each tool’s current documentation.

What You’ll Need

• Access to the repository and permission to add or edit files and settings.
• A short list of the project’s languages, build and test commands, conventions, and sensitive areas.
• Documentation for each coding agent you plan to support, including its instruction-file format and any rule or permission settings.
• A way to review changes and run relevant checks, such as tests, linters, or type checks.

Step-by-Step

1. Decide what the instructions must achieve. Write down the recurring information a contributor needs before changing code: where the application starts, how its main components fit together, how to run checks, and which conventions matter. Add boundaries too, such as “do not edit generated files” or “ask before changing database migrations.” Prefer concrete, verifiable rules over general advice like “write good code.”
2. Check the repository’s existing guidance. Inspect its README, contribution guide, build configuration, CI workflows, and any existing agent-specific files. Look for contradictory or stale commands before adding anything. Keep authoritative project facts in their best existing home where possible; link to a maintained guide rather than copying a long section that may drift.
3. Choose instruction files the agent actually reads. Consult the current documentation for each tool and verify the exact filename, location, and scope it supports. Some tools use a root-level file; others support nested instructions, configuration files, or additional settings. Do not assume that a file recognized by one agent is read by another. If several agents are used, provide a concise shared guide and use small, tool-specific files to point to it or explain differences.
4. Write a concise root-level guide. State the repository’s purpose, important directories, setup steps, and exact commands for tests, linting, formatting, and builds. Include conventions that are not obvious from the code, such as API compatibility expectations or where new tests belong. Distinguish required checks from optional ones and say what to do when a check cannot run. Avoid dumping the entire README or asking the agent to reread every file on every task.
5. Add scoped instructions only where needed. For a monorepo or a project with distinct components, place additional guidance where the agent’s documented discovery rules will find it. Specify which paths the rules cover. For example, a mobile-app directory might describe its test command, while a database directory warns that migrations require human review. Keep local rules consistent with the root guide; resolve conflicting requirements rather than hoping the agent chooses correctly.
6. Separate guidance from enforceable controls. Instructions tell an agent what to do, but they are not a security boundary. Use repository permissions and agent settings to limit access where supported. Keep credentials out of prompts and instruction files; use approved secret-management mechanisms instead. Require human review for consequential changes, and use branch protection or CI checks to prevent unreviewed or failing changes from being merged. Never rely on wording alone to block access to sensitive systems.
7. Make the agent show its work. Ask it to inspect relevant files before editing, make focused changes, run the stated checks, and report files changed, checks run, failures, and assumptions. Tell it not to claim tests passed unless they actually ran successfully. For risky or ambiguous tasks, require a plan and human approval before implementation; verify the agent’s available approval controls rather than assuming a prompt instruction enforces them.
8. Test the guide on realistic tasks. Try a small documentation change and a modest code change. Check whether the agent finds the right instructions, follows the project’s commands, avoids restricted files, and reports results accurately. Review its diff yourself. If it misses a rule, clarify the wording or add an enforceable check; do not simply add more broad instructions.
9. Maintain the instructions as project code. Commit the files, review them like other changes, and update them when directories, scripts, or conventions change. Assign a maintainer or add instruction checks to an existing review process. Remove obsolete rules promptly: outdated commands can be more harmful than missing detail.

Common Mistakes

• Assuming an instruction file is universal: Agents differ in filenames, discovery, and precedence. Verify support for every tool in use.
• Writing vague or conflicting rules: “Be careful” is hard to test, and conflicting instructions force guesswork. State the action, scope, and verification method.
• Treating prompts as security controls: Text instructions cannot reliably prevent access or guarantee approval. Enforce important boundaries with permissions, protected branches, and review.
• Listing commands that no longer work: Test the documented commands in the repository’s normal development environment and update them when scripts change.
• Making the guide too long: Repeating large reference documents obscures the rules that matter. Keep the core guide short and link to focused documentation.
• Allowing unchecked changes to sensitive files: Call out migrations, deployment configuration, generated files, and secrets explicitly, then apply suitable review or CI controls.

Tips

• Use imperative, specific language: “Run npm test after changing application code” is clearer than “Tests are important.” Replace that example with a command verified for your project.
• Explain exceptions. If a full test suite takes too long, identify the focused check to run locally and the check CI performs.
• Give agents a safe default: make small, focused edits; preserve unrelated changes; and ask when requirements are unclear or a change crosses a stated boundary.
• Keep human review meaningful by asking for a concise change summary and test results, not merely a statement that the work is complete.
• Use automated checks for objective rules—formatting, tests, generated-file detection, or prohibited changes—when your existing tooling can enforce them reliably.

Troubleshooting

The agent ignores the guide: Confirm the filename and location against that agent’s documentation, ensure the file is committed or present in the working tree, and start a fresh task or session if instructions are loaded only at startup. Ask the agent to identify the instruction source it is following, then check whether another file overrides it.

The agent follows one rule but violates another: Search root and nested files for overlapping guidance. Clarify which rule applies to which paths and remove contradictions. If the rule is important for safety or quality, back it with permissions, CI, or required review.

Documented checks fail: Run the command yourself from the documented directory, confirm required dependencies and environment variables are available, and correct the guide. If a check is unavailable, have the agent report that limitation rather than inventing a successful result.

The agent edits too much or changes a protected area: Stop and review the diff before accepting it. Narrow the task and specify allowed paths; add stronger technical restrictions or require approval for sensitive changes. Revert unwanted edits rather than assuming a later instruction will undo them.

Different agents behave differently: Keep shared project facts in one maintained guide, but add minimal tool-specific files where required. Test each agent separately; instruction precedence, permissions, and supported controls are not necessarily interchangeable.

Frequently Asked Questions

Are repository instructions the same as agent permissions?
No. Instructions communicate expectations. Permissions and repository controls determine what tools or changes are allowed, so use both where appropriate.

Should every coding agent use the same file?
Only if each agent documents support for that file and location. Otherwise, keep shared guidance in a common document and add supported, tool-specific entry points.

Can instructions guarantee that an agent will not expose secrets?
No. Do not put secrets in instruction files or prompts. Limit access, use approved secret handling, and review changes that touch sensitive configuration.

How long should the instruction file be?
Long enough to explain essential setup, conventions, checks, and boundaries, but short enough to scan. Link to detailed documentation instead of duplicating it.

How do I know the instructions are working?
Test them with representative tasks, inspect the resulting changes, and verify that the agent ran and accurately reported the relevant checks.

When should the guide be updated?
Update it whenever documented commands, repository structure, or important conventions change. Review it periodically for obsolete or contradictory rules.

Related

• Samsung Smart TV Firmware Update: Step-by-Step Guide
• Stop My Data From Being Used to Train AI
• Track Changes to Competitor Website Messaging