AI Coding Agents: Repo Instructions, Tools & Permissions

This guide explains how AI coding agents use repository instructions, tools, and permissions to work on a codebase. You’ll learn how agents read project context, execute commands, and respect security boundaries, plus how to configure these for your own projects.

What You’ll Need

• A code repository (local or remote) with a supported AI coding agent installed (e.g., GitHub Copilot, Cursor, or a CLI agent like Aider).
• Basic familiarity with your agent’s configuration file (e.g., .cursorrules, AGENTS.md, or .aider.conf.yml).
• Access to the agent’s permission settings (usually in the IDE or CLI).

Step-by-Step

1. Understand repository instructions: Agents look for instruction files like README.md, CONTRIBUTING.md, or a dedicated AGENTS.md. These files tell the agent about coding style, build commands, and project structure. Place your instructions in a file the agent automatically reads—check your agent’s docs for the exact name.
2. Write clear instructions: In that file, include: how to run tests, linting commands, directory layout, and any constraints (e.g., “never modify generated files”). Be specific and use bullet points for readability.
3. Configure tool access: Agents can use tools like file editors, terminal commands, and web search. In your agent’s settings, enable only the tools you need. For example, allow terminal access if the agent must run tests, but disable web search if not required.
4. Set permission levels: Most agents have permission modes—often “read-only”, “edit files”, and “full access”. Start with read-only to review suggestions, then escalate to edit mode when you trust the agent. For terminal commands, you can allowlist specific commands (e.g., npm test) and deny others.
5. Test with a simple task: Ask the agent to make a trivial change, like fixing a typo. Observe what instructions it reads and what tools it uses. Check the agent’s logs if available.
6. Iterate on instructions: If the agent misses context, update your instruction file. For example, add “Use TypeScript for new files” if the agent keeps writing JavaScript.
7. Review and audit: Regularly check the agent’s actions via version control diffs. Ensure it didn’t modify files outside its scope or run unexpected commands.

Common Mistakes

• Vague instructions: Saying “write good code” doesn’t help. Be explicit about style, dependencies, and edge cases.
• Overly broad permissions: Giving the agent full terminal access without restrictions can lead to accidental destructive commands (e.g., rm -rf).
• Ignoring the instruction file: Some agents only read instructions from a specific file. If you put them in README.md but the agent expects AGENTS.md, it won’t see them.
• Not updating instructions: As your project evolves, your instructions become stale. Update them when you change build tools or coding standards.

Tips

• Use a dedicated instructions file: Even if your agent reads README, a separate AGENTS.md keeps agent-specific guidance from cluttering human-facing docs.
• Leverage allowlists: For terminal commands, allow only safe ones like git status or python -m pytest. Deny commands that modify system state.
• Version your instructions: Treat AGENTS.md like code—commit changes and review them in pull requests.
• Use agent-specific keywords: Some agents recognize phrases like “IMPORTANT:” or “DO NOT” to prioritize rules. Check your agent’s docs.
• Start small: Before letting the agent refactor a large module, test on a small file to gauge its behavior.

Troubleshooting

Agent ignores instructions: Ensure the instruction file is in the root directory and named correctly (e.g., AGENTS.md). Some agents require a specific encoding (UTF-8) or a maximum file size. Also check if the agent has a separate config file that overrides instructions.

Agent can’t run commands: Verify that the terminal tool is enabled in settings and that the working directory is correct. Some agents need explicit permission to run commands—check the permission prompt.

Agent edits wrong files: Add explicit rules like “Only modify files in src/” to your instructions. Also, review the agent’s file access logs to see what it touched.

Permission errors: If the agent can’t read a file, check file permissions and ensure the agent runs with the right OS user. On Windows, path separators can cause issues—use forward slashes in instructions.

Agent becomes unresponsive: This often happens when a command hangs (e.g., a dev server). Set a timeout for terminal commands in your agent’s config, or manually kill the process.

Frequently Asked Questions

What is AGENTS.md and why do I need it?

AGENTS.md is a convention for giving AI agents project-specific instructions. It’s like a README for the AI, containing rules for coding style, testing, and commands. Many agents automatically read it, so it’s a good place to centralize guidance.

Can I use the same instructions for different agents?

Mostly yes, but agents may have different syntax for special directives. For example, Cursor uses .cursorrules with YAML frontmatter, while Aider reads AGENTS.md as plain text. You can maintain a common set of rules and adapt the format per agent.

How do I restrict the agent from running destructive commands?

Use your agent’s permission system to deny specific commands. For example, in Cursor, you can deny rm or git push. Alternatively, run the agent in a sandboxed environment or container.

What should I do if the agent modifies a file I didn’t want changed?

Revert the change using version control (e.g., git checkout -- file). Then update your instructions to explicitly forbid modifying that file or directory. For example, add “Never edit config.json” to your AGENTS.md.

Do agents automatically read all repository files?

No. Agents typically read only the files they need for the current task, plus instruction files. They don’t read every file in the repo, as that would be inefficient. You can explicitly reference files in your prompt to make the agent read them.

How do I know what tools the agent is using?

Most agents log their actions in a console or a dedicated panel. Look for a “Tools” or “Activity” tab. In CLI agents, you’ll see the commands they run. Review these logs regularly to ensure the agent behaves as expected.

Related

• Measuring Business Value and ROI of Enterprise AI
• Office Tab 14.00 Release Notes: What’s New
• iPhone 1.6nm Processors? The Truth Explained