Instruction files

The agents work well without any files of your own. To steer them, add files to a folder .agents/ in your repository, on its default branch (the main branch). Review a change to these files as carefully as a change to your code. The platform's own limits stay: on keys, on the files the agents never change, and on the tools the agents may use.

To write your own instructions step by step, see Write your own instructions.

Instructions for each kind of job

Put a file at .agents/prompts/<name>.md on the default branch of your repository. The agents then follow it for that kind of job, in place of the platform's own instructions. Without the file, the platform's own instructions are used.

The file for questions, .agents/prompts/ask.md, counts for questions in Chat and Telegram. A question on GitHub always gets the platform's own instructions.

Auto-merge's rules

The file .agents/adlc.json on the default branch says which pull requests Auto-merge leaves to a person. It is one JSON object with these fields:

• version: always 1.
• manual_paths: up to 100 patterns, each 1 to 200 characters. A pull request that changes a path that matches one of them waits for a person. The patterns are regular expressions, and they match anywhere in the path.
• max_per_day: the most changes Auto-merge puts into your code in a day, from 1 to 10. Without it, 10. When Auto-merge's own option is lower, its option counts.
• about: a note for people. Auto-merge does not read it.

Without the file, Auto-merge uses the platform's own rules in Shadow mode. Live mode needs the file: it is one of the checks under Auto-merge in Product settings. Add the ADLC policy to the repository opens a pull request that adds the platform's own rules, for you to read and merge:

{
  "version": 1,
  "manual_paths": [
    "(?i)(auth|login|logout|session|passw|permission|rbac|oauth|saml|token|secret|credential|crypt)",
    "(?i)(^|[/_.-])(sso|acl|iam|mfa|otp)([/_.-]|$)",
    "(?i)(billing|payment|invoice|checkout|subscription|stripe|paypal|refund|pricing)",
    "(?i)(security|privacy|gdpr|consent)",
    "(?i)(^|/)(infra|infrastructure|terraform|deploy|deployment|k8s|kubernetes|helm|charts|ansible)/",
    "(?i)\\.(tf|tfvars|hcl|sql)$",
    "(?i)(^|/)(alembic|prisma|schema)(/|\\.)"
  ],
  "max_per_day": 3
}

Whatever the file says, these always wait for a person: the files in the list below, CODEOWNERS and .agents/ in any folder, the paths you add in Product settings, a pull request with the label no-auto-merge, and a pull request that changes more than 300 files.

Files the agents never change

The agents never change these files, in any product. A change that touches one of them is not proposed. You can add more paths in Product settings. The one exception is the pull request that adds .agents/adlc.json when you ask for it, and a person always merges that one.

• CI workflows: .github/, .gitlab/ and .circleci/ at the top of the repository; .gitlab-ci*.yml, .gitlab-ci*.yaml, Jenkinsfile*, azure-pipelines*.yml, azure-pipelines*.yaml, bitbucket-pipelines.yml and bitbucket-pipelines.yaml in any folder.
• Infrastructure and deploy files: docker/, ops/, scripts/, monitoring/ and nginx/ at the top of the repository.
• Container files: Dockerfile* and docker-compose* in any folder.
• The agents' own instructions: .claude/, .agents/, CLAUDE.md, AGENTS.md, CLAUDE.*.md and AGENTS.*.md in any folder.
• Database migrations (the deploy runs them): migrations/ in any folder.
• Secrets and environment files: secrets/, config/secrets/ and config/jwt/ at the top of the repository; .env* in any folder.
• Dependencies: package.json, package-lock.json, composer.json, composer.lock, yarn.lock, pnpm-lock.yaml, requirements*.txt, pyproject.toml, poetry.lock and uv.lock in any folder.
• Git settings: .gitattributes and .gitmodules in any folder.

Clarity queries

The Collector (Clarity) reads the file .agents/clarity-queries.txt on the default branch. Without the file, it does not work. Each line is one query: a name, then Clarity's dimensions, separated by commas, without spaces. A line that starts with # is a note. Clarity answers 10 requests a day, so keep the list short.

# name   dimensions
device   Device
url      URL
os       OS