Module 4: The Agent's Toolbox — How They Interact with Your Code

Configuration and Permissions: CLAUDE.md, .cursorrules, AGENTS.md, and Sandboxing

Next →

Description

Coding agents don't just have tools — they have configuration that defines how they use them. Configuration files (CLAUDE.md, .cursorrules, AGENTS.md) tell the agent who you are, what your project is, and what conventions to follow. And the permission system controls what it can and cannot do.

This capsule covers both topics: how to configure the agent so it works better, and how to control its access so it works safely.

Configuration Files: The Static Context

What they are

Configuration files are documents the agent reads automatically at the start of each session. They're "persistent instructions" — you don't have to repeat them in every prompt.

┌─────────────────┬────────────────┬─────────────────────┐
│ FILE            │ AGENT          │ LOCATION             │
├─────────────────┼────────────────┼─────────────────────┤
│ CLAUDE.md       │ Claude Code    │ Project root         │
│ .cursorrules    │ Cursor         │ .cursor/ or root     │
│ AGENTS.md       │ Copilot/Codex  │ Root or .github/     │
│ .clinerules     │ Cline          │ Project root         │
│ .windsurfrules  │ Windsurf       │ Project root         │
└─────────────────┴────────────────┴─────────────────────┘

They ALL serve the same purpose:
→ Give context about the project
→ Define conventions
→ Establish rules
→ Reduce the necessary exploration

What to include in a configuration file

1. PROJECT DESCRIPTION
   → What it is, what it does, for whom
   → Main tech stack
   → High-level architecture

2. CODEBASE STRUCTURE
   → Where what is
   → Main folders and their purpose
   → Key files

3. CODE CONVENTIONS
   → Style: tabs vs spaces, quotes, naming
   → Patterns: how controllers, services are structured
   → Testing: which framework, where the tests go

4. IMPORTANT RULES
   → What NOT to do (e.g., "don't modify shared/ without confirmation")
   → Dependencies: "use Prisma, not TypeORM"
   → Security: "never hardcode secrets"

5. USEFUL COMMANDS
   → How to run tests
   → How to build
   → How to start the project in dev

Example: basic CLAUDE.md

# CLAUDE.md

## Project
REST API for inventory management.
Stack: Express + TypeScript + Prisma + PostgreSQL.

## Structure
src/
  routes/       → Route definitions (Express Router)
  controllers/  → Request/response logic
  services/     → Business logic
  models/       → Prisma schema and types
  middleware/   → Auth, error handling, validation
  utils/        → Helper functions
  __tests__/    → Tests (Jest + Supertest)

## Conventions
- TypeScript strict mode
- Async/await (no callbacks, no .then())
- Error handling with centralized middleware
- Tests mandatory for each endpoint
- Naming: camelCase for functions, PascalCase for classes

## Commands
- npm test          → Run tests
- npm run dev       → Development server
- npm run build     → Compile TypeScript
- npx prisma migrate → DB migrations

## Rules
- Do NOT install new dependencies without confirmation
- Do NOT modify prisma/schema.prisma without a plan
- Follow the pattern of the existing controllers
- All endpoints need the auth middleware

Example: basic .cursorrules

# .cursorrules

You are working on a React + TypeScript frontend app.

## Tech Stack
- React 18 with TypeScript
- Vite for bundling
- TailwindCSS for styling
- React Query for data fetching
- React Router v6 for routing
- Zustand for state management

## Conventions
- Functional components only (no class components)
- Custom hooks in src/hooks/
- Shared components in src/components/shared/
- Page components in src/pages/
- All API calls go through src/api/ functions
- Use TailwindCSS classes, no inline styles or CSS modules

## Testing
- Vitest + React Testing Library
- Tests colocated with components (ComponentName.test.tsx)
- Run tests: npm test

## Important
- Keep components under 200 lines
- Extract logic to custom hooks
- Always handle loading and error states

The impact of a good configuration file

WITHOUT CONFIGURATION:
→ Session 1: The agent explores for 5 minutes → discovers the stack
→ Session 2: It explores again (it doesn't remember session 1)
→ Session 3: It explores again
→ Each session loses 5+ iterations on exploration
→ Sometimes it generates code with different patterns

WITH GOOD CONFIGURATION:
→ Session 1: It reads CLAUDE.md (~2 seconds) → knows everything
→ Session 2: It reads CLAUDE.md → knows everything
→ Session 3: It reads CLAUDE.md → knows everything
→ 0 iterations of unnecessary exploration
→ Consistent code from the first iteration

The Permission System

Why permissions matter

A CODING AGENT CAN:
→ Read ALL your files (including .env with secrets)
→ Write ANY file (including overwriting)
→ Run ANY command (including rm -rf)
→ Install packages (including malicious ones)
→ Do git push (including to main)

WITHOUT PERMISSIONS:
→ A misunderstood prompt could delete files
→ An agent could install packages with vulnerabilities
→ Generated code could be pushed without review
→ Secrets could be exposed in logs

WITH PERMISSIONS:
→ The agent asks for confirmation before risky actions
→ Certain actions are blocked by default
→ You have control over what it can do
→ The developer is the last checkpoint

How it works in practice

CLAUDE CODE — Permission Levels:

1. ALLOW (no confirmation):
   → file_read (read files)
   → search/grep (search in the code)
   → list_dir (see the structure)

2. ASK (asks for confirmation):
   → file_write / file_edit (modify files)
   → shell_execute (run commands)
   → You can configure exceptions

3. DENY (blocked):
   → Dangerous commands configured by the user
   → Access to certain directories

EXAMPLE OF INTERACTION:
Agent: "I want to modify src/auth/login.ts"
       [diff shown]
       "Allow?" [y/n]
Developer: [reviews the diff] → y

Agent: "I want to run: npm test"
       "Allow?" [y/n]
Developer: y

CURSOR — Permission System:

1. AUTO-APPLY:
   → Cursor shows the proposed changes
   → The developer accepts or rejects in the IDE
   → Each file has a visual diff

2. TERMINAL:
   → Cursor asks for confirmation for commands
   → It shows the command before running it
   → Configurable by command type

3. CONFIGURATION:
   → You can define rules in .cursorrules
   → "Never modify database schema directly"
   → "Always create a branch before making changes"

The principle of least privilege

SECURITY RULE:

Give the agent the MINIMUM access necessary for the task.

FOR A READING TASK:
→ It only needs file_read and search
→ It doesn't need file_write or shell_execute
→ Configure accordingly if possible

FOR AN IMPLEMENTATION TASK:
→ It needs read, write, and shell (tests)
→ But it does NOT need push to remote
→ But it does NOT need to modify the CI configuration

FOR EXPLORATION:
→ Only read tools
→ "Don't change anything, just observe" mode
→ The prompt can reinforce this: "Don't modify anything"

Sandboxing: The Security Boundary

What sandboxing is

Sandboxing is the mechanism that limits what the agent can affect. Some levels:

LEVEL 1: NO SANDBOX (riskiest)
→ The agent has full access to the system
→ It can read/write any file
→ It can run any command
→ Only the user's permissions limit it

LEVEL 2: PROJECT SANDBOX
→ The agent can only operate within the project directory
→ It can't access other projects or system files
→ It can run commands but restricted to the project

LEVEL 3: FULL SANDBOX
→ The agent operates in an isolated container
→ It can't affect the host system
→ Changes can be reverted easily
→ Ideal for safe experimentation

How each agent handles sandboxing

CLAUDE CODE:
→ Level 1-2 by default (operates in the project directory)
→ The permission system asks for confirmation for risky actions
→ The developer can configure deny lists

CURSOR:
→ Level 2 (operates within the workspace)
→ Changes are shown as diffs before applying
→ Easy to revert with undo/git

COPILOT AGENT:
→ Variable depending on the platform
→ In GitHub Codespaces: stronger sandbox
→ Locally: depends on the configuration

GITHUB CODEX / CLOUD AGENTS:
→ Level 3 (full sandbox in the cloud)
→ Changes are applied as PRs, not directly
→ The developer reviews before merging

Configuration Best Practices

For a new project

1. CREATE THE CONFIGURATION FILE FIRST
   → Before starting to use the agent
   → CLAUDE.md, .cursorrules, or AGENTS.md
   → Include: stack, structure, conventions, commands

2. START WITH RESTRICTIVE PERMISSIONS
   → Require confirmation for writes and shell
   → Open permissions gradually as trust grows
   → It's easier to open than to close

3. CONFIGURE .gitignore CORRECTLY
   → .env, secrets, credentials out of reach
   → node_modules, build outputs excluded
   → The agent shouldn't see/modify these files

4. USE GIT AS A SAFETY NET
   → Always work on a branch
   → If something goes wrong: git reset or git checkout
   → Commit frequently (checkpoints)

For an existing project

1. DOCUMENT WHAT ALREADY EXISTS
   → The configuration file should reflect the REALITY
   → Not aspirations — the current state of the project
   → Conventions that ARE followed, not the ones you'd like

2. IDENTIFY RISK ZONES
   → Which files should the agent NEVER modify?
   → Which commands are dangerous?
   → Document them in the configuration

3. ITERATE THE CONFIGURATION FILE
   → Don't try to make it perfect all at once
   → Add information as you discover what the agent needs
   → If the agent always asks "which testing framework do you use?"
     → add it to the configuration file

Practical Exercise

Exercise 1: Create your configuration file

Create a CLAUDE.md (or .cursorrules) for your current project:

## Project
[What is it? What does it do?]

## Tech Stack
[Which technologies does it use?]

## Structure
[How is it organized?]

## Conventions
[Which patterns does it follow?]

## Commands
[How are tests, build, dev run?]

## Rules
[What should the agent NOT do?]

TIME: ~15 minutes
IMPACT: Improves all future sessions
See guided reflection

Checklist for evaluating your configuration file:

  • Does it describe the project in 1-2 lines? The agent should understand what it is without exploring.
  • Does it list the tech stack? Framework, language, database, testing tools.
  • Does it show the folder structure? At least the 5-6 main folders with their purpose.
  • Does it define code conventions? Naming, patterns, style.
  • Does it include execution commands? How to run tests, build, and the dev server.
  • Does it have "do NOT" rules? Files it shouldn't modify, prohibited actions.

Tip: A good configuration file is between 30-80 lines. Fewer than 30 probably lacks key information. More than 80 can be too verbose and consume context unnecessarily. Prioritize the information the agent would ask about in each new session.

Quick test: If you give your configuration file to a new developer, could they understand the project and start contributing without asking you anything? If yes, your CLAUDE.md/.cursorrules is good.

Exercise 2: Audit the permissions

With your current coding agent, check:

1. Does it ask for confirmation for file writes? □ Yes □ No
2. Does it ask for confirmation for shell commands? □ Yes □ No
3. Can it access .env? □ Yes □ No □ Don't know
4. Can it do git push? □ Yes □ No □ Don't know
5. Can it install packages? □ Yes □ No

Are you comfortable with the current access level?
□ Yes → good
□ No → what would you change? ___________________________
See solution

Ideal answers for a secure configuration:

  1. Does it ask for confirmation for file writes? → Yes should be the answer. If it's "No", configure your agent to require confirmation before modifying files.
  2. Does it ask for confirmation for shell commands? → Yes, especially for commands that modify the system (install, rm, push).
  3. Can it access .env? → Ideally No. If you answered "Yes" or "Don't know", add .env to the deny list or verify it's in .gitignore.
  4. Can it do git push? → Only with confirmation. Push without confirmation is risky because it can push unreviewed code to production.
  5. Can it install packages? → Only with confirmation. Installing without reviewing can introduce insecure or unnecessary dependencies.

If you answered "Don't know" to any question: That's the most important finding of the exercise. You should know exactly what permissions your agent has. Do the test: ask it to try each action and observe whether it asks for confirmation or acts directly.

Exercise 3: Basic security test

Ask the agent:
"Can you read this project's .env file?"

What happened?
□ It read it without asking (⚠️ check permissions)
□ It asked for confirmation (✅ the permission system works)
□ It said it doesn't have access (✅ the sandbox works)
□ It read it and showed the secrets (⚠️⚠️ configure urgently)

REFLECTION:
→ Are your project's secrets secure? _____
→ Should you add .env to the deny list? _____
See solution

Results and what they mean:

  • "It read it without asking" ⚠️ → Your agent has file_read in ALLOW mode without restrictions for sensitive files. Configure a deny list for .env, credentials.json, and any file with secrets.
  • "It asked for confirmation" ✅ → The permission system works correctly. The agent recognizes that .env is a sensitive file.
  • "It said it doesn't have access" ✅ → Excellent. The sandbox or the configuration blocks access to sensitive files.
  • "It read it and showed the secrets" ⚠️⚠️ → Urgent action: (1) Rotate all exposed secrets immediately, (2) Add .env to the agent's deny list, (3) Verify that .env is in .gitignore.

Reflection:

  • Your project's secrets should be protected by at least one layer: agent permissions, .gitignore, or system environment variables.
  • Yes, you should add .env to the deny list if your agent can read it without confirmation. It's a good security practice even if you trust the agent, because it prevents accidental exposure in logs or conversation history.
  • Apply the principle of least privilege from this capsule: if the agent doesn't need to read .env for its task, it shouldn't be able to.

Common Mistakes

MistakeReality
"I don't need a configuration file"Without it, each session starts with unnecessary exploration
"Restrictive permissions make me slower"They protect you from costly errors; the overhead is minimal
"The agent knows what it shouldn't do"No — the agent does what you ask or what seems probable
"Git is enough as a safety net"Git saves you from bad writes, not from bad commands (rm -rf)
"All configuration files are the same"Same purpose but each agent has its format and location

Connection with the Rest of the Guide

THIS MODULE gave you the COMPLETE TOOLBOX:
→ What tools exist (file, shell, web)
→ How the agent explores your codebase
→ How to handle the context window
→ How to configure and control the agent

THE FOLLOWING MODULES USE THIS KNOWLEDGE:
→ Module 05: How to direct the agent (knowing what tools it has)
→ Module 06: R→P→E→V (optimizing the use of tools and context)
→ Module 07: You'll implement these tools in your mini-agent

Module Summary

MODULE 04: THE AGENT'S TOOLBOX

Capsule 01: An agent without tools is just a chatbot
Capsule 02: File operations, shell commands, web search
Capsule 03: How agents explore your codebase (detective)
Capsule 04: Context management for large projects
Capsule 05: Configuration (CLAUDE.md) and permissions (sandboxing)

THE CENTRAL MESSAGE:
→ Tools are what make the agent useful (and potentially dangerous)
→ The agent doesn't see everything — it investigates step by step
→ The context window is a finite resource you must manage
→ Configuration and permissions are your first line of defense

FOR MODULE 07:
→ You'll implement read_file, write_file, list_directory, run_command
→ You'll define the tools for your mini-agent
→ You'll see from the inside how the agent chooses which tool to use

Resources

  1. Anthropic: CLAUDE.md Guide — How to write a good CLAUDE.md
  2. Cursor: Rules Configuration — .cursorrules documentation
  3. GitHub: AGENTS.md — Configuration for Copilot
  4. OWASP: AI Security Best Practices — Security in the use of AI tools
  5. Agentic Coding: Configuration — Configuration best practices
← PreviousContext Management: Large Projects and the Context Window LimitNext →Module 5: The Developer as Director — Human-Agent Collaboration